A body-less 304 dead-letters — make "not modified" a first-class outcome before conditional GET is usable

[gregoryfoster]

Flagged as a follow-on by #10 and by cannobserv#271; filed so it is decided
before an issuer sends its first validator header rather than discovered by the
first one that does.

Why

A body-less 304 Not Modified is today a dead-letter outcome. _raise_for_status
(src/worker/handler.py) branches on is_2xx,
not is_success, deliberately — a 304 reports is_success while carrying an empty
body, and storing it would content-address the empty string. Everything non-2xx that
is not 5xx/408/429 becomes a PermanentFetchError with
reason=FailureReason.HTTP_STATUS, so the command closes as
fetch_failed / http_status / status_code=304 and the frame is copied to
content.fetch.dlq.

That is correct today, because nothing sends a conditional request: a 304 arriving
unbidden really is an origin behaving oddly. It stops being correct the moment an
issuer replays a validator, because then the 304 is the single most useful answer
the origin can give — "your bytes are current, here is nothing, you are done" — and
Replicator reports it as a failure with a 304 attached and dead-letters the command.

Both halves of the conditional-GET seam are otherwise in place or in flight:

• Read half — shipped (Emit the enriched BlobAvailableEvent fields (cannobserv#271) #10). blob_available now returns etag and
  last_modified verbatim, so an issuer can store validators without Replicator
  holding any per-URL history.
• Write half — Honour ContentFetchCommand request options: headers, timeout_seconds (cannobserv#272) #11. ContentFetchCommand.headers (co-core ≥ 0.7.3,
  cannobserv#272) replays them as If-None-Match / If-Modified-Since.
• This issue is what happens when the replay succeeds.

docs/contracts/content-fetch-issuer-contract.md currently carries an explicit "do not
attempt conditional GET yet" warning naming all three. This issue is what removes it.

The decision

Two shapes were floated (#10, cannobserv#271). Recommending the first:

A. reason="not_modified", terminal=True, on the existing fetch_failed fact.

• The failure taxonomy already has a row for the body-less 304 (http_status); this
  splits one row into two rather than inventing a category.
• reason is a plain str, not a Literal, precisely so a producer can add a token
  without crashing an older extra="ignore" consumer. The vocabulary is designed to
  grow this way.
• Consumers already branch on terminal first and treat an unknown reason as
  opaque, so an issuer that has not been taught the token still does the right thing:
  closes the pending entry, records a reason it does not recognise. That is a much
  better default than a payload type it cannot dispatch at all.
• No new stream wiring, no new dispatch arm, no from_wire table entry.

B. A dedicated content_unchanged fact. Cleaner naming — "unchanged" genuinely is
not a failure — but it costs every consumer a new dispatch arm for an outcome that is
structurally identical to the others on this stream: no blob is coming, close the
entry. It also needs a co-core model, a ChangeEventPayload union member, an
idempotency_key rule, and a from_wire entry, none of which buy an issuer anything
it cannot get from a token.

The honest cost of A is that fetch_failed is then carrying a non-failure. Worth
stating in the model docstring and in the contract: the event's real meaning is "this
command will not produce a blob", and terminal is the field that matters. If that
naming later becomes untenable, B stays available and additive.

Scope, once decided

• FailureReason.NOT_MODIFIED in src/core/errors.py, raised at the 304 site in
  _raise_for_status — named at the raise site, never recovered from a message string,
  per the convention.
• The reporter carries it through unchanged; status_code=304 still rides along.
• Whether a 304 should still be dead-lettered is the sub-decision worth making
  explicitly. A successful conditional GET is not operator-actionable, so copying every
  one to content.fetch.dlq would fill the DLQ with routine successes and devalue it
  as an operator surface. Recommend: fact yes, DLQ no — which makes this the first
  outcome to close a command without a DLQ entry, and therefore worth its own test.
• Contract doc: a taxonomy row, the reason token table, removal of the
  "do not attempt conditional GET yet" warning, and MUST-6's silence accounting.
• co-core companion issue to document the token in FetchFailedEvent's docstring — the
  canonical home of the vocabulary (cf. cannobserv#277, which struck wrong_payload_type
  from it).

Sequencing

Does not block #10 (shipped) or #11 (the request options are useful for User-Agent and
timeouts independently of validators). It does gate the contract's warning coming
out, and it should land before any issuer is told conditional GET is available.

Refs

• Producer of the validators: Emit the enriched BlobAvailableEvent fields (cannobserv#271) #10 (cannobserv#271, cannobserv#279)
• Replay of the validators: Honour ContentFetchCommand request options: headers, timeout_seconds (cannobserv#272) #11 (cannobserv#272)
• The failure fact this extends: Publish fetch_failed facts so permanent failures stop being silent (cannobserv#270) #9 (cannobserv#270)
• Consumer: Phase 4: build the content.fetch producer against Replicator's issuer contract watcher#241 (Phase 4)
• Contract: docs/contracts/content-fetch-issuer-contract.md

[gregoryfoster]

Readiness reassessment — the issuer is live, and the recommendation holds

Reviewed against the code as it stands after #19/#22/#24 and against Watcher's cutover.
Both decisions in the issue body stand. What changed is the priority argument, which
inverts, and the scope, which grows by two paired issues in sibling repos.

The premise moved

This issue was filed to be decided before an issuer sends its first validator.
watcher#241 closed completed
2026-08-06: Watcher is the live content.fetch issuer for all four WatchedItems across
two origins, and HttpFetcher / Fetcher / DomainRateLimiter are deleted on that side.
The read half of the conditional-GET seam is on a fact Watcher already receives.

So the only thing standing between a live 304 and a false failure is a prose warning in
a doc — content-fetch-issuer-contract.md:155
and content-fetch-issuer-reference.md:108.
No code, no test, nothing that fails loudly. Conditional GET is the obvious next
optimisation for anyone looking at 122 KB re-downloaded per scheduled check, and on the
issuer's side it is a two-line change.

Worth naming the production failure now that there is production to fail. A replayed
validator earns a 304, Replicator publishes fetch_failed · http_status ·
terminal=True, and Watcher's reaper correctly does not re-issue — so it is not a
retry loop. It is worse than a loop: a WatchedItem whose content is perfectly current
records a terminal fetch failure on every successful no-change check, while
content.fetch.dlq fills with successes. A false negative that looks like an answer.

Against that, the change here is small. Landing it beats guarding the trap.

The two decisions

A (reason="not_modified" on the existing fact) — agreed, and one argument the body
does not make is close to decisive: A needs no co-core bump. reason is already a
plain str on FetchFailedEvent, so this ships against the current >=0.7.7,<0.8 floor
with no wheelhouse mirror, no from_wire entry, no ChangeEventPayload union member.
Unlike #9/#10/#11 the co-core companion is docs-only. B costs a model, a union member, an
idempotency-key rule and a version floor, for an outcome whose consumer-side handling —
"no blob is coming, close the entry" — is byte-for-byte what A already produces.

#25 strengthens A. Adaptive 429 backoff needs a signal path for a non-terminal
outcome, which is the #9 §3 deferral. If #25 reopens that, content.blobs becomes a
general command-status stream rather than a success/failure pair, and A's honest cost —
fetch_failed carrying a non-failure — stops being a special case and becomes the
stream's actual shape. B would then be the second exception rather than the clean one.
Recommend recording #25 here as the reason a dedicated content_unchanged event is not
worth minting.

Fact yes / DLQ no — agreed, with one addition. Filling content.fetch.dlq with
routine successes is right to avoid. But note the observability being given up: today an
unbidden 304 — origin misbehaving, no validator sent — is caught precisely because
it dead-letters. Preserve that cheaply: log at WARNING when the 304 arrives for a command
whose headers carried no if-none-match / if-modified-since, INFO otherwise. Three
lines, and it keeps the "origin behaving oddly" signal the DLQ was carrying by accident.

The cost of A the body understates

The body argues 304s must not pollute the DLQ because that devalues it as an operator
surface. The same argument applies to the fact stream: anything counting fetch_failed
rate now counts routine no-change checks, and at steady state those will dominate.
State it next to the taxonomy row, not only in the model docstring: fetch_failed volume
is no longer a failure signal; fetch_failed where reason != "not_modified" is.

Same for reporter.py's "published fetch_failed"
INFO line, which becomes the most common line in the journal and reads as an error to
log-based alerting. Give the not-modified case its own message.

Implementation shape — the part the body leaves open

"Raised at the 304 site in _raise_for_status" understates it: a 304 needs a third
fate the loop does not have. Today transient ⇒ retry, no fact; permanent ⇒ fact + DLQ.
This is fact + ack, no DLQ.

1. A sibling exception under HandlerError, not a PermanentFetchError subclass.
   PermanentFetchError's docstring says "dead-letter it now", and a subclass would be
   swallowed by the existing except PermanentFetchError arm in process_message. The
   alternative — branching on exc.reason is FailureReason.NOT_MODIFIED inside that arm —
   makes a wire token load-bearing for local control flow: renaming it would change
   retry/DLQ behaviour. Keep the fate structural, exactly as the existing two are.
2. Name it in the loop's vocabulary, not HTTP's — CompletedWithoutBlobError
   carrying reason=FailureReason.NOT_MODIFIED and status_code=304, rather than
   NotModifiedError. The token is the issuer's vocabulary; the exception type is the
   loop's, per the ARCHITECTURE.md convention. It also leaves room for the next
   body-less-but-fine outcome without a second one-off type.
3. A _close_without_dlq beside _close, and a new Outcome member. Reusing
   Outcome.ACKED would make the counter that matters unreadable. The ordering inverts
   here — publish, then ack — and that deserves its own docstring paragraph, since _close
   exists specifically so the ordering cannot be got wrong one call site at a time and
   this is a second ordering.

Sub-decisions the body does not name

The dedupe key. Every close path today acks without writing
replicator:cmd:<command_id>; only the success path writes it. Recommend writing it on
the 304 path: this is a completed command, not a discarded one, and the key stops a
reclaim-after-crash from re-asking an origin that just said nothing changed —
politeness-adjacent, and it costs one SET. Either way pin it with a test; this is exactly
the kind of thing that gets decided by omission.

412 Precondition Failed. The other conditional-request status. Decide it in the same
commit or the first issuer using If-Match files the follow-on. Recommend it stays
http_status + DLQ — a failed precondition on a GET is an issuer error — and say so in
the taxonomy table so it reads as a decision rather than a gap.

A 304 carrying a body. Classify on status alone, ignore the body, never store. The
is_2xx guard already prevents storage; make the docstring say that is deliberate.

Boundaries charter. Runs clean — no durable per-resource history (the validators live
with the issuer, per the charter's own worked example), no cross-command coordination, no
domain vocabulary. Worth a line in the PR recording that the three tests were run.

Scope corrections

The body's doc list predates #22 (curation) and #24 (the contract/reference split). Four
sites now:

• docs/ARCHITECTURE.md:68 — the "loop's vocabulary"
  bullet naming a body-less 304 as PermanentFetchError
• content-fetch-issuer-contract.md:155-157
  (the warning) and :182 (the token table)
• content-fetch-issuer-reference.md:108-120
  (the warning) and :134 (the taxonomy row)
• The DLQ section of the reference: "the DLQ is the complement of the fact" is
  currently true because every terminal close leaves an entry. This is the first close
  with no DLQ entry — say so there, not only in the taxonomy table.

Plus src/core/errors.py's HTTP_STATUS docstring and _raise_for_status's, both of
which name the 304 explicitly today.

And the piece that is genuinely new

Landing this does not by itself make conditional GET usable, so the warning cannot come
out on merge. Watcher's apply_fetch_blob is built around a blob arriving; there is no
branch for "no bytes, your last fingerprint still stands", and its tracker carries no
conditional-GET issue at all. co-core's FetchFailedEvent docstring is the canonical home
of the token vocabulary (cf. cannobserv#277, which struck wrong_payload_type from it) and
does not list this one.

Three paired pieces, filed:

• Vocabulary — CannObserv/cannobserv#298 (docs-only, no version bump)
• Consumer — Conditional GET: handle not_modified, then store and replay validators — do not send one before part 1 watcher#249 (replay validators, branch on the token)
• Producer — this issue

The contract's "do not attempt conditional GET yet" warning comes out when the issuer can
act on the token, not when this merges. Until then it downgrades from "the outcome does not
exist" to "the outcome exists; your consumer does not handle it yet".

Tests

One genuinely new assertion: XLEN <topic>.dlq == 0 after a 304 closes a command — the
first outcome to close a command without a DLQ entry. Everything else is conventional
(handler raises the new type, reporter carries terminal=True + status_code=304, dedupe
key written, the unbidden-304 WARNING). Check whether any existing loop test asserts "every
non-retry outcome produces a DLQ entry"; that invariant becomes "every failed close does".

Blocked on

#27 — main is red (the CI test job never checks out skills-vendor/), so a PR for this
lands on a broken baseline until that is fixed.