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