JuliusBrussee/caveman · error · Error

adapter-specific build_sha256 values must differ

Error message

adapter-specific build_sha256 values must differ

What it means

The validator asserts that the two adapter fixtures' build_sha256 values are DIFFERENT (`if (claude.build_sha256 === pi.build_sha256) throw`). Each harness has its own build artifact, so identical hashes mean the fixture was copy-pasted, a placeholder value was reused, or the digest computation is wrong. This is an anti-collapse check complementing the field-equality checks for the shared contract keys.

Solutions

1. Compute the real build artifact hash for each harness separately and put each one in its own fixture's build_sha256.
2. If a fixture was copy-pasted, verify every adapter-specific field (harness, build_sha256, upstream_version) after duplication.
3. If builds genuinely produce identical artifacts, investigate the build pipeline — the adapters should produce distinct build_sha256 values per harness.
4. Re-run the validation script to confirm the hashes now differ.

Example fix

// before (pi-conformance.json)
"build_sha256": "19ca7cd98e52d928f70839a303e48ef3d7d8b0fb84d4ea0725f2a1ef307c98a7"

// after
"build_sha256": "76287b2d2d18e4a69aaae9f7f65a32f9eb34dc4a4bfa24d86d10a5f948a4ed31"

const [a, b] = fixtures;
if (a.build_sha256 === b.build_sha256) {
  throw new Error("build_sha256 identical; recompute per-harness artifact hashes");
}

function hasDistinctBuilds(fixtures) {
  return new Set(fixtures.map(f => f.build_sha256)).size === fixtures.length;
}

try {
  await runValidationScript();
} catch (err) {
  if (err.message === "adapter-specific build_sha256 values must differ") {
    console.error("A build_sha256 was copy-pasted between fixtures; recompute each harness's hash.");
    process.exit(1);
  }
  throw err;
}

When it happens

Trigger: Running the contracts validation script when: build_sha256 in pi-conformance.json was copied from claude-conformance.json (or vice versa) while templating; both fixtures were regenerated with a script that hashed the same artifact; a placeholder/zero hash was pasted into both files; fixtures were merged and one file's distinct hash got overwritten with the other's.

Common situations: Creating a new fixture by duplicating the sibling file and forgetting to swap build_sha256; generating fixtures in CI from a single artifact by mistake; a bot auto-filling missing fields with the previously seen value; a bad sed/replace that normalized both hashes.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• agent conformance mismatch
• agent conformance fixtures must cover claude and pi
• middleware
• unknown adapter failure must preserve original bytes
• canonical span

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

Appendix: source

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

if (claude.harness !== "claude" || pi.harness !== "pi") {
  throw new Error("agent conformance fixtures must cover claude and pi");
}

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)