@soulcraft/cor 3.0.0-rc.1

package/dist/graph/GraphAccelerationAdapter.js

@@ -0,0 +1,326 @@
+/**
+ * @module graph/GraphAccelerationAdapter
+ * @description The `'graphAcceleration'` provider — cor's native graph
+ * engine behind brainy 8.0's optional {@link GraphAccelerationProvider}
+ * contract (ADR-006). When brainy feature-detects this provider, the
+ * public `brain.graph.*` surface (`subgraph` / `export`) and the
+ * `related()` / `find({ connected })` paths route here instead of brainy's
+ * pure-TS adjacency fallback.
+ *
+ * **It wraps the SAME native handle the `graphIndex` provider already
+ * holds** — never a second `NativeGraphAdjacencyIndex` (which would split
+ * state + double RAM). brainy's `activate(context)` hook has no storage and
+ * its provider factories are called with storage only (not the graphIndex
+ * instance), and the `graphAcceleration` value is feature-detected raw
+ * (the factory is never invoked with storage), so this adapter is
+ * registered at `activate()` time bound to a *resolver* that the
+ * `graphIndex` factory fills once it constructs the native engine. Until
+ * the engine is built + loaded, {@link isInitialized} reports `false` and
+ * brainy keeps serving graph ops from TS — the contract's safety valve, so
+ * a read is never routed here before the data is loaded.
+ *
+ * **Scope (cor 3.0 / brainy 8.0):** the full `GraphAccelerationProvider`
+ * surface — `traverse`, `edgesForNode`, the streaming cursor
+ * (`graphCursorOpen` / `graphCursorNext` / `graphCursorClose`), AND the Phase C
+ * analytics (`pageRank`, `connectedComponents`, `shortestPath`,
+ * `neighborhoodSample`, `topByDegree`). All five analytics ship together (the
+ * feature-detect anchors on `traverse` + `graphCursorOpen`, but brainy does not
+ * per-method-guard the analytics — a partial set would throw). **`shortestPath`
+ * is hops-only** — cor stores no edge weights, so the adapter refuses
+ * `weight: 'edge'` and brainy must serve weighted paths from TS.
+ *
+ * **Zero-copy decode:** native reads return columnar little-endian
+ * {@link Buffer}s; this adapter views each as the matching typed array over
+ * the same memory (no element-wise copy) on the little-endian hosts cor
+ * targets, falling back to a copy only on the (never-expected) misaligned
+ * Buffer. brainy resolves the u64 node/verb ints to UUIDs lazily.
+ *
+ * **Not applied here:** `excludeVisibility` (the graph index carries no
+ * node-visibility data — that lives in the metadata/vector layer; brainy
+ * applies visibility on reassembly) and `subtypes` (cor's traverse filters
+ * by verb-type index only). Both are dropped at this seam, matching Phase A
+ * `traverse`.
+ */
+/** View a packed little-endian `u64` column as a `BigInt64Array` (the wire
+ * format brainy's {@link Subgraph} expects), zero-copy when the Buffer is
+ * 8-aligned (the napi `Vec`-backed norm), else via a one-time aligned copy. */
+function viewBigInt64(buf) {
+    if (buf.byteLength === 0)
+        return new BigInt64Array(0);
+    if (buf.byteOffset % 8 === 0 && buf.byteLength % 8 === 0) {
+        return new BigInt64Array(buf.buffer, buf.byteOffset, buf.byteLength / 8);
+    }
+    const copy = new ArrayBuffer(buf.byteLength);
+    new Uint8Array(copy).set(buf);
+    return new BigInt64Array(copy);
+}
+/** View a packed little-endian `u16` column as a `Uint16Array`. */
+function viewUint16(buf) {
+    if (buf.byteLength === 0)
+        return new Uint16Array(0);
+    if (buf.byteOffset % 2 === 0 && buf.byteLength % 2 === 0) {
+        return new Uint16Array(buf.buffer, buf.byteOffset, buf.byteLength / 2);
+    }
+    const copy = new ArrayBuffer(buf.byteLength);
+    new Uint8Array(copy).set(buf);
+    return new Uint16Array(copy);
+}
+/** View a `u8` column as a `Uint8Array` (always byte-aligned → zero-copy). */
+function viewUint8(buf) {
+    if (buf.byteLength === 0)
+        return new Uint8Array(0);
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+}
+/** View a packed little-endian `f64` column as a `Float64Array` (brainy's
+ * `GraphScores.scores`), zero-copy when 8-aligned else via an aligned copy. */
+function viewFloat64(buf) {
+    if (buf.byteLength === 0)
+        return new Float64Array(0);
+    if (buf.byteOffset % 8 === 0 && buf.byteLength % 8 === 0) {
+        return new Float64Array(buf.buffer, buf.byteOffset, buf.byteLength / 8);
+    }
+    const copy = new ArrayBuffer(buf.byteLength);
+    new Uint8Array(copy).set(buf);
+    return new Float64Array(copy);
+}
+/** View a packed little-endian `u32` column as a `Uint32Array` (brainy's
+ * `GraphComponents.componentIds`), zero-copy when 4-aligned else via a copy. */
+function viewUint32(buf) {
+    if (buf.byteLength === 0)
+        return new Uint32Array(0);
+    if (buf.byteOffset % 4 === 0 && buf.byteLength % 4 === 0) {
+        return new Uint32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+    }
+    const copy = new ArrayBuffer(buf.byteLength);
+    new Uint8Array(copy).set(buf);
+    return new Uint32Array(copy);
+}
+/** Map a native columnar {@link NativeSubgraph} to brainy's {@link Subgraph}
+ * typed-array shape. `nodeDepth` is omitted when the native column is empty
+ * (the cursor's flat export, or `includeDepth: false`). */
+function decodeSubgraph(sg) {
+    const out = {
+        nodes: viewBigInt64(sg.nodes),
+        edgeSources: viewBigInt64(sg.edgeSources),
+        edgeTargets: viewBigInt64(sg.edgeTargets),
+        edgeVerbInts: viewBigInt64(sg.edgeVerbInts),
+        edgeTypes: viewUint16(sg.edgeTypes),
+        truncated: sg.truncated,
+    };
+    if (sg.nodeDepth.byteLength > 0) {
+        out.nodeDepth = viewUint8(sg.nodeDepth);
+    }
+    return out;
+}
+/** Wrap a `Uint8Array` ({@link OpaqueIdSet}) as a `Buffer` over the same
+ * memory (zero-copy) for the napi seed-set parameter. */
+function asBuffer(u8) {
+    return Buffer.from(u8.buffer, u8.byteOffset, u8.byteLength);
+}
+/**
+ * @description cor's `'graphAcceleration'` provider. Registered structurally
+ * (NOT via `implements GraphAccelerationProvider`, which would force the 5
+ * Phase-C analytics methods to exist) — brainy validates it at runtime via
+ * the two-anchor feature-detect (`traverse` + `graphCursorOpen`).
+ */
+export class GraphAccelerationAdapter {
+    resolveEngine;
+    /**
+     * @param resolveEngine - Resolver for the shared `graphIndex` provider
+     *   instance. Returns `undefined` until the `graphIndex` factory has
+     *   constructed the native engine; the adapter reports
+     *   {@link isInitialized} `false` until then so brainy doesn't route here.
+     */
+    constructor(resolveEngine) {
+        this.resolveEngine = resolveEngine;
+    }
+    /** The shared native graph engine, or `undefined` before construction. */
+    get engine() {
+        return this.resolveEngine();
+    }
+    /**
+     * `false` until the shared native graph engine is constructed AND has
+     * loaded its persisted state. brainy probes this before routing, so a
+     * read is never served from native before the data is present.
+     */
+    get isInitialized() {
+        const engine = this.engine;
+        return engine !== undefined && engine.isInitialized;
+    }
+    /** Resolve the native instance or throw a clear error (defensive — brainy
+     * gates on {@link isInitialized}, so this should never fire in practice). */
+    native() {
+        const engine = this.engine;
+        if (engine === undefined) {
+            throw new Error('GraphAccelerationAdapter: native graph engine not yet constructed ' +
+                '(graphIndex provider not initialized) — brainy should gate on isInitialized');
+        }
+        return engine.nativeInstance;
+    }
+    /** Translate brainy's {@link TraverseOptions} to the native shape (drops
+     * `subtypes` / `excludeVisibility`, which this seam does not apply). */
+    toNativeTraverse(options) {
+        return {
+            direction: options.direction ?? 'both',
+            depth: options.depth,
+            verbTypes: options.verbTypes,
+            maxNodes: options.maxNodes,
+            maxEdges: options.maxEdges,
+            includeEdges: options.includeEdges,
+            includeDepth: options.includeDepth,
+        };
+    }
+    /**
+     * @description Bounded multi-hop expansion from `seeds` (entity ints or a
+     *   `find()` {@link OpaqueIdSet}), returning the reachable subgraph in one
+     *   native call.
+     * @param seeds - Start nodes as `bigint[]`, or an OpaqueIdSet envelope
+     *   (forwarded with no id materialization — the query→expand fusion).
+     * @param options - Depth, direction, verb-type filter, caps.
+     * @param generation - Optional as-of generation (omitted = now).
+     */
+    async traverse(seeds, options, generation) {
+        const opts = this.toNativeTraverse(options);
+        const sg = Array.isArray(seeds)
+            ? this.native().traverse(seeds, opts, generation ?? null)
+            : this.native().traverseFromOpaqueIdSet(asBuffer(seeds), opts, generation ?? null);
+        return decodeSubgraph(sg);
+    }
+    /**
+     * @description All edges incident to one node, both directions — a
+     *   depth-1 {@link traverse} from the single node.
+     * @param nodeInt - The node's interned entity int.
+     * @param options - Direction, verb-type filter, limit.
+     * @param generation - Optional as-of generation.
+     */
+    async edgesForNode(nodeInt, options, generation) {
+        const opts = {
+            direction: options.direction ?? 'both',
+            depth: 1,
+            verbTypes: options.verbTypes,
+            maxEdges: options.limit,
+            includeEdges: true,
+            includeDepth: false,
+        };
+        return decodeSubgraph(this.native().traverse([nodeInt], opts, generation ?? null));
+    }
+    /**
+     * @description Open a snapshot-consistent streaming walk of the whole
+     *   graph (or a seeded region), pinned to a generation. Returns a
+     *   TTL-bounded handle for {@link graphCursorNext} / {@link graphCursorClose}.
+     * @param options - Direction, projection, optional seeds / resume cursor.
+     * @param generation - Optional explicit as-of generation to pin.
+     */
+    async graphCursorOpen(options, generation) {
+        const nativeOpts = {
+            direction: options.direction,
+            projection: options.projection,
+            cursor: options.cursor,
+            generation: generation ?? undefined,
+        };
+        if (options.seeds !== undefined) {
+            if (Array.isArray(options.seeds)) {
+                nativeOpts.seeds = options.seeds;
+            }
+            else {
+                nativeOpts.seedsOpaque = asBuffer(options.seeds);
+            }
+        }
+        return this.native().graphCursorOpen(nativeOpts);
+    }
+    /**
+     * @description Pull the next chunk from an open cursor.
+     * @param handle - From {@link graphCursorOpen}.
+     * @param chunkSize - Target number of edges in this chunk.
+     * @throws An error whose message starts `SnapshotExpired:` if the handle
+     *   sat idle past its TTL — reopen with the last chunk's `cursor` to resume.
+     */
+    async graphCursorNext(handle, chunkSize) {
+        const chunk = this.native().graphCursorNext(handle, chunkSize);
+        return {
+            subgraph: decodeSubgraph(chunk.subgraph),
+            cursor: chunk.cursor,
+            done: chunk.done,
+        };
+    }
+    /**
+     * @description Release an open cursor's pinned generation + server-side
+     *   state. Idempotent.
+     * @param handle - From {@link graphCursorOpen}.
+     */
+    async graphCursorClose(handle) {
+        this.native().graphCursorClose(handle);
+    }
+    /**
+     * @description `rank` — importance/influence ranking over the visible graph.
+     *   Intent-level: cor implements it natively via PageRank (algorithm is the
+     *   provider's choice). `excludeVisibility` is dropped at this seam — brainy
+     *   post-filters (and renormalizes/re-top-Ks) on hydrate; the native rank is
+     *   over all nodes. (Renamed from `pageRank` for brainy rc.3 intent contract, #71.)
+     */
+    async rank(options, generation) {
+        const r = this.native().pageRank({ topK: options.topK }, generation ?? null);
+        return { nodeInts: viewBigInt64(r.nodeInts), scores: viewFloat64(r.scores) };
+    }
+    /**
+     * @description `communities` — group related nodes. Intent-level: cor
+     *   implements it natively via connected components (`directed` → strong/SCC,
+     *   else weak). The labels are arbitrary-but-stable — only the partition is
+     *   meaningful; do not cache them as keys. (Renamed from `connectedComponents`, #71.)
+     */
+    async communities(options, generation) {
+        const r = this.native().connectedComponents({ mode: options.directed ? 'strong' : 'weak' }, generation ?? null);
+        return {
+            nodeInts: viewBigInt64(r.nodeInts),
+            communityIds: viewUint32(r.componentIds),
+            communityCount: r.componentCount,
+        };
+    }
+    /**
+     * @description `path` — best route between two nodes. Intent-level: cor
+     *   implements hops natively. cor stores no edge weights, so `by: 'weight'` is
+     *   unsupported here — brainy serves least-weight paths from its TS fallback.
+     *   Returns `null` when unreachable. (Renamed from `shortestPath`; `weight` →
+     *   `by` for brainy rc.3, #71.)
+     * @throws If `options.by === 'weight'`.
+     */
+    async path(fromInt, toInt, options, generation) {
+        if (options.by === 'weight') {
+            throw new Error('GraphAccelerationAdapter.path: by:"weight" is unsupported — cor stores no edge ' +
+                'weights; brainy must serve least-weight paths from its TS fallback');
+        }
+        const r = this.native().shortestPath(fromInt, toInt, { direction: options.direction, verbTypes: options.verbTypes, maxDepth: options.maxDepth }, generation ?? null);
+        return r === null
+            ? null
+            : { nodeInts: viewBigInt64(r.nodeInts), edgeVerbInts: viewBigInt64(r.edgeVerbInts), cost: r.cost };
+    }
+    /**
+     * @description `sample` — deterministic, seeded bounded neighborhood sample for
+     *   dense-graph viz. Intent-level; cor implements it natively. (Renamed from
+     *   `neighborhoodSample`, #71.)
+     * @param seeds - `bigint[]` or a `find()` OpaqueIdSet.
+     */
+    async sample(seeds, options, generation) {
+        const opts = {
+            direction: options.direction,
+            depth: options.depth,
+            fanout: options.fanout,
+            seed: options.seed,
+            maxNodes: options.maxNodes,
+        };
+        const r = Array.isArray(seeds)
+            ? this.native().neighborhoodSample(seeds, null, opts, generation ?? null)
+            : this.native().neighborhoodSample([], asBuffer(seeds), opts, generation ?? null);
+        return decodeSubgraph(r);
+    }
+    /**
+     * @description `mostConnected` — the top-K most-connected nodes. Intent-level:
+     *   cor implements it natively via degree. `excludeVisibility` dropped at this
+     *   seam (brainy post-filters). (Renamed from `topByDegree`, #71.)
+     */
+    async mostConnected(options, generation) {
+        const r = this.native().topByDegree({ direction: options.direction, topK: options.topK }, generation ?? null);
+        return { nodeInts: viewBigInt64(r.nodeInts), scores: viewFloat64(r.scores) };
+    }
+}
+//# sourceMappingURL=GraphAccelerationAdapter.js.map

