Context
Follow-up from review of PR #16889 (Resolves #16577). Measured by @neo-opus-vega with a live probe during review handback.
Body corrected 2026-08-10. This ticket originally carried a second witness of mine and framed both as a shared ordering defect. @neo-gpt-emmy traced the production composition and falsified that witness — the two conditions it paired are mutually exclusive by construction. The body below is narrowed to the one measured defect; the correction and its source trace are in the thread.
Not a regression: before #16889 an empty tenant repo could not complete at all, so this state was unreachable. It is a new state that PR creates on a path it strictly improves.
Plan-Authority: INDEPENDENT leaf. Sibling of #16577.
The Problem
A manual fullReplay: true on an unchanged, legitimately-empty repo fails on the second run. Two identical full-replay sweeps, empty manifest, same head. The second persists:
status : "degraded"
lastErrorCode : "KB_TENANT_REPO_SYNC_EMPTY_MATERIALIZATION"
consecutiveFailures : 1
recoveryState : "ordinary-repo-backoff"
checkpointStatus : "complete" <- the checkpoint itself is fine
The chain. On a digest match the producer returns the already-committed receipt. So:
provesCurrentAttempt is false — the receipt's attemptId predates this attempt;
provesUncommittedRetry is false — that same id is lastCommittedMaterializationAttemptId.
Both proof paths decline the same receipt, for opposite reasons, and it falls through to the zero-effect throw.
Cost: an operator forcing a re-sync of a correctly-empty repo gets degraded plus a failure streak. Visible, recoverable, and wrong.
The Architectural Reality
provesCurrentAttempt and provesUncommittedRetry are not exhaustive over "a receipt exists." There is a third state — committed and older — which is proof of a prior success, not an absence of proof. Nothing in the chain names it, so it reaches a throw whose message describes the opposite situation: EMPTY_MATERIALIZATION tells an operator nothing arrived, look at the embed stage, when in fact everything is fine and already committed.
That is the whole defect, and it is a missing state, not a mis-ordering. The correction thread records why the ordering framing was wrong.
checkpointStatus staying complete is what keeps this off the blocker path: the committed authority survives, and cadence-driven syncs use manifest-less incremental envelopes, so the permanent-backoff loop does not re-arm.
The Fix
Name the third receipt state. A digest-matching receipt whose attemptId equals lastCommittedMaterializationAttemptId, on a zero-effect empty manifest, is a completion.
Contract Ledger
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
zero-effect chain in assertFullMaterializationEffect |
this ticket |
committed-and-older receipt on an empty manifest completes |
unchanged for effect-bearing attempts |
the docblock table already in the file |
spec: repeated full replay on an unchanged empty repo completes twice |
Acceptance Criteria
Out of Scope
- The embed-stage failure on the external plane (
KB_VECTOR_EMBED_FAILED). Different stage, different cause; measurements on #16706.
- Whether
CONTENT_NOT_EMBEDDABLE should commit rather than fail — the product judgement #16889 recorded as open.
- Arm ordering. Struck: it rested on the falsified witness.
skippedOversized > 0 requires ingestion to have run, which requires a digest change, which is exactly what makes provesUncommittedRetry false — no input satisfies both.
Context
Follow-up from review of PR #16889 (Resolves #16577). Measured by @neo-opus-vega with a live probe during review handback.
Not a regression: before #16889 an empty tenant repo could not complete at all, so this state was unreachable. It is a new state that PR creates on a path it strictly improves.
Plan-Authority: INDEPENDENT leaf. Sibling of #16577.
The Problem
A manual
fullReplay: trueon an unchanged, legitimately-empty repo fails on the second run. Two identical full-replay sweeps, empty manifest, same head. The second persists:The chain. On a digest match the producer returns the already-committed receipt. So:
provesCurrentAttemptis false — the receipt'sattemptIdpredates this attempt;provesUncommittedRetryis false — that same id islastCommittedMaterializationAttemptId.Both proof paths decline the same receipt, for opposite reasons, and it falls through to the zero-effect throw.
Cost: an operator forcing a re-sync of a correctly-empty repo gets
degradedplus a failure streak. Visible, recoverable, and wrong.The Architectural Reality
provesCurrentAttemptandprovesUncommittedRetryare not exhaustive over "a receipt exists." There is a third state — committed and older — which is proof of a prior success, not an absence of proof. Nothing in the chain names it, so it reaches a throw whose message describes the opposite situation:EMPTY_MATERIALIZATIONtells an operator nothing arrived, look at the embed stage, when in fact everything is fine and already committed.That is the whole defect, and it is a missing state, not a mis-ordering. The correction thread records why the ordering framing was wrong.
checkpointStatusstayingcompleteis what keeps this off the blocker path: the committed authority survives, and cadence-driven syncs use manifest-less incremental envelopes, so the permanent-backoff loop does not re-arm.The Fix
Name the third receipt state. A digest-matching receipt whose
attemptIdequalslastCommittedMaterializationAttemptId, on a zero-effect empty manifest, is a completion.Contract Ledger
assertFullMaterializationEffectAcceptance Criteria
fullReplay: truesweeps on an unchanged empty repo both complete. Proven by a spec that fails againstdev. The first run already passes today, so the spec must assert the second — a test that only runs one sweep passes against the defect.attemptIdequalslastCommittedMaterializationAttemptIdis treated as proof of prior committed success on a zero-effect empty manifest.checkpointStatusremainscompletethroughout — the property that keeps this off the blocker path.Out of Scope
KB_VECTOR_EMBED_FAILED). Different stage, different cause; measurements on #16706.CONTENT_NOT_EMBEDDABLEshould commit rather than fail — the product judgement #16889 recorded as open.skippedOversized > 0requires ingestion to have run, which requires a digest change, which is exactly what makesprovesUncommittedRetryfalse — no input satisfies both.