canon(cache-fetches-and-parses): same-URL freshness — the cost the plumbing tax missed

[git-repo-auth]

Draft. Canon text: captain or a canon seat reviews the exact words before merge. Voice is neutral, so a seat may propose; this seat does not merge it.

One file, appended, nothing rewritten (canon/principles/cache-fetches-and-parses.md):

1. The encode paragraph said its cache "invalidates cleanly when canon source changes". True only when the URL changes. Reworded, with a pointer to the new paragraph.
2. New paragraph under the plumbing tax, Same-URL freshness: a URL-keyed parse cache never notices a new commit at the same URL; a kept parse cache must expire no later than the fetch tier beneath it; worst case is the sum of the two limits and gets written down. Carries the 2026-09-21 production observation (old gate parse on 3 of 40 calls, 65 minutes after klappy.dev cb37f62).
3. A dated status note, not a resolution: oddkit 0.23.0 removed the encode parse cache citing this principle, while this document still lists it under "Cache It". Someone with the pen decides which one is right.

Heading text untouched so existing anchors hold. Frontmatter untouched (date stays the authoring date; the amendment is dated inline) — say if house style wants a changelog block here instead.

Receipt: klappy/oddkit#215 (fix + test + A/B reading).

Amended 15:40Z on the captain's word — canon points up, not down: the adopter reference is gone from the file and from this description.

[github-actions]

Canon Quality — Homepage Surfacing ✅

51 essay(s) scanned. Soft report — never blocks; the hard field gate is the Frontmatter Schema job.

All published essays resolve to the homepage feed.

_{Report: scripts/surfacing-report.py · Canon: klappy://canon/constraints/frontmatter-validation-before-merge}

[github-actions]

Canon Quality — Frontmatter Schema ✅

All 51 file(s) in writings/ conform to klappy://canon/meta/frontmatter-schema.

_{Validator: scripts/validate-frontmatter.py · Canon: klappy://canon/constraints/frontmatter-validation-before-merge · Run: #462}

[github-actions]

Canon Quality — oddkit_audit ✅

No dead klappy:// references or legacy link patterns found in writings/. 53 files scanned.

_{Spec: klappy://docs/oddkit/specs/oddkit-audit · Workflow: .github/workflows/canon-quality.yml · Run: #462}

[github-actions]

Canon Quality — P0010 Retrieval-Readiness ⚠️

Soft report for klappy://canon/constraints/retrieval-disclosure-contract. 716 files scanned. Never blocks — informational until the corpus is ready to enforce.

• Blocking-class findings: 19 (structural fields the contract would filter on)
• Warnings: 0 (kind resolves to unknown)
• Informational: 13 (exempt templates/archive/drafts)

Kind distribution: {'essays': 53, 'canon': 252, 'apocrypha': 38, 'docs': 307, 'journals': 60, 'unknown': 6}
Kind source: {'path': 578, 'frontmatter': 132, 'none': 6} (frontmatter-primary, path-secondary)
Default-include visibility: 612 visible, 104 hidden (journals/apocrypha/unknown)

By rule: {'audience-invalid': 4, 'exposure-missing': 7, 'tier-missing': 5, 'tier-invalid': 7, 'fm-missing': 3, 'kind-unresolvable': 6}

These are not schema violations (see the Frontmatter Schema job for those on writings/). They are corpus-readiness signals for the retrieval contract: invalid/missing audience, exposure, tier, and docs whose kind cannot be resolved. Fix in a corpus-cleanup PR before the contract flips to enforcing. See the retrieval-readiness-findings artifact for the full list.

_{Validator: scripts/audit-retrieval-readiness.py · Constraint: klappy://canon/constraints/retrieval-disclosure-contract · Run: #462}