PR #2065 review at 74e399150#

The ten-item medium-effort review of packages/query-db-collection/src/query.ts was based on reading code and Query Core source; it ran no tests. This record tracks the executable contract exposed by the review.

Laws and executable owner#

The Query Collection guide promises that an accepted direct write changes Collection rows without automatically requesting a new server result. A fetch that began before the write cannot undo its accepted keys. An explicit refetch must establish post-write request authority. Cache edits must not claim fetch success, freshness, or error recovery. A scoped cache may remain approximate, but it cannot replay a stale row over the accepted write. A held deferDataRefresh barrier prevents server result publication until release. These are separate laws: no request on write, per-key order, explicit request order, cache-state separation, and publication order.

The primary owner is ownership-lifecycle.oracle.test.ts. Its reference is the authored provider response, accepted direct-write order, and subset ownership, not a copy of Query Core's fetch or cache-patch branches. The legal histories added here include derived-select unload/reacquisition and eager restart; ordinary unload of a still-fetching Query with an outside observer; an explicit subset refetch; a derived result behind a held refresh barrier; a provisional cached result waiting on a persisted baseline scan; two logical observers sharing one physical Query; and a direct insert while the first eager request is in flight. The driver uses the real QueryClient and Collection. It checks request counts, public rows, Query cache rows and state at the specific load, write, barrier, and refetch settlement cuts. Existing load-subset-lifecycle-oracle.test.ts owns broader load settlement; cursor-pagination-oracle.integration.test.ts checks that an idle, empty eager cache entry can still be seeded by a direct write.

The first five new regressions failed by assertion on the reviewed production code before repair: derived subset reacquisition had no row; ordinary unload revived a deleted row or reused the old request; explicit subset refetch reused the old request; and a derived result published during the barrier. The pending eager Query test also failed with data present in status: pending. After repair, the pending-application test rejects a mutant that removes its pending check at the cache-row checkpoint (Older versus Manual). The alias test rejects a mutant that marks the physical Query visited before the disjoint-scope skip (Before versus After). Separately deleting the ordinary-unload fetch-start retention and the unobserved-fetch key claims revived the row in the same controlled history; removing fetch-start retention also left explicit refetch at one request instead of two. These are assertion failures at the intended checkpoints, not setup failures or timeouts.

The review's empty-cache deferred-refresh scenario cannot schedule a deferred refresh: that path first requires a successful cached result. A cached-result barrier-release control passes even when the extra cancellation call is removed, because Query Core's normal refetch cancels a request when data exists. The explicit subset-refetch subclaim is real and repaired. The review also proposed replacing logical-hash fetch positions with a Query-keyed WeakMap. That may simplify retirement, but query-function context provides a key rather than the physical Query. A switch would add a Query lookup at fetch entry and alter the ownership boundary. This review retains the current map and checks both keep and retirement behavior instead.

Query Core compatibility#

The package had declared @tanstack/query-core: ^5.0.0. A standalone probe against Query Core 5.0.0 held an empty-cache first fetch, cancelled it synchronously, and called observer.refetch(). It made only one provider call; the replacement refetch rejected with CancelledError. The current installed 5.90.20 source restarts when the retryer is already rejected, and the ownership oracle passes the post-write refetch histories at that version. The peer minimum is now ^5.90.20, the version tested by this repository. A foreign QueryClient.fetchQuery awaiting the cancelled request can still receive CancelledError on that version. The existing overlapping-refetch oracle records that separate Query Core boundary while requiring Collection refetch callers to follow the successor.

Scope and remaining witnesses#

The finite Query Core histories prove the stated observation cuts for the authored response shapes, observer order, and controlled persistence barrier. They do not prove every custom hash collision, every Query cache removal schedule, unbounded performance, native SQLite timing, or a full offline reconnect replay. The Query DB ownership oracle owns further direct-write cache histories; the cursor pagination owner covers windowed receiving, and the offline transactions owner covers real deferDataRefresh replay. The coverage map records these limits. No reachable in-scope counterexample was left by this review's ten reported traces.

Compatibility follow-up at c64fd999#

The prior ^5.90.20 peer floor was the installed test version, not the first compatible release. Against the PR head before this manifest-only follow-up, the post-write subset-refetch oracle timed out on Query Core 5.85.2 and passed on 5.85.3. The upstream 5.85.3 change makes a fetch restart when its retryer has already rejected. The full Query DB suite passed 668/668 on 5.90.15 and 5.90.19. On 5.90.14, the cursor fault-recovery property and the explicit refetch-error remount test failed; upstream 5.90.15 changed error invalidation and refetch-on-mount behavior. Query Core 5.0.0 cannot run the suite because the package's pre-existing partialMatchKey import is not exported there. The peer floor is therefore ^5.90.15, the lowest full-suite version observed. This finite version sample does not establish support for every newer 5.x release.