Agent Versioning

Agent versioning tracks which version of an agent is deployed where, and creates a verifiable chain from source commit to running configuration. LODE’s VersionManifest schema captures this mapping as a compact binary payload.

Schema: VersionManifest

version-manifest-v1.lode


{
  "schema": "lode",
  "version": 1,
  "name": "VersionManifest",
  "fields": [
    { "id": 1, "name": "agentName",          "type": "string",             "required": true },
    { "id": 2, "name": "currentVersion",     "type": "string",             "required": true },
    { "id": 3, "name": "commitHash",         "type": "string",             "required": true },
    { "id": 4, "name": "tags",               "type": "string[]",           "required": false },
    { "id": 5, "name": "branchMappings",     "type": "map<string,string>", "required": false },
    { "id": 6, "name": "manifestFingerprint","type": "string",             "required": false },
    { "id": 7, "name": "previousVersion",    "type": "string",             "required": false },
    { "id": 8, "name": "changelog",          "type": "string",             "required": false }
  ]
}

TypeScript Interface


interface VersionManifest {
  agentName: string;                        // "compliance-analyst"
  currentVersion: string;                   // "2.1.0"
  commitHash: string;                       // Git SHA linking to source
  tags?: string[];                          // ["stable", "production"]
  branchMappings?: Record<string, string>;  // branch → version
  manifestFingerprint?: string;             // Hash of the agent manifest
  previousVersion?: string;                 // For rollback chain
  changelog?: string;                       // Human-readable change summary
}

Example

compliance-analyst-v2.1.0.json


{
  "agentName": "compliance-analyst",
  "currentVersion": "2.1.0",
  "commitHash": "a1b2c3d4e5f6",
  "tags": ["stable", "production"],
  "branchMappings": {
    "main": "2.1.0",
    "staging": "2.2.0-rc1"
  },
  "manifestFingerprint": "e7b3a1f9c4d2...",
  "previousVersion": "2.0.3",
  "changelog": "Added SOX compliance framework support"
}

Compilation


$ lodec compile compliance-analyst-v2.1.0.json -s version-manifest-v1.lode -o versions/ca-2.1.0.vein
Compiled compliance-analyst-v2.1.0.json → versions/ca-2.1.0.vein (246 bytes)
Fingerprint: f1a2b3c4...

Version Resolution

A registry serves the version manifest so clients know which agent version to pull:


app.get("/v1/agents/:name/version", async (req, res) => {
  const manifest = registry.getVersionManifest(req.params.name);
  const schema = loadLode("version-manifest-v1.lode");
  const vein = compile(manifest, schema);
  const fp = fingerprint(manifest);
 
  res.set("Content-Type", "application/x-vein");
  res.set("X-Lode-Fingerprint", fp);
  res.send(Buffer.from(vein));
});

Rollback

The previousVersion field creates a linked list of versions. Rolling back means loading the previous version manifest, verifying its fingerprint, and redeploying:


async function rollback(agentName: string): Promise<string> {
  const current = await fetchVersionManifest(agentName);
  if (!current.previousVersion) {
    throw new Error("No previous version to roll back to");
  }
  const previous = await fetchVersionManifest(agentName, current.previousVersion);
  await deploy(agentName, previous);
  return previous.currentVersion;
}

Branch-Based Promotion

The branchMappings field maps git branches to version strings, enabling branch-based promotion workflows:


function resolveVersion(manifest: VersionManifest, branch: string): string {
  return manifest.branchMappings?.[branch] ?? manifest.currentVersion;
}
 
resolveVersion(manifest, "main");    // → "2.1.0"
resolveVersion(manifest, "staging"); // → "2.2.0-rc1"
resolveVersion(manifest, "dev");     // → "2.1.0" (fallback to current)