canon(principles): add partial-data-with-transparency-and-background-warm + graduation ledger

[klappy]

Summary

Adds canon/principles/partial-data-with-transparency-and-background-warm.md as a tier-2 canon principle, plus the session graduation ledger at odd/ledger/2026-04-24-aquifer-session-principles-graduated.md.

The principle: The user-blocking path never pays the full cost of an expensive corpus scan. Return whatever the system has already observed, disclose the missing portion concretely, schedule the remaining work in the background via ctx.waitUntil. The next request finds the cache warmed. This inverts the common instinct that "scan the full corpus, then respond" is the correct architecture. The correct architecture is "respond now with what is available, warm in the background, honor the user's time as the bottleneck."

The operator stated the principle verbatim during the aquifer-mcp J-002 → H11b session as the reason to reject H11's framing and pivot to H11b.

Three Deciding-Argument Recurrences

1. refreshAndUpdateCurrentIndex in aquifer-mcp src/registry.ts — implicit prior art; composite-SHA-staleness check already used this architecture before the principle was named.
2. H11b architecture rejection and redesign (PR feat(entity): H11b — partial data with transparency + background warm aquifer-mcp#20) — operator named the principle verbatim as the reason to reject H11's build-time-scan framing. H11b implemented it via FanOutEntityResult, formatPartialFanOutNote, and warmEntityIndexesForResources under ctx.waitUntil.
3. The operator-reframe at 2026-04-24T03:20Z that surfaced manual enforcement across PRs Fix acronym search: add acronym-aware indexing, scoring, routing, and auto-rebuild #17–Add canon: irreversibility, finite capacity, and double diamond #20 as deciding-argument recurrences and produced this canon promotion. Meta-level deciding argument for graduation itself.

Live Validation Evidence

2026-04-24T02:43Z probe against aquifer-mcp post-H11b:

• entity:Obadiah first visit: 985ms, partial=true, "0/33 indexed, 33 warming". ctx.waitUntil(warmEntityIndexesForResources) scheduled.
• entity:Obadiah 20s later: 1094ms, 78 matches, partial=true, "28/33 indexed, 5 warming". Background warm populated 28 of 33 per-resource entity indexes during the interval.
• entity:Onesimus cold: 1347ms, 73 matches, partial=false. Shared amortization from Obadiah's warm — any entity in those 28 warmed resources is servable complete without fresh scan.

Architecture worked exactly as the principle names it.

Writing Canon Checklist

• Title test — names concept and stance.
• Blockquote test — full compressed argument; independently actionable.
• Metadata test — frontmatter schema compliance.
• Summary test — ## Summary — Move The Scan Off The User-Blocking Path, Not To A Different Time is self-contained.
• Header scan test — headers tell the document's argument in sequence.
• No buried claims — every key assertion present at a higher tier.
• Axiom space test — amplifies Axiom 4 + Vodka Architecture principle.
• Ghost writer test — em-dash density 0.31 vs reference 0.24 (within tolerance); no formulaic transitions.

Release-Validation-Gate Disposition

Same reasoning as the sibling PR (canon add, ambiguous under Rule 2's worker-surface trigger list, defaulting to load-bearing per gate's ambiguity clause). Bugbot will be waited for; fresh-context Sonnet 4.6 validator dispatched before merge; findings dispositioned in closeout comment.

Companion Artifacts

• Sibling PR canon(principles): add type-contract-plus-adversarial-review #136: feat/canon-type-contract-plus-adversarial-review graduates the first principle. The two PRs cross-reference each other by URI; URIs resolve once both merge.
• The graduation ledger on this PR records the full arc: handoff received from prior session, fresh-context validation against strict letter of the graduation test flagged the count as narrow, operator reframe to manual-enforcement reading, two principles graduated, one (observe-before-you-fix-the-wrong-axis) held.

Not In Scope

• observe-before-you-fix-the-wrong-axis — one explicit recurrence only; held.
• aquifer-mcp project carry-forwards remain at the source project.

---

Note

Low Risk
Low risk: adds new canon/ledger markdown documents only, with no runtime code or behavior changes.

Overview
Adds a new tier-2 canon principle, partial-data-with-transparency-and-background-warm, formalizing the pattern of returning honest partial results while scheduling expensive corpus scans in the background (e.g., via ctx.waitUntil) and providing concrete completeness disclosure.

Adds a new odd/ledger entry documenting the fresh-context validation and promotion rationale for graduating this principle (and cross-referencing the sibling type-contract-plus-adversarial-review graduation), including the manual-enforcement-based recurrence count used to clear the canon graduation bar.

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

[klappy]

Closeout — Release-Validation-Gate Disposition

Rule 1 — Bugbot

Original commit 7a6b92a: Bugbot completed conclusion=success, 0 findings. Satisfied.

Follow-up commit f0750f3 (validator fixes): Bugbot re-running. Will not merge until completed.

Rule 2 — Independent Fresh-Context Validator

Dispatched Sonnet 4.6 validator via Managed Agents (session sesn_011CaMtUHrKD7aPxpRj1rzDE) against commit 7a6b92a. Validator was scoped to review both the canon doc AND the session ledger shipped in this PR.

Verdict: PARTIAL — 0 blockers, 5 warnings (2 on canon doc, 2 on ledger, 1 methodology note). All findings dispositioned.

Warnings — File A: canon/principles/partial-data-with-transparency-and-background-warm.md

W-A1 — Em-dash density methodology

• Validator: "Per-line density 0.674; per-sentence ~0.29. Methodology not stated. Operative signal per constraint is paragraph clusters, not ratios. Only 1 genuine narrative cluster found (Para 5)."
• Disposition: Waived. The validator's own analysis demonstrates that the ai-voice-cliches constraint's operative signal is paragraph clusters, not a ratio — and only 1 narrative cluster was found in this 96-line doc, within tolerance. The PR body's 0.31 vs 0.24 claim was a loose comparative heuristic; the cluster-based analysis is the canonical check and it passes. No doc change needed.

W-A2 — Negation parallelism in "What This Principle Does NOT Say"

• Validator: "Four consecutive **It does not say...**. 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."
• Disposition: Waived. Validator explicitly concluded this is structural canon language, not the AI-tell pattern. Established canon precedent (contract-governs-handoff-drift, cache-fetches-and-parses) uses the same section structure.

W-A3 — Forward reference to type-contract-plus-adversarial-review

• Validator: "Not on main, not on this branch. Will land via PR canon(principles): add type-contract-plus-adversarial-review #136. The PR body and File A body both acknowledge this. Already documented forward reference."
• Disposition: Acknowledged. Resolves on PR canon(principles): add type-contract-plus-adversarial-review #136 merge, which precedes this PR's merge in the plan.

W-A4 — ## Related Canon + ## See Also partial overlap

• Validator: "Non-standard Writing Canon structure (progressive disclosure prefers single related-content section)."
• Disposition: Waived — established canon precedent. Both sections appear in contract-governs-handoff-drift, cache-fetches-and-parses, and release-validation-gate — all three are sibling tier-2/tier-1 canon docs in the same directory. The convention is: Related Canon = narrative cross-references with explanation; See Also = structured pointer list to primary evidence (recurrences, incidents). Different purposes, not overlap.

(Fix applied) The derives_from frontmatter had the same ledger-forward-reference issue flagged on sibling PR #136 (though neither validator flagged it here because the ledger DOES exist on this branch). Removed in f0750f3 for epistemic consistency: the canon principle does not derive from the session ledger documenting its graduation.

Warnings — File B: odd/ledger/2026-04-24-aquifer-session-principles-graduated.md

W-B1 — session_span format non-conforming with schema examples

• Validator: Schema shows "YYYY-MM-DD closed" or "YYYY-MM-DD to YYYY-MM-DD"; ledger had just "2026-04-24".
• Disposition: Fixed in f0750f3. Updated to "2026-04-24 closed". By the time this ledger lands on main, the graduation work is complete; "closed" is the accurate state.

W-B2 — Forward references in ledger Related Canon not labeled as such

• Validator: "Low priority. Optional: add (forward ref — PR #X) annotations."
• Disposition: Waived — low priority, self-resolving. The ledger's ## The Canon PRs section explicitly discloses which PRs carry which docs. Once both PRs merge (the plan), the forward-reference nature becomes historical context, not a live caveat. Annotating them now would create text that needs removal after merge.

All Other Checks — Passed

Per validator report:

• Frontmatter schema (both files): PASS — zero type violations, all universal + audience-specific fields present.
• Writing-canon Tiers 1–4 (both files): PASS.
• Recurrence 1 (refreshAndUpdateCurrentIndex in aquifer-mcp src/registry.ts): VERIFIED live against source — function exists, calls ctx.waitUntil(refreshAndUpdateCurrentIndex(...)) on SHA-staleness.
• Recurrence 2 (H11b, PR feat(entity): H11b — partial data with transparency + background warm aquifer-mcp#20): VERIFIED — all claimed symbols confirmed in PR body and source; operator verbatim quote confirmed.
• Recurrence 3 (operator reframe): prior-session-attestation; ledger is source record; internally consistent.
• Live validation numbers (985ms / 0-of-33, 28/33 warmed, etc.): prior-session-attested, not independently re-verifiable, no contradiction.
• All cross-references resolve except forward refs to sibling PR (known + planned).

Rule 3 — Canon Wins

Same disposition as PR #136: operator reframe produced canon promotion; no session-artifact recommendation is being overridden.

Validator session references

• Session: sesn_011CaMtUHrKD7aPxpRj1rzDE
• Agent: agent_011CaMtUGN1x4hP2p1oqx8DZ
• Model: claude-sonnet-4-6
• Environment: env_016RffZyqSdHeb5s3Z6UABw8

Merge plan

Merge after PR #136 lands so all URI cross-references resolve at the moment the ledger goes live.