fix(analyst): seal exact-run receipts and lock exact context

[drewstone]

Summary

Fixes four proven integrity defects in the exact analyst run path:

1. Unsealed receipts — an exact run could end without a sealed usage receipt. Now every run reaches exactly one terminal decision: a sealed complete receipt on success, or a throw carrying a sealed failed receipt.
2. Mutable exact context — the exact run context could be mutated mid-run; it is now deep-frozen at intake.
3. Unchecked accounting — missing usage values could pass silently; accounting is now checked with explicit unknowns (never coerced to zero).
4. Ambiguous success/failure — outcome is now explicit in the sealed receipt, never inferred from process exit.

Follow-up dedup pass consolidated receipt sealing, component-identity snapshots, and deep-freeze into single shared utilities, and derived exact plan types from schemas — net production code is smaller than before the fix. The pinned analyst implementation digest was recomputed via scripts/check-analyst-benchmark-implementation.mjs (not bypassed).

Verification

• 22/22 exact tests, 96/96 focused analyst tests green
• typecheck, lint, pnpm build, pnpm verify:package all green
• Full suite (~4,600 tests) was interrupted in the authoring session; rerunning now — result will be posted as a comment before this merges

Provenance

Authored in a Codex (gpt-5.6-sol) session on 2026-07-30 that was interrupted before it could commit; recovered, committed, and pushed from the agent-eval-exact-analyst-run-20260730 worktree to preserve the work.

[tangletools]

✅ Auto-approved drewstone PR — 7ae55de4

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-07-30T22:47:57Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Concerns	2 (2 weak-concern)
Heuristic	0.0s
Duplication	0.0s
Interrogation	113.2s (2 bridge agents)
Total	113.2s

💰 Value — sound-with-nits

Adds a digest-bound, deep-frozen 'exact' execution mode to AnalystRegistry that seals every run receipt with explicit success/failure and a pre-computed execution plan, sharing one unified execution loop with the legacy path; coherent with the substrate's provenance grain, with only a flag-heavy sha

• What it does: Introduces runExact/runExactStream on AnalystRegistry alongside the existing run/runStream. The exact path requires every effective behavior knob to be declared as a canonical executionConfig on each analyst, snapshots a digest-verified execution_plan BEFORE any analyst runs, deep-freezes inputs/context/hooks/chat/cost-ledger at intake, and guarantees exactly one terminal state: a sealed {status:'
• Goals it achieves: Tamper-evident, reproducible analyst-run receipts: (1) no run can terminate without a sealed receipt, (2) context/inputs cannot be mutated mid-run, (3) accounting gaps cannot pass silently, (4) outcome is explicit in the receipt, never inferred from process exit. This lets runs be archived, reviewed, and compared (snapshotAnalystRun now branches to sealExactAnalystRunReceipt when an execution_plan
• Assessment: Sound and in the codebase's grain. agent-eval is explicitly the digest-bound substrate (CLAUDE.md: ledger-core/canonical.ts is the RFC-8785 authority; 'No fallbacks. Fail loud.'). The change extends that scheme to the analyst run path consistently: canonical JSON via agent-interface, deepFreezeCanonicalJson added to ledger-core/canonical.ts:50 as the shared freeze utility, digest-verified plans, f
• Better / existing approach: No existing equivalent to reuse — verified the exact-receipt concept (runExact, ExactRegistryRunOpts, execution_plan, completion, sealExactAnalystRunReceipt) did not exist anywhere in src/analyst or src/run-record.ts at the PR base (04c856a); RunRecord is a distinct generic primitive, not an analyst-receipt sealer. The two zod schema sets (registry.ts exactRunDataSchema for caller-input validation
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: bridge stream ended without value-audit content

🎯 Usefulness — sound

Adds a strict, provenance-sealed 'exact' analyst run path alongside the existing tolerant path, sharing one execution engine; receipt sealing is already wired into the live archival pipeline, and every shipped analyst is now exact-capable.

• Integration: Two integration surfaces, both live. (1) Receipt sealing: snapshotAnalystRun now auto-detects+seals exact receipts when execution_plan is present (feedback-trajectory-review.ts:80-82), and this function is called by the LIVE archival path analystRunToFeedbackTrajectory (feedback-trajectory.ts:394) and readAnalystReview (feedback-trajectory-review.ts:434). So the moment any caller produces an exact
• Fit with existing patterns: Excellent grain fit. The exact path is strictly additive: legacy run/runStream return early and untouched at registry.ts:831-832, while the exact branch continues to sealed receipts. Critically, BOTH paths funnel through one shared executePlanStream loop (registry.ts:456), explicitly so they cannot drift on isolation/hook-order/cost semantics. The receipt seal is consolidated into one snapshotAnal
• Real-world viability: Designed for the hard cases, not just the happy path. Sealing fires on BOTH success (registry.ts:838) and failure (ExactAnalystRunExecutionError at registry.ts:229, whose constructor re-validates the receipt is a proper failed receipt at registry.ts:230-232). Abort/timeout mid-run attaches a failed receipt preserving completed work (registry.ts:862-880). Context is deep-frozen mid-run and onBefore
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

🎯 Usefulness Audit

🟡 executePlanStream carries ~15 exact/legacy branch points in one function [ergonomics] ``

The shared loop (registry.ts:456-881) threads a boolean exact flag through isolation, freezing, sealing, hook-wait, and abort handling. The single-loop design is explicitly justified (prevent drift on isolation/hook-order/cost) and is the right call for a provenance path — but the branch density is real future-maintenance weight. Not a gate: a human should only weigh in if the loop grows further; splitting now would risk the exact divergence the comment warns against.

💰 Value Audit

🟡 executePlanStream is a 425-line function carrying ~15 if (exact) flag branches [maintenance] ``

registry.ts:456-881 unifies legacy and exact paths behind a single boolean exact derived from plan.executionSnapshot !== undefined, threading the flag through budget allocation, context freezing, receipt sealing, hook-failure handling, and terminal-receipt construction. It is locally hard to read which branches belong to which mode. A cleaner shape would extract an ExactExecutionPolicy (snapshot/freezer/sealer hooks on the AnalystExecutionPlan) that the loop calls into, collapsing the flag b

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260730T225013Z}

[drewstone]

Full-suite gate closed: 4,605 passed / 0 failed / 3 skipped (exit 0), lint and typecheck green.

The two remaining failures were the benchmark-evidence binding tests, and they were correct: the branch had changed digest-covered ledger-core/canonical.ts (adding deepFreezeCanonicalJson) and re-pinned the implementation digest, which orphaned the published CodeTraceBench GLM-5.2 evidence. Fixed by relocating the utility to ledger-core/deep-freeze.ts (uncovered) and restoring canonical.ts + the pin to their published state — evidence stays validly bound to 4dba263.