feat(db): opt in to provisional initial ordered results

[alec-watts]

Observed limitation

Kino uses ordered on-demand queries over locally available rows. When the ordered provider subset is still pending, the initial live-query Collection stays empty even though matching cached rows exist. Rendering those rows sooner currently requires a local patch.

This proposes an opt-in publishUnconfirmedOrderedResults option. The default remains to withhold the initial ordered window. With the option enabled, available local rows can publish while the initial Collection is loading, but initial-query readiness and preload() still wait for provider coverage. Cached order is not authoritative: missing provider rows can change window membership and order.

The change extends the existing publication gate; it does not add a parallel loading or persistence mechanism. Failure, replay, repair, and joined-demand holds stay intact. Explicit window moves stay atomic, including a move started while the initial Collection is still loading.

React already forwards config through the shared query resolver, so no duplicate hook forwarding path is needed on current main. The option participates in derived config identity so switching publication policy does not reuse a Collection with the previous policy. No generated/dist files are committed.

Related upstream work

• feat(db): add network-first initial rendering for persisted collections #1955 adds persisted readiness and network-first rendering for eager persisted sources, and explicitly rejects on-demand initial rendering.
• fix: restore warm on-demand query readiness #1860 restores warm on-demand readiness when retained demand is already satisfied.
• fix: preserve synchronous readiness for ordered live queries #1896 preserves synchronous ordered readiness when every acquisition settles synchronously. It deliberately retains asynchronous behavior for pending provider work.

Searched open PRs and exact option/provisional/unconfirmed/cached-ordered/on-demand-ordered terms before preparing this proposal; no equivalent opt-in asynchronous initial-publication PR was found.

Verification

• Demonstrated the missing behavior before the source change: opt-in initial local window expected [1], observed []; default hold control passed.
• pnpm install --frozen-lockfile using repository-pinned pnpm 11.1.0.
• Builds: @tanstack/db-ivm, @tanstack/db, @tanstack/react-db.
• DB ordered loader, loader-state and live-query Collection suites: 237 tests passed before the additional initial-move regression.
• DB live-query Collection, ordered lifecycle oracle, pagination oracle and live-query options suites: 651 tests passed.
• React useLiveQuery suite: 60 tests passed, including opt-in/default forwarding, readiness, and option-identity rerender coverage.
• Final DB live-query Collection suite: 124 tests passed, including the added move-during-initial-loading regression.
• Changed-file ESLint and git diff --check passed.
• Tests cover indexed and unindexed initial windows, provider rows replacing the cached top row while readiness is false, preload waiting for coverage, and atomic pagination after readiness and during initial loading.

These are scoped package checks, not a claim that the entire monorepo or real provider/network/browser matrix was tested. The new focused traces exercise the public Collection and React observation cuts; existing ordered/pagination oracles continue protecting the default atomic policy.

Why each file changes

File	Reason
packages/db/src/query/live/types.ts	Define and document the opt-in publication option and its limits.
packages/db/src/query/live/collection-config-builder.ts	Relax only the initial ordered-request publication hold; preserve other gates.
packages/db/src/live-query-options.ts	Include publication policy in derived config identity.
packages/db/tests/query/live-query-collection.test.ts	Check provisional rows versus readiness, provider replacement, indexed/scan paths, and atomic window moves.
packages/react-db/tests/useLiveQuery.test.tsx	Verify existing hook config forwarding, loading/readiness, and policy changes on rerender.
packages/db/src/query/live/ARCHITECTURE.md	Document the deliberate opt-in exception to initial atomic publication.
docs/guides/live-queries.md	Explain usage, non-authoritative cached ordering, and readiness/Suspense/authorization caveats.
.changeset/provisional-initial-ordered-results.md	Request a DB minor release for the new public option.

Diff cleanup found no formatting-only churn, parallel mechanism, or abandoned exports. Production change is 18 added lines and 1 removed line; tests and contract/docs are separate. Kino's local patches remain unchanged until an upstream release is available and verified.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3ca3769

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 29 packages

Name	Type
@tanstack/db	Minor
@tanstack/angular-db	Patch
@tanstack/capacitor-db-sqlite-persistence-e2e-app	Patch
@tanstack/db-sqlite-persistence-core	Patch
@tanstack/electric-db-collection	Patch
@tanstack/expo-db-sqlite-persistence-e2e-app	Patch
@tanstack/offline-transactions	Patch
@tanstack/powersync-db-collection	Patch
@tanstack/query-db-collection	Patch
@tanstack/react-db	Patch
@tanstack/rxdb-db-collection	Patch
@tanstack/solid-db	Patch
@tanstack/svelte-db	Patch
@tanstack/tauri-db-sqlite-persistence-e2e-app	Patch
@tanstack/trailbase-db-collection	Patch
@tanstack/vue-db	Patch
todos	Patch
offline-transactions-react-native	Patch
shopping-list-react-native	Patch
@tanstack/db-example-react-next-ssr-e2e	Patch
@tanstack/db-example-paced-mutations-demo	Patch
@tanstack/browser-db-sqlite-persistence	Patch
@tanstack/capacitor-db-sqlite-persistence	Patch
@tanstack/cloudflare-durable-objects-db-sqlite-persistence	Patch
@tanstack/electron-db-sqlite-persistence	Patch
@tanstack/expo-db-sqlite-persistence	Patch
@tanstack/node-db-sqlite-persistence	Patch
@tanstack/react-native-db-sqlite-persistence	Patch
@tanstack/tauri-db-sqlite-persistence	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[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

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

Autopilot is currently an internal CodeRabbit preview.

---

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.}