Plan: final initial errors and the source health channel#

Superseded (2026-10-16). The error surface was redesigned: status crashed, node failureReason/error, fail(), reload(), and collection.health. Read error-surface/README.md and error-surface/RULES.md, the shipped docs/guides/error-handling.md, and packages/db/src/query/live/ARCHITECTURE.md laws 14, 16, and 17.

Status: implemented on feat/source-health-channel; the pull request is next. It ships as one pull request, because it is a breaking change and a significant product change. It replaces #2129. Later decisions (2026-10-14): a crashed Collection ends every live query and Effect above it; terminal local persistence failures crash; request stays the public phase name; a live query's Collection health includes its request errors. markError means the sync adapter gave up in both phases, so reportError has no final option and nothing warns; query-db's error utilities and the infinite query's error field give way to Collection health.

Branch: feat/source-health-channel (worktree .worktrees/source-health-channel).

1. Decisions (maintainer, 2026-10-13)#

1. A retry that succeeds is a success. While the sync adapter retries, it reports nothing. The Collection stays loading. (Already in #2127 for Electric.)
2. markError is final for its sync run. A sync adapter calls it only when it gives up. The framework never heals a sync run: no error → ready.
3. Recovery is the app's job. cleanup() then preload(), a refetch, or a user refresh starts a fresh attempt. The framework adds no retries.
4. A final initial error reaches every consumer with its cause: readiness waits and one-shot reads reject, live queries enter error for every shape, Suspense throws, Effects are disposed through onSourceError, and subscribers get lastError and loadSubset:error.
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 health tree for every collection the query depends on. It always has the same shape, shows whether each node is in error, and carries detailed error info, so apps can parse it.
7. A buggy source or an app with endless retries can still look stuck. That is a plugin or app problem, not a framework guarantee.
8. Generated API reference docs are produced on release by an automated pull request. Do not edit them in this pull request.

Rationale and controls: README.md (failure-law grammar, SourceFailure.tla, 10 configurations) and HEALTH-CANDIDATE.md plus SourceHealth.tla (health channel, 6 configurations). The user-facing target is USER-DOCS-DRAFT.md (candidate v2).

2. Target design (candidate v2)#

Summarized from USER-DOCS-DRAFT.md; that file is the source of truth for names and shapes.

• Two axes. Gate: status (idle | loading | ready | error | cleaned-up), decided only by an attempt's initial sync. Health: per Collection, changed only by its sync adapter after Collection readiness.
• Adapter API. Sync params gain reportError(error) and reportHealthy(). markError means the sync adapter gave up: an initial error before Collection readiness, a final health error after it. markReady() after markError() in one sync run throws.
• Collection surface. collection.health and a health:change event.
• Error info. { phase: 'initial' | 'sync' | 'request', final, name, message, code?, at, cause }. Everything except cause is JSON-safe.
• Health tree. HealthNode = { alias, collectionId, kind: 'source' | 'live-query' | 'include', status, isError, hasErrors, error, instances?, sources }.
  • One node per query alias, in query order, fixed by the query definition (fracture F-a). A self-join appears once per alias.
  • An include has one node for all its per-row child Collections, with instances: { total, inError }.
  • Nested live queries recurse.
  • Healthy nodes are present with isError: false.
• Final flag (fracture F-b). final: true means the sync adapter stopped trying; only a restart clears it. reportHealthy() cannot clear it.
• Request errors (fracture F-c). A load for new demand that fails after Collection readiness sets phase: 'request' on the live-query node that issued it. The Collection stays healthy. It clears when that demand later settles or is released.
• Hooks. Return health beside data. isError keeps meaning "the initial gate is error". Docs lead with health.hasErrors for stale data.
• Effects. onHealthChange(health) after Collection readiness; no disposal. Initial gate errors still dispose through onSourceError.
• SSR. health is not dehydrated; the client builds its own tree.

3. Work breakdown#

3.1 Core: packages/db#

• collection/lifecycle.ts: remove error → ready from the valid transitions. markReady() after markError() in the same sync run throws. Keep error → cleaned-up and idle.
• collection/lifecycle.ts / sync.ts: add Collection health state, reportError, reportHealthy, the final rule, and reset on cleanup and restart. Scope the callbacks to the sync-run epoch so a stale sync run cannot report.
• collection/events.ts: add health:change to AllCollectionEvents. Define the payload (previous, current) and the ordering: same tick, after status:change when both change (the ordering is still to be checked).
• types.ts: SyncConfig params, CollectionErrorInfo, HealthNode, and the Collection.health and health types.
• markError after the first ready: forward to reportError(error, { final: true }) and warn in development.
• query/live/collection-config-builder.ts:
  • a Collection entering error before the live query's initial-query readiness stays a gate error for every shape (root, join, include alike);
  • remove the erroredSourceIds recovery path (line ~1131) and its status-based healing;
  • post-readiness Collection health does not change the live query's status or rows;
  • build and maintain the health tree: per-alias nodes, include roll-ups, nested live-query relay, and request errors;
  • failDemand and recordSubsetError: before ready, terminal (gate); after ready, a request error on the live-query node, cleared on settle or release.
• collection/subscription.ts: keep lastError and loadSubset:error for every rejected load (#2129 review C8). Do not detach demand for recovery.
• query/effect.ts: onHealthChange; no disposal after Collection readiness.
• live-query-adapter.ts and live-query-observer.ts: add health to the snapshot and status flags, so every framework adapter gets it from one place. Keep isError as the gate.
• query/live/pooled-live-query*: decide and implement health for pooled views that share sources (open question).
• query/live/ARCHITECTURE.md: replace #2129's law 16 with the final error law and the health channel law. Update the cleanup and restart section.

3.2 Adapters#

• Electric (electric-db-collection/src/electric.ts, 9 call sites):
  • post-readiness markError at :2628 and :2708 becomes reportError (final per site);
  • reportHealthy() after the next successful up-to-date following a problem;
  • the SDK give-up path: before Collection readiness, markError; after it, reportError(..., { final: true }). This extends #2127's E1 fix.
• query-db (query-db-collection/src/query.ts, 6 sites):
  • a failed refetch after readiness calls reportError; a successful result after a problem calls reportHealthy();
  • :2556: no markReady() when the status is error (V1);
  • keep utils.lastError, utils.isError, and utils.errorCount, and state how they relate to Collection health (assay compromise).
• PowerSync (powersync-db-collection/src/powersync.ts, 6 sites): a failed tracking rebuild at :826 calls reportError; a successful rebuild at :813 calls reportHealthy() instead of markReady() (V2, post-readiness health).
• TrailBase (trailbase-db-collection/src/trailbase.ts, 4 sites): post-readiness stream failures call reportError. Check them against the #2126 fix.
  • A stream that ends, whether it closes or health, reports reportError(error, { final: true }) after Collection readiness. The adapter does not resubscribe. The trailbase SDK (0.10.0) has no reconnect or resume: subscribe is one fetch stream, and subscribeWs closes without retrying. A correct reconnect would have to subscribe again and re-list every active subset. The maintainer decided to leave reconnect to the TrailBase maintainers.
  • Update the stream-end lane in tests/lifecycle-oracle.property.test.ts (added in #2126) from "rows stay, later changes are not delivered" to also expect a final health error.
• RxDB (rxdb-db-collection/src/rxdb.ts): no change. V10 is closed by inspection: RxDB is eager and has no loadSubset, so a final error has no pending subset loads; its only failure path is the initial fetch, which calls markError before Collection readiness and rejects readiness waiters under the core initial-error law. Open: the rxCollection.$ subscription has no error handler, so an RxDB stream failure after readiness is not reported at all. Reporting it as a final health error needs an RxDB fault a test can drive; owner: RxDB adapter, witness: an observable error after readiness.
• Persistence (db-sqlite-persistence-core/src/persisted.ts, 19 sites):
  • forward upstream Collection health; keep local storage failures on persistedError;
  • follower tabs learn the leader's upstream health through the coordinator (open question);
  • check the browser and Electron hosts, and the node host.
• Local-only and local-storage Collections: confirm they never need health, and document it.

3.3 Framework hooks#

• React, Vue, Solid, Svelte, and Angular return health from every live-query hook, including infinite-query hooks and useLiveSuspenseQuery.
• Suspense: throws only for the initial gate, never for post-ready health.
• Decide whether health keeps stable node identity for memoization (open question).

3.4 Tests and oracles#

• Flip the #1751 healing tests on purpose: each one that asserts error → ready becomes "stays error; recovery needs a restart". Search collection-health.test.ts, live-query recovery tests, and query-db and PowerSync recovery tests.
• A new oracle owner for the health channel, from SourceHealth.tla's properties: stable shape, mirroring through nested live queries, only the source clears, gate independence after ready, gate explained by a node, final not clearable, and request errors that clear on settle or release. Extend the topology beyond the TLA model: a collection reached by two aliases, includes with per-row children, and pooled views.
• Model D (includes-temporal-oracle.test.ts): rework the source-error lane to the final-error law. Start from evidence/ model-d-source-error-grammar.patch (the C4, C5, and C6 grammar dimensions: truncate during the error, ready → error, exact acquisitions, and every source-ready position). Under the new law, source-ready after source-error in one sync run is illegal, so those histories become "restart, then recover".
• Shared framework conformance suite (packages/db/tests/conformance/): a health scenario, so all five drivers check health the same way.
• Adapter witnesses: each adapter reports post-ready failures through health and keeps its rows. Electric adds SDK give-up cases through the real SDK (missing headers, retry exhaustion).
• Mutant calibration for each new law, including the TLA weakenings: health flips status, nested live query doesn't relay, framework clears, healthy nodes dropped, failure clears rows, heal on ready, framework retry.
• Rerun the #2129 review probes in evidence/ pr-2129-review-probes.test.ts.txt against the new law. Several expectations change, because recovery now needs a restart.

3.5 Hand-written docs (not generated reference)#

• docs/guides/error-handling.md: rewrite the collection error sections around the two axes. Remove the contradiction between line ~361 (manual recovery) and line ~534 (a refetch recovers).
• docs/guides/collection-options-creator.md: the adapter rules from USER-DOCS-DRAFT.md (stay silent while retrying; markError only when giving up before Collection readiness; reportError and reportHealthy after readiness; never drop rows).
• docs/guides/live-queries.md: the health tree and the isError / health.hasErrors callout.
• docs/guides/sqlite-persistence.md, docs/guides/offline-transactions.md: upstream Collection health against persistedError.
• docs/health.md: the markReady-after-markError contract error, and any new error code.
• docs/collections/electric-collection.md: onError retries are silent; a give-up is final; post-readiness health.
• docs/collections/local-storage-collection.md: check its error-state wording.
• docs/collections/query-collection.md (if present): how utils relate to health; recovery by restart.
• Package skills: packages/db/skills/db-core/custom-adapter/SKILL.md (remove "later successful work in the same sync run can call markReady() to recover", line ~349, since recovery now requires a restart), and the React, Vue, Solid, and Angular skill files. Confirm with the maintainer that these package skills are in scope.
• Package READMEs that mention isError (for example packages/angular-db/README.md).
• docs/contributing/oracle-coverage.md: the new health owner, and the Model D source-error lane.
• docs/contributing/oracle-reviews/progressive-source-readiness.md: record the decided law and the companion fixes (#2126, #2127, #2128). #2129 carried this update and is being replaced.

3.6 Release#

• Changeset: a breaking change for @tanstack/db and every adapter that changes. Include a migration guide:
  • an initial error no longer heals; recover with cleanup() and preload();
  • after Collection readiness, failures no longer move a Collection or a live query to error; read health;
  • adapter authors: reportError and reportHealthy;
  • markReady() after markError() now throws.
• PR body: the decisions above, the design, the evidence, and the breaking changes.

4. Order of work#

1. Merge #2126, #2127, and #2128 after their review findings.
2. Close #2129 in favor of this pull request, and move its review-record update here.
3. Core lifecycle and the health channel, with the health oracle first (RED, then GREEN).
4. Live queries: the gate for every shape, then the health tree, then request errors.
5. Effects, then the observer and status flags, then the hooks and the conformance suite.
6. Adapters, one at a time, each with witnesses.
7. Docs, then the changeset and the PR body, then review and CI.

5. Open questions#

• The health:change ordering relative to status:change (proposed: same tick, after it). Model-check it before relying on it.
• How follower tabs learn the leader's upstream health.
• Health for pooled live queries that share sources.
• Stable node identity in health for memoization.
• Which semver bump the packages get, given the 0.x line.
• Whether the shipped package skills are in scope for edits.

6. Carried from the reviews#

• #2129 C1, C2, C3, C7, C9, C10, and S1 concerned recovery machinery that this design removes. Recheck them against the new law using the probes in evidence/.
• #2129 C8 (keep reporting lastError and loadSubset:error) is decided yes. It is in 3.1.
• #2129 C4, C5, and C6 (Model D grammar gaps) carry over in 3.4.
• #2127 E1 (an SDK give-up must be reported) is fixed in #2127 for the initial gate. The post-readiness half is in 3.2.