[Jose10go]

Fixes #2202
Electric progressive collections use core's on-demand sync mode, so initialRender currently rejects them. Allow local initial rendering only when the adapter can certify a previously completed full snapshot, with matching durable row-set evidence. Network synchronization continues in the background.

initialRender: {
  strategy: 'network-first',
  networkTimeoutMs: 0,
}

No caller-supplied progressive flag is required. A completed empty snapshot is eligible; an empty cold cache is not. Partial, legacy, reset, mismatched-shape, tag-dependent, and inconsistent-row-set caches cannot release initial rendering. Explicitly configured cursors cannot certify unseen rows as a full snapshot.

Changes across the monorepo:

• @tanstack/db: add an adapter-owned isPersistedSnapshotComplete capability and an unavailable persisted-readiness state. Failed network loads reject rather than hanging when no eligible snapshot exists.
• @tanstack/electric-db-collection: record completion with the rows and resume metadata when progressive full synchronization completes; expose the capability only for progressive collections. Resume legacy progressive caches conservatively with a fresh full sync.
• @tanstack/db-sqlite-persistence-core: hydrate a progressive startup baseline only after checking completion metadata and key-set evidence from the same atomic SQLite snapshot.
• Add regression coverage, documentation, and a changeset for all three runtime packages. React receiving tests cover Suspense waiting when the cache is unavailable.

Validation:

• Full Electric suite: 30 test files passed; Vitest reports 1,135 passed and 1 skipped, with no type errors.
• Persistence readiness oracle: 42 runtime and 29 type cases passed, including a 64-case outcome model, empty/nonempty progressive hydration before query demand, joins, restart, and unavailable-cache network failures.
• Electric SQLite receiving suite (included above): 40 runtime and 20 type cases passed. Completed and rejected cache cases use real SQLite with controlled SDK delivery. Full snapshots are saved and reopened without network delivery, including completed empty snapshots.
• Core observer/readiness regression suites: 82 tests passed. React Suspense suite: 31 tests passed.
• Additional persistence lifecycle, readiness exposure, and oracle suites passed.
• Calibration: bypassing completion certification makes partial, cold, and legacy receiving cases fail because they become wrongly eligible. The mutation was restored.
• DB core and both affected adapter/persistence package builds passed. ESLint reports no errors (20 existing warnings); formatting and git diff --check passed.

Tradeoffs and scope:

• Older progressive caches lack completion evidence and require one fresh full sync before local fallback becomes eligible.
• Startup restores the full cached collection, so local I/O, CPU, and memory costs still apply. A completed snapshot can be stale until background synchronization catches up.
• This changes the initial-render fallback contract; ordinary collection reads and useLiveQuery are not gated by it. Genuine on-demand collections remain unsupported.
• The adapter capability is a proposed public API for maintainer review. This does not claim full-monorepo, live Electric server, browser OPFS, multi-tab, or cache-rotation validation.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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]

Thank you for this PR, @Jose10go, and for the report that started this work.

We merged #2263 instead. It fixes #2202 without a new adapter API. With initialRender: { strategy: 'network-first' }, an on-demand persisted Collection, including Electric progressive, now works offline:

• A query whose exact demand settled online in an earlier session renders from SQLite after networkTimeoutMs. It renders at once if its upstream load fails.
• After a progressive full sync completes, a query that never ran is also ready offline, because Electric settles each later load at once from its complete rows. A shared-model history in the Electric receiving test checks this case.

Because of this, isPersistedSnapshotComplete is not necessary, so I am closing this PR. One limit stays open: an eager Collection that is legitimately empty still stays loading offline. That is a separate law, and we will track it apart from #2263.

This comment was written by Isaac.