Failing repro: loadSubset resolves & live query marks ready while synced rows are parked behind a persisting transaction

[TomasGonzalez]

What this is

A failing test (no fix) reproducing an on-demand loadSubset readiness bug in @tanstack/db. Opened as draft so the repro runs in CI — happy to turn it into a fix PR once maintainers weigh in on the approach.

• Adds packages/db/tests/query/load-subset-persisting-deferral.test.ts
• Control test passes; the persisting-transaction case fails (received []). Verified failing on current main (expected [] to deeply equal [ 'r1', 'r2' ]).

The bug

In on-demand sync mode, await loadSubset(...), collection.status === 'ready', and toArrayWhenReady() all resolve before the rows loadSubset fetched are readable, whenever any user transaction on the collection is in state persisting (an in-flight optimistic mutation).

commit() is fire-and-forget: commitPendingTransactions() in packages/db/src/collection/state.ts skips applying committed synced transactions while hasPersistingTransaction (guard: !hasPersistingTransaction || hasTruncateSync || hasImmediateSync), leaving the rows parked in pendingSyncedTransactions. Nothing downstream is signalled, so loadSubset resolves, the live query calls markReady(), and the read returns []. The rows become readable only when the mutation settles.

The test's loadSubset begins/writes/commits synchronously then resolves — exactly what @tanstack/electric-db-collection does inside its subscribe handler on a subset-end control message before requestSnapshot resolves. @electric-sql/client is not involved and not at fault (it delivers to subscribers before resolving since 1.5.20).

Why it matters

Downstream (offline-first apps using @tanstack/offline-transactions) this surfaces as silently empty/partial reads whenever a background write is in flight — e.g. duplicating a template's child rows into a new record returns nothing. Settle-window/timer workarounds cannot recover the rows, because a parked commit emits no change events until the transaction settles.

Possible fixes (happy to implement)

• loadSubset shouldn't resolve until its synced transaction(s) are applied (e.g. commit() returns a promise / a whenApplied() signal). This also fixes the DeduplicatedLoadSubset coverage-poisoning, since tracking runs on resolution.
• Or commit subset-snapshot data with begin({ immediate: true }) (already bypasses the guard; used today for resume-metadata resets). Authoritative server rows have nothing to reconcile against.
• Or make live-query readiness account for committed-but-parked synced transactions.

Related

• Synced data does not appear in a derived (live query) collection while there is a pending optimistic mutation. #1017 — same underlying deferral (fix attempt [fix] synced data not appearing in derived collection during pending optimistic mutation (issue #1017) #1167 closed unmerged); this adds the readiness/loadSubset composite on top.
• RFC: Fixing the loadSubset / pagination core (no new features) #1657 — loadSubset / pagination RFC; this failure mode isn't listed there yet.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d02df8b9-0c7a-4a41-b5ee-c2f477ad9b3c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[KyleAMathews]

Thanks for the excellent reproduction — this is exactly the kind of report that's easy to act on.

We verified it against main: the control case passes and the persisting case fails precisely as you described (expected [] to deeply equal ['r1','r2']), and the mechanism checks out — the commitPendingTransactions guard silently parks committed synced transactions with no downstream signal, commit() returns void, and DeduplicatedLoadSubset records the predicate as covered on resolution, so retries can't recover. We also confirmed your begin({ immediate: true }) direction makes the repro pass, though with the caveat that an immediate commit flushes all parked sync transactions.

This is now tracked in the loadSubset/pagination RFC (#1657) as evidence item E13 with a dedicated work item (§3.8): loadSubset resolution must mean the rows are actually applied — your test is the red test for it. A maintainer will be picking up the RFC work soon, and we'd rather land this as a proper fix at the contract level within that effort than as a one-off patch — that's the whole point of the cluster analysis. We'll keep this PR open for its repro until then.