[kriszyp]

⊙ Problem

A transaction that requests replicatedConfirmation waits on a log position that was never written when every confirmable write in it is a relocation that loses to a newer version (harper#3182). Peers never acknowledge that key, so the caller blocks until unrelated traffic replicates, or until the confirmation times out.

Cause: _writeRelocate's commit handler returned early on precedesExistingVersion(...) < 0 without setting write.skipped. Staging reads a falsy skipped as "this write appended an audit entry" and records appendedTo, so confirmationTarget chose the committed log key instead of falling back to the stored entry's version. Main only: the log-key target came from Count only a record's residents toward replicatedConfirmation (#3148), which no release carries yet.

❓ Your call: as specified, yes. The trigger is narrow (a confirmed transaction whose only confirmable writes are losing relocations), but the fix is the convention every other commit handler already follows. Milestoned v5.4, not v5.3: the _writeRelocate early return is also on v5.3, but nothing there reads skipped for a relocation (no appendedTo, no saved blobs).

💡 Solution

_writeRelocate's commit handler now resets write.skipped = false at the start of each round and sets it to true before the losing return, the same way _writeInvalidate and _writeDelete do: _writeRelocate marks its losing return skipped and resets it each round — the one runtime line pair to read. That is the whole runtime change. The per-round reset matters as well as the mark: when an open iterator forces the commit to re-stage its writes on a fresh transaction, a relocation that lost when first staged can apply on the re-stage, and a stale true would hide its append.

Audit of the other commit handlers in resources/Table.ts: none had the same gap. Every version-conflict early return in _writeInvalidate, _writeUpdate, _writeDelete and the source-resolution write already marks skipped; _writeUpdate's return writeCommit(false) paths do append an audit-only entry, so leaving them unmarked is correct; _writePublish has no early return; the reload-marker and lock-control writes set skipReplicationConfirmation.

Side effect checked: removalBefore now passes over a losing relocation when a later delete to the same key looks for what left it empty, as it already did for a losing invalidate and as its doc comment says. The relocation stored nothing, so the stored entry is the right answer there.

resources/DESIGN.md now says that staging reads skipped as "appended nothing", so an unmarked early return also breaks replicatedConfirmation, not just blob cleanup.

⚖️ Alternatives

Planning review: Framing-Verdict: chosen-approach-sound.

• Have staging learn "appended" from the audit write itself (updateRecord / the transaction log reporting that it wrote) instead of inferring it from skipped. That removes this whole class of bug: a forgotten flag would fail safe. Not done here because it changes the bookkeeping contract for every handler and the sticky appendedAuditEntry retry dedup, which is more than this fix needs.

  ❓ Your call: worth a follow-up issue? Any future early return that forgets skipped brings this bug back without any visible error.

• Set skipReplicationConfirmation on a losing relocation. Rejected: the caller would then get no confirmation of the surviving entry, which the existing fallback gives them.

✅ Verification

• New tests in unitTests/resources/residencyConfirmation.test.js:
  • a confirmed transaction whose only write is a losing relocation confirms on the stored entry's version, leaves the record unchanged, and confirms once;
  • a losing relocation next to an applied write still confirms on the committed log key;
  • a relocation that loses when staged but applies when an open iterator forces re-staging (its base evicted in between) confirms on its own audit entry's log key. This test covers the per-round reset.
• Fails on base: with origin/main's resources/Table.ts built into dist, the first test fails (confirms on the log key, version − 60000). With the fix but without the reset line, the re-staging test fails (0 == 1: no confirmation issued). Both pass with the fix.
• npm run test:unit:resources: 4257 passing, 0 failing (RocksDB).
• Under HARPER_STORAGE_ENGINE=lmdb, residencyConfirmation, localOnly, dualClockAuditRecord, indexOrphanStagingOrder and subscriptionSuperseded pass (45 passing). residencyConfirmation skips itself on LMDB, which keeps its own confirmation registry, so the new tests are RocksDB-only.
• oxlint and prettier clean on the changed files.
• End-to-end route: not observable from core alone; actual peer acknowledgement runs in harper-pro's replication layer. The unit tests check the value core hands to the replication callback, and the callback resolves immediately in them.

Refs #3182

— Claude Opus 5.5

🤖 Generated with Claude Code

https://claude.ai/code/session_01MquViG8a7UtvqFChsoL7qH

_{🤖 Generated by Claude Opus 5.5 (Claude Code dev-agent); posted via @kriszyp.}

Release target: v5.4 — the log-key confirmation target this fixes came from #3148 (v5.4); v5.3 has no appendedTo, so the unmarked return is harmless there
Related PRs: #2446 independent (MCP session deletion; does not touch _writeRelocate or removalBefore)
Complexity: medium

Closes #3182

_{Dispatch: task harper-3182-losing-relocate-skipped · queued by unknown · ran by claude/opus/high · worker kzyp-xps-1}

_{Review-Coverage: authored=claude; ran=gemini,codex; adjudicated=domain; declined=cursor-grok,cursor-composer,cursor-kimi,cursor-muse; rounds=2; full=1 @ db4669b}

_{Review-Attention: study ~9m (critical: Table.ts; decisions: skipped-flag-as-append-proof, all-lost-confirmation-target) @ db4669b}

[gemini-code-assist]

Code Review

This pull request ensures that early-return paths in the Table commit handlers, specifically when a write precedes an existing version, correctly set write.skipped to true to prevent replication confirmation from waiting indefinitely (harper#3182). The changes include updates to resources/Table.ts to set this flag, corresponding documentation updates in resources/DESIGN.md, and new unit tests in unitTests/resources/residencyConfirmation.test.js to validate various losing relocation scenarios. There are no review comments, and I have no feedback to provide as the implementation is correct and adheres to the repository style guide.