feat(health): the gate reads the named report — reads refuse loudly, never rebuild; open serves before it returns; the ceremony door
The read gate stops consulting the unnamed isReady() boolean: every provider
may expose healthReport() (sync, O(1), composed from exact ledgers —
HealthReport with a monotonic generation, per-invariant source
ledger|deep|unledgered, missing {count, sample}), and one readiness
authority (assessProviderHealth) derives the verdict. Unledgered families
are UNKNOWN — never healthy, never broken; a report that throws is a loud
not-ready, never a shrug. Reads at the four index choke points refuse with
the typed NotReady errors, narrated once per (provider, generation) — a
read NEVER starts a store walk:
- the first-read lazy build retires (open builds instead, regardless of
size — the ≥10k deferral and the "lazy loading on first query" branch go;
disableAutoRebuild is re-meant honestly in its docs);
- the verify*Live read-path rebuild triggers retire (refuse-or-serve);
- the read-time consistency probe that could launch a dark rebuild from an
ordinary find() retires;
- repairIndex({ rebuild: ['metadata'|'graph'|'vector'] | 'all' }) is the
one explicit door: rebuilds the named leg unconditionally and reports
rebuilt per family; bare repairIndex() stays report-driven.
test(lifecycle): the biography lane — a store's whole life, refereed
tests/lifecycle/: an independent shadow model referees every read after
every chapter (founding, a working day, clean restart, crash, repair,
second life). Chapters 1-3 green. Chapters 4-6 assert the true contract and
are marked .fails as a release-blocking finding (the kill-matrix
convention): after a crash + adopt reopen the metadata index computes its
'catchup' watermark verdict and nothing consumes it — find() serves the
pre-crash index while canonical and counts recover. The catchup wiring is
the cure; a passing .fails will force the marker's removal. The lane runs
in the integration gate (config + coverage guard).
2026-08-24 12:45:51 -07:00
|
|
|
# The Lifecycle Lane
|
|
|
|
|
|
|
|
|
|
One brain, driven through founding, a working day, a clean restart, a
|
|
|
|
|
crash, a repair, and a second life, checked chapter by chapter against an
|
|
|
|
|
independent shadow-model referee (`biographyHarness.ts`). It catches
|
|
|
|
|
COMPOSITION regressions unit tests miss — a store fine in one process but
|
|
|
|
|
broken across a restart/crash/repair. Runs on the plain JS engine, so it
|
|
|
|
|
gates every commit.
|
|
|
|
|
|
|
|
|
|
Run it: `npx vitest run tests/lifecycle --pool=forks`
|
|
|
|
|
|
|
|
|
|
A red names the chapter label, the id, and expected-vs-actual — diagnosable
|
|
|
|
|
from the message alone. `biography.test.ts` is split into two `it` blocks
|
|
|
|
|
(Ch1-3, then Ch4-6) purely for reporting; it is still ONE fixed-order story.
|
|
|
|
|
Chapters must never be reordered, skipped, or made conditional, and a
|
|
|
|
|
failing chapter's assertion must never be weakened to force green.
|
2026-08-25 10:02:25 -07:00
|
|
|
|
|
|
|
|
Lab notes (hard-won, keep):
|
|
|
|
|
- `git reset --hard` does NOT remove untracked files — a "clean" tree can still
|
|
|
|
|
carry stray test stores; use `git clean -fd tests/lifecycle-tmp` equivalents.
|
|
|
|
|
- `silent: true` patches `console` process-wide — never assert narration through
|
|
|
|
|
`console` spies in this lane; the engine's always-on channel is `prodLog`.
|