@soulcraft/cor 3.0.0-rc.1

package/dist/graph/NativeGraphAdjacencyIndex.js

@@ -0,0 +1,944 @@
+/**
+ * NativeGraphAdjacencyIndex — Thin TS wrapper around the Rust graph engine
+ *
+ * Handles async storage I/O while the Rust engine handles all in-memory
+ * data operations (4 LSM-trees, verb tracking, relationship counts).
+ *
+ * Storage pattern: adapter-controlled I/O with 3-tier fallback.
+ * - Tier 1 (mmap): saveBinaryBlob + getBinaryBlobPath → zero-copy queries
+ * - Tier 2 (binary blob): saveBinaryBlob only → binary format in memory
+ * - Tier 3 (legacy): saveMetadata → base64 JSON
+ *
+ * UnifiedCache integration stays in TS (getVerbCached, getVerbsBatchCached)
+ * since it coordinates cross-subsystem caching and requires async storage access.
+ */
+import { dirname } from 'node:path';
+import { TypeUtils, VerbType } from '@soulcraft/brainy/types/graphTypes';
+import { loadNativeModule } from '../native/index.js';
+import { getGlobalCache, prodLog } from '@soulcraft/brainy/internals';
+/**
+ * Fallback verb-type index for unknown / missing verb-type strings.
+ * Mirrors cor's `VERB_FALLBACK_INDEX` from `graph_types.rs` and
+ * brainy's `TypeUtils.getVerbIndex` runtime fallback to
+ * `VerbType.RelatedTo`. Resolved once at module load — the lookup
+ * itself is sub-microsecond but the constant is part of the
+ * closed-vocabulary contract documented at
+ * [[nountype-verbtype-closed-vocabulary]].
+ */
+const VERB_FALLBACK_INDEX = TypeUtils.getVerbIndex(VerbType.RelatedTo) ?? 3;
+/**
+ * Blob key probed to derive the durable verb-ID namespace directory when
+ * the caller didn't pass an explicit {@link GraphIndexConfig.persistenceDir}.
+ *
+ * On a filesystem-backed adapter, `getBinaryBlobPath(key)` resolves to a real
+ * on-disk path such as `<root>/_blobs/_graph_verb_ns/x.bin`; taking its
+ * `dirname` yields a local, per-brain directory (`<root>/_blobs/_graph_verb_ns`)
+ * that sits under the storage root ALONGSIDE the graph LSM SSTables
+ * (`<root>/_blobs/graph-lsm/…`), so brainy's hard-link snapshot captures the
+ * verb namespace + endpoints files together with the SSTables coherently.
+ *
+ * The trailing `/x` segment exists only so `dirname` peels back to the
+ * dedicated directory; no blob is ever written at this exact key — the native
+ * `VerbIdNamespace` owns the files inside the directory
+ * (`verb-uuid-to-int.mkv`, `verb-int-to-uuid.bin`, `verb-endpoints/`).
+ */
+const GRAPH_VERB_NS_PROBE_KEY = '_graph_verb_ns/x';
+/**
+ * Resolve a verb-type string to its canonical `VerbTypeEnum` index,
+ * falling back to {@link VERB_FALLBACK_INDEX} (`VerbType.RelatedTo`)
+ * for unknown / missing input. Avoids two FFI hops by doing the
+ * lookup in TS via brainy's `TypeUtils`, then handing the index
+ * directly to the native `addVerbByIndex` / `trackVerbIdByIndex`
+ * surface.
+ */
+function resolveVerbTypeIndex(verbType) {
+    if (!verbType)
+        return VERB_FALLBACK_INDEX;
+    const idx = TypeUtils.getVerbIndex(verbType);
+    return idx ?? VERB_FALLBACK_INDEX;
+}
+// Storage prefixes for each tree
+const TREE_PREFIXES = {
+    'source': 'graph-lsm-source',
+    'target': 'graph-lsm-target',
+    'verbs-source': 'graph-lsm-verbs-source',
+    'verbs-target': 'graph-lsm-verbs-target',
+};
+/**
+ * Native 4-LSM-tree graph adjacency index. Implements {@link GraphIndexProvider}
+ * so a compile error fires the moment this wrapper drops or drifts a member
+ * brainy calls via `this.graphIndex.*` (e.g. the `isInitialized` getter).
+ */
+export class GraphAdjacencyIndex {
+    migrationCoordinatorGetter;
+    storage;
+    native;
+    unifiedCache;
+    config;
+    initialized = false;
+    isRebuilding = false;
+    flushTimer;
+    rebuildStartTime = 0;
+    totalRelationshipsIndexed = 0;
+    isCompacting = {};
+    // Adapter capability detection (set in constructor)
+    hasBinaryBlobs;
+    hasMmapPaths;
+    /**
+     * Lazy resolver to the shared entity-id mapper (the metadata index's mapper —
+     * the one brainy resolves verb endpoints through at write time). Used ONLY by
+     * `rebuild()` to turn persisted `verb.sourceId`/`targetId` UUIDs back into the
+     * entity ints the 4 LSM adjacency trees are keyed on. Lazy because the
+     * metadata-index instance may be constructed after this one; it is resolved at
+     * rebuild time (post-init), by when both providers exist. `undefined` when cor
+     * is used without a metadata index — `rebuild()` then degrades to the
+     * membership-only pass and says so. (#68)
+     */
+    mapperResolver;
+    get isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * The underlying native graph engine handle. Exposed so the
+     * `graphAcceleration` provider adapter ({@link GraphAccelerationAdapter})
+     * can drive `traverse` / the streaming cursor against the SAME native
+     * instance this provider already holds — never a second index (which
+     * would split state + double RAM). Read-only by contract: the adapter
+     * only calls read/cursor methods on it.
+     */
+    get nativeInstance() {
+        return this.native;
+    }
+    constructor(storage, config = {}, mapperResolver, 
+    /**
+     * Lazy resolver to the shared {@link MigrationCoordinator} — the same getter
+     * the metadata + vector providers receive, so Brainy's feature-detected lock
+     * methods return a consistent answer across all three. Undefined when no
+     * migration path is wired.
+     */
+    migrationCoordinatorGetter) {
+        this.migrationCoordinatorGetter = migrationCoordinatorGetter;
+        this.storage = storage;
+        this.mapperResolver = mapperResolver;
+        // **related()-correctness + billion-scale RAM (#23).** When the caller
+        // did not pass an explicit `persistenceDir` but the storage adapter is
+        // filesystem-backed, derive one from a dedicated blob key so the native
+        // engine selects the DURABLE mmap `VerbIdNamespace` (+ mmap
+        // `VerbEndpointsStore`) instead of the in-memory fallback. This matters
+        // for correctness, not just speed:
+        //   • The in-memory namespace's reverse map (verbInt → verb-UUID) is a
+        //     no-op — `get_uuid` returns `None` — so `verbIntsToIds()` yields
+        //     `[null]`, brainy filters those out, and `getVerbsBySource()` /
+        //     `related()` come back empty even though the edge exists.
+        //   • The in-memory forward map is O(edges)-resident (~75–85 GB at 1B
+        //     edges) — a live RAM-invariant violation; the mmap namespace is
+        //     demand-paged (O(working-set)).
+        //   • The in-memory map re-interns from zero on reopen, so the fresh ints
+        //     never match the durable LSM's baked ints; only the persisted mmap
+        //     namespace is reopen-coherent.
+        //
+        // **Tier guard — gate on the RETURN VALUE, not method presence.**
+        // `getBinaryBlobPath` is an ABSTRACT member every adapter implements; the
+        // cloud/memory adapters implement it and return `null`. A `typeof … ===
+        // 'function'` guard would mis-route cloud into the filesystem path and
+        // hand native a bogus directory. So we invoke it and branch strictly on a
+        // non-null path. Cloud/memory return `null` → `persistenceDir` stays
+        // undefined → the in-memory namespace, unchanged (durable cloud
+        // materialization is task #26). Never throws for cloud.
+        let persistenceDir = config.persistenceDir;
+        if (persistenceDir === undefined) {
+            const probePath = storage.getBinaryBlobPath?.(GRAPH_VERB_NS_PROBE_KEY);
+            if (probePath) {
+                persistenceDir = dirname(probePath);
+            }
+        }
+        this.config = {
+            maxIndexSize: config.maxIndexSize ?? 100000,
+            rebuildThreshold: config.rebuildThreshold ?? 0.1,
+            autoOptimize: config.autoOptimize ?? true,
+            flushInterval: config.flushInterval ?? 30000,
+            memTableThreshold: config.memTableThreshold ?? 100000,
+            maxSSTablesPerLevel: config.maxSSTablesPerLevel ?? 10,
+            persistenceDir,
+        };
+        const bindings = loadNativeModule();
+        // Cor 3.0 zero-config: graph wrapper passes verbIdSpace='U64'
+        // so the verb-ID interning namespace + live-verb / per-(type,
+        // subtype) membership bitmaps support `u64::MAX - 1` verb IDs
+        // out of the box. The raw napi GraphAdjacencyConfig still
+        // defaults to 'U32' for direct-napi back-compat — the production
+        // path goes through this wrapper.
+        this.native = new bindings.NativeGraphAdjacencyIndex({
+            memTableThreshold: this.config.memTableThreshold,
+            maxSstablesPerLevel: this.config.maxSSTablesPerLevel,
+            persistenceDir: this.config.persistenceDir,
+            verbIdSpace: 'U64',
+        });
+        this.unifiedCache = getGlobalCache();
+        // Detect adapter capabilities via optional method presence
+        this.hasBinaryBlobs = typeof storage.saveBinaryBlob === 'function';
+        this.hasMmapPaths = typeof storage.getBinaryBlobPath === 'function';
+        if (this.hasMmapPaths) {
+            prodLog.info('GraphAdjacencyIndex initialized with native Rust engine (4 embedded LSM-trees, mmap SSTable I/O)');
+        }
+        else if (this.hasBinaryBlobs) {
+            prodLog.info('GraphAdjacencyIndex initialized with native Rust engine (4 embedded LSM-trees, binary blob I/O)');
+        }
+        else {
+            prodLog.info('GraphAdjacencyIndex initialized with native Rust engine (4 embedded LSM-trees)');
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Initialization
+    // ---------------------------------------------------------------------------
+    /**
+     * **Eager cold-load entry — brainy 8.0 rebuild gate (#36).** Brainy
+     * awaits this right after `metadataIndex.init()` and BEFORE it consults
+     * {@link isReady}, so the durable graph is restored (the four u64 LSM
+     * trees cold-loaded from their `.sst` blobs) before the gate reads
+     * readiness — otherwise `isReady()` would be `false` until the first
+     * lazy op and brainy would needlessly rebuild a graph that is already on
+     * disk. Idempotent and a no-op for an in-memory index; mirrors
+     * {@link MetadataIndexProvider.init}. Delegates to the same
+     * {@link ensureInitialized} guard the lazy read/mutation paths use, so
+     * an index that is never `init()`-ed still cold-loads on first touch.
+     */
+    async init() {
+        await this.ensureInitialized();
+    }
+    /**
+     * Idempotent lazy-init guard. Runs the cold-load
+     * ({@link openGraphLsmEngine}) exactly once, then arms auto-flush. Both
+     * the eager {@link init} and every read/mutation path funnel through
+     * here, so a caller that skips `init()` still gets a fully cold-loaded
+     * graph on first touch.
+     */
+    async ensureInitialized() {
+        if (this.initialized) {
+            return;
+        }
+        await this.openGraphLsmEngine();
+        this.startAutoFlush();
+        this.initialized = true;
+    }
+    /**
+     * Cold-load the four u64 LSM trees from persistence: load each tree's
+     * manifest and register every persisted SSTable (mmap tier, then binary
+     * blob tier) so the adjacency is queryable with NO rebuild. Each SSTable
+     * load latches the native `is_ready()` flag, so {@link isReady} reports
+     * `true` the instant durable edges are mapped in.
+     *
+     * The trailing membership-consistency walk is the **deferred O(N)
+     * fast-follow** (#19): it repopulates the verb-id membership bitmap when
+     * the trees hold edges but membership came back empty. It is explicitly
+     * NOT part of readiness — `isReady()` is already `true` from the SSTable
+     * loads above, so a slow membership walk can never make a graph with
+     * queryable edges report "not ready".
+     */
+    async openGraphLsmEngine() {
+        // Load manifests and SSTables for all 4 trees
+        const treeNames = this.native.treeNames();
+        for (const treeName of treeNames) {
+            await this.loadTreeFromStorage(treeName);
+        }
+        // Defensive check: if LSM-trees have data but verbIdSet is empty, populate.
+        // This is the deferred membership fast-follow — it does NOT gate isReady().
+        const sourceSize = this.native.size();
+        if (sourceSize > 0 && this.native.verbIdCount() === 0) {
+            prodLog.warn(`GraphAdjacencyIndex: LSM-trees have ${sourceSize} relationships but verbIdSet is empty. ` +
+                `Triggering auto-rebuild to restore consistency.`);
+            await this.populateVerbIdSetFromStorage();
+        }
+    }
+    async populateVerbIdSetFromStorage() {
+        prodLog.info('GraphAdjacencyIndex: Populating verbIdSet from storage...');
+        const startTime = Date.now();
+        let hasMore = true;
+        let cursor = undefined;
+        let count = 0;
+        while (hasMore) {
+            const result = await this.storage.getVerbs({
+                pagination: { limit: 10000, cursor }
+            });
+            for (const verb of result.items) {
+                // Cor 3.0 Piece D: trackVerbIdByIndex was deleted along with
+                // the other strict-index variants. trackVerbId takes the verb-
+                // type as a string; unknown strings fall back to RelatedTo —
+                // acceptable on the rebuild slow path because the membership
+                // bitmap converges to the same set either way.
+                this.native.trackVerbId(verb.id, verb.verb);
+                count++;
+            }
+            hasMore = result.hasMore;
+            cursor = result.nextCursor;
+        }
+        const elapsed = Date.now() - startTime;
+        prodLog.info(`GraphAdjacencyIndex: Populated verbIdSet with ${count} verb IDs in ${elapsed}ms`);
+    }
+    // ---------------------------------------------------------------------------
+    // Core graph operations
+    // ---------------------------------------------------------------------------
+    async getNeighbors(id, optionsOrDirection) {
+        await this.ensureInitialized();
+        const options = typeof optionsOrDirection === 'string'
+            ? { direction: optionsOrDirection }
+            : (optionsOrDirection || {});
+        const startTime = performance.now();
+        const direction = options.direction || 'both';
+        const limit = options.limit ?? null;
+        const offset = options.offset ?? null;
+        const result = this.native.getNeighbors(id, direction, limit, offset);
+        const elapsed = performance.now() - startTime;
+        if (elapsed > 5.0) {
+            prodLog.warn(`GraphAdjacencyIndex: Slow neighbor lookup for ${id}: ${elapsed.toFixed(2)}ms`);
+        }
+        return result;
+    }
+    async getVerbIdsBySource(sourceInt, options) {
+        await this.ensureInitialized();
+        const startTime = performance.now();
+        const limit = options?.limit ?? null;
+        const offset = options?.offset ?? null;
+        const result = this.native.getVerbIdsBySource(sourceInt, limit, offset);
+        const elapsed = performance.now() - startTime;
+        if (elapsed > 5.0) {
+            prodLog.warn(`GraphAdjacencyIndex: Slow getVerbIdsBySource for ${sourceInt}: ${elapsed.toFixed(2)}ms`);
+        }
+        return result;
+    }
+    async getVerbIdsByTarget(targetInt, options) {
+        await this.ensureInitialized();
+        const startTime = performance.now();
+        const limit = options?.limit ?? null;
+        const offset = options?.offset ?? null;
+        const result = this.native.getVerbIdsByTarget(targetInt, limit, offset);
+        const elapsed = performance.now() - startTime;
+        if (elapsed > 5.0) {
+            prodLog.warn(`GraphAdjacencyIndex: Slow getVerbIdsByTarget for ${targetInt}: ${elapsed.toFixed(2)}ms`);
+        }
+        return result;
+    }
+    async getVerbCached(verbId) {
+        const cacheKey = `graph:verb:${verbId}`;
+        const verb = await this.unifiedCache.get(cacheKey, async () => {
+            const loadedVerb = await this.storage.getVerb(verbId);
+            if (loadedVerb) {
+                this.unifiedCache.set(cacheKey, loadedVerb, 'other', 128, 50);
+            }
+            return loadedVerb;
+        });
+        return verb;
+    }
+    async getVerbsBatchCached(verbIds) {
+        const results = new Map();
+        const uncached = [];
+        for (const verbId of verbIds) {
+            const cacheKey = `graph:verb:${verbId}`;
+            const cached = this.unifiedCache.getSync(cacheKey);
+            if (cached) {
+                results.set(verbId, cached);
+            }
+            else {
+                uncached.push(verbId);
+            }
+        }
+        if (uncached.length > 0 && this.storage.getVerbsBatch) {
+            const loadedVerbs = await this.storage.getVerbsBatch(uncached);
+            for (const [verbId, verb] of loadedVerbs.entries()) {
+                const cacheKey = `graph:verb:${verbId}`;
+                this.unifiedCache.set(cacheKey, verb, 'other', 128, 50);
+                results.set(verbId, verb);
+            }
+        }
+        return results;
+    }
+    // ---------------------------------------------------------------------------
+    // Mutation operations
+    // ---------------------------------------------------------------------------
+    /**
+     * Add a verb to the graph. Cor 3.0 Piece D requires the brain's
+     * canonical `(sourceInt, targetInt)` entity-int pair as explicit
+     * parameters — brainy 8.0 resolves these via its `BinaryIdMapper`
+     * before calling. The `verb` object provides the verb-ID, verb-type,
+     * and optional subtype; entity UUIDs on the verb (`verb.sourceId`,
+     * `verb.targetId`) are no longer used by cor.
+     */
+    /**
+     * Index a new verb (relationship). Returns the verb's interned
+     * `u64` integer ID so brainy 8.0's `verb_int ↔ verb_id_string`
+     * sidecar map populates without a follow-up
+     * `getVerbIntForString` FFI roundtrip — one boundary crossing
+     * saved per add at billion-scale ingest (PLATFORM-HANDOFF
+     * BRAINY-8.0-RENAME-COORDINATION A.3).
+     *
+     * The wrapper's previous brainy 7.x signature was
+     * `Promise<void>`; brainy 7.x callers that ignore the new
+     * return value continue to work unchanged.
+     */
+    async addVerb(verb, sourceInt, targetInt, generation) {
+        await this.ensureInitialized();
+        const startTime = performance.now();
+        const verbTypeIndex = resolveVerbTypeIndex(verb.verb);
+        // Native subtype param is `String` with '' = "no subtype" (the empty-string
+        // escape; graph_adjacency.rs guards on `!subtype.is_empty()`). Passing JS
+        // null throws "Failed to convert Null into String" at the napi boundary, so
+        // coalesce absent subtype to '' here.
+        const subtype = verb.subtype ?? '';
+        const result = this.native.addVerbWithEndpointsByIndex(verb.id, sourceInt, targetInt, verbTypeIndex, subtype, generation);
+        // Flush any trees that hit their threshold
+        const flushPromises = [];
+        if (result.needsFlushSource) {
+            flushPromises.push(this.flushTree('source'));
+        }
+        if (result.needsFlushTarget) {
+            flushPromises.push(this.flushTree('target'));
+        }
+        if (result.needsFlushVerbsSource) {
+            flushPromises.push(this.flushTree('verbs-source'));
+        }
+        if (result.needsFlushVerbsTarget) {
+            flushPromises.push(this.flushTree('verbs-target'));
+        }
+        if (flushPromises.length > 0) {
+            await Promise.all(flushPromises);
+        }
+        const elapsed = performance.now() - startTime;
+        this.totalRelationshipsIndexed++;
+        if (elapsed > 10.0) {
+            prodLog.warn(`GraphAdjacencyIndex: Slow addVerb for ${verb.id}: ${elapsed.toFixed(2)}ms`);
+        }
+        return result.verbInt;
+    }
+    async removeVerb(verbId, generation) {
+        await this.ensureInitialized();
+        // Load verb to get type + subtype info
+        const verb = await this.getVerbCached(verbId);
+        if (!verb)
+            return;
+        const startTime = performance.now();
+        const verbTypeIndex = resolveVerbTypeIndex(verb.verb);
+        // Native subtype param is `String` with '' = "no subtype" (the empty-string
+        // escape; graph_adjacency.rs guards on `!subtype.is_empty()`). Passing JS
+        // null throws "Failed to convert Null into String" at the napi boundary, so
+        // coalesce absent subtype to '' here.
+        const subtype = verb.subtype ?? '';
+        this.native.removeVerb(verbId, verbTypeIndex, subtype, generation);
+        const elapsed = performance.now() - startTime;
+        if (elapsed > 5.0) {
+            prodLog.warn(`GraphAdjacencyIndex: Slow removeVerb for ${verbId}: ${elapsed.toFixed(2)}ms`);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Size, counts, stats
+    // ---------------------------------------------------------------------------
+    size() {
+        return this.native.size();
+    }
+    getRelationshipCountByType(type) {
+        return this.native.getRelationshipCountByType(type);
+    }
+    getTotalRelationshipCount() {
+        return this.native.verbIdCount();
+    }
+    getAllRelationshipCounts() {
+        const json = this.native.getAllRelationshipCountsJson();
+        const obj = JSON.parse(json);
+        return new Map(Object.entries(obj));
+    }
+    /**
+     * **Batch verb-int reverse resolver** — brainy 8.0
+     * `GraphIndexProvider.verbIntsToIds` contract (handoff Section L.7).
+     *
+     * Given a batch of verb-int BigInts, return the canonical UUID
+     * string for each — `null` for any int that has no entry in
+     * cor's persistent reverse map.
+     *
+     * Cor's namespace is the single source of truth for the
+     * `verb-int ↔ verb-id` mapping (the persisted `verb-int-to-uuid.bin`
+     * is direct-indexed for O(1) random reads). Brainy keeps only a
+     * bounded in-memory LRU warm cache fed by `addVerb` returns and
+     * resolver hits — no full reverse map on the JS side.
+     *
+     * The identity-fingerprint design (handoff L.7) makes this
+     * lossless: brainy's `relate()` validates verb-ids are canonical
+     * UUIDs, cor stores the raw 16 UUID bytes, and `verbIntsToIds`
+     * formats them back to the canonical lowercase 8-4-4-4-12 form.
+     */
+    async verbIntsToIds(verbInts) {
+        if (verbInts.length === 0)
+            return [];
+        const raw = this.native.verbIntsToUuids(verbInts);
+        // napi-rs renders `Option<String>` as `string | undefined | null`
+        // on the .d.ts surface; normalise to `string | null` for the
+        // GraphIndexProvider contract (brainy 8.0 declares the
+        // null-or-string return shape strictly).
+        return raw.map((v) => v ?? null);
+    }
+    getRelationshipStats() {
+        const json = this.native.getRelationshipStatsJson();
+        return JSON.parse(json);
+    }
+    getStats() {
+        const stats = this.native.getStats();
+        return {
+            totalRelationships: stats.totalRelationships,
+            sourceNodes: stats.sourceSstableCount,
+            targetNodes: stats.targetSstableCount,
+            memoryUsage: stats.sourceMemTableMemory + stats.targetMemTableMemory + (stats.verbIdCount * 8),
+            lastRebuild: this.rebuildStartTime,
+            rebuildTime: this.isRebuilding ? Date.now() - this.rebuildStartTime : 0,
+        };
+    }
+    isHealthy() {
+        if (!this.initialized) {
+            return false;
+        }
+        return !this.isRebuilding && this.native.isHealthy();
+    }
+    /**
+     * Whether the graph's edges are loaded and queryable WITHOUT a rebuild —
+     * brainy 8.0's rebuild gate (#36). Delegates straight to the native
+     * edges-ready latch (set on SSTable cold-load, a non-empty manifest, or a
+     * memtable flush) ORed with a live non-empty memtable. Synchronous (no
+     * await) and **never gated on the verb-id membership walk**, so the
+     * deferred O(N) membership fast-follow can never depress readiness for a
+     * graph whose edges are already mapped in.
+     */
+    isReady() {
+        return this.native.isReady();
+    }
+    /**
+     * @description **#18 migration lock — feature-detected by Brainy.** `true` while
+     * the brain is undergoing (or has failed) the coordinated 7.x → 8.0 rebuild, so
+     * Brainy holds reads+writes behind the lock (and, in rc.9, `verifyGraphAdjacencyLive`
+     * short-circuits to `'live'` rather than firing its own rebuild-on-read).
+     * Delegates to the shared {@link MigrationCoordinator}; `false` when none is wired.
+     * @returns `true` when the brain must not be read from or written to.
+     */
+    isMigrating() {
+        return this.migrationCoordinatorGetter?.()?.isMigrating() ?? false;
+    }
+    /**
+     * @description **#18 migration lock — structured progress** Brainy relays into
+     * `getIndexStatus().migration`. `null` unless a migration is in flight.
+     * @returns The current {@link MigrationStatus}, or `null`.
+     */
+    migrationStatus() {
+        return this.migrationCoordinatorGetter?.()?.migrationStatus() ?? null;
+    }
+    // ---------------------------------------------------------------------------
+    // Rebuild
+    // ---------------------------------------------------------------------------
+    /**
+     * Rebuild the graph adjacency from brainy's persisted verbs — used after a
+     * restore/migration that wiped the native subdirs (#68).
+     *
+     * **Full adjacency reconstruction** when a shared entity-id mapper resolver is
+     * wired (the metadata index's mapper — the SAME one brainy resolves verb
+     * endpoints through at write time, `metadataIndex.getIdMapper().getOrAssign`).
+     * For each persisted verb this resolves `sourceId`/`targetId` → entity ints via
+     * that mapper and replays `addVerbWithEndpointsByIndex`, rebuilding all four
+     * u64-keyed LSM trees exactly as the live write path does (which also
+     * repopulates the membership bitmap + per-type counts — so `trackVerbId` is NOT
+     * also called for a reconstructed edge, or membership/counts would double). Brainy
+     * 8.0 `restore()` awaits `metadataIndex.getIdMapper().rebuild()` BEFORE the
+     * `Promise.all` that runs this, so the mapper is fully populated with the
+     * snapshot's assignments before endpoints are resolved here.
+     *
+     * Cursor-paginated (#74) — O(batch) RAM at any edge count; memtable flush
+     * thresholds are respected mid-walk so RAM stays bounded at billion-edge scale.
+     * Endpoints whose UUID does not resolve in the mapper (an entity that is a graph
+     * node but was not walked as a noun) are tracked for membership, counted, and
+     * warned — never silently dropped. Restored edges reconstruct at the floor
+     * generation (0): present-state is exact; historical as-of-g for pre-restore
+     * edges is not reconstructable from canonical records (the same limit the
+     * metadata + vector rebuilds carry).
+     *
+     * Without a mapper resolver (cor used without a metadata index), it degrades to
+     * the membership-only pass (bitmap + per-type counts via `trackVerbId`) and logs
+     * that adjacency was not reconstructed — the on-disk `.sst` trees loaded in
+     * {@link ensureInitialized} remain the adjacency source in that case.
+     */
+    async rebuild() {
+        await this.ensureInitialized();
+        if (this.isRebuilding) {
+            prodLog.warn('GraphAdjacencyIndex: Rebuild already in progress');
+            return;
+        }
+        this.isRebuilding = true;
+        this.rebuildStartTime = Date.now();
+        try {
+            const mapper = this.mapperResolver?.();
+            const reconstructAdjacency = mapper !== undefined;
+            prodLog.info(reconstructAdjacency
+                ? 'GraphAdjacencyIndex: Starting rebuild (full adjacency — resolving endpoints via shared mapper)...'
+                : 'GraphAdjacencyIndex: Starting rebuild (membership-only — no shared mapper wired)...');
+            this.native.clearVerbTracking();
+            // Restored edges reconstruct present-state at the floor generation; the
+            // canonical verb records carry no per-edge history, so as-of-g for
+            // pre-restore edges is not reconstructable (same limit as metadata/vector
+            // rebuilds). Current (non-as-of) reads see them — a single floor-gen entry
+            // is the latest in each verb's version chain.
+            const REBUILD_GENERATION = 0n;
+            // Cursor-paginate for EVERY storage type — O(batch) RAM, complete at any
+            // scale; never load-all (the OOM / silent-10M-truncation trap). (#74)
+            let totalVerbs = 0;
+            let edgesRebuilt = 0;
+            let unresolvedEndpoints = 0;
+            let hasMore = true;
+            let cursor = undefined;
+            const batchSize = 10000;
+            while (hasMore) {
+                const result = await this.storage.getVerbs({ pagination: { limit: batchSize, cursor } });
+                for (const verb of result.items) {
+                    totalVerbs++;
+                    const verbType = verb.verb ?? 'relatedTo';
+                    if (!reconstructAdjacency) {
+                        this.native.trackVerbId(verb.id, verbType);
+                        continue;
+                    }
+                    const sourceId = verb.sourceId;
+                    const targetId = verb.targetId;
+                    const sourceInt = sourceId !== undefined ? mapper.getInt(sourceId) : undefined;
+                    const targetInt = targetId !== undefined ? mapper.getInt(targetId) : undefined;
+                    if (sourceInt === undefined || targetInt === undefined) {
+                        // Endpoint not in the mapper — still record membership so the verb
+                        // isn't lost; its adjacency can't be rebuilt without the int.
+                        this.native.trackVerbId(verb.id, verbType);
+                        unresolvedEndpoints++;
+                        continue;
+                    }
+                    const verbTypeIndex = resolveVerbTypeIndex(verbType);
+                    // Native subtype param is `String` with '' = "no subtype" (the
+                    // empty-string escape; graph_adjacency.rs guards on
+                    // `!subtype.is_empty()`). JS null throws "Null into String" at the
+                    // napi boundary, so coalesce absent subtype to ''.
+                    const subtype = verb.subtype ?? '';
+                    const addResult = this.native.addVerbWithEndpointsByIndex(verb.id, BigInt(sourceInt), BigInt(targetInt), verbTypeIndex, subtype, REBUILD_GENERATION);
+                    edgesRebuilt++;
+                    // Respect memtable flush thresholds mid-walk so RAM stays bounded.
+                    const flushPromises = [];
+                    if (addResult.needsFlushSource)
+                        flushPromises.push(this.flushTree('source'));
+                    if (addResult.needsFlushTarget)
+                        flushPromises.push(this.flushTree('target'));
+                    if (addResult.needsFlushVerbsSource)
+                        flushPromises.push(this.flushTree('verbs-source'));
+                    if (addResult.needsFlushVerbsTarget)
+                        flushPromises.push(this.flushTree('verbs-target'));
+                    if (flushPromises.length > 0)
+                        await Promise.all(flushPromises);
+                }
+                hasMore = result.hasMore;
+                cursor = result.nextCursor;
+            }
+            this.totalRelationshipsIndexed = totalVerbs;
+            if (reconstructAdjacency) {
+                // Persist partially-filled memtables from the final batch.
+                await this.flush();
+                if (unresolvedEndpoints > 0) {
+                    prodLog.warn(`GraphAdjacencyIndex: ${unresolvedEndpoints.toLocaleString()} verb endpoint(s) did not ` +
+                        `resolve in the shared mapper and kept membership-only (entity is a graph node but was ` +
+                        `not walked as a noun). ${edgesRebuilt.toLocaleString()} edges fully rebuilt.`);
+                }
+            }
+            const rebuildTime = Date.now() - this.rebuildStartTime;
+            const memoryUsage = this.calculateMemoryUsage();
+            prodLog.info(`GraphAdjacencyIndex: Rebuild complete in ${rebuildTime}ms`);
+            prodLog.info(`  - Total verbs tracked: ${totalVerbs.toLocaleString()}`);
+            if (reconstructAdjacency) {
+                prodLog.info(`  - Adjacency edges rebuilt: ${edgesRebuilt.toLocaleString()} (unresolved endpoints: ${unresolvedEndpoints.toLocaleString()})`);
+            }
+            prodLog.info(`  - Memory usage: ${(memoryUsage / 1024 / 1024).toFixed(1)}MB`);
+            prodLog.info(`  - Stats:`, this.native.getStats());
+        }
+        finally {
+            this.isRebuilding = false;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Flush and close
+    // ---------------------------------------------------------------------------
+    async flush() {
+        if (!this.initialized) {
+            return;
+        }
+        const startTime = Date.now();
+        const treeNames = this.native.treeNames();
+        const flushPromises = treeNames
+            .filter(name => !this.native.memTableIsEmpty(name))
+            .map(name => this.flushTree(name));
+        if (flushPromises.length > 0) {
+            await Promise.all(flushPromises);
+        }
+        const elapsed = Date.now() - startTime;
+        prodLog.debug(`GraphAdjacencyIndex: Flush completed in ${elapsed}ms`);
+    }
+    async close() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        if (this.initialized) {
+            // Flush all trees that have pending data
+            await this.flush();
+        }
+        prodLog.info('GraphAdjacencyIndex: Shutdown complete');
+    }
+    // ---------------------------------------------------------------------------
+    // Private: Per-tree storage I/O (adapter-controlled)
+    // ---------------------------------------------------------------------------
+    /** Blob key for an SSTable: "graph-lsm/{treeName}/{sstableId}" */
+    blobKey(treeName, sstableId) {
+        return `graph-lsm/${treeName}/${sstableId}`;
+    }
+    async loadTreeFromStorage(treeName) {
+        const prefix = TREE_PREFIXES[treeName];
+        if (!prefix)
+            return;
+        try {
+            const metadata = await this.storage.getMetadata(`${prefix}-manifest`);
+            if (metadata && metadata.data) {
+                const data = metadata.data;
+                // Pass the FULL persisted manifest to the native loader, NOT a hand-picked
+                // subset. `saveTreeManifest` persists `JSON.parse(getManifestJson(tree))`
+                // verbatim, so `data` already IS the native manifest shape. The previous
+                // rebuild kept only {sstables, lastCompaction, totalRelationships} and
+                // DROPPED the other fields `getManifestSstableIds` reads — so on a cold
+                // reopen the native loader saw ZERO sstable ids, loaded nothing, and the
+                // adjacency came back empty (manifest count present, getNeighbors → []).
+                // This is the 2.7.6 Venue-P1 cold-load bug; 3.0 had the identical defect.
+                const manifestJson = JSON.stringify({
+                    ...data,
+                    sstables: data.sstables || {},
+                    lastCompaction: data.lastCompaction || Date.now(),
+                    totalRelationships: data.totalRelationships || 0,
+                });
+                this.native.loadManifestJson(treeName, manifestJson);
+                await this.loadTreeSSTables(treeName, prefix);
+            }
+        }
+        catch (loadErr) {
+            // Previously a silent `catch {}` ("no manifest, starting fresh") that ALSO
+            // swallowed a real cold-load failure, leaving the count loaded and the
+            // adjacency empty. Surface it so a genuine failure is never silent.
+            prodLog.warn(`GraphAdjacencyIndex: cold-load failed for ${treeName} — adjacency may be incomplete`, loadErr);
+        }
+    }
+    async loadTreeSSTables(treeName, prefix) {
+        const ids = this.native.getManifestSstableIds(treeName);
+        let mmapLoaded = 0;
+        let binaryLoaded = 0;
+        const loadPromises = ids.map(async (sstableId) => {
+            try {
+                const level = this.native.getManifestSstableLevel(treeName, sstableId);
+                if (level === null || level === undefined) {
+                    return;
+                }
+                const key = this.blobKey(treeName, sstableId);
+                // Tier 1: Try mmap path (getBinaryBlobPath → loadSstableFromFile)
+                if (this.hasMmapPaths) {
+                    const filePath = this.storage.getBinaryBlobPath(key);
+                    if (filePath) {
+                        try {
+                            this.native.loadSstableFromFile(treeName, sstableId, level, filePath);
+                            mmapLoaded++;
+                            return;
+                        }
+                        catch (mmapErr) {
+                            // On a cold reopen the file exists, so a throw here is a real
+                            // failure (not "first run") — surface it, then fall through to the
+                            // binary tier which can still serve it. Never silent (2.7.6 parity).
+                            prodLog.warn(`GraphAdjacencyIndex: mmap SSTable load failed for ${treeName}/${sstableId} @ ${filePath} — trying binary tier`, mmapErr);
+                        }
+                    }
+                }
+                // Tier 2: Try binary blob (loadBinaryBlob → loadSstableFromBinary).
+                // Cor 3.0 Piece D dropped the legacy base64-in-JSON tier
+                // because the napi-side `loadSstable` (msgpack) is gone — the
+                // u64-keyed LSM core only ships the binary `.sst` format. Any
+                // brain persisted under the old shape needs the offline
+                // migrator (Piece E) before it can be opened.
+                if (this.hasBinaryBlobs) {
+                    const blobData = await this.storage.loadBinaryBlob(key);
+                    if (blobData) {
+                        this.native.loadSstableFromBinary(treeName, sstableId, level, blobData);
+                        binaryLoaded++;
+                        return;
+                    }
+                }
+                // No tier matched — log and skip.
+                prodLog.warn(`GraphAdjacencyIndex: SSTable ${sstableId} for ${treeName} found in manifest but no readable backing exists (skipped)`);
+            }
+            catch (error) {
+                prodLog.warn(`GraphAdjacencyIndex: Failed to load SSTable ${sstableId} for ${treeName}`, error);
+            }
+        });
+        await Promise.all(loadPromises);
+        const parts = [];
+        if (mmapLoaded > 0)
+            parts.push(`${mmapLoaded} mmap`);
+        if (binaryLoaded > 0)
+            parts.push(`${binaryLoaded} binary`);
+        const detail = parts.length > 0 ? ` (${parts.join(', ')})` : '';
+        prodLog.info(`GraphAdjacencyIndex: Loaded ${ids.length} SSTables for ${treeName}${detail}`);
+    }
+    async flushTree(treeName) {
+        if (this.native.memTableIsEmpty(treeName)) {
+            return;
+        }
+        const prefix = TREE_PREFIXES[treeName];
+        if (!prefix)
+            return;
+        const startTime = Date.now();
+        try {
+            // Binary blob flush (adapter-controlled): Rust serializes → adapter writes
+            if (this.hasBinaryBlobs) {
+                const result = this.native.flushTreeToBinary(treeName);
+                if (!result)
+                    return;
+                const key = this.blobKey(treeName, result.sstableId);
+                await this.storage.saveBinaryBlob(key, Buffer.from(result.data));
+                // If adapter supports mmap, upgrade InMemory → Mapped
+                if (this.hasMmapPaths) {
+                    const filePath = this.storage.getBinaryBlobPath(key);
+                    if (filePath) {
+                        try {
+                            this.native.registerMmapSstable(treeName, result.sstableId, result.level, filePath);
+                        }
+                        catch {
+                            // Non-fatal: InMemory variant still works
+                        }
+                    }
+                }
+                await this.saveTreeManifest(treeName, prefix);
+                const elapsed = Date.now() - startTime;
+                prodLog.info(`GraphAdjacencyIndex: Flushed ${treeName} in ${elapsed}ms (${result.entryCount} entries, ${result.valueCount} values, binary blob)`);
+                if (this.native.needsCompaction(treeName, 0)) {
+                    setImmediate(() => this.compactTree(treeName, 0));
+                }
+                return;
+            }
+            // Cor 3.0 Piece D dropped the legacy base64-in-JSON flush
+            // path — the napi-side `flushTree` (msgpack) is gone. The only
+            // remaining flush path is the binary blob branch above which
+            // requires an adapter exposing `saveBinaryBlob`.
+            prodLog.warn(`GraphAdjacencyIndex: Skipping flush for ${treeName}: storage adapter does not expose saveBinaryBlob (Piece D requires binary blob I/O)`);
+        }
+        catch (error) {
+            prodLog.error(`GraphAdjacencyIndex: Failed to flush ${treeName}`, error);
+            throw error;
+        }
+    }
+    async compactTree(treeName, level) {
+        if (this.isCompacting[treeName]) {
+            return;
+        }
+        this.isCompacting[treeName] = true;
+        const prefix = TREE_PREFIXES[treeName];
+        if (!prefix)
+            return;
+        const startTime = Date.now();
+        try {
+            // Binary blob compaction (adapter-controlled).
+            //
+            // **Piece 6 manifest ordering invariant**: durability requires
+            //   1. write new blob (fully persisted)
+            //   2. update manifest (the durable source-of-truth that
+            //      references the new blob and no longer references the
+            //      old blobs)
+            //   3. THEN delete old blobs (orphan cleanup, only safe to do
+            //      AFTER the manifest no longer references them)
+            //
+            // The earlier shape deleted old blobs BEFORE updating the
+            // manifest. A crash between those two steps left the
+            // manifest pointing at blobs that had been physically removed,
+            // so reopening the brain failed with "missing SSTable file".
+            // Putting the manifest update before the delete makes the
+            // crash-between-steps state recoverable: the manifest still
+            // references the just-deleted (or pending-deletion) blobs,
+            // both of which exist on disk during that window.
+            if (this.hasBinaryBlobs) {
+                const result = this.native.compactTreeToBinary(treeName, level);
+                if (!result)
+                    return;
+                prodLog.info(`GraphAdjacencyIndex: Compacting ${treeName} L${level} → L${result.newLevel} (binary blob)`);
+                // 1. Save new merged SSTable via adapter — must complete
+                //    BEFORE any reference (manifest) is updated.
+                const newKey = this.blobKey(treeName, result.newSstableId);
+                await this.storage.saveBinaryBlob(newKey, Buffer.from(result.data));
+                // If adapter supports mmap, upgrade InMemory → Mapped.
+                // Best-effort; the InMemory variant still works.
+                if (this.hasMmapPaths) {
+                    const filePath = this.storage.getBinaryBlobPath(newKey);
+                    if (filePath) {
+                        try {
+                            this.native.registerMmapSstable(treeName, result.newSstableId, result.newLevel, filePath);
+                        }
+                        catch {
+                            // Non-fatal: InMemory variant still works
+                        }
+                    }
+                }
+                // 2. Update the manifest. After this point the durable
+                //    source-of-truth references the new blob and no longer
+                //    references the old blobs — so a crash before step 3
+                //    just leaves orphans, never a missing-blob error.
+                await this.saveTreeManifest(treeName, prefix);
+                // 3. Delete old blobs (best-effort orphan cleanup AFTER the
+                //    manifest no longer references them). Failures here are
+                //    harmless — the worst outcome is leaked disk space until
+                //    a future operator-level GC sweep.
+                for (const oldId of result.oldIds) {
+                    const oldBlobKey = this.blobKey(treeName, oldId);
+                    this.storage.deleteBinaryBlob(oldBlobKey).catch(() => { });
+                }
+                const elapsed = Date.now() - startTime;
+                prodLog.info(`GraphAdjacencyIndex: Compaction ${treeName} L${level} → L${result.newLevel} complete in ${elapsed}ms`);
+                if (result.newLevel < 6 && this.native.needsCompaction(treeName, result.newLevel)) {
+                    setImmediate(() => this.compactTree(treeName, result.newLevel));
+                }
+                return;
+            }
+            // Cor 3.0 Piece D dropped the legacy base64-in-JSON compaction
+            // path — the napi-side `compactTree` (msgpack) is gone. The only
+            // remaining path is the binary blob branch above which requires
+            // an adapter exposing `saveBinaryBlob`.
+            prodLog.warn(`GraphAdjacencyIndex: Skipping compaction for ${treeName} L${level}: storage adapter does not expose saveBinaryBlob (Piece D requires binary blob I/O)`);
+        }
+        catch (error) {
+            prodLog.error(`GraphAdjacencyIndex: Compaction failed for ${treeName} L${level}`, error);
+        }
+        finally {
+            this.isCompacting[treeName] = false;
+        }
+    }
+    async saveTreeManifest(treeName, prefix) {
+        try {
+            const manifestJson = this.native.getManifestJson(treeName);
+            const manifestData = JSON.parse(manifestJson);
+            await this.storage.saveMetadata(`${prefix}-manifest`, {
+                noun: 'thing',
+                data: manifestData,
+            });
+        }
+        catch (error) {
+            prodLog.error(`GraphAdjacencyIndex: Failed to save manifest for ${treeName}`, error);
+            throw error;
+        }
+    }
+    startAutoFlush() {
+        this.flushTimer = setInterval(async () => {
+            await this.flush();
+        }, this.config.flushInterval);
+    }
+    calculateMemoryUsage() {
+        const stats = this.native.getStats();
+        let bytes = 0;
+        bytes += stats.sourceMemTableMemory;
+        bytes += stats.targetMemTableMemory;
+        bytes += stats.verbIdCount * 8;
+        return bytes;
+    }
+}
+//# sourceMappingURL=NativeGraphAdjacencyIndex.js.map