#24 docs: split the content.fetch issuer contract to the per-doc budget

[gregoryfoster]

Closes #24.

docs/contracts/content-fetch-issuer-contract.md was 14,772 tokens against the 10,000 per-doc budget — the last live doc over it after #22, and the one most likely to be read by an agent working in a sibling repo, which is where an over-budget file does the most damage.

Two commits

1. Promote the fact schemas out of the request-options subsection. There was no heading between ### Request options and ## What the issuer MUST do, so both wire schemas — BlobAvailableEvent and FetchFailedEvent — were structurally nested under a subsection about headers and timeout_seconds. The issue's split table read that heading tree faithfully; following it would have relocated the schemas into a lookup annex. Fixed first, verbatim, on its own.

That also corrects the issue's arithmetic: ### Request options proper is 49 lines / ~1,562 tokens (10.6%), not the 168 lines / 29% the heading span suggested.

2. The split. Measured per-section, the core as the issue scoped it came to 10,911 — over budget with request options, the taxonomy, provenance and the Settled section all removed. So the cut goes further.

File	Tokens	Contents
content-fetch-issuer-contract.md (path unchanged)	14,772 → 9,966	The frame, the payload shapes, the seven MUSTs, the guarantee / non-guarantee pair
content-fetch-issuer-reference.md (new)	7,349	Refusal list, enriched-field reasoning + the #17 conditional-GET trap, failure taxonomy, the four silent conditions, reading the DLQ, provenance and trust, version history, envelope-key rationale, pacing at deployed defaults
docs/plans/2026-07-31-fetch-failed-fact-settled.md (new)	—	The resolved silence-as-failure question. Archival, so outside the measured surface

Both contract files are normative. A rule did not become advisory by moving.

The linked path stays the core, not a stub. A stub would cost every issuer-side agent a second read to reach the MUSTs, which is the cost the split exists to remove.

Verification

• prove-no-loss.sh --base d4a5e02 — 471 of 475 lines verbatim. The four exceptions are the intra-document pointers whose referent moved (see the taxonomy below, the refusal table above); the move itself disproved them and they are now cross-file links.
• Every live doc under 10,000. AGENTS.md 5,896 of 6,000.
• No dead links, no orphans, every anchor resolves.
• uv run pytest 444 passed · uv run ruff check . clean.
• Manifest updated and codebase_context_index re-run in the same change (Consume content.fetch-policy — replace the single env default with Watcher's per-host numbers (cannobserv#285) #19 CR A body-less 304 dead-letters — make "not modified" a first-class outcome before conditional GET is usable #17).
• Telemetry row recorded.

Cross-repo

CannObserv/watcher#241 notified, per the contract's own announcement rule — the failure taxonomy moved, so the rule fired. CannObserv/watcher#241 (comment)

Refs updated

AGENTS.md (Detail Docs + the Bus Conventions signpost), README.md, docs/ARCHITECTURE.md, docs/COMMANDS.md, docs/contracts/replicator-boundaries.md, src/core/errors.py — its docstring names the file for the taxonomy specifically, which is now the reference.

🤖 Generated with Claude Code