# Content temporarily unavailable
# Frozen grammar v4: app-facing error model for a reactive local-first data library

A *Collection* holds rows kept in sync with a backend by a *sync adapter*. A *live query*
reads one or more Collections ("sources", one per query alias) and is itself a Collection.
Apps read a live query through framework hooks. Some Collections are *persisted*: they
restore rows from local disk storage and also sync with a remote backend.

## Surface
- `status`: 'idle' | 'loading' | 'ready' | 'error' | 'crashed' | 'cleaned-up'
- One boolean per status: isIdle, isLoading, isReady, isLoadingError (status 'error'),
  isCrashed, isCleanedUp. `isError` is deprecated.
- `isSyncError`: status is 'ready' and the tree holds any `failureReason` or `error`.
- `health`: a tree, one node per query alias plus a root node for the query. Each node:
  { alias, kind: 'source'|'live-query'|'include', status, hasErrors, error | null, sources }.
  A source node carries at most one of:
  - `failureReason`: the latest problem while the adapter keeps trying (like TanStack Query's
    `failureReason` during retries);
  - `error`: the adapter stopped (`fail`), or the gate failed.
  Each value is { name, message, code?, at, cause }. A node also shows `reloading` while a
  reload's new run is in flight. The query's own node carries a request `error`.
- `collection.health`: the Collection's current after-ready error, or null.
- `collection.reload()`: start a new sync run while keeping the current rows (see R7).
- `collection.cleanup()`: throws while the Collection has subscribers. The app can list a
  Collection's subscribers (live queries, Effects, raw subscriptions) and ask cleanup to clean
  up those dependents first.

## Rules
R1 Gate. Each sync run: loading -> ready | error | crashed. An adapter that keeps retrying
   before its first ready reports nothing (status stays loading). 'error' (gave up before the
   first ready) is final for the run.
R2 Crash. 'crashed' = the Collection can no longer serve reads or accept writes: local
   storage broken (closed IndexedDB, a failed local write or restore) or an internal invariant
   failure. Final for the run; ends every live query and Effect over it. The cause may or may
   not persist into a new run.
R3 Query gate. Until a live query is ready, it takes its sources' worst gate
   (crashed > error > loading > ready). After it is ready, only 'crashed' propagates.
R4 After ready, a failure never changes status or removes rows. It appears on the node that
   owns it:
   - source node, sync problem: `failureReason` (adapter still trying; clears itself) or
     `error` (adapter stopped; rows frozen until reload);
   - a source whose new sync run fails before its first ready while the query is ready
     (an on-demand source loading late, or a source being reloaded): node `error`; the query
     stays ready;
   - query's own node, request error: a request for more data (next page, newly joined rows)
     failed; clears when that data loads or is no longer needed.
R5 Adapter verbs: markReady(); reportError(e) = something went wrong, still running
   (sets `failureReason`); fail(e) = stopped (before ready -> status 'error'; after -> node
   `error`); reportHealthy() clears `failureReason`. A node `error` clears only when a
   reload's new run commits.
R6 Tree identity is stable while content is unchanged; every field except `cause` is JSON.
R7 Reload. reload() starts a new sync run like a sync-side truncate. Nothing visible changes
   until the new run's first commit or failure: rows, status ('ready' or 'error'), and the
   current error stay, and the node shows `reloading`. The first commit replaces all rows
   atomically and clears the node's problem (an 'error' status becomes 'ready'). If the new
   run fails first, the old rows and status stay and the node shows the new `error`.
   reload() while a reload is in flight returns that reload's promise. reload() on a
   'crashed' Collection throws: a crash is not recovered in place; recovery is a cascade
   cleanup, which discards all state, and a fresh start (of the same object or a new one). reload() during 'loading' starts a new run; commits from the old run are
   ignored. A failed request is re-issued by the new run.
R9 Live-query reload. reload() on a live query in 'error' reloads each of its sources in
   'error' or with a node `error`. Its status stays 'error' while any source still has a
   failure, including a source whose reload is in flight (it keeps its 'error' gate). Once no
   source has a failure, the query moves to 'loading', or straight to 'ready'. Adapters retry inside their
   first load (for example query-db's retry or the queryFn) before calling fail().
R8 Persisted Collections. A completed local restore of previously synced rows opens the gate
   (status 'ready') even if the remote has not connected; remote problems after that are
   reported (R4/R5), including before the remote's first sync. A remote that fails before the
   restore finishes waits for the restore: synced rows -> 'ready' with node `error`; none ->
   'error'. A failed restore is a crash. An empty restore of a Collection that never synced
   does not open the gate.

## Invariants
I1 isLoadingError is never true after the query has shown data in its run.
I2 After a query is ready, its status is 'ready' or 'crashed' until it is recreated.
I3 Status 'ready' implies rows are shown; no after-ready failure or reload blanks rows.
I4 From what the app can observe, it can pick one remedy: wait, retry the action, reload,
   report broken storage.
I5 No silent recovery or silent degradation: 'error' becomes 'ready' only through a reload's
   commit; 'crashed' never becomes 'ready' without a cleanup in between; a failing remote is never
   shown as healthy; a reload never shows 'loading' in place of 'error'.
I6 'crashed' always means broken local storage or an invariant failure.
I7 Rows shown never come from a superseded run.
I8 'ready' never means "no rows" when the truth is "unknown".