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

fix(8.0): restore() reloads a native entity-id mapper before graphIndex.rebuild()

Browse source 
A logical snapshot restore could silently lose graph edges on a brain backed by
a native provider: the graph adjacency keys on the shared id-mapper's interned
ints (sourceInt/targetInt), which are derived + never persisted, and restore()
never reloaded the mapper — so a native graph rebuild resolved verb endpoints
against a stale/empty mapper and dropped edges.

restore() now calls entityIdMapper.rebuild() — a new OPTIONAL method on the
EntityIdMapperProvider contract — BEFORE rebuilding the indexes, so a native
mapper reloads its int<->uuid from the restored binary KV first and the graph
resolves endpoints correctly. The JS mapper deliberately has NO rebuild() and
needs none: MetadataIndex.rebuild() re-derives it from the restored entities via
append-only getOrAssign, consistently with the bitmaps it builds — forcing a
reload there would blank a still-referenced mapping and break find() after a
same-instance restore.

Contract: graphIndex.rebuild() resolves sourceId/targetId -> ints through the
shared mapper itself (brainy does not re-feed resolved endpoints); brainy's only
job is to ensure the mapper is reloaded first.

Test: relationships survive a snapshot round-trip (db-mvcc.test.ts). 84
generation/temporal/visibility tests green; tsc clean.
This commit is contained in:
David Snelling 2026-06-23 12:02:17 -07:00
parent 3783e61b30
commit 4d0b64f455
4 changed files with 72 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

12
src/plugin.ts
View file

@ -771,6 +771,18 @@ export interface VectorIndexProvider {
*/
export interface EntityIdMapperProvider {
init(): Promise<void>
/**
* @description OPTIONAL: reload the uuid↔int mapping from the CURRENT storage,
* discarding in-memory state — called by `brain.restore()` AFTER the storage
* has been replaced from a snapshot and BEFORE the graph index rebuilds, so
* the graph resolves each verb endpoint through a mapper that reflects the
* snapshot's assignments (without it, native adjacency edges — keyed on these
* ints — resolve to stale/missing ints and are silently dropped). A native
* mapper reloads from its restored binary KV; the JS fallback re-reads its
* persisted metadata. Optional so a mapper that already reloads via `init()`
* stays compatible — `restore()` falls back to `init()` when this is absent.
*/
rebuild?(): Promise<void>
getOrAssign(uuid: string): number
getUuid(intId: number): string | undefined
getInt(uuid: string): number | undefined