{"record":{"id":"b6e9406e4a40acfa","repo":"JuliusBrussee/caveman","slug":"cave-context-ir-unknown-schema","errorCode":"cave_context_ir_unknown_schema","errorMessage":"cave_context_ir_unknown_schema","messagePattern":"cave_context_ir_unknown_schema","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/context-ir.ts","lineNumber":61,"sourceCode":"  safety: SafetyClass;\n  priority: ContextPriority;\n  recovery: RecoveryKind;\n  cache_region: CacheRegion;\n  privacy: PrivacyClass;\n  opaque: boolean;\n  ttl_turns?: number;\n  provenance_digest: string;\n  token_count: number;\n  body_handle: string;\n}\n\nexport interface ContextIRWire {\n  schema_version: 1;\n  segments: ContextSegmentWire[];\n}\n\nexport function contextIRToWire(ir: ContextIR): ContextIRWire {\n  if (ir.schemaVersion !== 1) throw new Error(\"cave_context_ir_unknown_schema\");\n  return {\n    schema_version: 1,\n    segments: ir.segments.map((segment) => ({\n      id: segment.id,\n      kind: segment.kind,\n      stability: segment.stability,\n      safety: segment.safety,\n      priority: segment.priority,\n      recovery: segment.recovery,\n      cache_region: segment.cacheRegion,\n      privacy: segment.privacy,\n      opaque: segment.opaque,\n      ...(segment.ttlTurns === undefined ? {} : { ttl_turns: segment.ttlTurns }),\n      provenance_digest: segment.provenanceDigest,\n      token_count: segment.tokenCount,\n      body_handle: segment.bodyHandle,\n    })),\n  };","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/context-ir.ts#L43-L79","documentation":"contextIRToWire serializes a ContextIR to its wire form and only understands schema_version 1. If the IR was produced by a different schema version (e.g. newer library writing v2 read by v1), it throws cave_context_ir_unknown_schema rather than guessing.","triggerScenarios":"Passing a ContextIR whose schemaVersion is not 1; deserializing persisted IR from a different library version into a v1-expecting contextIRToWire; hand-constructing an IR object with a wrong or missing schemaVersion.","commonSituations":"Version skew: persisted context caches written by a newer caveman release read by an older one; copying IR structs between services with mismatched package versions.","solutions":["Upgrade/downgrade packages so both producer and consumer use schema version 1","Rebuild the ContextIR from source data instead of reusing a stale persisted IR","Fix hand-constructed IR objects to set schemaVersion: 1"],"exampleFix":"// before\nconst ir = { schemaVersion: 2, segments: [] } as unknown as ContextIR;\ncontextIRToWire(ir);\n// after\nconst ir: ContextIR = { schemaVersion: 1, segments: [] };\ncontextIRToWire(ir);","handlingStrategy":"type-guard","validationCode":"if (ir.schemaVersion !== 1) {\n  throw new Error(`Unsupported ContextIR schema ${ir.schemaVersion}; regenerate with a v1-compatible library`);\n}","typeGuard":"const isV1IR = (ir: { schemaVersion?: unknown }): ir is ContextIR => ir.schemaVersion === 1;","tryCatchPattern":"try {\n  const wire = contextIRToWire(ir);\n} catch (err) {\n  if ((err as Error).message === \"cave_context_ir_unknown_schema\") {\n    console.error(\"ContextIR schema version mismatch; rebuild the IR or align package versions\");\n  } else throw err;\n}","preventionTips":["Pin matching versions of packages that produce and consume ContextIR","Check schemaVersion before serializing IRs restored from persisted caches","Invalidate cached IR data after upgrading the library"],"tags":["serialization","schema","versioning"],"backgroundTag":"schema-version-mismatch","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}