soulcraft/brainy
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

fix: graph adjacency cold-load consistency guard — no more silent [] on connected

Browse source 
A native graph provider can load its relationship COUNT (manifest) on a cold open
but fail to load the source→target adjacency itself (observed on mmap-filesystem:
the SSTable-segment load is swallowed). The result is find({ connected }),
neighbors(), and related() silently returning [] despite persisted edges — and
staying empty after warm-up. Because it is [] not an error, callers cannot tell
real data is missing.

Brainy now runs a one-time consistency check on the first graph read: if the index
reports relationships exist but a known persisted edge's source resolves to no
neighbors, force a rebuild from storage (which re-scans + repopulates the adjacency);
if even that cannot read the edge, throw the new GraphIndexNotReadyError instead of
serving [] as truth. O(1) probe (one verb + one neighbor lookup), cached per brain,
and a no-op once the adjacency is live — so it self-heals the cold-open case and is
loud when it genuinely can't.

Wired into neighbors() + getRelations() (the graph-read primitives behind
find({ connected })). The underlying cold-open load is a native-provider concern
(addressed upstream); this makes the failure self-healing + loud rather than silent.

Tests: tests/unit/brainy/graph-adjacency-cold-load.test.ts (live → no-op; broken →
rebuild; unfixable → throws; size 0 / no edges → no-op; transient failure → re-checks
without breaking the query). Full unit gate green (1531/1531).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
David Snelling 2026-06-24 10:55:12 -07:00
parent 811c7da89e
commit 1694f68419
4 changed files with 240 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

26
RELEASES.md
View file

@ -10,6 +10,32 @@ Full auto-generated changelog: `CHANGELOG.md` · Releases: https://github.com/so
---
## v7.33.2 — 2026-06-24
**Affected products:** any consumer using graph traversals — `find({ connected: { from, via } })`,
`neighbors()`, `related()` — with a **native graph index** on **`mmap-filesystem`** (or any adapter
whose cold-open adjacency load can fail), where a process restart could leave graph queries returning
`[]` despite persisted edges. Drop-in; no API or data changes.
### Fix — graph adjacency no longer silently returns `[]` on a cold open
On a fresh brain open, a native graph provider can load its relationship **count** (the manifest) but
fail to load the source→target **adjacency** itself — so `find({ connected })` / `neighbors()` /
`related()` returned an empty array **indistinguishable from "no edges"**, and stayed empty after
warm-up. Because it was `[]` and not an error, callers could not tell real data was missing.
Brainy now runs a one-time consistency check on the first graph read: if the index reports that
relationships exist but a known persisted edge's source resolves to **no** neighbors, it **rebuilds
the adjacency from storage**. If even a rebuild cannot read the edge, it throws a loud, catchable
`GraphIndexNotReadyError` instead of serving `[]` as truth. The probe is O(1) (one edge + one neighbor
lookup), cached per brain, and a **no-op once the adjacency is live** — so consumers can return to
clean graph queries instead of in-memory-filter workarounds.
> The underlying cold-open load is a native-provider concern (being addressed upstream); this Brainy
> change makes the failure **self-healing and loud** rather than silent.
---
## v7.33.1 — 2026-06-22
**Affected products:** any consumer on `filesystem` / `mmap-filesystem` storage with **more than one