Initial ordered fallback readiness (issue #2152)#

Reviewed code commit: bb1ed1d87ffb2de1b27b8a024fc402d2755dcb26 (parent 91cefa2602cf35929cbc5402f6afd7c8dbe9c88d). This record and the final coverage-map limit are documentation follow-ups to that code commit.

Contract and finding#

The initial synchronous cut in packages/db/src/query/live/ARCHITECTURE.md covers every acquisition needed to complete an unpublished first ordered window. A provider-ordered prefix whose locale-string or null boundary cannot form a cursor may need a full-source fallback. When each request returns literal true after its rows apply, the rows and ready status are owed before the initiating preload() returns. A Promise fallback stays asynchronous. The cut does not promise a render-time result for a deferred on-demand React source or synchronous timing for repair, replay, or a later window operation.

The old warm null-boundary test read status before preload() started acquisition. It therefore accepted loading without observing the promised cut. The loader also classified a full-source request as initial only if no earlier source request had settled. That excludes the fallback after the first ordered page. The revised oracle starts the sync run and records request shape. It reads public state at fallback entry and immediately after preload() starts, then compares again after settlement. Its two-row ISO-string reference predicts row 2 for distinct dates and row 1 for tied dates with a public-key tie-breaker. It does not use the production comparator. The warm null case checks an already installed source, where the continuation has no new row input to drive another graph turn.

The independent oracle reviewer found two gaps before production changed. First, the architecture said full-source repair always settles asynchronously, although the prior design review left that timing open. The architecture now states the actual atomic-publication obligation without fixing repair scheduling. Second, the new index cells could both have used the same ordered request path. The first request now checks offset 0 for the indexed page and no offset for the unindexed prefix. The reviewer found no remaining blocking issue in the revised architecture, oracle, and coverage map. The reviewer inspected the path discriminator; no index-selection mutant was executed.

Executed evidence#

Four independent oracle reviewers challenged the contract, request path, observation checkpoints, and receiving boundary. They found three false-green gaps in the original four cells. A locale-string cursor mutant passed them because the oracle omitted the fallback's where predicate. A mutant that dropped fallback source changes also passed the original 264-test lifecycle suite because distinct dates kept row 2 as the winner. The original oracle did not read public rows when the fallback started. The new request assertion, tied-row dimension, and entry checkpoint close those gaps for the eight cells.

The locale-string cursor mutant now fails all eight cells at the request-shape assertion. The dropped-fallback-changes mutant fails all four tied-row cells at the public-row comparison: it returns row 2 instead of row 1. A synthetic early-publication fault fails all eight cells at the fallback-entry read. These were comparison failures, not setup failures or timeouts. That state read alone cannot reject a transient or duplicate event after fallback entry. A separate subscriber-event assertion now records nonempty change batches across the same eight histories. A temporary duplicate-event fault fails all eight new cells at that assertion. Empty readiness callbacks do not count as row publication.

The original !hasSettledSourceRequest gate is the calibrated wrong design: it reaches both acquisitions but fails the immediate comparison, then passes after settlement. The production repair preserves the existing exclusions for ordering repair debt and explicit window operations from the synchronous path. Its original production diff is five added and three removed lines, net two. Test and contract prose are accounted for separately.

ORC-001 through ORC-014#

Bounded result#

The repair is evidenced for the fixed indexed and unindexed locale-string findOne() histories, distinct and tied rows, a warm null boundary, Promise fallbacks, an eager React first layout commit, and a warm Query DB adapter handoff. The Query DB witness covers cached subsets. It does not establish a first-commit React result for a real on-demand provider or other adapters. The event assertion covers the eight controlled fallback histories. It does not establish every event ordering or another provider's publication path. No reachable counterexample remains in the executed core and receiving paths at their stated checkpoints.

Follow-up review of the readiness proxy#

A seven-item code-reading review targeted 6bc943992; the evaluation used 1e4bba40c after a type-only test fix. The accepted law promises a synchronous result for a first ordered window whose required acquisitions return literal true after their writes apply. It does not require a later full-source acquisition to settle asynchronously. A later request without ordering-repair debt may finish in the same graph turn.

A public probe reached the reviewer's publication/readiness distinction: a joined-filter window published row 1 while a pending child demand kept the live-query Collection loading. Removing row 1's join match requested another ordered page, received a null boundary, then requested the full source after that first publication. The original !canRetryRepair() check classified it as initial, but its public rows and change event remained coherent. The reviewer's suggested insert alone did not make a full window need more data. In a separate ready post-publication probe, dropping the check changed only a transient isLoadingSubset observation: the final row was 2 in both versions. The revised loader uses isFullSource && !needsOrderingRepair for synchronous eligibility, leaving retry policy with its own callback. The full-source repair and explicit-window exclusions remain in place.

An async first page followed by a literal-true fallback tested the claimed request/observe race through a public live-query Collection. Synchronous fallback writes left status loading and rows unpublished until observe() ran; after preload settled, it was ready with the expected row. A direct loader probe could flip a mock callback during request() and change the branch, but did not establish that transition on a legal public path. Removing the callback from this branch also removes that sensitivity.

The old ordered lifecycle owner accepted a mutant that removed the readiness clause: all 276 tests passed. That mutant is permitted by the documented timing law, so its survival does not expose a missing required timing assertion. The retained initial cells still reject the old !hasSettledSourceRequest gate at the immediate public checkpoint. A new warm null-boundary cell covers a constructor-started on-demand sync run: it sees the first ordered request, but not the fallback or publication, at the immediate preload cut; after settlement it sees both requests, the four expected rows, and ready. The adjacent preload-started cell remains synchronously ready. The focused warm cells and all 277 ordered lifecycle tests passed with no type errors. Other adapters and a real on-demand React first commit remain outside these witnesses.

Post-publication oracle follow-up#

Reviewed oracle and coverage-map commit: 44cf62e2d9597e2a58a213d24c31e8733fdd2884 (parent 3aca442c6549048246379661f2dcc133f12d0d53). This section is a documentation follow-up to that exact code revision; the earlier ORC table describes the initial-fallback change.

The ordered-lifecycle oracle now exercises the publication/readiness distinction through the public live-query Collection. Its finite model joins three root rows to marker rows and takes the first eligible row in nulls-last order. An on-demand child holds Collection status at loading after root 1's first window publishes. Two legal marker histories, deletion and retargeting, remove root 1's match. The next ordered page supplies ineligible root 2 at a null boundary; a later unfiltered full-source request supplies eligible root 3. The controlled adapter evaluates request predicates and cursor expressions, sorts the requested page, and applies its writes before returning literal true.

The oracle checks the already public row and loading status at fallback entry, the pending child acquisition, the ordered page before the full-source request, the final public row, and the net delete/insert events. Its explicit getKey uses the root ID, so the comparison does not depend on the compiler's composite-key encoding. At each nonempty event callback, applying its changes to the prior public snapshot must reproduce the rows read in that callback. The net comparison allows either order for changes to distinct keys. It waits for the final public change rather than a fixed number of scheduler turns. It also keeps every callback-visible window within the one-row limit. The refinement check runs before cleanup so its mismatch remains the primary diagnostic if cleanup fails. It allows coherent intermediate publications and makes no synchronous-timing claim for work started after first publication. A temporary fault kept the full-source request and its reported served rows but dropped the newly delivered root 3 write. Both histories failed at the final public snapshot: the faulty run showed [] and ready instead of root 3 and loading. The fault was removed after calibration. Another temporary fault duplicated the recorded public event batch. Both histories failed at the net change-event comparison while their final rows remained correct; this fault was also removed.

At the reviewed code commit, all 279 ordered lifecycle tests and the DB test TypeScript check passed. Prettier and git diff --check passed. ESLint had no errors and one warning on an unchanged line. An independent source review found and prompted repairs to the key-encoding assumption, event order, page-before-fallback reach, pending-child reach, fixed-turn wait, callback window bound, and failure fidelity before this commit.

This is a controlled core witness for these two marker actions and one null boundary. It does not establish other provider delivery schedules, real adapter handoffs, or a first React commit over an on-demand source. The initial synchronous-cut histories above retain those separate limits.

Post-publication response schedules#

Reviewed oracle and coverage-map commit: 762a29a4e777629470b9011a6c17e537401f005d (parent 06ba31eaeecd44e5172391bbde9d3a72957ea29e). This section supplements the two-action post-publication record above; no production code changed.

The finite grammar now runs eight histories. Marker deletion and retargeting each cross a literal-true fallback, a Promise result after applied writes, and a fallback returning its held applied receipt while child demand remains pending. Each action also runs the held receipt after the child demand settles. All histories first observe row 1 published while that child demand still keeps the live-query Collection loading. The ready-child histories then await the initial preload and observe row 1 with ready status and no subset load in flight before changing the marker.

The held-receipt provider starts an optimistic update to an unselected root field after the ordered page applies. While its persistence is pending, root 3's full-source sync transaction has a pending applied receipt and root 3 is absent from the root Collection. The ready-child histories observe the public root and live-query isLoadingSubset flags become true at this held cut. After releasing the update, the driver waits for the public row-3 change and the relevant public loading-end signals before comparing the final window and change events with the finite join model. The marker mutation may publish an empty intermediate window or retain row 1; callback replay checks that each observed event matches its public snapshot. The final net delta must contain one delete for row 1 and one insert for row 3.

A temporary loader fault ignored the pending applied receipt while retaining the provider writes. All four held-receipt histories reached the comparison and failed at the public live-query loading flag: the faulty run reported false while the root receipt was still pending. The fault was removed. The normal eight focused histories and all 285 ordered lifecycle tests passed; DB test TypeScript, Prettier, and git diff --check passed. ESLint reported no errors and one warning on an unchanged line. Two independent oracle reviewers found and prompted repairs to an overstrict old-row intermediate assertion, a tautological response-kind check, unwitnessed blocker startup, dropped cleanup diagnostics, and a final checkpoint tied to one scheduler turn. A final read-only check found no race or cleanup defect in the revised event wait.

The Promise-after-applied-writes history exercises the asynchronous callback path and checks eventual public coherence. The architecture gives later full-source work no initial synchronous cut, so this case does not distinguish that Promise from a literal return at an immediate public checkpoint. A held Promise after applied writes with overlapping source changes remains for this owner to witness. The held isLoadingSubset comparison proves the public load tracker retains the applied receipt; it does not alone prove that every ordered publication participant waits for it. The row and event comparisons cover the named final checkpoint. Real provider handoffs and an on-demand React first commit remain outside this controlled core witness.

Later-fallback re-review at cdc370b04#

The initial synchronous cut ends when the first window publishes. A later full-source fallback without ordering-repair debt may complete in the same graph turn, but the contract does not require that timing. A controlled public probe observed row 3 and its change event before the marker transaction's commit() returned for literal true. Promise and held-receipt responses had not published row 3 at that cut. The oracle retains its coherence law across both schedules instead of turning the current later timing into a guarantee.

Two additional histories make the first ordered acquisition's adapter unload throw while a later literal-true fallback replaces it. The marker transaction's commit() still returns true; the successful row-3 window and its change event remain, and the live-query Collection reports error. A temporary fault that rethrew the already reported release error from the subscriber failed both histories at the marker commit. The direct loader's release-error tests continue to check its separate caller boundary.

The controlled providers now record applied-receipt shapes and compare them after production returns. Deliberately reversing one assertion inside the provider had previously produced six unrelated setup failures among the eight post-publication histories, showing how request-failure handling could hide the intended diagnostic. The architecture's prior statement that full-source repair keeps asynchronous settlement was restored; the untested broad publication-hold sentence added during this PR was removed. The changeset names the permitted later completion. Framework render timing remains outside the core cut, and the React first-layout-commit witness does not claim to cover Vue, Solid, Svelte, or Angular.

Held provider Promise across a later marker change#

Reviewed oracle and coverage-map commit: a613f96e07728257b543e65695dfc5266a5c8a70 (parent 1c557a4ddc7a03b08059ea2f069f26e6770de3dd). This section supersedes the earlier open held-Promise item above without changing that historical record. No production code changed.

The architecture requires coherent public windows and callback events when source changes overlap ordered work. It does not prescribe synchronous timing for a full-source fallback started after first publication. The finite grammar adds four histories: deletion or retargeting of marker 1, each with pending or settled child demand. The fallback applies root 3 and returns a Promise that remains pending while marker 2 retargets from root 3 to root 2. The independent join model predicts root 3 after the first marker action and root 2 after the second. A coherent root-3 window may publish before marker 2 changes; it may remain visible while the later change is pending. The oracle does not require or forbid either schedule.

The driver confirms that root 3 applied, the provider Promise remains pending, and the root Collection reports a pending subset at the overlap cut. It reads the public window before and after marker 2 changes, then compares the final window with the model. It replays every public change callback against that callback's visible rows. If root 3 published before the overlap, its insert and later delete are expected; an insert first published after the overlap is rejected. The provider request still has no predicate, cursor, order, limit, or offset. A synthetic wrong-result control adds a coherent stale root-3 publication and retraction after the correct root-2 result, leaving final rows unchanged. The event comparison rejects that control.

After the commit hook, the full ordered-lifecycle file passed 292/292 tests with no Vitest type errors; Prettier and git diff --check passed. ESLint had no errors and one warning on an unchanged line. A temporary loader mutant that replaced settlesAsync ? result : Promise.resolve() with Promise.resolve() survived all four new histories. This is a survival, not a kill: all provider writes in this fixture had already applied, and the source Collection still tracked the provider Promise, so these public cuts did not distinguish early loader completion. The mutant was removed. The new witness protects overlap publication and events, but it does not establish that the loader waits for provider settlement before claiming full-source authority when later provider writes or rejection are possible. That separate ordered-acquisition limit is retained in the coverage map.

Late provider write and acquisition lease#

Reviewed oracle and coverage-map commit: 2c01526a67d03040366922f2b78449b70374106b (parent ff23fd2ecd887cef39459add6aba925eb3b09dc6). This section follows the held-Promise overlap record above. No production code changed.

Four neighboring histories keep the same first marker deletion or retarget and pending or settled child demand. The full-source provider applies root 3, then holds its returned Promise. Marker 2 retargets from root 3 to the as-yet-absent root 4. After the gate opens, the provider applies root 4 before its returned Promise settles. The independent join model predicts root 4 at the final public checkpoint; callback replay and the net change comparison check the path to that result. The adapter also records acquisition unloads. The cursor-page lease must remain active at the held-Promise cut and retire after successful full-source settlement. This follows the architecture's rule that authoritative full-source success retires settled finite acquisitions; a pending provider answer has not established that success.

The normal focused histories passed, and the full ordered-lifecycle file passed 296/296 tests with no Vitest type errors. Prettier and git diff --check passed; ESLint had no errors and one warning on an unchanged line. A temporary loader mutant that replaced the provider Promise with Promise.resolve() failed all four new histories at the held cursor-page lease assertion. The provider entry and overlap cuts were reached, so these are intended-checkpoint assertion failures. The mutant was removed before the code commit. This closes the specific false-green result from the prior held-Promise histories: early loader completion can no longer pass this bounded late-write schedule. Provider rejection, overlapping root-source changes, real adapter delivery, and an on-demand React first commit remain outside this witness.