docs: split and compress content-fetch-issuer-contract.md — 14,772 tokens, over the 10,000 per-doc budget

[gregoryfoster]

docs/contracts/content-fetch-issuer-contract.md is 14,772 tokens (exact,
count_tokens) against curating-context's 10,000 per-doc budget. It is the only
live doc in the repo still over it after #22.

Why it matters more than a number

The per-doc budget exists because demotion only removes cost if the destination is
smaller than the thing an agent would otherwise read. This doc is the opposite
case: it is linked from sibling repos (Watcher, Phase 4) as the normative
statement of what a content.fetch producer must do, so an issuer-side agent that
needs one of the seven MUST rules pays 14,772 tokens to reach it. #22 deliberately
demoted nothing into it for this reason.

It is also the doc most likely to be read by an agent that is not working in this
repo — which is exactly the case where an over-budget file does the most damage,
because the reader has no cheaper local surface to fall back on.

Shape of the split

The headings already suggest the seams:

Lines	Section	Audience
40–92	The frame, the payload	anyone constructing a command
92–260	Request options: what Replicator will send, and what it refuses (#11)	168 lines — a reference, not a rule
261–444	What the issuer MUST do (7 numbered rules)	the contract proper
445–492	What Replicator guarantees / does not guarantee	the contract proper
493–558	Failure taxonomy, provenance and trust	reference
559–580	Settled: the fetch_failed fact	historical — resolved, and dated

### Request options alone is 29% of the file and is a lookup table by nature:
an issuer consults it when a header is refused, not while writing its publisher.
The seven MUST rules are the part that must stay in one place and stay short
enough to be read start to finish.

A defensible split is a normative core (frame, payload, the seven rules, the
guarantee/non-guarantee pair) plus one companion reference carrying the request-
options rules and the failure taxonomy. Both under 10,000; the core well under.

Constraints

• Sibling repos link to this path. Watcher and Phase 4 point at
  docs/contracts/content-fetch-issuer-contract.md by name. The existing path
  must keep resolving — either it stays as the normative core, or it becomes a
  stub that routes, but it does not disappear. Whichever is chosen, the sibling
  links need checking before the split lands, and a cross-repo issue if they
  need updating.
• AGENTS.md asserts things about this doc. "Anything asserted there is
  asserted about this repo's code; change one, change both (Document the content.fetch issuer contract: per-occasion command_id, url-is-not-a-key, durable command_id→domain map #8)." Splitting is a
  change to the contract's shape, so the ## Detail Docs index entry and the
  Bus Conventions signpost both need updating in the same PR.
• Compression is not paraphrase. Where the split is a move, move verbatim —
  prove-no-loss.sh --file docs/contracts/content-fetch-issuer-contract.md will
  check it. Revision that genuinely tightens prose is welcome, but it should be a
  visible, separately-justified part of the diff rather than something that
  happens in transit.
• Register and re-embed. The new doc goes in .socraticodecontextartifacts.json
  and codebase_context_index runs in the same change — editing the manifest is
  not what codebase_context_search returns (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).

Verification

bash .claude/skills/curating-context/scripts/measure-context.sh --exact \
  | python3 -c "import json,sys; d=json.load(sys.stdin); [print(x['tokens'], x['over_budget'], x['path']) for x in d['docs']]"

Every live doc under 10,000, no new orphans, no dead links.

Follow-up to #22.

[gregoryfoster]

Review before starting

Goal is sound. Three corrections to the plan, one of which changes the first commit.

1. The section table reads a broken heading structure

There is no heading between line 92 and line 261, so ### Request options structurally
swallows both fact schemas — BlobAvailableEvent (141–211) and FetchFailedEvent
(212–258). The table above is a faithful read of the headings; the headings are wrong.

So "### Request options alone is 29% of the file, and is a lookup table by nature" is
true of the heading span and false of the content. Request options proper is 92–140:
49 lines, ~1,562 tokens, 10.6%.

A split that follows the table would relocate both fact schemas into the companion
reference — backwards, since an issuer consuming content.blobs needs those tables to
write its correlator.

First commit, on its own: promote the two **Fact — …** blocks to ### siblings of
the command table under ## The payload. Structure only, verbatim, no move.

2. The proposed split does not reach 10,000

Per-section, exact count_tokens, normalised to the 14,772 whole-file figure:

Section	~tokens
preamble 1–38	1,044
The frame 40–77	833
command table 78–91	399
request options 92–140	1,562
BlobAvailableEvent 141–211	2,180
FetchFailedEvent 212–258	1,197
the 7 MUSTs 261–443	4,078
guarantees / non-guarantees 445–490	1,180
failure taxonomy 493–526	1,150
provenance and trust 529–556	563
Settled 559–580	586

The core as scoped above — preamble + frame + payload + MUSTs + guarantees — is
10,911. Over budget with request options, the taxonomy, provenance and Settled all
removed. "Both under 10,000; the core well under" is not reachable by the cut described.

What reaches it: move request options + failure taxonomy + provenance + the enriched-field
rationale at 161–210 (the None-means-nobody-said bullets, the per-occasion blockquote,
the conditional-GET/#17 trap — ~1,200 of BlobAvailableEvent's 2,180, leaving the table)
→ core ≈ 10,300. Then relocate ## Settled: the fetch_failed fact (586) to docs/plans/,
which measure-context.sh skips as archival. It is not reference material — it is #9 §3
re-litigated, and both its claims already live in MUST-6 and the non-guarantees.

Compression is not load-bearing for the target under that plan, which keeps it honest per
the constraint above.

3. Path decision, and a cross-repo obligation the issue misses

The core keeps docs/contracts/content-fetch-issuer-contract.md. Not a stub: a stub costs
every issuer-side agent a second read to reach the MUSTs, which is the cost the split
exists to remove. No sibling link breaks, so no cross-repo issue is needed for resolution.

But the doc's own rule at lines 15–18 — "A change to any MUST, or to the failure taxonomy,
is announced on the open issuer-side trackers … in the same change that edits this file" —
fires here. Moving the failure taxonomy is a change to the failure taxonomy.
CannObserv/watcher#241 gets a comment in the same change.

4. In-repo references: six, not two

Beyond AGENTS.md's ## Detail Docs and Bus Conventions — README.md:29,
docs/COMMANDS.md:89, docs/ARCHITECTURE.md:44, docs/contracts/replicator-boundaries.md
:13 and :368, src/core/errors.py:33 (names the file for the taxonomy specifically —
retargets to the companion), scripts/seed_fetch.py:104 (cites MUST-1 — stays with the core).

5. Two fixes to the verification recipe

• The measure command as written fails: measure-context.sh emits INFO lines on
  stdout ahead of the JSON, so the python3 -c pipe dies on JSONDecodeError.
  Needs | sed -n '/^{/,$p' between them.
• prove-no-loss.sh defaults --base HEAD. Across a multi-commit split that compares
  against the wrong revision — pass --base <branch-point> explicitly.

Proceeding on this plan.

[gregoryfoster]

Shipped in #26, merged as afb1f97.

Result

File	Tokens	Margin
content-fetch-issuer-contract.md — path unchanged	14,772 → 9,481	519
content-fetch-issuer-reference.md — new, equally normative	8,668	1,332
docs/plans/2026-07-31-fetch-failed-fact-settled.md — new, archival	—	outside the measured surface

Every live doc under the 10,000 per-doc budget. AGENTS.md 5,896 of 6,000.

Against this issue's constraints

• Sibling links. The path Watcher and Phase 4 point at stays the normative 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. No link needs updating.
• Cross-repo announcement. The doc's own rule (lines 15–18) fired: the failure taxonomy moved, so watcher#241 was notified in the same change. This issue listed only the link-resolution half of that obligation.
• AGENTS.md. Both the ## Detail Docs index and the Bus Conventions signpost updated. Four further in-repo references this issue did not list also needed retargeting: README.md, docs/ARCHITECTURE.md, docs/COMMANDS.md, docs/contracts/replicator-boundaries.md, and src/core/errors.py — whose docstring names the file for the taxonomy specifically, so it follows the taxonomy to the reference rather than the filename to the contract.
• Compression is not paraphrase. prove-no-loss --base d4a5e02: 447 of 475 lines verbatim in place. The 28 unaccounted are all pointers the move itself disproved (see the taxonomy below, the refusal table above, see **The frame**), now cross-file links, plus one dropped duplicate heading — each under an explicit review directive.
• Register and re-embed. 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). Verified by search that issuer-reference actually returns.

Two corrections to this issue's analysis

1. The section table read a broken heading tree. No heading sat between line 92 and line 261, so ### Request options structurally swallowed both wire schemas. Following the table would have relocated BlobAvailableEvent and FetchFailedEvent into a lookup annex. Fixed first, verbatim, in 7cb8e9f. Request options proper is 49 lines / ~1,562 tokens — 10.6%, not the 29% the heading span suggested.
2. The proposed split did not reach 10,000. Core as scoped here measured 10,911 with request options, the taxonomy, provenance and the Settled section all removed. The cut went further: also the enriched-field rationale, the four silent conditions, the DLQ-reading block, the failure-fact notes, version history, the envelope-key rationale, pacing detail, and five MUST mechanisms — every rule stayed in the contract, every mechanism moved.

Review

Two rounds. Round 1 found a 🔴: a slice-based cut swept the No ordering non-guarantee out of the contract into the reference's pacing section, where it dangled under an unrelated heading. prove-no-loss passed it — the check verifies a line exists somewhere, not that it landed in the right place. Worth knowing as a limit of that gate. Fixed in 34c1ed7 along with ten other findings; round 2 found no new defects.

Known limitation

CI is red on this branch and on main, pre-existing since #16: actions/checkout@v5 in .github/workflows/ci.yml fetches no submodules, so the skills-vendor/ symlink that tests/test_skills_hook.py asserts on dangles. 443 of 444 pass in CI; unrelated to this work. Merged per maintainer direction. The fix is submodules: recursive on both checkout steps — both submodules are public, so no credentials are involved.