docs(release): the 10.4.0 entry, the index-health concept doc, and the API surfaces — written from the tree, not the plan

docs/PLUGINS.md

@@ -10,7 +10,7 @@ next:
   - guides/storage-adapters
 ---
 
-# Plugin Development Guide
+# Plugin System
 
 Brainy has a plugin system that allows third-party packages to replace internal subsystems with custom implementations. This is how `@soulcraft/cor` provides optional native acceleration, and it's the same system available to any developer.
 
@@ -200,15 +200,30 @@ members so a warm reopen never pays a redundant rebuild-from-canonical:
 - **`init?(): Promise<void>`** — eager cold-load. Brainy awaits it once during
   `brain.init()`, after the metadata provider's `init()` (the id-mapper hydrates first)
   and **before the rebuild gate**.
-- **`isReady?(): boolean`** — honest durability signal. `true` ⇔ the persisted index is
-  loaded (or cheaply demand-loadable) and consistent with what was last persisted. When
-  exposed, the rebuild gate defers to this signal **instead of** the `size() === 0` /
-  `totalEntries === 0` heuristics — a disk-native index may report 0 resident entries
-  while fully durable. Never return `true` if the durable state failed to load: the
-  signal is honest in both directions, and a not-ready provider gets its rebuild even
-  when `size() > 0`.
+- **`healthReport?(): HealthReport`** — the PREFERRED signal (10.4+). A named,
+  synchronous, O(1) verdict derived from the provider's own exact ledgers — never a
+  sample, never I/O, must never throw for a well-formed provider. Brainy's read gate
+  (`assessProviderHealth()`) reads this INSTEAD of `isReady()` / size heuristics when
+  present: `serving: false` refuses the read with a typed `*NotReadyError` rather than
+  triggering a rebuild — a read never starts a store walk. `healthy` marks every
+  *verified* invariant holding; a family named in `unledgered` counts as neither
+  healthy nor broken. See `HealthReport` / `LedgerInvariantResult` /
+  `InvariantSource` in `src/plugin.ts`, and
+  [Index Health](concepts/index-health.md) for the consumer-facing story.
+- **`isReady?(): boolean`** — honest durability signal, the fallback when
+  `healthReport()` is absent. `true` ⇔ the persisted index is loaded (or cheaply
+  demand-loadable) and consistent with what was last persisted. When exposed, the
+  gate defers to this signal **instead of** the `size() === 0` / `totalEntries === 0`
+  heuristics — a disk-native index may report 0 resident entries while fully durable.
+  Never return `true` if the durable state failed to load: the signal is honest in
+  both directions, and a not-ready provider gets its rebuild even when `size() > 0`.
 - **`isMigrating?(): boolean`** — while `true`, the provider owns its index (background
   migration); brainy skips its rebuild entirely.
+- **`validateInvariants?(): Promise<ProviderInvariantReport>`** — the async DEEP
+  diagnostic (full scans allowed), distinct from the bounded, sync `healthReport()`.
+  Must never throw — a failure is `healthy: false` data, not an exception; a provider
+  that throws anyway is read as a loud, unverified failure (never as "healthy") by
+  every caller, never silently retried into a rebuild.
 
 Providers that implement none of these keep the size/count heuristics — correct for
 engines whose `rebuild()` *is* their load path (like brainy's built-in JS vector index).