fix: metadata cold-read guard — no more silent [] on cold find({where}) (7.33.5)

Companion to 7.33.4's graph cold-read guard, now for the metadata field index. A
downstream deployment reported find({where}) returning a silent [] on a
freshly-opened brain (a native metadata provider that reports data but hasn't
loaded its field postings), blanking filtered pages after every restart.

verifyMetadataLive() — one-shot per brain on the first filtered find(): probe a
known persisted field value; if served, live (one O(1) probe on a warm brain). If
not, rebuild from canonical + re-probe; if still unserved, throw the new exported
MetadataIndexNotReadyError rather than let a silent [] pass. Inconclusive cases
(empty store, no plain field, shared-store foreign entity) resolve to live, no
false rebuild. Also exports BrainyError + GraphIndexNotReadyError (were internal).

The JS index cold-loads correctly; this guards the native path (durable cure is
cortex-side, same shape as the graph 2.7.8 cure). 4 unit tests. tsc 0, guard 4/4,
full unit 1538 pass (+1 pre-existing flaky VFS perf test, green in isolation).
This commit is contained in:
David Snelling 2026-07-02 10:28:04 -07:00
parent 2be3d0f88b
commit 9dc4c5e62b
5 changed files with 268 additions and 1 deletions

View file

@ -10,6 +10,34 @@ Full auto-generated changelog: `CHANGELOG.md` · Releases: https://github.com/so
---
## v7.33.5 — 2026-07-02
**Affected products:** any consumer whose brain restarts cold (every deploy) and issues
`find({ where: { field } })` filtered reads against a **native metadata index** — where a cold
open could return `[]` for a field lookup that HAS matching data, silently blanking filtered
pages until the index warmed. Drop-in; no API or data changes.
### Fix — filtered `find({ where })` no longer silently returns `[]` on a cold open
The companion to 7.33.2's graph cold-read guard, now for the **metadata field index**. On a fresh
brain open, a native metadata provider can report that data exists but not yet serve its `where`
postings — so `find({ where: { status: 'active' } })` returned an empty array **indistinguishable
from "no such data"**, and callers rendered "nothing found" over real data.
Brainy now runs a one-time serving check on the first filtered `find()`: it probes a known
persisted field value and, if the index doesn't return the known entity, **rebuilds the index from
the canonical records** and re-probes. If it still cannot serve, it throws a loud, catchable
`MetadataIndexNotReadyError` (now exported, alongside `GraphIndexNotReadyError` and `BrainyError`)
rather than let a silent `[]` stand. On a warm brain the only cost is one O(1) probe.
**What you get:** cold `where` reads are correct-by-default (self-healed) or fail loudly — never a
silent empty result. Catch `MetadataIndexNotReadyError` (or check `error.type ===
'METADATA_INDEX_NOT_READY'`) to render a "warming up / retry" state instead of a false "no results".
The durable native cold-load cure remains a cortex-side follow-up; this guard makes silent-empty
impossible regardless of provider.
---
## v7.33.2 — 2026-06-24
**Affected products:** any consumer using graph traversals — `find({ connected: { from, via } })`,