Report a transaction log's corrupt-frame stop to getRange callers through an onCorruptFrame hook

[kriszyp]

RocksTransactionLogStore.getRange now exposes an onCorruptFrame(error, logName) hook when a transaction-log iterator stops at a corrupt frame, giving replication consumers the signal they need to recover instead of parking on a dead iterator. The hook is composed with main's corruption stop tracking and telemetry at the existing latch, while aggregate delivery remains safe under re-entrancy and keeps mutable exclusions private to each range.

Independent review also identified a pre-existing addLog convergence issue: re-including an excluded peer does not itself invalidate latestUpdates, so that peer waits for another log-list update before receiving an iterator. It is outside this PR's change and is recorded as a follow-up finding.

Refs #2016, #2063. The paired engine work is HarperFast/rocksdb-js#817; harper-pro owns the policy that turns a mid-log report into a bounded base-copy resync.

For the human reviewer

1. Core reports the gap; the consumer repairs it. The alternative is for core to seek past the break or initiate resync itself. Core cannot assign one recovery policy to boot replay, replication, and subscriptions, while harper-pro has the source and bounded-copy machinery. Reversing this later is invasive because recovery ownership crosses repositories; rejecting it now requires moving the policy and its end-to-end proof into core.
2. The hook is synchronous inside next(). An event or microtask would be simpler, but the replication sender must learn why the drain stopped before it parks on a future transaction. Reports wait until the aggregate buffer is stable, and iterator splices wait for the outermost poll. Changing this later is behaviorally breaking; rejecting it now requires redesigning the sender notification contract.
3. Promise-returning hooks are fire-and-forget. Rejections are contained and logged, but async recovery cannot gate a synchronous iterator. The alternatives are a synchronous-only signature or an asynchronous iterator contract. This is cheapest to change before adoption; rejecting it requires choosing one of those narrower APIs.
4. Exclusions belong to the range, not the caller's options object. removeLog records the private exclusion immediately but defers structural mutation, so frozen options work and a hook's exclusion is visible to a nested refresh. The alternative is retaining the caller's array as live shared state. Reversal is local but restores hidden mutation and the frozen-options failure.

Verification

• npm run build — passed.
• npm run lint:required — passed.
• npx mocha unitTests/resources/auditLog.test.js --grep "onCorruptFrame|removeLog remembers|hook exclusion" — 14 passing, including frozen options across refresh, a future peer excluded before it exists, hook-time exclusion before a nested refresh, sync/async failure containment, and a real on-disk torn-frame report.
• npm run test:unit:resources — 2,055 passing, 27 pending on the final reviewed head.
• Regression controls — the frozen-options test fails against the prior mutating implementation with TypeError: object is not extensible; the nested-refresh test fails before immediate exclusion registration because the excluded future peer is polled twice.
• harper-pro integrationTests/cluster/txnlogTearReplication.test.mjs — prior paired-branch evidence: base parks at 39/60 rows; this hook plus the sender's bounded base copy converges to 60/60 and accepts a post-recovery row.
• npm run test:integration:all — began successfully and passed numerous unrelated scenarios, then the runner saturated and multiple independent instances timed out together at 120 seconds; stopped after the synchronized infrastructure failures. npm run test:unit:main and npm run test:unit:windows likewise stopped producing a summary, with the Windows slice also exposing an unrelated ambient credential-socket failure.

Complexity: complicated

_{Review-Coverage: authored=codex; ran=claude,gemini; declined=cursor-grok,cursor-composer,domain; rounds=6 @ e6d26bd}

_{Human-Review-Need: 4 @ e6d26bd}

[github-actions]

Release cherry-pick v5.2: cancelled

Cherry-pick branch cherry-pick/v5.2/pr-2463 was deleted — this PR no longer targets v5.2 (milestone is now v5.3).

[gemini-code-assist]

Code Review

This pull request introduces a new onCorruptFrame hook option to RocksTransactionLogStore.getRange(), allowing callers to be notified synchronously when a transaction log iterator stops early due to a corrupt frame. The implementation safely handles hook execution, defers reports for construction-time corrupt frames, and queues log removals requested during polling to prevent iterator disruption. Comprehensive unit tests have been added to verify these behaviors under various scenarios, including aggregate/single-log paths, throwing/async hooks, and on-disk torn frame detection. No review comments were provided, so there is no feedback to address.

[claude]

Reviewed; no blockers found.