The empty-manifest replay exception never reached its two doc surfaces

Context

#16897 shipped in PR #16907 (merged 2b0cabc975, 20:02Z) and changed when a zero-effect full replay may advance a checkpoint. Two documentation surfaces still state the pre-shipped rule, so they are now false on dev. Found by @neo-gpt at review; folded here rather than carried as an Approve+Follow-Up, per the operator's normal-review-mode directive.

Debt paid before opening, per the resolve-before-open rule: #16910 (closed with receipts, 20:02Z) and #16897 (closed COMPLETED via the merge, 20:02:33Z). Nine tickets resolved today total.

Live latest-open sweep at 2026-08-10T19:57:17Z; no equivalent open ticket.

The Problem

learn/agentos/cloud-deployment/Troubleshooting.md:282 on current dev:

A zero-effect retry can advance only when it settles the matching unacknowledged receipt from an interrupted post-ingest checkpoint commit before repeating Knowledge Base mutation.

That only is now wrong. A zero-effect replay also advances when the manifest authoritatively declares no content and the matching receipt's attempt is already committed — which is exactly the case #16897 fixed.

Why this one matters more than an ordinary stale comment: it is in the troubleshooting guide, and it tells an operator that a repeated --full on an empty repo should fail. Post-#16897 it succeeds. So the guide now instructs a reader to treat correct behaviour as a defect — the failure mode is a false bug report, not a missing sentence.

The helper's own leading JSDoc (assertFullMaterializationEffect) carries the same superseded only, so the contract a future author reads before editing that function describes behaviour the function no longer has.

This is incomplete delivery on my own merged PR, not a discovered defect.

The Architectural Reality

• ai/daemons/orchestrator/services/TenantRepoSyncService.mjs — the @summary block above assertFullMaterializationEffect (the shipped predicate is provesCommittedSuccess, admitted only in conjunction with declaresNoContent).
• learn/agentos/cloud-deployment/Troubleshooting.md — the --full CLI replay paragraph.

No runtime surface is involved. Comments and prose only; the executable diff is empty by construction.

The Fix

State the exception and the boundary that keeps it safe in the same sentence on both surfaces: the committed-and-older receipt is admitted only where the manifest declares no content, and a zero-effect attempt on a manifest that declares content still cannot manufacture a receipt. Naming the exception without the boundary would read as a general relaxation, which is the misreading worth preventing.

Contract Ledger Matrix

Decision Record impact

none.

Acceptance Criteria

• Neither surface still says a zero-effect retry may settle only an unacknowledged receipt.
• Both name the committed-and-older exception and the declares-content boundary in the same breath.
• The guide states plainly that repeating --full on an unchanged, legitimately-empty repo succeeds on every run.
• The executable diff is empty — verified mechanically, not asserted.

Out of Scope

• Any behavioural change. If this ticket edits an executable line, the premise is wrong.
• The other docs #16897 touched — the in-function comments already carry the new rule.
• #16906's guard and the evidence-ladder.md template amendment.

Avoided Traps

• Naming the exception without its boundary. Would read as "zero-effect replays are fine now," the opposite of the shipped conjunction.
• Filing this as an A+FU leaf. The directive is explicit; it was folded into the open PR, and only became its own ticket because the PR merged first.
• Reopening #16897. A closed close-target cannot carry a residual — that is the class #16906 records.

Related

#16897 (shipped), PR #16907 (merged 2b0cabc975), #16906.

Origin Session ID: 1c01e6b9-923c-4051-8dac-7f46c9eba661

Retrieval Hint: "empty-manifest replay exception doc surfaces"; grep 'unacknowledged receipt' across ai/ and learn/.