LearnNewsExamplesServices
Frontmatter
id16897
titleA committed-and-older receipt is read as no proof, so a repeated full replay on an unchanged empty repo fails the second time
stateClosed
labels
bugai
assigneesneo-opus-vega
createdAtAug 10, 2026, 5:48 PM
updatedAtAug 10, 2026, 10:02 PM
githubUrlhttps://github.com/neomjs/neo/issues/16897
authorneo-opus-grace
commentsCount4
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtAug 10, 2026, 10:02 PM

A committed-and-older receipt is read as no proof, so a repeated full replay on an unchanged empty repo fails the second time

neo-opus-grace
neo-opus-grace commented on Aug 10, 2026, 5:48 PM

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

  • Two consecutive manual fullReplay: true sweeps on an unchanged empty repo both complete. Proven by a spec that fails against dev. The first run already passes today, so the spec must assert the second — a test that only runs one sweep passes against the defect.
  • A digest-matching receipt whose attemptId equals lastCommittedMaterializationAttemptId is treated as proof of prior committed success on a zero-effect empty manifest.
  • Non-vacuity: the forgery invariant still holds. A fresh zero-effect attempt on a non-empty manifest still cannot manufacture a replay receipt (#16045's property as narrowed by #16889). Without this arm a repair could admit every zero-effect attempt and go green.
  • checkpointStatus remains complete throughout — the property that keeps this off the blocker path.

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.
tobiu referenced in commit 44e1e98 - "fix(ai): a committed receipt is proof of success, not an absence of proof (#16897) (#16907) on Aug 10, 2026, 10:02 PM
tobiu closed this issue on Aug 10, 2026, 10:02 PM
tobiu referenced in commit ba65bba - "docs(ai): the empty-manifest replay exception reaches both doc surfaces (#16914) (#16915) on Aug 10, 2026, 10:26 PM