Snapshot selection review for PR #2086

The external review inspected 2e0afc8a9; subsequent callback-key work reached 6ec97f8a0 before this repair. This record distinguishes that earlier calibration from the new controlled-provider experiments. The listed RED results were reproduced against 6ec97f8a0 or the named hostile edit; the GREEN results use the repaired working tree. The law concerns Collection subscription selection and provider requests within the stated histories.

The independent follow-up review covered implementation commit eeb3a8673. Merge commit 91bef133d76990ce93256d4881d27182431c0fbf adds only the remote bot's formatting change to that implementation. It contains origin/main at f6857fee9de59dc82cbe596ca7df4a18152004ed. The final evidence commit in that earlier cycle changed this record only. The repaired full package run was before that formatting merge; the four focused suites passed again afterwards.

Law and observation cuts

requestLimitedSnapshot promises not to resend a key already sent to its subscriber. Collection.subscribeChanges promises per-key causal order; the change-event history owner in the coverage map requires a strict consumer's valid insert, update, and delete stream. A published delete releases a public key; a source delete held in a private replay has not done so. A later ordered local snapshot must skip every key selected earlier, including a private replay selection, and every still-public callback key. The Collection API, the change-event owner, and the method contract in packages/db/src/collection/subscription.ts authorize this selection rule.

A selected or public key does not certify that all earlier provider rows were fetched. The ordered-loading contract in packages/db/src/query/live/ARCHITECTURE.md explicitly rejects a local row as a remote offset or continuation boundary. Without minValues, an ordered request with no explicit offset must cover a provider prefix wide enough to admit its requested number of unseen rows. With minValues and no explicit offset, an adapter may ignore cursor expressions; no finite bound derived from local keys can reach an arbitrary cursor value, so provider acquisition is unbounded. A locally selected key cannot supply cursor.lastKey. An explicit offset supplied by the ordered source loader remains a separate, caller-established boundary.

The lifecycle publication owner models source rows in a plain Map. A separate Set models subscriber-visible keys. It runs two source-action histories: a new insert, and a delete followed by reinsert and a new insert. Each history runs with filtering, full-state pass-through, and includeInitialState: false pass-through. Each mode runs with and without a cursor. The driver uses a real Collection, its ordered index, sync transactions, and a subscription. It checks callback key/type batches after each source commit and after the ordered request. It also checks the retained key count after deletion. That count is a deterministic capacity observation, separate from the public-row law.

The replay owner controls an accepted load promise. It compares public batches while the truncate replacement is private and after the promise fulfills. It also checks that private selections widen a later prefix request and that a sparse retained row does not turn into a provider key cursor. A second replay test checks a filtered snapshot selected during callback reentry. The publication owner uses a controlled adapter over [one, two, three] to return actual offset pages after sparse callbacks and ordered callback reentry. An offset-only provider over three and seven ranks checks a high cursor value: the request has offset zero and no finite limit, and its target row becomes public. The pagination recomputation oracle exercises cursor-expression and offset transports. CollectionSubscription never supplies cursor.lastKey, so its former key-transport cases exercised the offset path and were removed. The TrailBase adapter test exercises an explicit last-key caller and its offset fallback. All 16 pending-mutation transport cases pass in the two reachable live-query modes.

RED and GREEN calibration

Subject	Reached comparison and result
Prior follow-up: restore the old trackSentKeys early return	Eight pass-through callback cases failed: both source histories duplicated insert:two, and delete/reinsert retained one deleted key. Four filtering cases passed. This earlier run established callback tracking, not provider coverage.
Prior follow-up: publish ordered snapshots during a private replay	The held-publication comparison saw early inserts for one, two, and three instead of only the initial one batch.
Prior follow-up: select held replay by loadOptions.length === 2	An extra empty subset load made the fixture hold the wrong request and caused early replacement publication. Matching the ordered request by its options passed that perturbation.
6ec97f8a0 as the original implementation against the new provider witnesses	Sparse callbacks lost two in both initial-state modes, with and without a key cursor; ordered callback reentry lost three in skip-filtering mode without a cursor. After a successful sparse replay, a cursor honoring lastKey could not acquire one at the first request. Six of nine new cases failed at public-row comparisons.
6ec97f8a0 against the high-cursor offset-only witness	All four three- and seven-row cases reached the adapter request assertion and failed with limit: 1 instead of an unbounded request. The fixture cleanup completed; these failures are request-bound assertions, not setup failures or public-row comparisons.
Remove the regular snapshot reservation from the repaired tree	The private mixed-replay witness reached its provider-prefix comparison with limit 2, below the independent minimum 3. Its selected filtered row had not been reserved before publication.
Remove the ordered snapshot reservation from the repaired tree	The repeated ordered-replay witness reached the provider-prefix comparison with limit 1, below minimum 4; the mixed-replay witness saw 2 below minimum 3.
Repaired tree	The provider, replay, selection, and subscription suites pass: 629 tests in four files. The package Vitest configuration passed 242 files and 11,789 tests with coverage and Vitest typecheck disabled; a separate source/test TypeScript check passed. The new provider and replay cases pass at their public-row checkpoints.

