Error surface (2026-10-16)#

This folder supersedes the health-channel surface in ../HEALTH-CANDIDATE.md and the phase / final health tree. The maintainer chose it after a Field Lab study of how other libraries separate loading errors from errors after data is shown.

• RULES.md: the frozen rules (grammar v4) and invariants. This is the contract the implementation follows.
• ErrorSurface4.tla, cfg/, tlc-results.tsv: the TLA+ model of those rules, its safe configuration, and twelve weakened controls, each of which fails at its target. Run from the field-lab skill root: scripts/tlc <this dir> -deadlock -config cfg/safe.cfg ErrorSurface4.
• readout.md: what the model checks and what it does not.
• user-docs-draft.md: the developer-facing guide written against the rules before implementation.

Decisions, in short:

1. status answers "can the data be shown": idle | loading | ready | error | crashed | cleaned-up, one flag per value (isLoadingError, isCrashed, ...). After a query has shown data, only a crash changes its status. isError is deprecated.
2. health answers "is the data still kept current". Each node carries failureReason (the adapter still tries) or error (it stopped), like TanStack Query. isSyncError is status === 'ready' and any problem in the tree. Every Collection has health and health:change; the errors names are gone.
3. Adapter calls: markReady(), reportError(e), fail(e), reportHealthy(). A call that does not fit the state machine throws; reportHealthy() with nothing wrong is a no-op.
4. reload() starts a new sync run like a sync-side truncate: nothing visible changes until it commits or fails. It returns the in-flight promise when called again, throws on crashed, and works during loading and after error. A live query's reload() reloads its failed sources.
5. cleanup() throws while the Collection has subscribers; subscribers lists them and cleanup({ dependents: true }) cleans them up first. A crash is not recovered in place; recovery is a cascade cleanup and a fresh start.
6. Persisted Collections join the same model: a synced disk restore opens the gate, a failed remote waits for the restore, remote problems after that are reported, and a failed restore is a crash. persistedStatus, isPersistedReady, and persistedError are removed.