KyleAMathews · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026
diff --git a/.changeset/persisted-initial-render-split.md b/.changeset/persisted-initial-render-split.md
diff --git a/.changeset/source-health-channel.md b/.changeset/source-health-channel.md
@@ -0,0 +1,38 @@
+---
+'@tanstack/db': minor
+'@tanstack/db-sqlite-persistence-core': minor
+'@tanstack/electric-db-collection': minor
+'@tanstack/powersync-db-collection': minor
+'@tanstack/query-db-collection': minor
+'@tanstack/rxdb-db-collection': minor
+'@tanstack/trailbase-db-collection': minor
+'@tanstack/react-db': minor
+'@tanstack/vue-db': minor
+'@tanstack/solid-db': minor
+'@tanstack/svelte-db': minor
+'@tanstack/angular-db': minor
+---
+
+Collections now answer two questions separately: can the data be shown (`status`), and is it still kept up to date (`health`). Once a query has shown data, a network or backend failure never takes it off the screen.
+
+- `status` gains `crashed`: local storage broke (a closed IndexedDB connection, a failed SQLite persistence write or restore, a throwing sync function, or an invariant failure). Nothing recovers it in place, and `reload()` rejects. To recover, call `cleanup({ dependents: true })`, then start the Collection again (for example with `preload()`); it starts with no rows. It reaches every live query and Effect above it. `error` now means only "the first load failed".
+- Every Collection has `collection.health`, a health node with `status`, `failureReason` (the adapter is still trying), `error` (the adapter stopped, or the first load failed), `reloading`, and `hasErrors`. A live query's `health` has one node per source alias, in query order, and keeps object identity while unchanged. `health:change` fires when it changes. `findProblems(health)` lists the nodes that have a problem, in query order. After a live query is ready, a failed request for more data (a page, a joined row, or a source reload's replay of its data) is an `error` on the query's own node; the source stays healthy.
+- `collection.reload()` starts a new sync run and keeps the rows, status, and error on screen until the new run commits. On a live query it reloads every Collection below it that shows an `error`, through nested live queries, then the query itself when its own node has an `error`, including a failed request for more data. It rejects on a `crashed` Collection. When the cleanup of the sync run that a reload retired rejects, the Collection crashes, also if the rejection comes later. A query in `error` stays there until its `reload()`.
+- `cleanup()` rejects with `CollectionHasSubscribersError` while a live query with subscribers or an Effect reads the Collection. `cleanup({ dependents: true })` ends them first. `collection.subscribers` lists every dependent.
+- Persisted Collections have one status. With `initialRender: { strategy: 'network-first' }`, restored rows make the Collection `ready` once the deadline passes or the remote fails; an empty restore stays `loading`.
+
+Breaking changes and migration:
+
+| Before                                                                                                      | After                                                                                            |
+| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| hook `isError`                                                                                              | `isLoadingError` (first load failed) or `isCrashed`                                              |
+| —                                                                                                           | `isSyncError`: `ready` and the health tree has a problem                                         |
+| `status: 'error'` after a crash                                                                             | `status: 'crashed'`                                                                              |
+| adapter `markError(error)`                                                                                  | `fail(error)`. After readiness it sets the node's `error` and keeps the rows. Later calls throw. |
+| `cleanup()` then `preload()` to recover                                                                     | `reload()`                                                                                       |
+| `cleanup()` while live queries or Effects read the Collection                                               | rejects; unmount first or pass `{ dependents: true }`                                            |
+| `persistedStatus`, `isPersistedReady`, `persistedError`, `preloadForInitialRender()`, `PERSISTED_READINESS` | `status` and `health`                                                                            |
+| query-db `utils.lastError`, `utils.isError`, `utils.errorCount`, `utils.clearError()`                       | `collection.health`, `reload()`                                                                  |
+| infinite-query hooks' `error` (React, Vue, Svelte)                                                          | the root node's `error` in `health`; `fetchNextPage()` still resolves                            |
+
+Custom sync adapters: keep the run's readiness in your `sync` function. A reload calls `sync` again while `collection.status` still shows the previous run's status, and a reload replaces every row at the new run's first commit, so write a full snapshot then. `reportError()` and `reportHealthy()` throw before the first `markReady()`. `markReady()` after a failed first load throws. Calls after a crash do nothing. For an on-demand Collection, a reload aborts the retired run's `loadSubset` calls and asks the new run's `loadSubset` for the current demand as soon as `sync` returns. Honor the `signal`: a load that ignores the abort holds a query's first load until it settles. `useLiveSuspenseQuery` now throws the first load's original cause instead of a generic error.
diff --git a/docs/collections/electric-collection.md b/docs/collections/electric-collection.md
@@ -407,9 +407,17 @@ rather than when its durable-cache notification arrives. Outside scoped
 recovery, coordinator invalidation retains its normal behavior.
 
 An eager or progressive resume cannot apply a partial update to an unknown row.