The high-cursor baseline and the two reservation mutants were run against the latest witnesses in an isolated archive with the repaired test file. They failed by value assertion, with cleanup complete; their failures did not rely on a timeout or fixture error. The older last-enumerated-row cursor mutant is no longer relevant to the accepted law: no locally derived lastKey is now sent. The old reset witness in filtering mode remains narrower because callback tracking alone lets it pass when the regular reservation is removed. The mixed replay witness owns that private-selection requirement.

Oracle guide audit

Requirement	Outcome
ORC-001	The Collection callback and ordered-snapshot contracts authorize the public-key law; the live-query architecture denies a continuation boundary from local rows. The retained-key check is an internal work bound, not an API memory limit.
ORC-002	A source Map, visible Set, and plain ordered remote array choose expected rows independently of subscription tracking. Replay expectations derive from initial and replacement row sets; a separate callback map records actual public rows.
ORC-003	Each owner states its law and limits. The new comments place the model rule, legal histories, real driver, public cuts, and comparisons beside their code.
ORC-004	The callback matrix crosses three subscription modes, two source histories, and both local cursor paths. Sparse callbacks, ordered callback reentry, and sparse replay add three-row provider histories; a high-cursor offset fixture uses three and seven ranks. They exclude arbitrary ties, predicates, and remote schedules.
ORC-005	The driver calls real snapshot methods and source sync transactions. Raw callback batches retain duplicate inserts and their order. Controlled adapters apply actual offset and key-cursor pages; replay checks before and after settlement.
ORC-006	The original implementation reached the public-row comparison in six of nine provider/replay cases and failed the request-bound comparison in all four high-cursor cases. Both current reservation mutants failed their request-bound comparisons. Earlier callback and publication mutants are listed separately.
ORC-007	No important generated property changed. Both existing owners still run their fixed and random campaigns in the package test suite.
ORC-008	The model keeps source, selected, and visible keys distinct. A source row absent from the subscriber can be selected next; a public key may still leave earlier provider rows unseen. Published deletion and reinsertion distinguish a prior selection from current visibility.
ORC-009	Model source rows map to installed Collection rows; model visible keys map to the subscriber's public snapshot. The remote array models provider order, not a production index. Retained-key count is an internal observation, not model ownership state.
ORC-010	Replay fixtures resolve held promises in finally. Current mutant failures reached value assertions and cleanup succeeded. These fixed witnesses do not separately report a future simultaneous cleanup failure.
ORC-011	The sparse-provider counterexample challenges the old offset and key-cursor rule. The callback fold separately detects duplicate inserts that a final-key check would miss.
ORC-012	This record names the original review head, the later baseline, finite histories, and the exact fresh mutant outcomes.
ORC-013	Full-state and skip-filtering cases reach the pass-through premise; filtering is the neighboring control. Delete/reinsert and new-insert histories distinguish release from permanent reservation. The high-cursor request assertion rejects a plausible finite overfetch even when the three- and seven-row public results would pass.
ORC-014	Controlled adapters supply replay timing and offset or key-cursor pages. Their three- and seven-row results demonstrate the Collection boundary but do not prove every real provider's pagination behavior.

Open scope: rank ties, other predicates, arbitrary and changing provider result sets, provider-specific cursors, and compiled live-query windows outside the bounded optimistic and settled-page histories remain with the owners named in the coverage map. These controlled providers and bounded histories do not prove every possible source schedule.

Second review: optimistic rows and source coverage

The next external review inspected ba6dcb3dd. It found that a pending optimistic delete can consume a bounded provider page without supplying a visible row. The same source-coverage law also applies to optimistic inserts and rank moves: a local row can fill the visible window, but it cannot prove that the provider supplied an earlier rank. The ordered-loading architecture authorizes this distinction. The pagination recomputation oracle owns the compiled live-query window, while the lifecycle publication oracle owns the direct Collection subscription request.

The lifecycle owner checks one and two pending deletes or predicate-removing updates at request submission. The remote array's next visible rank must lie within the submitted provider page. The original bounded request and a one-row-only headroom edit fail those comparisons. The pagination owner also checks final public rows after authoritative source acceptance. Its continuation matrix holds one or two inserts or rank moves, widens a window, and crosses cursor-expression and offset-only adapters; insert histories start with zero or one source row in the initial window. The array model sorts the remote rows and applies the authored mutation without reading loader state. It requires a request for the needed unchanged source rank when that request can start before settlement, and exact public rows after the source commit.

Before the source-coverage repair, six of the first eight continuation cells failed at the request comparison: both offset-only inserts and all four rank moves. The two-move history also failed at the final public window after the earlier request assertion was moved past a legally held repair. Filtering currently optimistic keys alone fixed the single-row cases but left that two-move failure. The source commit could drop the overlay before a padded request settled, allowing moved rows beyond its original requested count to be mistaken for its provider boundary. Capping that boundary read at the original count and checking the source-coverage deficit on delayed continuations repaired the same history. Runtime hostile edits that disabled overlay exclusion, optimistic headroom, the original-count cap, or delayed coverage each failed a corresponding public-row witness. The complete pagination file passed 289 tests; the four relevant DB files passed 641 tests; TrailBase's adapter file passed 27 tests. These checks use controlled providers, not a real Electric, query-db, or TrailBase backend.