Make initial sync errors final and report later failures as Collection health

Start with PLAN.md and the design folder in docs/contributing/designs/source-failure-and-health/ on the feat/source-health-channel branch, then the oracle at packages/db/tests/source-health-oracle.test.ts. Stage 1 is in packages/db, so read the health API there before touching any adapter. Done means the listed adapter and framework work lands, the oracle passes, and the breaking changeset ships. This is maintainer-led design work, not a first task.

Summary

Make an initial sync error final, and report problems after the first ready as health metadata instead of an error status. A live query exposes an errors tree for every Collection it depends on. This is a breaking change. Stage 1 (core) is done on the branch feat/source-health-channel (e8508df79). The plan, design, and TLA+ models are in docs/contributing/designs/source-failure-and-health/ on that branch.

Decisions

The maintainer made these decisions on 2026-10-13:

1. A retry that succeeds is a success. While a source retries, it reports nothing, and the Collection stays loading.
2. markError is final for its sync attempt. A source calls it only when it gives up. The framework never moves error back to ready.
3. Recovery is the app's job. cleanup() then preload(), a refetch, or a user refresh starts a fresh attempt.
4. A final initial error reaches every consumer, with its cause. Readiness waits reject, and live queries enter error for every shape. Suspense throws, and Effects are disposed.
5. status is only the initial gate. After the first ready, a sync failure is metadata on the Collection. The data stays, even if it grows stale.
6. useLiveQuery returns an errors tree. It has one node for each Collection the query depends on. The shape is always the same, and apps can parse it.
7. An Effect works the same as a query. Its gate is "every initial load settled", whatever skipInitial says.
8. IndexedDB closure stays a crash. A closed local store cannot recover.
9. Ordering. When both change, status:change fires before health:change, in the same tick.
10. The errors tree keeps stable object identity. A node changes only when something in its subtree changes.
11. TrailBase does not resubscribe after its stream ends. A stream end reports a final health error. Reconnect is for the TrailBase maintainers.

Done in stage 1 (packages/db)

• Lifecycle. error → ready is removed, and markReady() after markError() throws.
• Health API. The reportError(error, { final }) and reportHealthy() sync callbacks, Collection.health, and the health:change event. markError() after the first ready becomes a final health error, with a development warning.
• Live queries. A source failure before the first ready fails the query for every shape, and the old erroredSourceIds healing is removed. After the first ready, health does not change status or rows.
• The errors tree. One node per query alias, recursing through nested live queries, with stable identity. Include nodes carry instances: { total, inError }. A load that fails after the first ready is a request error, which clears when the load later succeeds or the demand is released.
• Effects. Every Effect gates on its initial loads. After the gate, problems reach onHealthChange, and the Effect is not disposed.
• Readers and docs. The observer and pooled views expose errors, and isError stays the gate. ARCHITECTURE.md has laws 16 and 17.
• Oracle. packages/db/tests/source-health-oracle.test.ts (property source-health.history) covers direct, join, self-join, nested, include, and pooled shapes, with request and Effect lanes. Base code fails 45 of 49 cells, and 16 mutants fail at assertions. The full @tanstack/db suite passes.
• Bugs found. A pooled view over a failed source reported isError: false. A second markError before ready replaced the first error.

Remaining work

The plan's checklist (PLAN.md, sections 3.2 to 3.6) has the details.

• Adapters.
  • Electric: change the markError calls after the first ready to reportError, and call reportHealthy() after recovery.
  • query-db: a successful refetch must not revive a failed initial load (query.ts, the markReady() call after an application).
  • PowerSync: replace the markError/markReady heal around the tracking rebuild.
  • TrailBase: a stream end reports a final health error.
  • RxDB and persistence: report health, and handle a follower's view of the leader's upstream health.
• Framework hooks. React, Vue, Solid, Svelte, and Angular return errors, and Suspense throws only for the initial gate. Add a health scenario to the shared conformance suite. Rebuild packages/db/dist first, because the framework packages read it.
• Docs.
  • error-handling.md, which contradicts itself on recovery today.
  • collection-options-creator.md, with the adapter rules.
  • live-queries.md, with the errors.hasErrors callout.
  • sqlite-persistence.md and offline-transactions.md.
  • The custom-adapter skill and the framework skills.
  • Do not edit generated reference docs.
• Release. A breaking changeset with a migration guide, then the pull request.

Open items

• Code weight. Production code in stage 1 is about +418 net lines in packages/db. Do a reduction pass before review.
• Effect request errors clear only when a later load of the same source succeeds. They do not clear when the failed demand is released, because failures are tracked per source.
• Pooled views end for good when their source is cleaned up, so the oracle skips restart steps for them.
• Review record. docs/contributing/oracle-reviews/progressive-source-readiness-tla/README.md, limit P6 ("disposes an Effect"), is now true only before the gate.
• Oracle review. No oracle-review has run on the health oracle yet.

Related: #2115, #2117, #2118, #2139.