JuliusBrussee/caveman · error · Error

unknown adapter failure must preserve original bytes

Error message

unknown adapter failure must preserve original bytes

What it means

The validator enforces that both adapter fixtures declare failure_fallback === "original", throwing this error otherwise. This encodes the repo's byte-safety/honesty rule: when an adapter hits an unknown failure it must fall back to emitting the original, untransformed bytes rather than dropping or substituting output. It guards against a fixture (or contract change) that opts an adapter into a lossy or fail-closed-on-output fallback.

Solutions

1. Set failure_fallback back to "original" in both packages/shared/contracts/fixtures/agent/*.json files.
2. If the fallback semantics intentionally changed, update the literal in validate-schemas.mjs (line 81), the adapter-conformance schema enum, and both fixtures together in one coordinated change.
3. Confirm the adapter implementations actually preserve original bytes on unknown failure before encoding any new fallback value.
4. Re-run the validation script to confirm all checks pass.

Example fix

// before (claude-conformance.json)
"failure_fallback": "last_known_good"

// after
"failure_fallback": "original"

const [a, b] = fixtures;
if (a.failure_fallback !== "original" || b.failure_fallback !== "original") {
  throw new Error("failure_fallback must be 'original' in both fixtures (byte-safety rule)");
}

function preservesOriginalBytes(fixture) {
  return fixture?.failure_fallback === "original";
}

try {
  await runValidationScript();
} catch (err) {
  if (err.message === "unknown adapter failure must preserve original bytes") {
    console.error("failure_fallback drifted from 'original'; restore it or coordinate a deliberate contract change.");
    process.exit(1);
  }
  throw err;
}

When it happens

Trigger: Running the contracts validation script when failure_fallback in a fixture is changed to any other string (e.g. "passthrough", "fail_closed", "last_known_good", ""); a refactor renames the enum value in fixtures or schemas without updating the validator; a new fixture is authored with a missing/alternative fallback value that still passes adapter-conformance.schema.json because its enum is looser than this hardcoded check.

Common situations: Editing the failure-handling policy for an adapter and updating fixtures to match; a bulk enum rename across schemas/fixtures that missed this literal "original" comparison; onboarding a new adapter whose fallback design differs and needs the validator (and contract) updated deliberately.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• adapter-specific build_sha256 values must differ
• agent conformance fixtures must cover claude and pi
• agent conformance mismatch
• middleware
• canonical span

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/08165dadc5446e82. Report an issue: GitHub.

Appendix: source

Thrown at packages/shared/contracts/scripts/validate-schemas.mjs:82

for (const key of [
  "normalized_context_digest",
  "plan_sha256",
  "ordered_transform_ids",
  "provider_visible_digest",
  "recovery_handles",
  "accounting_method",
  "failure_fallback",
]) {
  if (JSON.stringify(claude[key]) !== JSON.stringify(pi[key])) {
    throw new Error(`agent conformance mismatch: ${key}`);
  }
}
if (claude.build_sha256 === pi.build_sha256) {
  throw new Error("adapter-specific build_sha256 values must differ");
}
if (claude.failure_fallback !== "original") {
  throw new Error("unknown adapter failure must preserve original bytes");
}

const middleware = JSON.parse(await readFile(path.join(packageRoot, "..", "..", "sdk", "parity", "middleware.fixtures.json"), "utf8"));
for (const [field, schemaName] of Object.entries({ capabilities: "capabilities", request: "optimize", plan: "plan", page: "page" })) {
  const validate = ajv.getSchema(`https://caveman.so/schemas/middleware-${schemaName}.schema.json`);
  if (!validate?.(middleware[field])) throw new Error(`middleware ${field}: ${ajv.errorsText(validate?.errors)}`);
}

console.log(
  `validated ${files.length} JSON schemas and ${fixtureFiles.length} static agent contract fixtures (not executable parity)`,
);

View on GitHub (pinned to 3ee70a1026)