canon(principles): add type-contract-plus-adversarial-review

[klappy]

Summary

Adds canon/principles/type-contract-plus-adversarial-review.md as a tier-2 canon principle. Graduates a paired pattern that was manually enforced across the aquifer-mcp J-002 → H11b session (PRs klappy/aquifer-mcp#17 through #20).

The principle: When a function's correctness depends on reporting its own incompleteness honestly, a type-system contract at the API boundary is necessary but not sufficient. The type forces every caller to acknowledge the incompleteness axis; adversarial review catches the implementation lying about that axis. Either defense alone ships silent-truth-loss bugs. The pair collapses to a single line of defense when the build pipeline bypasses the type system (esbuild transpile-only), at which point adversarial review is the only thing standing between compile and production.

Three Deciding-Argument Recurrences

1. PR fix(entity): bound bootstrap fanout to prevent Worker OOM (closes J-002, J-003) aquifer-mcp#18 — BootstrapEntityResult + 9 Bugbot findings including 3 silent-truth-loss bugs (complete=true could ship under contract-violating conditions). The paired pattern was the reason those bugs did not ship.
2. PR feat(entity): H11b — partial data with transparency + background warm aquifer-mcp#20 — FanOutEntityResult + High-severity ctx ReferenceError that esbuild transpile-only compiled cleanly and would have shipped as production crash on every cold-cache entity search. Bugbot was the sole defense.
3. esbuild-transpile-only boundary condition (J-005 generalization) — orchestrator's load-bearing decision to treat Bugbot as the sole defense (not secondary) across the remaining session PRs. Distinct deciding-argument recurrence because the decision was about the pair itself.

Under the operator's manual-enforcement reading of the graduation test, all three cleared the bar in one session.

Writing Canon Checklist

• Title test — names concept and stance.
• Blockquote test — full compressed argument; independently actionable.
• Metadata test — full frontmatter schema compliance per klappy://canon/meta/frontmatter-schema.
• Summary test — ## Summary — The Pair Is Load-Bearing, Not the Parts is self-contained.
• Header scan test — headers tell the document's argument in sequence, descriptive subtitles throughout.
• No buried claims — every key assertion present at a higher tier.
• Axiom space test — amplifies Axioms 2 and 4; does not crowd them out.
• Ghost writer test — em-dash density 0.30 vs reference 0.24 (20% over, within tolerance); no formulaic transitions; no negation parallelism.

Release-Validation-Gate Disposition

Per klappy://canon/constraints/release-validation-gate:

Rule 1 (no merge with active reviews): will wait for Bugbot to reach completed status; dispositioning every finding before merge.

Rule 2 (independent fresh-context validation): Rule 2's trigger list is scoped to oddkit worker surface (orchestrate.ts, bm25.ts, governance file reads, response envelope). A new canon doc at a new URI is ambiguous under that list. Per the gate's "ambiguous cases default to load-bearing" clause, dispatching a fresh-context Sonnet 4.6 validator via Managed Agents before merge. Validator findings will be dispositioned in a closeout comment on this PR.

Rule 3 (canon wins over session artifacts): the handoff that proposed this graduation recommended promoting only one candidate principle (not two). The operator reframed toward manual-enforcement-as-deciding-argument, which graduated this and the sibling partial-data principle. Canon rule (graduation test) was honored; handoff recommendation was overridden by operator direction; audit trail lives in the graduation ledger on the sibling PR.

Companion Artifacts

• Sibling PR: feat/canon-partial-data-with-transparency-and-background-warm graduates the second principle and carries the session graduation ledger (odd/ledger/2026-04-24-aquifer-session-principles-graduated.md). The two PRs cross-reference each other by URI; URIs will resolve once both merge.

Not In Scope

• observe-before-you-fix-the-wrong-axis — one explicit recurrence only; held for future session graduation.
• aquifer-mcp project carry-forwards (H15 observability monitoring, H16 bootstrap deletion, H12 fan-out audit) remain at the source project.

---

Note

Low Risk
Low risk because this PR only adds documentation and does not change runtime code or behavior.

Overview
Introduces a new canon principle doc, canon/principles/type-contract-plus-adversarial-review.md, which formalizes a paired requirement: typed boundary contracts for partial/failed results plus adversarial review of implementations against those contracts.

The document defines what qualifies as a trust boundary and adversarial review, and records three manual-enforcement recurrences (including the esbuild transpile-only type-bypass case) as justification for graduating the principle.

^{Reviewed by Cursor Bugbot for commit fd6f0ea. Bugbot is set up for automated code reviews on this repo. Configure here.}

[klappy]

Closeout — Release-Validation-Gate Disposition

Rule 1 — Bugbot

Original commit 2c40a8d: Bugbot completed conclusion=success, 0 findings, mergeable_state=clean. Satisfied.

Follow-up commit fd6f0ea (validator fixes): Bugbot re-running. Will not merge until completed with acceptable conclusion.

Rule 2 — Independent Fresh-Context Validator

Dispatched Sonnet 4.6 validator via Managed Agents (session sesn_011CaMtQCYU9xpdUcREMyH6s) against commit 2c40a8d. Validator ran under a clean agent system prompt with full oddkit MCP access, pulled live governance docs, verified claims against GitHub source data, and reported.

Verdict: PARTIAL — 2 blockers, 3 warnings, 6 notes. All findings now dispositioned.

Blockers — Fixed in fd6f0ea

B1 — derives_from forward reference to non-existent ledger file

• Validator: odd/ledger/2026-04-24-aquifer-session-principles-graduated.md listed in derives_from but lives on sibling PR canon(principles): add partial-data-with-transparency-and-background-warm + graduation ledger #137 branch only; not acknowledged as forward reference in PR body.
• Disposition: Fixed. Removed ledger path from derives_from. The canon principle does not epistemically derive from the session ledger documenting its own graduation — direction is reverse. This was a real error; the validator's catch was correct.

B2 — Em-dash density self-report inaccurate (0.30 claimed, 0.34 actual)

• Validator: specific driver was inline 9-field listing on line 67.
• Disposition: Fixed. Restructured the 9-field parenthetical from em-dash to parens. Density now 0.28 (~15% over existing canon baseline 0.24-0.25, previously 20% over). Also operationally aligned with the ai-voice-cliches constraint's actual operative signal (paragraph clusters, not ratios).

Warnings — Waived with Reasoning

W1 — Bold-then-explain pattern (14 instances, 4 sections)

• Disposition: Waived. Established canon precedent. klappy://canon/principles/contract-governs-handoff-drift and klappy://canon/principles/cache-fetches-and-parses both use the same structural pattern at similar density. The pattern is canonical for tier-2 principle docs; flagging it as saturated in one doc while the precedent canon uses it would fork the style without a principle change. If canon voice is to evolve away from this pattern, it should evolve via a writing-canon amendment, not a single-doc rewrite.

W2 — Negation cluster in "Does NOT Say" section (4 consecutive **It does not say X.**) + bold-then-explain

• Disposition: Waived. Validator 2 on sibling PR canon(principles): add partial-data-with-transparency-and-background-warm + graduation ledger #137 independently reached the opposite conclusion on the same structural pattern, noting: "This is a governance scope-limitation structure, not the conversational 'It's not X. It's Y.' AI-tell the constraint specifically names. No conversational negation parallelism was found in the document." Validator 2's reading is the more precise application of ai-voice-cliches — the pattern specifically named there is conversational AI-tell, which this section is not.

W3 — Recurrence 3 unverifiable without ledger

• Disposition: Resolves on sibling PR canon(principles): add partial-data-with-transparency-and-background-warm + graduation ledger #137 merge. The session ledger at odd/ledger/2026-04-24-aquifer-session-principles-graduated.md ships on PR canon(principles): add partial-data-with-transparency-and-background-warm + graduation ledger #137 and contains the Recurrence 3 attestation detail. Once both PRs merge, Recurrence 3 is fully corroborable against the ledger.

Notes — All Verified

• N1 Frontmatter schema: full pass (validator confirmed).
• N2 Writing-canon Tiers 1–4: all pass.
• N3 PR body attestations structurally complete (subject to the above dispositions).
• N4 Recurrences 1 and 2 fully corroborated by validator against GitHub source: 9 Bugbot findings on aquifer-mcp#18 with verbatim match; ctx ReferenceError on aquifer-mcp#20 with exact esbuild diagnosis in finding text.
• N5 All currently-resolvable cross-references resolve on main.
• N6 Typo dispositon → disposition: Fixed in fd6f0ea.

Rule 3 — Canon Wins Over Session Artifacts

The upstream handoff recommended promoting only one principle. The operator's reframe (manual enforcement across session PRs = deciding-argument recurrence) took precedence and produced this canon promotion. The reframe is an operator directive, not a session-artifact recommendation, so Rule 3 is not triggered. Audit trail lives in the graduation ledger on sibling PR #137.

Validator session references

• Session: sesn_011CaMtQCYU9xpdUcREMyH6s
• Agent: agent_011CaMtQAxiNaLfEmpFKnukM
• Model: claude-sonnet-4-6
• Environment: env_016RffZyqSdHeb5s3Z6UABw8
• Full findings: encoded by validator to its session storage

Merge plan

1. Wait for Bugbot re-run on fd6f0ea to reach completed with acceptable conclusion.
2. Merge this PR.
3. Sibling PR canon(principles): add partial-data-with-transparency-and-background-warm + graduation ledger #137 then has no forward references to unmerged work for its canon doc's sibling ref.
4. Sibling closeout + merge follows.