package/dist/graph/NativeGraphAdjacencyIndex.d.ts

@@ -0,0 +1,286 @@
+/**
+ * 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 type { GraphVerb, StorageAdapter } from '@soulcraft/brainy';
+import type { NativeGraphAdjacencyInstance } from '../native/types.js';
+import type { GraphIndexProvider } from '../providerContracts.js';
+import type { EntityIdMapperLike } from '../utils/columnStoreTypes.js';
+import type { MigrationCoordinator, MigrationStatus } from '../migration/MigrationCoordinator.js';
+export interface GraphIndexConfig {
+    maxIndexSize?: number;
+    rebuildThreshold?: number;
+    autoOptimize?: boolean;
+    flushInterval?: number;
+    memTableThreshold?: number;
+    maxSSTablesPerLevel?: number;
+    /**
+     * **Piece 12.** Optional directory for the native verb-ID
+     * interning namespace. When set, the `VerbIdNamespace` writes
+     * `verb-uuid-to-int.mkv` + `verb-int-to-uuid.bin` under this
+     * directory so verb-ID interning survives process restart — a
+     * verb-ID re-encountered after reopen lands at the same internal
+     * u32, which keeps the Roaring32 membership bitmap consistent
+     * across restarts.
+     *
+     * When omitted, the constructor auto-derives it from the storage
+     * adapter for filesystem-backed brains (see
+     * {@link GRAPH_VERB_NS_PROBE_KEY}), so the durable mmap namespace is
+     * the default whenever a real on-disk path exists — required for
+     * `related()` / `getVerbsBySource()` to resolve verb ids (the
+     * in-memory reverse map is a no-op) and for O(working-set) RAM at
+     * billion-edge scale. It only falls back to the 64-shard in-memory
+     * interner when the adapter has no local path (cloud / memory
+     * storage — task #26 materializes a scratch dir there) or for a
+     * transient in-process index built directly against `MemoryStorage`.
+     */
+    persistenceDir?: string;
+}
+export interface GraphIndexStats {
+    totalRelationships: number;
+    sourceNodes: number;
+    targetNodes: number;
+    memoryUsage: number;
+    lastRebuild: number;
+    rebuildTime: number;
+}
+/**
+ * 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 declare class GraphAdjacencyIndex implements GraphIndexProvider {
+    /**
+     * 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.
+     */
+    private readonly migrationCoordinatorGetter?;
+    private storage;
+    private native;
+    private unifiedCache;
+    private config;
+    private initialized;
+    private isRebuilding;
+    private flushTimer?;
+    private rebuildStartTime;
+    private totalRelationshipsIndexed;
+    private isCompacting;
+    private hasBinaryBlobs;
+    private 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)
+     */
+    private mapperResolver?;
+    get isInitialized(): boolean;
+    /**
+     * 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(): NativeGraphAdjacencyInstance;
+    constructor(storage: StorageAdapter, config?: GraphIndexConfig, mapperResolver?: () => EntityIdMapperLike | undefined, 
+    /**
+     * 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?: (() => MigrationCoordinator | undefined) | undefined);
+    /**
+     * **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.
+     */
+    init(): Promise<void>;
+    /**
+     * 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.
+     */
+    private ensureInitialized;
+    /**
+     * 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".
+     */
+    private openGraphLsmEngine;
+    private populateVerbIdSetFromStorage;
+    getNeighbors(id: bigint, optionsOrDirection?: {
+        direction?: 'in' | 'out' | 'both';
+        limit?: number;
+        offset?: number;
+    } | 'in' | 'out' | 'both'): Promise<bigint[]>;
+    getVerbIdsBySource(sourceInt: bigint, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<bigint[]>;
+    getVerbIdsByTarget(targetInt: bigint, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<bigint[]>;
+    getVerbCached(verbId: string): Promise<GraphVerb | null>;
+    getVerbsBatchCached(verbIds: string[]): Promise<Map<string, GraphVerb>>;
+    /**
+     * 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.
+     */
+    addVerb(verb: GraphVerb, sourceInt: bigint, targetInt: bigint, generation: bigint): Promise<bigint>;
+    removeVerb(verbId: string, generation: bigint): Promise<void>;
+    size(): number;
+    getRelationshipCountByType(type: string): number;
+    getTotalRelationshipCount(): number;
+    getAllRelationshipCounts(): Map<string, number>;
+    /**
+     * **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.
+     */
+    verbIntsToIds(verbInts: bigint[]): Promise<(string | null)[]>;
+    getRelationshipStats(): {
+        totalRelationships: number;
+        relationshipsByType: Record<string, number>;
+        uniqueSourceNodes: number;
+        uniqueTargetNodes: number;
+        totalNodes: number;
+    };
+    getStats(): GraphIndexStats;
+    isHealthy(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * @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(): boolean;
+    /**
+     * @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(): MigrationStatus | null;
+    /**
+     * 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.
+     */
+    rebuild(): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    /** Blob key for an SSTable: "graph-lsm/{treeName}/{sstableId}" */
+    private blobKey;
+    private loadTreeFromStorage;
+    private loadTreeSSTables;
+    private flushTree;
+    private compactTree;
+    private saveTreeManifest;
+    private startAutoFlush;
+    private calculateMemoryUsage;
+}
+//# sourceMappingURL=NativeGraphAdjacencyIndex.d.ts.map