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

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

Browse source 
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
Download patch file Download diff file Expand all files Collapse all files

388
src/brainy.ts
View file

@ -161,7 +161,7 @@ import {
import { GenerationStore } from './db/generationStore.js'
import { isDeterministicEmbedMode } from './embeddings/deterministicEmbedMode.js'
import { GenerationConflictError } from './db/errors.js'
import { BrainyError } from './errors/brainyError.js'
import { BrainyError, GraphIndexNotReadyError } from './errors/brainyError.js'
import { MemoryStorage } from './storage/adapters/memoryStorage.js'
import type {
CompactHistoryOptions,
@ -403,6 +403,10 @@ export class Brainy<T = any> implements BrainyInterface<T> {
private _indexRebuildFailed: Error | null = null
/** One-shot guard so the metadata cold-open consistency probe runs once per brain. */
private _metadataConsistencyProbed = false
/** Graph-adjacency cold-load consistency: verified-live this session (one-shot). */
private _graphAdjacencyVerified = false
/** Re-entrancy guard: a verify (rebuild → reads) is in flight. */
private _graphAdjacencyVerifying = false
// Sub-APIs (lazy-loaded)
private _nlp?: NaturalLanguageProcessor
@ -2664,6 +2668,153 @@ export class Brainy<T = any> implements BrainyInterface<T> {
return this.entityIntsToUuids(neighborInts)
}
/**
* @description Hydrate the entity id-mapper from persisted state BEFORE a graph
* rebuild. A native int-keyed adjacency resolves every verb endpoint
* (`sourceId`/`targetId` → stable int) through this mapper, so it must reflect
* the persisted int assignments before `graphIndex.rebuild()` runs — otherwise
* edges resolve to stale/missing ints and are silently dropped
* (CTX-BR-RESTORE-REBUILD). The JS mapper has no `rebuild()` and needs no
* reload (it is re-derived by `MetadataIndex.rebuild()` via append-only
* `getOrAssign`), so this is a no-op for it. Mirrors the ordering in
* {@link restore}.
*/
private async hydrateIdMapperForGraphRebuild(): Promise<void> {
const idMapper = this.metadataIndex.getIdMapper() as { rebuild?: () => Promise<void> }
if (typeof idMapper.rebuild === 'function') {
await idMapper.rebuild()
}
}
/**
* @description Verify that the graph adjacency is actually LIVE before a graph read trusts
* its result. A native graph index can load its relationship COUNT (manifest) on a cold open
* of a LARGE brain (≥10k nouns, which skips the eager index rebuild) but NOT its
* source→target adjacency, so `getNeighbors()` returns `[]` for EVERY source even though
* edges are persisted — and `find({ connected })` / `neighbors()` / `related()` would serve
* that `[]` as if it were truth.
*
* Two detection strategies, in order of honesty:
* - **Preferred (8.0 contract):** the provider exposes a sync `isReady()` that is true ONLY
* when the edges are loaded. `false` → hydrate the id-mapper (a native int adjacency
* resolves endpoints through it), rebuild from storage, and re-check `isReady()`; if it is
* still `false`, throw {@link GraphIndexNotReadyError} rather than returning `[]`.
* - **Fallback (providers without `isReady()`):** a GLOBAL known-edge sample (a real
* persisted verb's `sourceId`, which by definition HAS an outgoing edge) — NOT any queried
* anchor, because brainy cannot cheaply tell "adjacency unloaded" from "this node is
* genuinely edgeless" per-anchor. If that known-edge source resolves to no neighbors, the
* adjacency did not load: rebuild and re-probe; if even that fails, throw.
*
* @returns `'live'` when the adjacency is already trustworthy (or there is genuinely nothing
* to verify), or `'rebuilt'` when a cold-unloaded adjacency was just healed from storage —
* in which case callers that observed an empty result must RE-RUN their collection.
* @throws {GraphIndexNotReadyError} when the index claims edges but cannot serve a known
* persisted edge (or stays not-ready) even after a rebuild.
*/
private async verifyGraphAdjacencyLive(): Promise<'live' | 'rebuilt'> {
if (this._graphAdjacencyVerified) return 'live'
// Re-entrancy: rebuild() can trigger reads (neighbors/related) that call back into this
// guard. While a verify is in flight, short-circuit so we cannot recurse into rebuild().
if (this._graphAdjacencyVerifying) return 'live'
this._graphAdjacencyVerifying = true
try {
const gi = this.graphIndex as GraphAdjacencyIndex & { isReady?: () => boolean }
// ── Strategy 1: honest isReady() signal (cortex >= 2.7.8 / 3.0) ──────────
if (typeof gi.isReady === 'function') {
if (gi.isReady()) {
this._graphAdjacencyVerified = true
return 'live'
}
// Not ready: the edges did not load on open. Hydrate the id-mapper, then rebuild.
if (!this.config.silent) {
console.warn(
`[Brainy] Graph adjacency reports not-ready (isReady() === false) — the persisted ` +
`adjacency did not load on open. Rebuilding from storage…`
)
}
await this.hydrateIdMapperForGraphRebuild()
await this.graphIndex.rebuild()
if (gi.isReady()) {
this._graphAdjacencyVerified = true
return 'rebuilt'
}
throw new GraphIndexNotReadyError(
`Graph adjacency index reports not-ready even after a rebuild — the persisted ` +
`adjacency could not be loaded. find({ connected }), neighbors() and related() ` +
`cannot be served reliably for this brain.`
)
}
// ── Strategy 2: known-edge-sample probe (providers without isReady()) ────
const claimed = await this.graphIndex.size()
if (!claimed || claimed <= 0) return 'live' // no edges claimed — nothing to verify
const sample = await this.storage.getVerbs({ pagination: { limit: 1 } })
const verb = sample.items?.[0]
if (!verb || !verb.sourceId) {
// no edges in storage — stale count, harmless; don't re-probe on every read.
this._graphAdjacencyVerified = true
return 'live'
}
// Resolve the known edge's source through THIS brain's id-mapper. An unmapped source means
// the sample is not one of this brain's own edges — e.g. a shared on-disk store reused
// across instances surfaces a foreign verb whose UUID this brain's resident mapper never
// interned. We cannot prove a cold-unloaded adjacency from such a sample, so treat it as
// INCONCLUSIVE: mark verified and return 'live' rather than rebuilding/throwing. (The honest
// cold-load signal for native providers is isReady(), checked above; the JS baseline keeps
// its mapper resident, so its OWN edges always resolve — the targeted 7.x failure mode,
// "mapper loaded but adjacency empty", still resolves the source and is detected below.)
const sourceInt = this.graphEntityInt(verb.sourceId)
if (sourceInt === undefined) {
this._graphAdjacencyVerified = true
return 'live'
}
// Ask the adjacency for ONE neighbor of the (mapped) known-edge source.
const probeKnownSource = async (): Promise<boolean> =>
(await this.graphIndex.getNeighbors(sourceInt, { limit: 1 })).length > 0
if (await probeKnownSource()) {
this._graphAdjacencyVerified = true
return 'live' // adjacency is live — the common case
}
// INCONSISTENT: the index reports edges but a KNOWN-mapped persisted edge's source has none →
// the adjacency did not load on open. Hydrate the mapper and rebuild from storage.
if (!this.config.silent) {
console.warn(
`[Brainy] Graph adjacency reports ${claimed} relationship(s) but a persisted edge ` +
`resolves to none — the persisted adjacency did not load on open. Rebuilding from storage…`
)
}
await this.hydrateIdMapperForGraphRebuild()
await this.graphIndex.rebuild()
if (await probeKnownSource()) {
this._graphAdjacencyVerified = true
return 'rebuilt'
}
throw new GraphIndexNotReadyError(
`Graph adjacency index reports ${claimed} relationship(s) but returns no edges even ` +
`after a rebuild — the persisted adjacency could not be loaded. find({ connected }), ` +
`neighbors() and related() cannot be served reliably for this brain.`
)
} catch (err) {
if (err instanceof GraphIndexNotReadyError) throw err
// A transient probe/rebuild failure must not break the actual query NOR be
// masked as "no data". Allow a re-check on the next graph read and fall through.
this._graphAdjacencyVerified = false
if (!this.config.silent) {
console.warn(`[Brainy] Graph adjacency consistency check skipped (transient): ${err}`)
}
return 'live'
} finally {
this._graphAdjacencyVerifying = false
}
}
// -------------------------------------------------------------------------
/**
@ -3197,6 +3348,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
paramsOrId?: string | RelatedParams
): Promise<Relation<T>[]> {
await this.ensureInitialized()
await this.verifyGraphAdjacencyLive()
// Handle string ID shorthand: related(id) -> related({ from: id })
const rawParams = typeof paramsOrId === 'string'
@ -6916,10 +7068,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
// JS mapper has no `rebuild()` and needs no reload: MetadataIndex.rebuild()
// re-derives it from the restored entities via append-only getOrAssign,
// consistently with the bitmaps it builds.
const idMapper = this.metadataIndex.getIdMapper() as { rebuild?: () => Promise<void> }
if (typeof idMapper.rebuild === 'function') {
await idMapper.rebuild()
}
await this.hydrateIdMapperForGraphRebuild()
// Every in-memory index is now stale — rebuild all three from the restored
// canonical records (each rebuild clears its own state first). The graph
@ -11041,6 +11190,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
}
): Promise<string[]> {
await this.ensureInitialized()
await this.verifyGraphAdjacencyLive()
const direction = options?.direction || 'both'
const limit = options?.limit
@ -11577,111 +11727,133 @@ export class Brainy<T = any> implements BrainyInterface<T> {
const connectedIds = new Set<string>()
if (subtypeFilter !== undefined) {
// Multi-hop BFS with per-hop (verbType, subtype) predicate. Works on the
// open-core JS path at any depth. When a graph-index provider exposes a
// faster `findConnectedSubtype` (native BFS with the same semantics),
// `nativeSubtypeBfs` routes through it transparently — same pattern as
// every other provider hook.
const subtypeArr = Array.isArray(subtypeFilter) ? subtypeFilter : [subtypeFilter]
const subtypeSet = new Set(subtypeArr)
// Population is extracted into a closure so it can be re-run VERBATIM after a
// cold-load heal (verdict 'rebuilt') — re-executing the SAME traversal once the
// adjacency is actually loaded, without changing any collection semantics.
const populate = async (): Promise<void> => {
connectedIds.clear()
if (subtypeFilter !== undefined) {
// Multi-hop BFS with per-hop (verbType, subtype) predicate. Works on the
// open-core JS path at any depth. When a graph-index provider exposes a
// faster `findConnectedSubtype` (native BFS with the same semantics),
// `nativeSubtypeBfs` routes through it transparently — same pattern as
// every other provider hook.
const subtypeArr = Array.isArray(subtypeFilter) ? subtypeFilter : [subtypeFilter]
const subtypeSet = new Set(subtypeArr)
// Native fast path (D.3): single verb type + single subtype + outgoing
// walk match the native BFS semantics exactly (out-edges only, source
// excluded, visited-set cycle guard). Entity ints in, entity ints out —
// UUID conversion stays at this boundary. Returns null when the query
// shape (or provider) can't take the native route.
const nativeSubtypeBfs = async (
anchor: string,
walk: 'in' | 'out' | 'both'
): Promise<Set<string> | null> => {
if (walk !== 'out') return null
if (via === undefined || Array.isArray(via)) return null
if (subtypeArr.length !== 1) return null
const provider = this.graphIndex as Partial<{
findConnectedSubtype(
sourceInt: bigint,
verbTypeIndex: number,
subtype: string | null,
depth: number,
limit?: number | null
): Promise<bigint[]>
}>
if (typeof provider.findConnectedSubtype !== 'function') return null
// Native fast path (D.3): single verb type + single subtype + outgoing
// walk match the native BFS semantics exactly (out-edges only, source
// excluded, visited-set cycle guard). Entity ints in, entity ints out —
// UUID conversion stays at this boundary. Returns null when the query
// shape (or provider) can't take the native route.
const nativeSubtypeBfs = async (
anchor: string,
walk: 'in' | 'out' | 'both'
): Promise<Set<string> | null> => {
if (walk !== 'out') return null
if (via === undefined || Array.isArray(via)) return null
if (subtypeArr.length !== 1) return null
const provider = this.graphIndex as Partial<{
findConnectedSubtype(
sourceInt: bigint,
verbTypeIndex: number,
subtype: string | null,
depth: number,
limit?: number | null
): Promise<bigint[]>
}>
if (typeof provider.findConnectedSubtype !== 'function') return null
const anchorInt = this.graphEntityInt(anchor)
if (anchorInt === undefined) return new Set() // unmapped → no relations
const anchorInt = this.graphEntityInt(anchor)
if (anchorInt === undefined) return new Set() // unmapped → no relations
const verbTypeIndex = TypeUtils.getVerbIndex(via as VerbType)
// No limit: match the JS BFS exactly — overall result limiting happens
// downstream against existingResults.
const reachedInts = await provider.findConnectedSubtype(
anchorInt, verbTypeIndex, subtypeArr[0], effectiveDepth, null
)
return new Set(this.entityIntsToUuids(reachedInts))
}
const verbTypeIndex = TypeUtils.getVerbIndex(via as VerbType)
// No limit: match the JS BFS exactly — overall result limiting happens
// downstream against existingResults.
const reachedInts = await provider.findConnectedSubtype(
anchorInt, verbTypeIndex, subtypeArr[0], effectiveDepth, null
)
return new Set(this.entityIntsToUuids(reachedInts))
}
const bfsWithSubtype = async (anchor: string, walk: 'in' | 'out' | 'both'): Promise<Set<string>> => {
const nativeResult = await nativeSubtypeBfs(anchor, walk)
if (nativeResult !== null) return nativeResult
const bfsWithSubtype = async (anchor: string, walk: 'in' | 'out' | 'both'): Promise<Set<string>> => {
const nativeResult = await nativeSubtypeBfs(anchor, walk)
if (nativeResult !== null) return nativeResult
const visited = new Set<string>([anchor])
const reached = new Set<string>()
let frontier = new Set<string>([anchor])
const visited = new Set<string>([anchor])
const reached = new Set<string>()
let frontier = new Set<string>([anchor])
for (let hop = 0; hop < effectiveDepth && frontier.size > 0; hop++) {
const nextFrontier = new Set<string>()
for (const node of frontier) {
// Walk outgoing edges (when direction includes outbound) and incoming
// edges (when direction includes inbound). Both = union.
const dirs: Array<'from' | 'to'> = []
if (walk === 'out' || walk === 'both') dirs.push('from')
if (walk === 'in' || walk === 'both') dirs.push('to')
for (let hop = 0; hop < effectiveDepth && frontier.size > 0; hop++) {
const nextFrontier = new Set<string>()
for (const node of frontier) {
// Walk outgoing edges (when direction includes outbound) and incoming
// edges (when direction includes inbound). Both = union.
const dirs: Array<'from' | 'to'> = []
if (walk === 'out' || walk === 'both') dirs.push('from')
if (walk === 'in' || walk === 'both') dirs.push('to')
for (const dir of dirs) {
const edges = await this.related({
...(dir === 'from' ? { from: node } : { to: node }),
...(via && { type: via as VerbType | VerbType[] }),
subtype: subtypeArr,
limit: 10000
})
for (const edge of edges) {
// Defensive: related() honors the subtype filter, but check
// again in case a future impl widens it.
if (edge.subtype !== undefined && !subtypeSet.has(edge.subtype)) continue
const neighbor = dir === 'from' ? edge.to : edge.from
if (visited.has(neighbor)) continue
visited.add(neighbor)
reached.add(neighbor)
nextFrontier.add(neighbor)
for (const dir of dirs) {
const edges = await this.related({
...(dir === 'from' ? { from: node } : { to: node }),
...(via && { type: via as VerbType | VerbType[] }),
subtype: subtypeArr,
limit: 10000
})
for (const edge of edges) {
// Defensive: related() honors the subtype filter, but check
// again in case a future impl widens it.
if (edge.subtype !== undefined && !subtypeSet.has(edge.subtype)) continue
const neighbor = dir === 'from' ? edge.to : edge.from
if (visited.has(neighbor)) continue
visited.add(neighbor)
reached.add(neighbor)
nextFrontier.add(neighbor)
}
}
}
frontier = nextFrontier
}
frontier = nextFrontier
return reached
}
return reached
}
if (from) {
for (const id of await bfsWithSubtype(from, direction)) connectedIds.add(id)
}
if (to) {
const reverse: 'in' | 'out' | 'both' = direction === 'in' ? 'out' : direction === 'out' ? 'in' : 'both'
for (const id of await bfsWithSubtype(to, reverse)) connectedIds.add(id)
}
} else {
// No subtype filter — fast path via neighbors(), which does the same
// depth-aware BFS but only filters by verbType.
const collect = (id: string, dir: 'incoming' | 'outgoing' | 'both'): Promise<string[]> =>
this.neighbors(id, { direction: dir, depth: effectiveDepth, verbType: via })
if (from) {
for (const id of await bfsWithSubtype(from, direction)) connectedIds.add(id)
}
if (to) {
const reverse: 'in' | 'out' | 'both' = direction === 'in' ? 'out' : direction === 'out' ? 'in' : 'both'
for (const id of await bfsWithSubtype(to, reverse)) connectedIds.add(id)
}
} else {
// No subtype filter — fast path via neighbors(), which does the same
// depth-aware BFS but only filters by verbType.
const collect = (id: string, dir: 'incoming' | 'outgoing' | 'both'): Promise<string[]> =>
this.neighbors(id, { direction: dir, depth: effectiveDepth, verbType: via })
if (from) {
for (const id of await collect(from, toNeighborDir(direction))) connectedIds.add(id)
}
if (from) {
for (const id of await collect(from, toNeighborDir(direction))) connectedIds.add(id)
}
if (to) {
const reverse: 'in' | 'out' | 'both' = direction === 'in' ? 'out' : direction === 'out' ? 'in' : 'both'
for (const id of await collect(to, toNeighborDir(reverse))) connectedIds.add(id)
if (to) {
const reverse: 'in' | 'out' | 'both' = direction === 'in' ? 'out' : direction === 'out' ? 'in' : 'both'
for (const id of await collect(to, toNeighborDir(reverse))) connectedIds.add(id)
}
}
}
await populate()
// Cold-load guard: an empty connected set is suspicious. The native adjacency can report
// size()>0 (or isReady()===false) on a cold open yet have loaded NO source→target edges — so
// traversal silently returns []. Re-verify against the honest isReady() signal (or, for older
// providers, a GLOBAL known-edge sample — NOT the queried anchor, which may be genuinely
// edgeless). If the adjacency was dead and a rebuild healed it, re-collect; if it stays dead,
// verifyGraphAdjacencyLive() throws GraphIndexNotReadyError. A genuinely edgeless anchor
// verifies 'live' and the empty result stands — no spurious rebuild/throw.
if (connectedIds.size === 0) {
const verdict = await this.verifyGraphAdjacencyLive()
if (verdict === 'rebuilt') {
await populate()
}
}
@ -12806,10 +12978,20 @@ export class Brainy<T = any> implements BrainyInterface<T> {
const hnswIndexSize = this.index.size()
const graphIndexSize = await this.graphIndex.size()
// Graph rebuild fires when the adjacency is empty OR when the provider's
// honest readiness signal says the edges did not load on a cold open — the
// native int adjacency can report size()>0 (count/manifest loaded) yet have
// NO source→target edges, the silent-empty cold-load failure. Providers
// without isReady() keep the exact prior behavior (size()===0 only).
const graphIsReady = this.graphIndex as GraphAdjacencyIndex & { isReady?: () => boolean }
const needsGraphRebuild =
graphIndexSize === 0 ||
(typeof graphIsReady.isReady === 'function' && !graphIsReady.isReady())
const needsRebuild =
metadataStats.totalEntries === 0 ||
hnswIndexSize === 0 ||
graphIndexSize === 0
needsGraphRebuild
if (!needsRebuild && !force) {
// All indexes already populated, no rebuild needed
@ -12841,13 +13023,23 @@ export class Brainy<T = any> implements BrainyInterface<T> {
console.log(`${rebuildReason} - rebuilding all indexes from persisted data...`)
}
// Before the graph rebuild, hydrate the entity id-mapper from the persisted
// snapshot. A native int-keyed adjacency resolves every verb endpoint through
// this mapper, so it must reflect the persisted int assignments BEFORE
// graphIndex.rebuild() runs — otherwise edges resolve to stale/missing ints
// and are silently dropped (CTX-BR-RESTORE-REBUILD). Mirrors restore()'s
// ordering; a no-op for the JS mapper (re-derived by metadataIndex.rebuild()).
if (needsGraphRebuild) {
await this.hydrateIdMapperForGraphRebuild()
}
// Rebuild all 3 indexes in parallel for performance
// Indexes load their data from storage (no recomputation)
const rebuildStartTime = Date.now()
await Promise.all([
metadataStats.totalEntries === 0 ? this.metadataIndex.rebuild() : Promise.resolve(),
hnswIndexSize === 0 ? this.index.rebuild() : Promise.resolve(),
graphIndexSize === 0 ? this.graphIndex.rebuild() : Promise.resolve()
needsGraphRebuild ? this.graphIndex.rebuild() : Promise.resolve()
])
const rebuildDuration = Date.now() - rebuildStartTime

30
src/errors/brainyError.ts
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 source→target 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)
}
}
}

14
src/plugin.ts
View file

@ -250,6 +250,20 @@ export interface GraphIndexProvider {
*/
readonly isInitialized: boolean
/**
* @description Returns true ONLY when the source→target EDGES are loaded (NOT
* membership/manifest count) — the honest cold-load readiness signal. brainy
* gates the graph rebuild + the connected read-time guard on it: a `false`
* forces a rebuild from storage, and a still-`false` after that rebuild raises
* a loud {@link import('./errors/brainyError.js').GraphIndexNotReadyError}
* rather than serving an empty traversal as truth. cortex >= 2.7.8 (2.x) / 3.0
* exposes it; ABSENT on older providers, where brainy falls back to a
* known-edge-sample probe.
* @returns `true` when the persisted adjacency is loaded and traversals are
* trustworthy; `false` when only the count/manifest loaded (cold-open).
*/
isReady?(): boolean
/**
* @description Entity ints reachable from `id` (1 hop), deduped.
* @param id - The entity's interned int (from the shared idMapper).