JuliusBrussee/caveman · error · Error

invalid Decision Ledger response

Error message

invalid Decision Ledger response

What it means

`caveman why <decision-id>` shells out to the local proxy (`proxyExec(["native-why", "--decision", id])`) and parses stdout as JSON. The response must carry schema `caveman.native.why.v1`, a decision_id equal to the requested one, and an object-typed input_basis. Any mismatch — or a JSON.parse failure — is reported as an invalid Decision Ledger response and the command exits 1.

Source

Thrown at packages/cli/src/index.ts:13756

  line("unresolved assumptions", String(receipt.policy.unresolved_assumptions ?? 0));
  console.log("\nClaim status");
  line("compression reduction", receipt.claim_status.compression_reduction ?? "not_attested");
  line("task savings", receipt.claim_status.task_savings ?? "not_verified");
}

function nativeWhy(argv: string[]) {
  const json = argv.includes("--json");
  const decisionID = argv.find((arg) => !arg.startsWith("--"));
  if (!decisionID || !/^dec_[0-9a-f]{24}$/.test(decisionID)) {
    console.error(`usage: ${invokedAs()} why <decision-id> [--json]`);
    process.exitCode = 2;
    return;
  }
  let explanation: NativeWhy;
  try {
    const parsed = JSON.parse(proxyExec(["native-why", "--decision", decisionID], process.env, false)) as NativeWhy;
    if (parsed?.schema !== "caveman.native.why.v1" || parsed.decision_id !== decisionID || typeof parsed.input_basis !== "object") {
      throw new Error("invalid Decision Ledger response");
    }
    explanation = parsed;
  } catch (error) {
    if (process.exitCode) return;
    console.error(`caveman why: ${(error as Error).message}`);
    process.exitCode = 1;
    return;
  }
  if (json) {
    print(explanation);
    return;
  }
  const line = (label: string, value: string) => console.log(`  ${label.padEnd(22)} ${value}`);
  console.log(`Decision ${explanation.decision_id}`);
  line("session", explanation.session_id);
  line("action", explanation.action);
  line("reason", explanation.reason);
  line("input basis", JSON.stringify(explanation.input_basis));

View on GitHub (pinned to 5184b3d11a)

Solutions

1. Confirm the decision id matches ^dec_[0-9a-f]{24}$ and originates from this environment's ledger
2. Upgrade CLI and proxy together so both speak schema `caveman.native.why.v1`
3. Run the proxy command directly (`<proxy-bin> native-why --decision <id>`) and inspect the JSON to see which field mismatches
4. Use `--json` to view the raw payload and distinguish parse errors from schema mismatches

const idOk = /^dec_[0-9a-f]{24}$/.test(decisionID);
if (!idOk) throw new Error('decision id must be dec_ followed by 24 hex chars');

const isNativeWhy = (v: unknown, id: string): v is NativeWhy =>
  typeof v === 'object' && v !== null &&
  (v as NativeWhy).schema === 'caveman.native.why.v1' &&
  (v as NativeWhy).decision_id === id &&
  typeof (v as NativeWhy).input_basis === 'object' &&
  (v as NativeWhy).input_basis !== null;

try {
  const parsed = JSON.parse(proxyExec(['native-why', '--decision', id], env, false));
  if (!isNativeWhy(parsed, id)) throw new Error('invalid Decision Ledger response');
} catch (e) {
  // distinguish JSON.parse failure (stdout pollution) from field mismatch (version skew) before reporting
  console.error(`caveman why: ${(e as Error).message}`);
  process.exitCode = 1;
}

When it happens

Trigger: Version skew where the installed proxy emits a different schema version or shape; proxy stdout polluted by warnings/logs so parsing or field checks fail; requesting a decision id the proxy does not know so the returned decision_id differs; proxy binary missing so proxyExec itself fails.

Common situations: CLI upgraded but the local proxy/daemon still old (or vice versa); multiple caveman installs shadowing each other on PATH; decision ids copied from another environment's ledger; proxy started with verbose logging that writes to stdout.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• recent stats was not a JSON array
• sync incomplete — ${failures.join("; ")}
• Qwen routed profile is missing ${key}
• cave_stale_lock:${checked.stale.join(",")}: run npm run buil
• cave_live_eval_sandbox_profile_invalid

AI-assisted analysis of JuliusBrussee/caveman@5184b3d11a (2026-08-18). Data as JSON: /api/errors/43987809028dcc98. Report an issue: GitHub.