Round-6 remediation: force provenance binding, honest cache accounting, x-br-build everywhere

2026-08-28

governancecost-attributiondata-protectionobservability

LOCKSTEP TRACEABILITY MATRIX --- api_endpoints: [ "GET /v1/budget (new bare alias of /v1/budget/status)", "GET /v1/usage/summary (+cacheSavedUsd, +routingSavedUsd)", "POST /v1/chat/completions (cache-hit usage body reports HIT; X-BR-Build on all responses)", "POST /v1/chat/completions (route.zdr -> 400 misplaced_compliance_field)", ] sdk_methods_updated: ["budget.get() / budget.get (TS+Py) for the /v1/budget alias"] mcp_tools_updated: ["none — response value/coverage changes only"] ---

What We Built

The two standing blockers from the round-6 audit (both scored 6) were the two items deliberately deferred from the prior wave. This closes them, plus a cross-cutting build-attribution lift several personas flagged.

Provenance binding under evidence_mode:required (compliance, was 6). The governance evidence layer signs and chain-commits a receipt, but provenance _binding_ was sampled at ~7% — so POST /v1/governance/audit/verify returned summary: incomplete for most required-mode requests, and the persona (fairly) read a headline compliance obligation as under-delivered. The sampling seam was in lineage-writer.ts: an allow-path decision fell into the ~0.07 sample rate and dropped its lineage digest. Denials were already exempt (rate 1.0); now a resolved evidence_mode: required/strict requirement is exempt too, so the row binds a non-null lineage digest and verify reaches summary: verified. Content-free, no tamper-evident invariant weakened. (Honest residual: the _streaming_ completion path never captures lineage at all — a broader pre-existing gap, not extended here.)

Honest cache accounting (cost-owner, was 6). Billing already reconciled exactly to the catalog, but a cache HIT was a liar's paradise in the JSON body: prompt_cache_hit_tokens: 0 while the x-br-cache: hit header and cost_usd: 0 said otherwise, and groupBy=model filed hits under a phantom provider/auto. Now the hit body reports HIT token semantics (agreeing with the header), the grouped view attributes the hit to the model that served it, /v1/usage/summary carries cacheSavedUsd + routingSavedUsd rollups, and GET /v1/budget is a bare alias so a payer can reconcile budget against usage.

Build attribution + a compliance footgun. X-BR-Build now stamps every API response (completions, /v1/messages, /v1/explain, /v1/usage, MCP, and 5xx envelopes — stream-safe), so any decision is attributable to a build from its own response. And a ZDR directive misplaced as route.zdr now fails closed with 400 misplaced_compliance_field (it was silently ignored), matching the top-level-key strictness.

Why It Matters

Two of the fixes are the same shape as the observability fix that converted a lying write into an honest 503: make the guarantee real, or don't imply it. evidence_mode: required now actually binds provable provenance; the cache body now tells the truth a header already told. That consistency — a claim the shipped build keeps under adversarial re-probe — is the product's whole thesis.

The Numbers

Closes the two round-6 blockers (compliance 6, cost-owner 6); X-BR-Build

lift flagged by ~half the personas.

New: GET /v1/budget; cacheSavedUsd/routingSavedUsd on the usage summary.
Unit suite 10034 passing, 0 failures.

Competitive Edge

Portkey/OpenRouter expose spend; BR now exposes _provable_ spend and _provable_ compliance — a signed, independently-recomputable provenance record for every request that demanded one, and a cache-savings figure whose body and headers cannot disagree.

Lockstep Checklist

[x] API Routes: new GET /v1/budget; response-value changes on

completions (cache body, X-BR-Build), usage summary (+savings), data protection (route.zdr 400).

[x] TS SDK: budget.get() added.
[x] Python SDK: budget.get added.
[x] MCP / discovery: no tool contract change; X-BR-Build now on MCP responses.
[x] llms / routes: regenerated on build (678 routes).

Open Follow-ups

Streaming completions don't capture provenance lineage (broader gap) — streaming

evidence_mode: required still verifies not_applicable.

Observability cross-task config persistence (writes honest-503 but feature down).
Dashboard frontend cluster (favicon via Cloudflare Worker, sub-cent cost display,

Top-models label) — needs a dedicated dashboard pass + deploy-site run.

Circuit-breaker fast-fail; router 9→10 residuals; /attestation verified:false; PyPI token.