{"record":{"id":"08165dadc5446e82","repo":"JuliusBrussee/caveman","slug":"unknown-adapter-failure-must-preserve-original-byt","errorCode":null,"errorMessage":"unknown adapter failure must preserve original bytes","messagePattern":"unknown adapter failure must preserve original bytes","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/shared/contracts/scripts/validate-schemas.mjs","lineNumber":82,"sourceCode":"\nfor (const key of [\n  \"normalized_context_digest\",\n  \"plan_sha256\",\n  \"ordered_transform_ids\",\n  \"provider_visible_digest\",\n  \"recovery_handles\",\n  \"accounting_method\",\n  \"failure_fallback\",\n]) {\n  if (JSON.stringify(claude[key]) !== JSON.stringify(pi[key])) {\n    throw new Error(`agent conformance mismatch: ${key}`);\n  }\n}\nif (claude.build_sha256 === pi.build_sha256) {\n  throw new Error(\"adapter-specific build_sha256 values must differ\");\n}\nif (claude.failure_fallback !== \"original\") {\n  throw new Error(\"unknown adapter failure must preserve original bytes\");\n}\n\nconsole.log(\n  `validated ${files.length} JSON schemas and ${fixtureFiles.length} static agent contract fixtures (not executable parity)`,\n);\n","sourceCodeStart":64,"sourceCodeEnd":88,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/shared/contracts/scripts/validate-schemas.mjs#L64-L88","documentation":"Thrown by the shared-contracts validation script when the static agent contract fixture for the Claude adapter does not declare failure_fallback: \"original\". The contract encodes a hard requirement: when an adapter encounters an unknown input, it must pass the original bytes through untouched rather than dropping or transforming them. Any deviation breaks the byte-preservation guarantee the adapter layer promises to callers.","triggerScenarios":"Running packages/shared/contracts/scripts/validate-schemas.mjs (usually via CI or a repo test script) after someone edited the claude fixture JSON so that failure_fallback is missing, set to \"drop\", \"error\", or any value other than the exact string \"original\".","commonSituations":"A developer adds a new fallback mode to an adapter and updates the fixture to match; a merge conflict resolution picks the wrong fixture value; someone regenerates fixtures with a tool that normalizes or omits the field.","solutions":["Open the claude agent contract fixture JSON referenced by the script and set \"failure_fallback\": \"original\".","If you intentionally changed adapter fallback behavior, revert that behavior instead — the contract test is asserting byte preservation on unknown input, which is the intended semantics.","Re-run the validation script to confirm the whole fixture set passes, including the build_sha256-must-differ and conformance-key checks above this throw."],"exampleFix":"// fixtures/claude.json\n// before\n{\n  \"failure_fallback\": \"drop\"\n}\n// after\n{\n  \"failure_fallback\": \"original\"\n}","handlingStrategy":"validation","validationCode":"// Before committing fixture changes:\nconst claude = JSON.parse(readFileSync(\"claude.fixture.json\", \"utf8\"));\nif (claude.failure_fallback !== \"original\") {\n  console.error(\"fixture must keep failure_fallback === 'original'\");\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat the contract fixtures as test assertions, not data — never edit failure_fallback without changing adapter semantics.","Run the validation script in a pre-commit hook or CI job so a bad fixture value is caught before merge."],"tags":["schema-validation","fixtures","contracts","ci"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}