From 2914e0eb42a43479245d40bab865a1886145dfc3 Mon Sep 17 00:00:00 2001 From: David Snelling Date: Wed, 26 Aug 2026 14:48:26 -0700 Subject: [PATCH] =?UTF-8?q?docs(concepts):=20the=20serving=20law=20?= =?UTF-8?q?=E2=80=94=20a=20failure=20is=20graded=20by=20whether=20an=20ans?= =?UTF-8?q?wer=20could=20be=20wrong,=20never=20by=20the=20cost=20of=20the?= =?UTF-8?q?=20fix;=20reads=20refuse=20per=20family?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/concepts/index-health.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/concepts/index-health.md b/docs/concepts/index-health.md index 18bf7010..96199f11 100644 --- a/docs/concepts/index-health.md +++ b/docs/concepts/index-health.md @@ -68,6 +68,19 @@ a maintenance window, a divergence `repairIndex()` will clean up on its own schedule. `serving: false` is not benign. It means this provider is refusing to answer, on its own word, right now. +**How a failure gets its grade — the serving law.** A provider grades `heal` by +one question only: *could an answer be wrong?* — never *how expensive is the +fix?* A missing-postings shortfall, however large, is `heal: 'repair'` (re-post +exactly what the ledger names, reads serving throughout); it can never withhold +serving just because healing it takes work. `serving` is withheld only by a +small, named set of rebuild-graded conditions — the index not initialized, its +durable state absent, a manifest naming files that are not resident, a replay +that did not complete cleanly — the states in which an answer could genuinely be +wrong. And a read is only ever refused by the family it actually consults: a +metadata filter is answered by the metadata index alone, vector search by the +vector index, traversal by the graph index — one family's refusal never blocks +another family's reads. + ## Reads refuse — they never rebuild A query that reaches a not-serving provider does not trigger a rebuild from inside