Model Versioning for Agentic Systems: Rolling Back Without Breaking What's Downstream

// Schema contract registry for agentic model versions
// TypeScript — runs as part of your CI pipeline before any model rollout

import { z } from 'zod';

const ToolCallEnvelope_v2 = z.object({
  tool_name: z.string(),
  arguments: z.record(z.unknown()),
  reasoning_trace: z.string().optional(),
});

const ToolCallEnvelope_v3 = z.object({
  tool_id: z.string(),           // renamed from tool_name — breaking change
  arguments: z.record(z.unknown()),
  reasoning_trace: z.string().optional(),
  confidence: z.number().optional(), // additive — safe
});

type SchemaVersion = { version: string; schema: z.ZodTypeAny };

function isBackwardCompatible(
  previous: SchemaVersion,
  next: SchemaVersion
): { compatible: boolean; breakingFields: string[] } {
  // In production you'd use a proper schema diffing library.
  // This illustrates the gate logic — if a required key disappears or is renamed,
  // flag it as breaking before the rollout proceeds.
  const prevShape = (previous.schema as z.ZodObject<z.ZodRawShape>).shape;
  const nextShape = (next.schema as z.ZodObject<z.ZodRawShape>).shape;

  const breakingFields = Object.keys(prevShape).filter(
    (key) => !(key in nextShape)
  );

  return {
    compatible: breakingFields.length === 0,
    breakingFields,
  };
}

const result = isBackwardCompatible(
  { version: 'v2', schema: ToolCallEnvelope_v2 },
  { version: 'v3', schema: ToolCallEnvelope_v3 }
);

if (!result.compatible) {
  console.error(
    `[CI GATE] Breaking schema change detected. Renamed or removed fields: ${result.breakingFields.join(', ')}. Rollout blocked.`
  );
  process.exit(1);
}

// TypeScript — Schema violation monitor for model canary
// Plugs into your observability pipeline as a stream processor

import { z } from 'zod';

interface ModelOutput {
  modelVersion: string;
  callId: string;
  payload: unknown;
}

interface SchemaViolationEvent {
  callId: string;
  modelVersion: string;
  expectedSchema: string;
  violations: string[];
  timestamp: string;
}

const registeredSchemas: Record<string, z.ZodTypeAny> = {
  'v2': z.object({ tool_name: z.string(), arguments: z.record(z.unknown()) }),
  'v3': z.object({ tool_id: z.string(), arguments: z.record(z.unknown()) }),
};

function validateCanaryOutput(
  output: ModelOutput,
  expectedVersion: string
): SchemaViolationEvent | null {
  const schema = registeredSchemas[expectedVersion];
  if (!schema) throw new Error(`No schema registered for version ${expectedVersion}`);

  const result = schema.safeParse(output.payload);
  if (result.success) return null;

  return {
    callId: output.callId,
    modelVersion: output.modelVersion,
    expectedSchema: expectedVersion,
    violations: result.error.errors.map(e => `${e.path.join('.')}: ${e.message}`),
    timestamp: new Date().toISOString(),
  };
}

// In your canary processor stream:
async function processCanaryCall(output: ModelOutput, emit: (event: SchemaViolationEvent) => void) {
  const violation = validateCanaryOutput(output, 'v3');
  if (violation) {
    emit(violation); // downstream: rollback controller listens to this channel
  }
}

// model_lock.json — checked into each agent's source repo
// Immutable artifact pin that ties behavior + schema together

const modelLock = {
  "agentId": "customer-support-agent",
  "modelArtifactId": "hash-abc123",         // content-addressed: weights + prompt + schema
  "modelVersion": "gpt-4o-2025-06-01",
  "outputSchemaVersion": "v2",
  "schemaRegistryRef": "https://registry.internal/schemas/tool-call-envelope/v2",
  "lockedAt": "2026-08-15T09:00:00Z",
  "lockedBy": "ci-pipeline/build-4421"
};

// CI gate check — TypeScript
async function enforceModelLock(
  lock: typeof modelLock,
  fetchArtifactMeta: (id: string) => Promise<{ deprecated: boolean; breakingSuccessor: string | null }>
): Promise<void> {
  const meta = await fetchArtifactMeta(lock.modelArtifactId);

  if (meta.deprecated) {
    throw new Error(
      `[CI GATE] Model artifact ${lock.modelArtifactId} is deprecated. ` +
      `Breaking successor: ${meta.breakingSuccessor ?? 'none'}. ` +
      `Update agent lock and apply schema migration before deploying.`
    );
  }

  console.log(`[CI GATE] Lock validated: ${lock.agentId} -> ${lock.modelArtifactId} (schema ${lock.outputSchemaVersion})`);
}