-The adapter rejects that batch, enters an error state, and records a reset so the
-next sync starts from a full snapshot. This does not silently retry the failed
-stream. Complete updates from an explicit `replica: 'full'` stream remain valid.
+The adapter rejects that batch, stops the stream, and records a reset so the
+next sync starts from a full snapshot. Before the Collection is ready, this
+fails the first load (`status: 'error'`); after it, the rows stay and the
+source node shows an `error` in `collection.health` and in each live query's
+`health` tree. This does not silently retry the failed stream;
+`collection.reload()` refetches.
+
+While the Electric stream retries a failed request, the Collection reports
+nothing: it stays `loading` before its first up-to-date, and keeps its health tree
+unchanged afterward. When the stream gives up, it calls `fail()`: a failed first load
+before readiness, or the source node's `error` after it. Complete updates from an explicit `replica: 'full'` stream remain valid.
 On-demand streams can observe updates outside their loaded subsets; unknown
 partial rows are ignored, while transaction acknowledgement evidence is retained.
 Outside scoped recovery, complete rows published by persistence reloads or

diff --git a/docs/collections/indexed-db-collection.md b/docs/collections/indexed-db-collection.md
@@ -278,7 +278,7 @@ db.close()
 ```
 
 Connections created by `createIndexedDB` close automatically on native
-`versionchange`. Unexpected native connection closure also notifies their managed Collections. In both cases, active Collections enter `error`.
+`versionchange`. Unexpected native connection closure also notifies their managed Collections. In both cases, active Collections crash: they enter `error` even after they were ready, and so does every live query and Effect over them.
 The descriptor's `db.close()` method has the same local effect. Their last
 published rows remain available. Recreate affected Collections with a new
 instance using the current database version. Calling the raw `db.db.close()`

diff --git a/docs/collections/query-collection.md b/docs/collections/query-collection.md
@@ -388,8 +388,8 @@ In eager mode, direct write utilities such as `writeInsert`, `writeUpdate`, and
 In both modes, a direct cache patch leaves Query's error, invalidation, and
 freshness state intact. A direct write is not a successful fetch: an eager
 query that failed still reports that error, and a stale eager query may fetch
-on remount. Use `utils.clearError()` to retry after an error, or
-`utils.refetch()` when you need fresh server results.
+on remount. Use `utils.refetch({ throwOnError: true })` to retry after an
+error, or `utils.refetch()` when you need fresh server results.
 
 This works automatically when `select` returns the wrapper's array property itself, as in these simple wrappers:
 
@@ -637,8 +637,8 @@ starts first. It includes calls through the handler parameter, captured or
 external Collection references, manual transaction mutation functions, and
 `createOptimisticAction` mutation functions. Code can await the mutation's
 `isPersisted.promise` when it needs the complete transaction and its queued
-Collection application. Utilities that refetch, including `clearError()`,
-inherit the same phase boundary.
+Collection application. Utilities that refetch inherit the same phase
+boundary.
 
 The handler's `collection` parameter and every matching
 `transaction.mutations[n].collection` alias preserve the external Collection
@@ -682,8 +682,14 @@ The collection provides these utility methods via `collection.utils`:
   - Bypasses `enabled: false` to support imperative/manual refetching patterns (similar to hook `refetch()` behavior)
   - Returns the tracked Queries' `QueryObserverResult` values in tracked-key order
   - Preserves an `undefined` slot if a tracked Query is removed while the refetch starts
-- `clearError()`: Refetch with errors enabled; retain the recorded error until a successful result applies to the Collection
-  - Uses the same phase-dependent boundary as `refetch()`. During a mutation handler, the promise can resolve at the fetch boundary before the result applies and clears the error.
+
+Failures appear in the health tree. Before the first successful result, a
+failed fetch fails the first load (`status: 'error'`). After the Collection is
+ready, a failed fetch or result application for any Query it observes sets the
+node's `failureReason`, because TanStack Query fetches again, and the next
+successful application clears it. Read it from `collection.health` or a live
+query's `health` tree. To retry a failed first load, call
+`collection.reload()`.
 
 ## Direct Writes
 

diff --git a/docs/contributing/designs/source-failure-and-health/HEALTH-CANDIDATE.md b/docs/contributing/designs/source-failure-and-health/HEALTH-CANDIDATE.md
@@ -0,0 +1,160 @@
+# Candidate: the source health channel and live-query health tree
+
+> **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: superseded candidate design, version 1. It came from a Field Lab
+design-grammar run. The shipped design differs; read `PLAN.md`, the shipped
+guides, and `packages/db/src/query/live/ARCHITECTURE.md` laws 16 and 17.
+
+## Success standard (frozen, user-confirmed)
+
+- H1 After the first ready, a sync failure is metadata. Status stays `ready`;
+  data stays, even if increasingly stale.
+- H2 Before the first ready, the gate is unchanged: a final failure is
+  `markError`, reaches every consumer, and readiness waits reject.
+- H3 The framework never heals or retries. Health reports what the source last
+  said; only the source clears its failure by reporting healthy sync again.
+- H4 A live query carries its sources' health, through joins, includes, and
+  nested live queries.
+- H5 Hooks expose health without changing data, `isReady`, or `status`. No
+  flicker; Suspense does not throw after ready.
+- H6 (open) A subset load for new demand that fails after ready is decided
+  per request: it affects the requesting query, not the source.
+- H7 One adapter API reports post-ready failures, replacing today's mix of
+  ready-to-`error` transitions and adapter utilities.
+- H8 query-db's `utils.lastError`, `isError`, and `errorCount` keep working.
+- H9 An Effect hears about health changes after ready instead of being
+  disposed.
+- H10 A persisted collection keeps serving local rows when upstream sync fails
+  after ready; health says upstream is degraded.
+- H11 `useLiveQuery` returns an `health` structure describing the tree of
+  collections it depends on. It always has the same shape, shows whether each
+  node is in error, and carries detailed error info when in error, so apps
+  can parse it.
+
+Prior law (frozen earlier): a source either keeps trying (loading), becomes
+ready, or reports a final error for its sync attempt; the framework never
+heals an attempt; recovery is app-level (`cleanup()` then `preload()`).
+
+## Source trace (current code)
+
+- Status is the only propagated channel: live queries handle sources'
+  `status:change` (`db/src/query/live/collection-config-builder.ts:1104`);
+  hooks derive `isError` from status (`react-db/src/useLiveQuery.ts`).
+- Electric (`electric.ts:2628, 2708`) and PowerSync (`powersync.ts:826`)
+  switch a ready collection to `error` after ready; PowerSync then heals with
+  `markReady` (`powersync.ts:813`).
+- query-db exposes `utils.lastError`, `isError`, `errorCount`, reset after a
+  successful result (`query-db-collection/src/query.ts:325-332`).
+- Hooks already expose a parallel metadata channel for persistence:
+  `persistedStatus`, `persistedError` (`react-db/src/useLiveQuery.ts`).
+- A live query's direct sources come from `extractCollectionSources(query)`
+  (`collection-config-builder.ts:197`); a source can itself be a live-query
+  Collection.
+
+## The candidate
+
+### Two independent axes
+
+- **Gate (`status`)**: `idle | loading | ready | error | cleaned-up`. Decided
+  only by the initial sync of an attempt. Unchanged from today except that
+  `error` is final for the attempt.
+- **Health**: `healthy | error`, plus error info. Meaningful after the first
+  ready. Only the source changes it.
+
+### Adapter API (sync function params)
+
+```ts
+sync: ({ begin, write, commit, markReady, markError, reportError, reportHealthy }) => { ... }
+```
+
+- `markError(error)` before the first ready: the final initial failure (gate).
+- `reportError(error)` after the first ready: health becomes `error` with this
+  cause. Status and rows do not change.
+- `reportHealthy()`: the source has synced successfully again; health becomes
+  `healthy`.
+- `markError(error)` after the first ready is forwarded to `reportError(error)`
+  with a development warning, so existing adapters keep working while they
+  migrate.
+- Calling `markReady()` after `markError()` in one attempt throws (contract
+  violation).
+
+### Collection surface
+
+```ts
+collection.health // { isError: boolean, error: CollectionErrorInfo | null }
+collection.on('health:change', (event) => { ... })
+
+type CollectionErrorInfo = {
+  phase: 'initial' | 'sync' | 'request'
+  name: string
+  message: string
+  cause: unknown
+  at: number // epoch milliseconds
+}
+```
+
+`phase: 'initial'` mirrors a gate `error`; `phase: 'sync'` is a post-ready
+health report; `phase: 'request'` is a subset load failure (H6).
+
+### The health tree
+
+Every live-query Collection exposes `health`, and every framework hook returns
+it beside `data`:
+
+```ts
+type HealthNode = {
+  collectionId: string
+  kind: 'source' | 'live-query'
+  status: CollectionStatus          // the node's gate
+  isError: boolean                  // this node: gate error, health error, or request error
+  hasErrors: boolean                // this node or any descendant
+  error: CollectionErrorInfo | null // detail when isError
+  sources: Array<HealthNode>     // dependencies; [] for a base source
+}
+```
+
+- The root is the live query itself. Its `sources` are the query's
+  collections in query order (`from`, then joins, then includes), each
+  recursing through nested live queries.
+- The shape is fixed by the query: every dependency is present whether or not
+  it is in error. A collection reached by two paths appears once per path.
+- Nodes mirror their collections in the same update as the change.
+- A post-ready request failure (H6) sets `error` with `phase: 'request'` on
+  the live-query node that issued the request. The source stays healthy.
+- `isError` on the hook result keeps its current meaning: the gate is
+  `error`. `health.hasErrors` reports anything anywhere in the tree.
+
+### Effects
+
+`createEffect({ onSourceHealth?: (health: HealthNode) => void })`. After
+the first ready a health change calls it; the Effect is not disposed. Before
+the first ready, a gate error still disposes the Effect through
+`onSourceError`.
+
+### Adapters
+
+- Electric and PowerSync replace post-ready `markError` with `reportError` and
+  call `reportHealthy` after their next successful sync. PowerSync's
+  `markReady` recovery becomes `reportHealthy`.
+- query-db keeps `utils.lastError/isError/errorCount` and also calls
+  `reportError`/`reportHealthy`; it no longer calls `markReady` from `error`.
+- Persisted collections: local storage failures stay on `persistedError`;
+  upstream failures after ready are the collection's health.
+
+### Recovery
+
+App-level only. `cleanup()` then `preload()` starts a fresh attempt and resets
+health to `healthy`.
+
+## Model check
+
+`SourceHealth.tla` checks stable shape, mirroring through a nested live query,
+only-the-source-clears, gate independence after ready, and that a gate error
+is explained by a tree node. Five weakened designs each produce their
+counterexample. The model has two sources and one nested live query; it does
+not cover a collection reached by two paths.