fix(mcp): make truncation and receipt evidence honest

[rickylabs]

Summary

Fixes the two existing MCP correctness defects identified by RFC #1123 S-13b/S-15: central truncation reports every applied cap honestly and diagnostic receipts settle only after a tool result is validated and safely bounded.

Closes #1134

Part of #1126.

Scope

• Archetype / area: Archetype 2 · packages/mcp · tooling
• Receipt lifecycle ordering in the existing runner/CLI composition seam
• Central truncation metadata propagation and a fixed result-level UTF-8 byte ceiling
• Existing MCP-A6-V2-SHAPE debt remains adjacent and untouched

Slices

• Harness research, locked design, and PLAN-EVAL — 5192b07a9, 0ade6736a
• Receipt settlement after validation + failure fixture — f00d6338e
• Central truncation metadata + byte ceiling fixtures — 8a0314931
• Separate-session IMPL-EVAL and final evidence — 3d328c507

Acceptance evidence

#1134

• gate: fixture — a flow returning invalid output leaves a failed (not green) receipt — invalid MCP tool output replaces stale green evidence with a failed receipt
• gate: fixture — a flow returning 75 rows cannot reach the client as 50 rows with truncated: false — 75 rows cannot become 50 rows with false truncation metadata

Validation

targeted truncation + receipt + doctor: ok | 20 passed | 0 failed
full packages/mcp suite: ok | 66 passed | 0 failed
scoped check: 68 files, 0 occurrences
scoped lint: 68 files, 0 occurrences
scoped format: 68 files, 0 findings
deno task quality:gate: exit 0
doc:lint --root packages/mcp: 2 entrypoints, 0 diagnostics

• No new deno-lint-ignore, as unknown as, or @ts-ignore.
• Whole-result output is bounded after recursive caps by a fixed 65,536-byte UTF-8 ceiling — ResultByteLimitError and fixture.
• No public export-map/type-surface change; publish dry-run/JSR audit therefore N/A.
• No deno.lock churn.
• e2e:cli not run, per orchestrator direction for this non-release slice.

Harness

• Run dir: .llm/runs/fix-mcp-truncation-receipt-ordering--s8/
• PLAN-EVAL: PASS (0ade6736a)
• IMPL-EVAL: PASS (3d328c507)
• Orchestrator retains merge authority; this PR must not self-merge.

Drift / Debt

• Minor location clarification: withReceipt is in cli.ts; output validation is in mcp-server.ts.
• Evaluator transport retries produced no verdict/source change; final guarded Qwen parent-only pass is authoritative.
• Existing MCP-A6-V2-SHAPE debt is unchanged; no new architecture debt.

Definition of Done

• Invalid tool output leaves a failed receipt, never a green or stale-green receipt for the new attempt.
• Receipt success commits only after output validation, central bounding, and revalidation.
• A 75-row result capped to 50 cannot reach the client with truncated: false.
• Existing boolean truncation metadata propagates descendant caps without inventing schema properties.
• Irreducibly oversized bounded output fails the fixed UTF-8 result ceiling before response/green receipt.
• Targeted fixtures, full MCP tests, scoped check/lint/fmt, and the Archetype-2 framework gate pass.
• Public exports, MCP v2 shapes, adjacent debt, and deno.lock remain unchanged.
• Separate-session IMPL-EVAL returned PASS with no findings.
• PR has type:fix, area:tooling, epic:openapi-mcp, exactly one current status:, and milestone 0.0.5.
• Closes #1134 is present only after both authoritative fixture boxes and all DoD boxes are truthfully complete.

[rickylabs]

[PHASE: RESEARCH]

Re-baseline confirmed #1134's two defects unchanged at origin/main@fb75cf6f.

Findings

1. Central array caps do not propagate an existing truncated flag and there is no serialized-result byte ceiling.
2. withReceipt persists before runner output validation; throws bypass persistence and can leave stale-green evidence.
3. The public two-entrypoint surface is doc-lint clean and can remain unchanged.
4. Adjacent MCP-A6-V2-SHAPE debt is explicitly untouched.

Evidence: .llm/runs/fix-mcp-truncation-receipt-ordering--s8/research.md.

[rickylabs]

[PHASE: PLAN]

Plan & Design are ready for the hard Plan-Gate.

Locked decisions

• Runner-owned post-validation/post-bound receipt settlement through an internal callback seam.
• Failed receipts for flow failures, throws, invalid output, and byte-limit failures.
• Existing truncated metadata flips when a descendant is centrally capped.
• Fixed internal UTF-8 byte ceiling; no public TruncationPolicy or export-map change.
• Two independently evidenced implementation slices.

Gates

Full RFC S-20 Archetype-2 column, targeted fixtures/package tests, scoped check/lint/fmt wrappers, and deno task quality:gate. No e2e:cli.

Next: separate-session local open-model PLAN-EVAL. No package source edit before PASS.

[rickylabs]

[PHASE: PLAN-EVAL] [VERDICT: APPROVED]

Separate local formal evaluator: Claude Code + OpenRouter / qwen/qwen3.7-max · high.

All eight Plan-Gate checklist items passed. The evaluator spot-checked both baseline defects, found no unresolved decision that would force rework, approved the full RFC S-20 Archetype-2 gate disposition, and authorized both implementation slices.

Tracked verdict: .llm/runs/fix-mcp-truncation-receipt-ordering--s8/plan-eval.md at 0ade6736a.

[rickylabs]

[PHASE: IMPL]

Both locked implementation slices are complete and pushed.

Slice 1 — f00d6338e

• Receipt settlement moved behind runner validation/bounding/revalidation.
• Flow errors, throws, invalid structured output, and semantic status: fail settle failed evidence.
• Focused evidence: 16 passed | 0 failed across receipt/doctor fixtures.

Slice 2 — 8a0314931

• Recursive central bounds now propagate caps into existing boolean truncated metadata.
• Fixed 65,536-byte UTF-8 post-bound ceiling rejects irreducibly oversized results.
• Full MCP evidence: 66 passed | 0 failed; scoped check/lint/fmt: 68 files, zero findings.

deno task quality:gate exited 0. Public exports, deno.lock, MCP v2 registration shapes, and prohibited ignores/casts are unchanged.

[rickylabs]

[PHASE: IMPL-EVAL] [VERDICT: PASS]

Separate guarded local evaluator: Claude Code + OpenRouter / qwen/qwen3.7-max · high, parent-only open-model turn.

The evaluator independently verified receipt ordering, honest 75→50 truncation metadata, the UTF-8 byte ceiling, unchanged public/lock/debt surfaces, all targeted/static/framework gates, and returned no findings.

Quoted evidence:

ok | 66 passed | 0 failed
scoped check: 68 files, 0 occurrences
scoped lint: 68 files, 0 occurrences
scoped format: 68 files, 0 findings
quality:gate: exit 0
doc:lint: 2 entrypoints, 0 diagnostics

Tracked verdict: .llm/runs/fix-mcp-truncation-receipt-ordering--s8/evaluate.md at 3d328c507.