fix(8.0): never serve a silent [] from find({connected}) on a cold-loaded graph

8.0 shipped with no cold-graph guard (the 7.33.4 fix was never ported), so on a
cold open of a large brain where the native adjacency reports membership but its
source->target edges did not load, find({connected})/neighbors()/related() could
silently return [] for persisted edges.

Add the converged isReady() contract: GraphIndexProvider.isReady?(): boolean is
the honest cold-load readiness signal (true ONLY when edges are loaded), so brainy
gates on it instead of the lying membership-size() proxy. verifyGraphAdjacencyLive()
checks it — Strategy 1: false -> hydrate the id-mapper, rebuild from storage, re-check,
throw GraphIndexNotReadyError if still not ready; providers without isReady() fall
back to a global known-edge-sample probe (Strategy 2, not the queried anchor, so a
genuinely edgeless node still returns []). rebuildIndexesIfNeeded gates the graph
rebuild on it too, with the id-mapper hydrated before the adjacency rebuild on the
lazy cold-open path (the CTX-BR-RESTORE-REBUILD ordering, shared with restore()).
executeGraphSearch re-verifies before trusting an empty connected result and
re-collects on a heal. 6-case integration test + 1718 unit green.
This commit is contained in:
David Snelling 2026-06-30 09:30:11 -07:00
parent 93f61dbc79
commit 229b0679fc
4 changed files with 542 additions and 98 deletions

View file

@ -11,6 +11,7 @@ export type BrainyErrorType =
| 'RETRY_EXHAUSTED'
| 'VALIDATION'
| 'FIELD_NOT_INDEXED'
| 'GRAPH_INDEX_NOT_READY'
/**
* Custom error class for Brainy operations
@ -223,3 +224,32 @@ export class BrainyError extends Error {
return BrainyError.storage(error.message, error)
}
}
/**
* Thrown when the graph adjacency index reports that relationships exist (its
* persisted manifest/count loaded, or its readiness signal says otherwise) but
* the sourcetarget adjacency itself did NOT load so graph traversals
* (`find({ connected })`, `neighbors()`, `related()`) would otherwise return an
* EMPTY array indistinguishable from "no edges".
*
* On 8.0 brainy detects this on the first graph read via the provider's honest
* sync `isReady()` signal (true ONLY when the edges are loaded; see
* {@link import('../plugin.js').GraphIndexProvider.isReady}); for older providers
* that do not expose it, it falls back to a known-edge-sample probe (one persisted
* verb + one neighbor lookup). Either way it attempts a rebuild from storage and
* raises this LOUD, catchable error only if even that cannot make the adjacency
* ready replacing silent data-invisibility with a clear failure.
*
* Observed with a native graph provider whose cold-open adjacency load is
* swallowed on certain storage adapters; the fix is upstream in the provider,
* but Brainy refuses to serve `[]` as if it were truth.
*/
export class GraphIndexNotReadyError extends BrainyError {
constructor(message: string, originalError?: Error) {
super(message, 'GRAPH_INDEX_NOT_READY', false, originalError)
this.name = 'GraphIndexNotReadyError'
if (Error.captureStackTrace) {
Error.captureStackTrace(this, GraphIndexNotReadyError)
}
}
}