canon: graduate cache-fetches-and-parses to tier-2 principle (P1.3.3 Phase 1)

[klappy]

Graduates the "cache fetches and parses, not microsecond derivations" pattern to canon as a tier-2 principle after its third deciding-argument recurrence across the oddkit tool sweep.

Why now

Three recurrences, per the graduation test:

1. Implicit (0.19.0, P1.3.1) — challenge cachedBasePrerequisites caches parse product. Natural decision, principle not yet named.
2. Explicit (0.20.0, P1.3.2, D9) — gate rejects the mirror-cache-this-too pattern for the BM25 transition index. Operator names the argument directly. First time the principle is load-bearing for a decision.
3. Explicit (0.21.0, P1.3.3) — challenge cachedChallengeTypeIndex removal applies D9 to a second tool. Second explicit application; graduation test satisfied.

The graduation test is three decision points where the principle is the reason, not three appearances of the pattern. Appearances are evidence; decisions are graduation.

What the doc says

• Cache parse products — fetches, table parses, stemmed vocabulary Sets. Four attestation points enumerated (0.18.0 encode types, 0.19.0 base prereqs, 0.20.0 gate stemmedTokens, 0.21.0 challenge stemmedTokens).
• Don't cache microsecond derivations — BM25 indexes over small parse products, regex compilations from literal lists, Set rebuilds from cached arrays. Two attestation points (gate 0.20.0 D9, challenge 0.21.0).
• The plumbing tax — four hidden costs avoided by rebuild-per-request: module-level state, URL-keyed invalidation, cleanup_storage wiring, drift risk when source data changes.
• Trade-off / threshold — rule-of-thumb anchored to current corpus sizes (6-9 types, 4 transitions, 8 prereqs). Global cachedBM25Index over 524+ canon docs sits on the other side of the threshold; out of scope here; revisit if any tool grows past ~50 entries.

Canon-first sequencing

This canon PR ships before the oddkit code PR that removes cachedChallengeTypeIndex. Same pattern as P1.3.2's Phase 1 canon preceding Phase 2 code (#120 → #118). Merge this; verify retrievable via oddkit_get; then open the code PR.

Writing canon gate

• Blockquote compressed argument: ✓
• Summary section: ✓ ("The Principle Has Two Halves")
• Descriptive headers: ✓ (all seven ## sections tell the story when scanned)

References

• Handoff: klappy://odd/handoffs/2026-04-20-p1-3-3-challenge-revisit
• P1.3.2 ledger (D9 origin): klappy://odd/ledger/2026-04-20-p1-3-2-gate-canary-landed
• P1.3.1 ledger (first recurrence): klappy://odd/ledger/2026-04-20-p1-3-1-challenge-canary-landed

---

Note

Low Risk
Adds a new canon principle document only; no runtime or behavioral code changes.

Overview
Adds a new tier-2 canon principle, cache-fetches-and-parses.md, formalizing guidance to cache expensive fetch/parse work while rebuilding cheap microsecond derivations (e.g., small BM25 indexes) to avoid invalidation/cleanup “plumbing tax.”

The document also records the principle’s graduation rationale (third deciding-argument recurrence) and sets a rule-of-thumb threshold for when caching derived values should be reconsidered as corpus size grows.

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