@soulcraft/cor 3.0.0-rc.1

package/dist/native/types.d.ts

@@ -0,0 +1,1298 @@
+/**
+ * Shared types for the native module integration.
+ *
+ * These types are used by both the napi-rs and bun:ffi loaders.
+ * Ported from src/embeddings/wasm/types.ts — keeps the same API surface.
+ */
+/**
+ * Embedding result with metadata
+ */
+export interface EmbeddingResult {
+    /** 384-dimensional embedding vector */
+    embedding: number[];
+    /** Number of tokens processed (0 when using native Candle — handled internally) */
+    tokenCount: number;
+    /** Processing time in milliseconds */
+    processingTimeMs: number;
+}
+/**
+ * Engine statistics
+ */
+export interface EngineStats {
+    /** Whether the engine is initialized */
+    initialized: boolean;
+    /** Total number of embeddings generated */
+    embedCount: number;
+    /** Total processing time in milliseconds */
+    totalProcessingTimeMs: number;
+    /** Average processing time per embedding */
+    avgProcessingTimeMs: number;
+    /** Model name */
+    modelName: string;
+}
+/**
+ * Model constants for all-MiniLM-L6-v2
+ */
+export declare const MODEL_CONSTANTS: {
+    readonly HIDDEN_SIZE: 384;
+    readonly MAX_SEQUENCE_LENGTH: 256;
+    readonly VOCAB_SIZE: 30522;
+    readonly MODEL_NAME: "all-MiniLM-L6-v2";
+};
+/**
+ * Device information from the native module
+ */
+export interface DeviceInfo {
+    /** Active device: "cpu", "cuda", or "metal" */
+    device: string;
+    /** Whether CUDA is available */
+    cudaAvailable: boolean;
+    /** Whether Metal is available */
+    metalAvailable: boolean;
+}
+/**
+ * License validation result from Rust Ed25519 JWT verification.
+ */
+export interface NativeLicenseResult {
+    valid: boolean;
+    tier: string;
+    email: string;
+    expiresAt: number;
+    error?: string;
+}
+/**
+ * Native module bindings interface.
+ * Both napi-rs and bun:ffi loaders implement this interface.
+ */
+export interface NativeBindings {
+    validateLicenseKey(token: string): NativeLicenseResult;
+    /**
+     * Raise the process's soft `RLIMIT_NOFILE` toward its hard cap (zero-
+     * config fd headroom for the multi-tenant brain pool). Optional — the
+     * bun:ffi loader may not expose it; callers feature-detect. See
+     * `native/src/resource_limits.rs` + ADR-004.
+     */
+    raiseOpenFileLimit?(): {
+        softBefore: number;
+        softAfter: number;
+        hard: number;
+        raised: boolean;
+        vmMaxMapCount: number;
+    };
+    NativeEmbeddingEngine: {
+        new (): NativeEmbeddingEngineInstance;
+    };
+    NativeRoaringBitmap32: {
+        new (values?: number[]): NativeRoaringBitmap32Instance;
+        and(a: NativeRoaringBitmap32Instance, b: NativeRoaringBitmap32Instance): NativeRoaringBitmap32Instance;
+        or(a: NativeRoaringBitmap32Instance, b: NativeRoaringBitmap32Instance): NativeRoaringBitmap32Instance;
+        orMany(bitmaps: NativeRoaringBitmap32Instance[]): NativeRoaringBitmap32Instance;
+        andNot(a: NativeRoaringBitmap32Instance, b: NativeRoaringBitmap32Instance): NativeRoaringBitmap32Instance;
+        xor(a: NativeRoaringBitmap32Instance, b: NativeRoaringBitmap32Instance): NativeRoaringBitmap32Instance;
+        deserialize(buffer: Buffer): NativeRoaringBitmap32Instance;
+    };
+    NativeEntityIdMapper: {
+        new (): NativeEntityIdMapperInstance;
+    };
+    NativeGraphAdjacencyIndex: {
+        new (config: NativeGraphAdjacencyConfig): NativeGraphAdjacencyInstance;
+    };
+    NativeAggregationEngine: {
+        new (): NativeAggregationEngineInstance;
+    };
+    cosineDistance(a: number[], b: number[]): number;
+    euclideanDistance(a: number[], b: number[]): number;
+    manhattanDistance(a: number[], b: number[]): number;
+    dotProductDistance(a: number[], b: number[]): number;
+    cosineDistanceBatch(query: number[], vectors: number[][]): number[];
+    euclideanDistanceBatch(query: number[], vectors: number[][]): number[];
+    quantizeSq8(vector: number[]): {
+        quantized: Buffer;
+        min: number;
+        max: number;
+    };
+    dequantizeSq8(quantized: Buffer, min: number, max: number): number[];
+    serializeSq8(quantized: Buffer, min: number, max: number): Buffer;
+    deserializeSq8(data: Buffer): {
+        quantized: Buffer;
+        min: number;
+        max: number;
+    };
+    cosineDistanceSq8(a: Buffer, aMin: number, aMax: number, b: Buffer, bMin: number, bMax: number): number;
+    cosineDistanceSq8Batch(query: Buffer, queryMin: number, queryMax: number, vectors: Buffer[], mins: number[], maxs: number[]): number[];
+    quantizeSq4(vector: number[]): {
+        quantized: Buffer;
+        min: number;
+        max: number;
+        dim: number;
+    };
+    dequantizeSq4(quantized: Buffer, min: number, max: number, dim: number): number[];
+    cosineDistanceSq4(a: Buffer, aMin: number, aMax: number, aDim: number, b: Buffer, bMin: number, bMax: number, bDim: number): number;
+    cosineDistanceSq4Batch(query: Buffer, queryMin: number, queryMax: number, queryDim: number, vectors: Buffer[], mins: number[], maxs: number[], dims: number[]): number[];
+    encodeConnections(ids: number[]): Buffer;
+    decodeConnections(data: Buffer): number[];
+    NativePqCodebook: {
+        train(vectors: number[], dim: number, m: number, ksub: number, iterations: number): NativePQCodebookInstance;
+        deserialize(data: Buffer): NativePQCodebookInstance;
+    };
+    msgpackEncode(value: unknown): Buffer;
+    msgpackDecode(buffer: Buffer): unknown;
+    msgpackEncodeBatch(values: unknown[]): Buffer[];
+    msgpackDecodeBatch(buffers: Buffer[]): unknown[];
+    NativeMetadataIndex: {
+        new (configJson?: string | null, idSpace?: 'u32' | 'u64' | null): NativeMetadataIndexInstance;
+    };
+    NativeLsmEngine: {
+        new (options?: NativeLsmEngineOptions | null): NativeLsmEngineInstance;
+        openWithManifest(manifestJson: string, options?: NativeLsmEngineOptions | null): NativeLsmEngineInstance;
+        /**
+         * **Piece 7 / LSM durability.** Construct an engine whose memtable is
+         * backed by mmap'd per-shard append logs under `<dir>/memtable/` (so a
+         * crash between inserts and the next `flush()` recovers transparently on
+         * reopen). Optionally seeds the epoch counter from a manifest so new
+         * mutations outrank every persisted SSTable epoch; when omitted, the
+         * post-replay epoch is `max(log_max_epoch) + 1`. The TS wrapper owns the
+         * SSTable + manifest disk I/O and registers each persisted SSTable via
+         * {@link NativeLsmEngineInstance.registerSstablePath} after open.
+         */
+        openWithDir(dir: string, manifestJson?: string | null, options?: NativeLsmEngineOptions | null): NativeLsmEngineInstance;
+    };
+    NativeColumnStore: {
+        new (): NativeColumnStoreInstance;
+    };
+    NativeUnifiedCache: {
+        new (maxSize: number): NativeUnifiedCacheInstance;
+    };
+    NativeBinaryIdMapper: {
+        create(config: NativeBinaryIdMapperConfig): NativeBinaryIdMapperInstance;
+        openExisting(config: NativeBinaryIdMapperConfig): NativeBinaryIdMapperInstance;
+    };
+    sortTopKScores(scores: number[], k: number, descending: boolean): number[];
+    getDeviceInfo(): DeviceInfo;
+    cosineSimilarity(a: number[], b: number[]): number;
+    /** Tokenize text exactly as brainy's `MetadataIndexManager.tokenize` (ASCII `\w`, 2–50 length, dedupe). */
+    parityTokenize(text: string): string[];
+    /** FNV-1a word hash, identical to brainy's `hashWord` (signed int32, UTF-16 code units). */
+    parityHashWord(word: string): number;
+    /** Long-value hash, identical to brainy's `hashValue` (`__HASH_<base36>`, UTF-16 code units). */
+    parityHashValue(value: string): string;
+    /** Normalize a JSON-encoded value exactly as brainy's `normalizeValue` (default config, empty field stats). */
+    parityNormalizeValue(valueJson: string): string;
+    /** Compare two strings by UTF-8 byte / code-point order (brainy's `compareCodePoints`). Returns -1/0/1. */
+    parityCompareCodePoints(a: string, b: string): number;
+    /** Sort strings by the native column-store order (UTF-8 byte / code-point order). */
+    paritySortStrings(values: string[]): string[];
+}
+/**
+ * Configuration for `NativeBinaryIdMapper.create` / `openExisting`.
+ * Mirror of the napi-exposed `BinaryIdMapperConfig` in
+ * `native/src/binary_id_mapper_napi.rs`.
+ */
+export interface NativeBinaryIdMapperConfig {
+    /** Path for `uuid_to_int.mkv` (extendible-hash KV file). */
+    uuidToIntPath: string;
+    /** Path for `int_to_uuid.bin` (direct-indexed sparse file). */
+    intToUuidPath: string;
+    /** Sparse file size for `int_to_uuid` in bytes. Default 32 GB. */
+    intToUuidSize?: bigint;
+    /** Sparse file size for `uuid_to_int` in bytes. Default 32 GB. */
+    uuidToIntSize?: bigint;
+    /** MmapKv bucket capacity (entries per bucket). Default 16. */
+    bucketCapacity?: number;
+    /** MmapKv max_global_depth (directory depth cap). Default 28. */
+    maxGlobalDepth?: number;
+    /**
+     * Entity-int wire-width. Default `"u32"` (cortex 2.x compatible —
+     * caps at 4.29 B entries). Set to `"u64"` to opt into the Piece 10
+     * U64 IdSpace (persists 8-byte ints + bumps `int_to_uuid.bin` to a
+     * v2 header). U64 mode is required when targeting >4.29 B entities.
+     *
+     * Ignored at `openExisting` time: the on-disk format dictates the
+     * IdSpace and any user-provided value is cross-checked against the
+     * file header (mismatch throws).
+     */
+    idSpace?: 'u32' | 'u64';
+}
+/**
+ * `NativeBinaryIdMapper` instance (cor 3.0). Bidirectional
+ * UUID ↔ int mapping backed by two mmap'd files.
+ *
+ * ## IdSpace surface
+ *
+ * The mapper has two parallel method surfaces selected by the
+ * `idSpace` mode (configured at create time, persisted in the
+ * `int_to_uuid.bin` header):
+ *
+ * - **U32 mode** (default, cortex 2.x compatible): `getOrAssign` /
+ *   `getInt` / `getUuid` / `size` / `nextInt` return `number`. The
+ *   BigInt siblings still work — they widen to `bigint` at the JS
+ *   boundary — but the `number` surface is the primary API.
+ * - **U64 mode** (Piece 10 — opt-in via `config.idSpace = 'u64'`):
+ *   the `number`-returning methods throw with `"requires u32 mode"`.
+ *   Callers must use the BigInt siblings (`getOrAssignBig`,
+ *   `getIntBig`, `getUuidBig`, `sizeBig`, `nextIntBig`).
+ *
+ * `idSpace()` reports the actual mode of the open file, which is
+ * authoritative over any user-supplied config at `openExisting` time.
+ */
+export interface NativeBinaryIdMapperInstance {
+    /** Retrieve the int for `uuid`, allocating one if absent. */
+    getOrAssign(uuid: Buffer): number;
+    /** Lookup the int for `uuid`. Null if absent or tombstoned. */
+    getInt(uuid: Buffer): number | null;
+    /** Lookup the UUID for `int`. Null if absent or tombstoned. */
+    getUuid(int: number): Buffer | null;
+    /** Live (non-tombstone) entry count. */
+    size(): number;
+    /** Largest int ever assigned + 1. */
+    nextInt(): number;
+    /** All live int ids. At billion-scale, prefer streaming hooks (TBD). */
+    getAllIntIds(): number[];
+    /**
+     * Retrieve the int for `uuid`, allocating one if absent. Returns a
+     * `bigint` so the full u64 range is representable.
+     */
+    getOrAssignBig(uuid: Buffer): bigint;
+    /** Lookup the int for `uuid`. `null` if absent or tombstoned. */
+    getIntBig(uuid: Buffer): bigint | null;
+    /** Lookup the UUID for `int`. `null` if absent or tombstoned. */
+    getUuidBig(int: bigint): Buffer | null;
+    /**
+     * Batch sibling of {@link getUuidBig} (ADR-006 Q5). Resolve many ints
+     * to their UUID bytes in one native call; `null` per unmapped int,
+     * index-aligned with the input.
+     */
+    intsToUuidsBig(ints: bigint[]): (Buffer | null)[];
+    /** Live (non-tombstone) entry count as a `bigint`. */
+    sizeBig(): bigint;
+    /** Largest int ever assigned + 1, as a `bigint`. */
+    nextIntBig(): bigint;
+    /** Tombstone an entry. Returns true if it was present. */
+    remove(uuid: Buffer): boolean;
+    /** Flush dirty mmap pages to disk. */
+    flush(): void;
+    /** Filesystem paths to the underlying files (`[uuid_to_int, int_to_uuid]`). */
+    paths(): string[];
+    /** Diagnostic snapshot for tooling. */
+    diagnostics(): NativeBinaryIdMapperDiagnostics;
+    /**
+     * Report the mapper's actual IdSpace mode. Authoritative over the
+     * config's `idSpace` field — the on-disk header wins.
+     */
+    idSpace(): 'u32' | 'u64';
+}
+/** Diagnostic snapshot returned by `NativeBinaryIdMapper.diagnostics`. */
+export interface NativeBinaryIdMapperDiagnostics {
+    uuidSize: number;
+    intSize: number;
+    intToUuidEntrySize: number;
+    assignShards: number;
+    size: number;
+    nextInt: number;
+}
+/**
+ * Native embedding engine instance
+ */
+export interface NativeEmbeddingEngineInstance {
+    load(modelBytes: Buffer, tokenizerBytes: Buffer, configBytes: Buffer): void;
+    isReady(): boolean;
+    embed(text: string): number[];
+    embedBatch(texts: string[]): number[][];
+    dimension(): number;
+    maxSequenceLength(): number;
+    getStats(): EngineStats;
+}
+/**
+ * Native roaring bitmap instance
+ */
+export interface NativeRoaringBitmap32Instance {
+    readonly size: number;
+    readonly isEmpty: boolean;
+    add(value: number): void;
+    delete(value: number): void;
+    tryAdd(value: number): boolean;
+    has(value: number): boolean;
+    toArray(): number[];
+    serialize(): Buffer;
+    serializationSizeInBytes(): number;
+    minimum(): number | null;
+    maximum(): number | null;
+}
+/**
+ * Statistics from native EntityIdMapper
+ */
+export interface NativeEntityIdMapperStats {
+    /** Number of active UUID ↔ integer mappings */
+    mappings: number;
+    /** Next integer ID to assign */
+    nextId: number;
+    /** Whether there are unsaved changes */
+    dirty: boolean;
+    /** Estimated memory usage in bytes */
+    memoryEstimate: number;
+}
+/**
+ * Native EntityIdMapper instance.
+ * Bidirectional UUID ↔ integer mapping for roaring bitmap integration.
+ */
+export interface NativeEntityIdMapperInstance {
+    /** Load state from JSON string (storage format) */
+    loadFromJson(json: string): void;
+    /** Serialize state to JSON string for storage persistence */
+    saveToJson(): string;
+    /** Get integer ID for UUID, assigning a new one if not mapped */
+    getOrAssign(uuid: string): number;
+    /** Get UUID for integer ID. Returns null if not found */
+    getUuid(intId: number): string | null;
+    /** Get integer ID for UUID without assigning. Returns null if not found */
+    getInt(uuid: string): number | null;
+    /** Check if UUID has been assigned an integer ID */
+    has(uuid: string): boolean;
+    /** Remove mapping for UUID. Returns true if it existed */
+    remove(uuid: string): boolean;
+    /** Get total number of mappings */
+    readonly size: number;
+    /** Convert array of UUIDs to array of integers (assigns new IDs as needed) */
+    uuidsToInts(uuids: string[]): number[];
+    /** Convert array of integers to array of UUIDs (skips unknown IDs) */
+    intsToUuids(ints: number[]): string[];
+    /**
+     * BigInt sibling of {@link intsToUuids} (ADR-006 Q5). Resolve many
+     * u64 ints to UUID strings in one native call, index-aligned with the
+     * input — the `entityIntsToUuids` provider path for `Subgraph.nodes`.
+     */
+    intsToUuidsBig(ints: bigint[]): string[];
+    /** Whether there are unsaved changes */
+    isDirty(): boolean;
+    /** Clear all mappings and reset counter */
+    clear(): void;
+    /** Get statistics about the mapper */
+    getStats(): NativeEntityIdMapperStats;
+}
+/**
+ * Configuration for NativeGraphAdjacencyIndex
+ */
+export interface NativeGraphAdjacencyConfig {
+    /** MemTable flush threshold per tree. Default: 100_000 */
+    memTableThreshold?: number;
+    /** Max SSTables per level per tree. Default: 10 */
+    maxSstablesPerLevel?: number;
+    /**
+     * **Piece 12.** Optional directory for the verb-ID interning
+     * namespace's mmap-backed files. When set, the namespace writes
+     * `verb-uuid-to-int.mkv` + `verb-int-to-uuid.bin` under this
+     * directory so verb-ID assignments survive process restart. When
+     * omitted, the namespace falls back to an in-memory interner —
+     * adequate for tests + transient brains but loses assignments on
+     * exit.
+     */
+    persistenceDir?: string;
+    /**
+     * **Piece B (cor 3.0).** Wire width of the verb-ID interning
+     * namespace + the live-verb / per-(type, subtype) membership
+     * bitmaps. `"U32"` (raw napi default, brainy 7.x-compatible) caps
+     * at ~4.29 B unique verb-IDs. `"U64"` (cor 3.0 wrapper default
+     * via `GraphAdjacencyIndex`) lifts the cap to `u64::MAX - 1`. The
+     * choice is independent of the brain's *entity* IdSpace.
+     * Case-sensitive.
+     */
+    verbIdSpace?: 'U32' | 'U64';
+}
+/**
+ * Result from addVerbWithEndpoints — indicates which trees need
+ * flushing and (cor 3.0 brainy-8.0 lockstep) returns the verb's
+ * interned `u64` integer ID so brainy 8.0's
+ * `verb_int ↔ verb_id_string` sidecar can be populated without a
+ * second FFI hop.
+ */
+export interface GraphAddVerbResult {
+    needsFlushSource: boolean;
+    needsFlushTarget: boolean;
+    needsFlushVerbsSource: boolean;
+    needsFlushVerbsTarget: boolean;
+    /**
+     * **Brainy 8.0 lockstep** (PLATFORM-HANDOFF
+     * BRAINY-8.0-RENAME-COORDINATION A.3): the verb's interned `u64`
+     * integer ID. Brainy 8.0 reads this directly to populate its
+     * sidecar map — one FFI round-trip per add saved at
+     * billion-scale ingest.
+     */
+    verbInt: bigint;
+}
+/**
+ * Result from {@link NativeGraphAdjacencyInstance.getVerbEndpoints}.
+ * Carries the verb's (source, target) entity ints as u64 BigInts so
+ * brainy 8.0 callers can round-trip them via the brain's canonical
+ * `BinaryIdMapper` without precision loss at 10B+ scale.
+ */
+export interface VerbEndpointsResult {
+    sourceInt: bigint;
+    targetInt: bigint;
+    /**
+     * The verb's `VerbType` index (generation-stable; ADR-006 Phase A). Carried on
+     * the endpoint record so an as-of-`g` read can type an edge whose verb was
+     * removed after `g`. Present on the Rust struct + generated `index.d.ts`; this
+     * hand-maintained mirror was missing it (latent type-drift). (#79 cluster C.)
+     */
+    verbType: number;
+}
+/**
+ * Statistics for the graph adjacency index.
+ *
+ * The legacy `number`-typed counters (`totalRelationships`,
+ * `verbIdCount`, `relationshipTypeCount`) cap at `0xFFFFFFFF` —
+ * preserved for cortex 2.x-compatible callers. The BigInt sibling
+ * fields (`*Big`) carry the same values losslessly at billion scale
+ * and should be preferred by any new consumer.
+ */
+export interface GraphAdjacencyStats {
+    totalRelationships: number;
+    verbIdCount: number;
+    relationshipTypeCount: number;
+    sourceMemTableSize: number;
+    targetMemTableSize: number;
+    sourceSstableCount: number;
+    targetSstableCount: number;
+    sourceMemTableMemory: number;
+    targetMemTableMemory: number;
+    /** BigInt total relationship count (no u32 ceiling). */
+    totalRelationshipsBig: bigint;
+    /** BigInt verb id count. */
+    verbIdCountBig: bigint;
+    /** BigInt relationship type count. */
+    relationshipTypeCountBig: bigint;
+}
+/**
+ * Result from flushing a tree's MemTable to binary .sst format
+ * (adapter-controlled).
+ *
+ * **Cor 3.0 Piece D**: `entryCount` and `valueCount` (renamed from
+ * pre-D `relationshipCount`) are u32 narrowings of the underlying u64
+ * counters. Per-SSTable totals never realistically approach the cap.
+ */
+export interface NativeBinaryFlushResult {
+    treeName: string;
+    sstableId: string;
+    data: Buffer;
+    level: number;
+    entryCount: number;
+    /** Sum of values across all entries in the flushed SSTable. */
+    valueCount: number;
+}
+/**
+ * Result from compacting a tree's level to binary .sst format
+ * (adapter-controlled).
+ */
+export interface NativeBinaryCompactResult {
+    treeName: string;
+    newSstableId: string;
+    data: Buffer;
+    newLevel: number;
+    oldIds: string[];
+}
+/**
+ * Native graph adjacency index instance.
+ * Wraps 4 u64-keyed LSM-trees (source, target, verbs-source,
+ * verbs-target) plus verb tracking and relationship counts.
+ *
+ * **Cor 3.0 Piece D**: entity ids cross as `bigint` (the canonical
+ * u64 from brainy's `BinaryIdMapper`). Verb ints (interned via cor's
+ * `verb_id_namespace`) also cross as `bigint`. Verb-id strings only
+ * appear at add-time (`addVerbWithEndpoints*`, `trackVerbId`) and
+ * endpoint lookups (`getVerbEndpoints`).
+ *
+ * Legacy `addVerb` / `addVerbByIndex` / `addVerb*WithSubtype` /
+ * `removeVerbByIndex` / `removeVerb*WithSubtype` / `trackVerbIdByIndex`
+ * / `flushTree` / `loadSstable` / `compactTree` are removed; brainy 8.0
+ * uses `addVerbWithEndpoints*` exclusively. See PLATFORM-HANDOFF row
+ * `CTX-30-U64-CONSISTENCY` for the brainy-side migration contract.
+ */
+/**
+ * Knobs for {@link NativeGraphAdjacencyInstance.traverse} (ADR-006 Phase A).
+ * Field names cross the napi boundary as camelCase.
+ */
+export interface TraverseOptions {
+    /** `"out"`, `"in"`, or `"both"` (any other value → `"both"`). */
+    direction: string;
+    /** Max hop count from the seed set (`0` = seeds only, no edges). */
+    depth: number;
+    /** Restrict to these `VerbType` indices (empty/omitted = all types). */
+    verbTypes?: Array<number>;
+    /** Cap on distinct nodes (sets `truncated` when hit). */
+    maxNodes?: number;
+    /** Cap on edges (sets `truncated` when hit). */
+    maxEdges?: number;
+    /** Capture edge columns (default `true`); `false` = nodes-only. */
+    includeEdges?: boolean;
+    /** Populate `nodeDepth` (default `true`). */
+    includeDepth?: boolean;
+}
+/**
+ * Columnar subgraph — parallel little-endian {@link Buffer} columns
+ * (ADR-006 wire format). View each as a typed array (`BigInt64Array` /
+ * `Uint16Array` / `Uint8Array`) with zero element copies; brainy resolves
+ * the u64 ints to UUIDs lazily. Shared by `traverse` + cursor chunks.
+ */
+export interface NativeSubgraph {
+    /** Distinct node ints, BFS-discovery order, `u64` LE. */
+    nodes: Buffer;
+    /** Per-node BFS depth (`u8`, parallel to `nodes`); empty when not requested. */
+    nodeDepth: Buffer;
+    /** Per-edge source node int (`u64` LE). */
+    edgeSources: Buffer;
+    /** Per-edge target node int (`u64` LE). */
+    edgeTargets: Buffer;
+    /** Per-edge interned verb int (`u64` LE); empty under `"light"` projection. */
+    edgeVerbInts: Buffer;
+    /** Per-edge verb-type index (`u16` LE). */
+    edgeTypes: Buffer;
+    /** `true` if a node/edge cap truncated a `traverse` (cursors page instead). */
+    truncated: boolean;
+}
+/**
+ * Options for {@link NativeGraphAdjacencyInstance.graphCursorOpen}
+ * (ADR-006 Phase B). Mirrors brainy's `GraphCursorOptions` + the trailing
+ * `generation`, flattened so seeds arrive as ints OR cor's opaque id-set.
+ */
+export interface GraphCursorOpenOptions {
+    /** `"out"`/`"in"`/`"both"` (default). Honored for seeded cursors only. */
+    direction?: string;
+    /** `"light"` (default; omits `edgeVerbInts`) or `"full"`. */
+    projection?: string;
+    /** Seed ints. Omitted (with `seedsOpaque`) = whole-graph walk. */
+    seeds?: Array<bigint>;
+    /** Seed set as cor's OpaqueIdSet envelope (the `find()`→export fusion). */
+    seedsOpaque?: Buffer;
+    /** Resume token from a prior chunk (reopen after `SnapshotExpired`). */
+    cursor?: string;
+    /** Explicit as-of generation to pin (omitted = current). */
+    generation?: bigint;
+}
+/**
+ * One streamed chunk from
+ * {@link NativeGraphAdjacencyInstance.graphCursorNext} (ADR-006 Phase B).
+ */
+export interface NativeGraphCursorChunk {
+    /** This chunk's nodes + edges, columnar (`nodeDepth` always empty here). */
+    subgraph: NativeSubgraph;
+    /** Resume token; `undefined` once the walk is exhausted. */
+    cursor?: string;
+    /** `true` once the walk is exhausted. */
+    done: boolean;
+}
+/** Per-node scalar scores (`pageRank` / `topByDegree`), descending — decoded
+ * to brainy's `GraphScores` (BigInt64Array + Float64Array). */
+export interface NativeGraphScores {
+    /** Entity ints, `u64` LE. */
+    nodeInts: Buffer;
+    /** Per-node score, `f64` LE, parallel to `nodeInts`. */
+    scores: Buffer;
+}
+/** Connected-component labelling (`connectedComponents`) — decoded to brainy's
+ * `GraphComponents`. */
+export interface NativeGraphComponents {
+    /** Entity ints, `u64` LE. */
+    nodeInts: Buffer;
+    /** Component label per node, `u32` LE, parallel to `nodeInts`. */
+    componentIds: Buffer;
+    /** Distinct component total (separate field, not `max(componentIds)`). */
+    componentCount: number;
+}
+/** A shortest path (`shortestPath`, `null` when unreachable) — decoded to
+ * brainy's `GraphPath`. */
+export interface NativeGraphPath {
+    /** Path node sequence, `u64` LE. */
+    nodeInts: Buffer;
+    /** Edge verb ints, `u64` LE; `length === nodeInts.length/8 - 1` (gaps). */
+    edgeVerbInts: Buffer;
+    /** Hop count (cor stores no edge weights → hops-only). */
+    cost: number;
+}
+/** Options for {@link NativeGraphAdjacencyInstance.pageRank}. */
+export interface NativePageRankOptions {
+    damping?: number;
+    maxIterations?: number;
+    tolerance?: number;
+    undirected?: boolean;
+    topK?: number;
+    /** Contextual scoping: rank only the seed-bounded induced subgraph (O(scope)). */
+    seeds?: Array<bigint>;
+    seedsOpaque?: Buffer;
+    scopeDepth?: number;
+}
+/** Options for {@link NativeGraphAdjacencyInstance.connectedComponents}. */
+export interface NativeComponentsOptions {
+    /** `"weak"` (default) or `"strong"`. */
+    mode?: string;
+    /** Contextual scoping: label only the seed-bounded induced subgraph. */
+    seeds?: Array<bigint>;
+    seedsOpaque?: Buffer;
+    scopeDepth?: number;
+}
+/** Options for {@link NativeGraphAdjacencyInstance.shortestPath} (hops-only —
+ * no `weight` field; cor stores no edge weights). */
+export interface NativeShortestPathOptions {
+    direction?: string;
+    verbTypes?: Array<number>;
+    maxDepth?: number;
+}
+/** Options for {@link NativeGraphAdjacencyInstance.neighborhoodSample}. */
+export interface NativeNeighborhoodSampleOptions {
+    direction?: string;
+    depth: number;
+    fanout: number;
+    /** RNG seed (a JS number; narrowed to u64, NaN/negative → 0). */
+    seed?: number;
+    maxNodes?: number;
+    includeDepth?: boolean;
+}
+/** Options for {@link NativeGraphAdjacencyInstance.topByDegree}. */
+export interface NativeTopByDegreeOptions {
+    /** `"out"` (default), `"in"`, or `"both"`. */
+    direction?: string;
+    topK: number;
+    /** Contextual scoping: rank degrees only within the seed-bounded subgraph. */
+    seeds?: Array<bigint>;
+    seedsOpaque?: Buffer;
+    scopeDepth?: number;
+}
+export interface NativeGraphAdjacencyInstance {
+    /**
+     * Add a verb with its `(sourceInt, targetInt)` endpoint pair.
+     * Updates all 4 LSM-trees, the membership bitmap, the per-type count
+     * slot, and (when `subtype` is set) the per-(type, subtype) bitmap +
+     * count slot. Returns which trees need flushing.
+     *
+     * The `verbType` string is resolved to its canonical `VerbTypeEnum`
+     * index — unknown strings coerce to `VerbType.RelatedTo` (3).
+     */
+    addVerbWithEndpoints(verbId: string, sourceInt: bigint, targetInt: bigint, verbType: string, subtype: string, 
+    /** brainy's commit generation for this write — recorded in the
+     * endpoint version chain so `getVerbEndpointsAtGeneration` (and
+     * thus `db.asOf(g)` graph hops) resolve historical edges. */
+    generation: bigint): GraphAddVerbResult;
+    /**
+     * Strict variant of {@link addVerbWithEndpoints} taking the canonical
+     * verb-type index directly. Brainy 8.0 happy path — resolves the
+     * index once via `TypeUtils.getVerbIndex` and hands it in.
+     * Out-of-range indices coerce to `VerbType.RelatedTo` (3).
+     */
+    addVerbWithEndpointsByIndex(verbId: string, sourceInt: bigint, targetInt: bigint, verbTypeIndex: number, subtype: string, 
+    /** brainy's commit generation — see {@link addVerbWithEndpoints}. */
+    generation: bigint): GraphAddVerbResult;
+    /**
+     * Remove a verb (tombstone deletion). LSM-tree edges persist —
+     * removed verbs are filtered out by the membership bitmap on query.
+     * When `subtype` is set, the per-(type, subtype) bitmap + count slot
+     * are also updated.
+     */
+    removeVerb(verbId: string, verbTypeIndex: number, subtype: string, 
+    /** brainy's commit generation — records the tombstone in the
+     * endpoint version chain at this generation for `db.asOf(g)`. */
+    generation: bigint): void;
+    /**
+     * Look up a verb's `(sourceInt, targetInt)` endpoint pair by verb-ID.
+     * Returns `null` when the verb was never added or has been tombstoned.
+     */
+    getVerbEndpoints(verbId: string): VerbEndpointsResult | null;
+    /**
+     * Number of verb-IDs currently carrying endpoint info. Useful for
+     * tests + ops dashboards.
+     */
+    verbEndpointsCount(): bigint;
+    /**
+     * Get neighbor entity ints for an entity.
+     * `direction`: `"in"`, `"out"`, or `"both"`. Returns deduped neighbor
+     * ints with optional pagination.
+     */
+    getNeighbors(id: bigint, direction: string, limit?: number | null, offset?: number | null): bigint[];
+    /**
+     * Get verb ints by source entity, filtered by the live-membership
+     * bitmap (tombstone filtering). Returns verb ints (BigInt); brainy
+     * 8.0 owns the verb_int ↔ verb_id_string mapping on its side.
+     */
+    getVerbIdsBySource(sourceInt: bigint, limit?: number | null, offset?: number | null): bigint[];
+    /**
+     * Get verb ints by target entity, filtered by the live-membership
+     * bitmap. See {@link getVerbIdsBySource}.
+     */
+    getVerbIdsByTarget(targetInt: bigint, limit?: number | null, offset?: number | null): bigint[];
+    /**
+     * Get verb ints by source entity, filtered by both the live-membership
+     * bitmap AND the per-(verbTypeIndex, subtype) bitmap. Both filter
+     * dimensions are optional.
+     */
+    getVerbIdsBySourceWithSubtype(sourceInt: bigint, verbTypeIndex?: number | null, subtype?: string | null, limit?: number | null, offset?: number | null): bigint[];
+    /**
+     * Get verb ints by target entity, filtered by both the live-membership
+     * bitmap AND the per-(verbTypeIndex, subtype) bitmap.
+     */
+    getVerbIdsByTargetWithSubtype(targetInt: bigint, verbTypeIndex?: number | null, subtype?: string | null, limit?: number | null, offset?: number | null): bigint[];
+    /** Per-(verbTypeIndex, subtype) relationship count. */
+    getRelationshipSubtypeCount(verbTypeIndex: number, subtype: string): bigint;
+    /** Distinct subtype values observed for the given verb-type. */
+    listVerbSubtypes(verbTypeIndex: number): string[];
+    /**
+     * Track a verb ID without adding to LSM-trees. Used during rebuild
+     * when LSM-trees are already loaded from persisted SSTables.
+     */
+    trackVerbId(verbId: string, verbType: string): void;
+    /** Clear membership bitmap + relationship counts (rebuild prelude). */
+    clearVerbTracking(): void;
+    /**
+     * Generation counter — bumped on every read-visible mutation. TS
+     * readers poll this to invalidate caches when state changes.
+     */
+    currentGeneration(): bigint;
+    /**
+     * Bounded multi-hop BFS from explicit `seeds`, returning the reachable
+     * subgraph (nodes + edges + per-node depth) in one boundary crossing.
+     * `generation` (omitted = now) selects an as-of-`g` time-travel read.
+     */
+    traverse(seeds: Array<bigint>, opts: TraverseOptions, generation?: bigint | null): NativeSubgraph;
+    /**
+     * {@link traverse} seeded from a `find()`-result OpaqueIdSet envelope
+     * (the query→expand fusion — no id materialization in TS). Fails loud
+     * on a stale/foreign buffer.
+     */
+    traverseFromOpaqueIdSet(seed: Buffer, opts: TraverseOptions, generation?: bigint | null): NativeSubgraph;
+    /**
+     * 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}.
+     */
+    graphCursorOpen(options: GraphCursorOpenOptions): string;
+    /**
+     * Pull the next chunk from an open cursor (up to `chunkSize` edges).
+     * `done: true` once exhausted; a handle idle past the TTL throws a
+     * `SnapshotExpired`-prefixed error.
+     */
+    graphCursorNext(handle: string, chunkSize: number): NativeGraphCursorChunk;
+    /** Release a cursor's pinned generation + server-side state (idempotent). */
+    graphCursorClose(handle: string): void;
+    /** PageRank over the as-of-g graph (power iteration; descending; topK). */
+    pageRank(options: NativePageRankOptions, generation?: bigint | null): NativeGraphScores;
+    /** Weak (union-find) or strong (iterative Tarjan) connected components. */
+    connectedComponents(options: NativeComponentsOptions, generation?: bigint | null): NativeGraphComponents;
+    /** Shortest path (BFS hops; `null` when unreachable). */
+    shortestPath(fromInt: bigint, toInt: bigint, options: NativeShortestPathOptions, generation?: bigint | null): NativeGraphPath | null;
+    /** Deterministic seeded bounded neighborhood sample (columnar Subgraph). */
+    neighborhoodSample(seeds: Array<bigint>, seedsOpaque: Buffer | null, options: NativeNeighborhoodSampleOptions, generation?: bigint | null): NativeSubgraph;
+    /** Top-K nodes by degree (out/in/both), descending. */
+    topByDegree(options: NativeTopByDegreeOptions, generation?: bigint | null): NativeGraphScores;
+    /** Flush a tree's MemTable to binary .sst format (no disk I/O). */
+    flushTreeToBinary(treeName: string): NativeBinaryFlushResult | null;
+    /** Compact a tree's level to binary .sst format (no disk I/O). */
+    compactTreeToBinary(treeName: string, level: number): NativeBinaryCompactResult | null;
+    /** Mmap an adapter-written file, upgrading InMemory variant to Mapped. */
+    registerMmapSstable(treeName: string, sstableId: string, level: number, filePath: string): void;
+    /** Load an SSTable from binary .sst data. */
+    loadSstableFromBinary(treeName: string, sstableId: string, level: number, data: Buffer): void;
+    /** Load an SSTable from a .sst file via mmap. */
+    loadSstableFromFile(treeName: string, sstableId: string, level: number, filePath: string): void;
+    /** Check if a tree's level needs compaction. */
+    needsCompaction(treeName: string, level: number): boolean;
+    /** Get manifest JSON for a tree. */
+    getManifestJson(treeName: string): string;
+    /** Load manifest JSON for a tree. */
+    loadManifestJson(treeName: string, json: string): void;
+    /** Get SSTable IDs from a tree's manifest. */
+    getManifestSstableIds(treeName: string): string[];
+    /** Get level for an SSTable ID in a tree's manifest. */
+    getManifestSstableLevel(treeName: string, id: string): number | null;
+    /** Check if a tree's MemTable is empty. */
+    memTableIsEmpty(treeName: string): boolean;
+    /** Total relationship count (caps at 2^32-1). */
+    size(): number;
+    /** BigInt total relationship count. */
+    sizeBig(): bigint;
+    /** Number of tracked verb IDs (caps at 2^32-1). */
+    verbIdCount(): number;
+    /** BigInt verb id count. */
+    verbIdCountBig(): bigint;
+    /**
+     * Batch verb-int reverse resolver (brainy 8.0 lockstep,
+     * `GraphIndexProvider.verbIntsToIds` contract). Given a batch of
+     * verb-int BigInts, returns the canonical UUID string for each —
+     * `null`/`undefined` for any int with no entry in the persistent
+     * reverse map. O(1) per lookup via `verb-int-to-uuid.bin`.
+     */
+    verbIntsToUuids(verbInts: Array<bigint>): Array<string | null | undefined>;
+    /** Per-type relationship count (saturates at 2^32-1). */
+    getRelationshipCountByType(verbType: string): number;
+    /** BigInt per-type relationship count (overflow-safe). */
+    getRelationshipCountByTypeBig(verbType: string): bigint;
+    /** Strict per-type count by canonical index. */
+    getRelationshipCountByIndex(verbTypeIndex: number): bigint;
+    /** All relationship counts as JSON `{type: count}` map. */
+    getAllRelationshipCountsJson(): string;
+    /** Relationship statistics as JSON. */
+    getRelationshipStatsJson(): string;
+    /** Whether the index is healthy. */
+    isHealthy(): boolean;
+    /**
+     * Whether the graph's edges are loaded and queryable WITHOUT a rebuild —
+     * brainy 8.0's rebuild gate (#36). `true` once an SSTable has cold-loaded
+     * (binary/file), a manifest named ≥1 SSTable, or a memtable was flushed,
+     * or while any tree's memtable is non-empty. Edges-loaded semantics only,
+     * never gated on verb-id membership.
+     */
+    isReady(): boolean;
+    /** Comprehensive statistics. */
+    getStats(): GraphAdjacencyStats;
+    /** List all tree names: `source`, `target`, `verbs-source`, `verbs-target`. */
+    treeNames(): string[];
+    /** Verb-ID interning namespace wire width: `"U32"` or `"U64"`. */
+    verbIdSpace(): string;
+}
+/**
+ * Mutation result from add/remove operations.
+ * Tells the TS wrapper which data needs to be persisted. Posting lists are
+ * owned + made durable by the LSM engine, so the only TS-side persistence is
+ * the value-enumeration field indexes and the field registry.
+ */
+export interface NativeMetadataMutationResult {
+    dirtyFieldIndexes: string[];
+    newFields: string[];
+    dirtyFieldRegistry: boolean;
+}
+/**
+ * Native metadata index instance.
+ * All query and mutation operations execute synchronously in Rust.
+ * TS wrapper handles async storage I/O.
+ */
+export interface NativeMetadataIndexInstance {
+    /** IdSpace this metadata index was constructed with — `"u32"` or `"u64"`. */
+    idSpace(): string;
+    /**
+     * Replace this index's LSM engine with the durable, mmap-backed engine the
+     * TS wrapper opened for the brain's storage path. The index is constructed
+     * with a non-persistent in-RAM engine (so it is usable immediately);
+     * production swaps in the persistent engine here during `init()`, before
+     * any mutation. The engine's IdSpace MUST match the metadata index's —
+     * mismatches throw at attach time.
+     */
+    setLsmEngine(engine: NativeLsmEngineInstance): void;
+    /**
+     * Whether mutations + queries route through the LSM engine. Always `true`
+     * in cor 3.0 — the LSM engine is the sole metadata engine and is attached
+     * at construction. Retained as a diagnostic surface for TS-side assertions.
+     */
+    isLsmEnabled(): boolean;
+    /**
+     * **Piece 6 generation counter.** Bumped by every read-visible
+     * mutation (`addToIndex` / `removeFromIndex`). Compared by readers to
+     * invalidate cached lazy-load state.
+     */
+    currentGeneration(): bigint;
+    /**
+     * **Piece 15 per-field generation counter.** Bumped by every
+     * `addToIndex` / `removeFromIndex` operation that touches the
+     * given field. Brainy 8.0+ wrappers use this to ask "did field X
+     * change since I last looked?" without dumping every loaded
+     * field's lazy-load state on every mutation. Returns `0n` for
+     * fields that have never been registered (cold-boot sentinel —
+     * matches `currentGeneration()` starting at `0n`).
+     */
+    fieldGeneration(field: string): bigint;
+    /**
+     * **#72 Phase C.** Inject the shared mmap `BinaryIdMapper` as this
+     * metadata index's canonical UUID ↔ entity-int allocator. The native
+     * core is constructed with no storage path; the TS wrapper derives the
+     * `_id_mapper/*` paths, builds the mapper, and injects it here before
+     * any mutation. The mapper's IdSpace MUST match the index's (both
+     * `"u64"` in production) — mismatches throw. Replaces the legacy
+     * `loadEntityIdMapper` / `saveEntityIdMapper` JSON path.
+     */
+    setIdMapper(mapper: NativeBinaryIdMapperInstance): void;
+    entityIdMapperSize(): number;
+    uuidToInt(uuid: string): number | null;
+    intToUuid(intId: number): string | null;
+    intsToUuids(ints: number[]): string[];
+    loadFieldRegistry(json: string): void;
+    saveFieldRegistry(): string;
+    loadFieldIndex(field: string, json: string): void;
+    saveFieldIndex(field: string): string | null;
+    getIds(field: string, valueJson: string): string[];
+    /**
+     * Count IDs for a single field-value pair WITHOUT materializing the UUID
+     * strings. Equals `getIds(field, valueJson).length` exactly (counts only
+     * ints that resolve in the entity-id mapper), but allocates no Strings —
+     * the count-only fast path for type/criteria/VFS counts at 10B scale.
+     */
+    getIdsCount(field: string, valueJson: string): number;
+    /**
+     * Resolve a filter to its matching ids. `limit`/`offset` are the optional
+     * page bound (#75): when `limit` is supplied the native producer returns
+     * only the `[offset, offset+limit)` window, short-circuiting the posting-list
+     * → UUID conversion at `offset+limit` instead of materializing then slicing.
+     * Omitting `limit` returns the full match set (back-compat).
+     */
+    getIdsForFilter(filterJson: string, allIdsJson?: string | null, limit?: number | null, offset?: number | null): string[];
+    /**
+     * Cumulative count of id-mapper resolutions performed by `getIdsForFilter`
+     * since construction (#75 observability). The page-bounded path keeps this
+     * at `offset+limit` per call instead of the full match cardinality.
+     */
+    filterIdsResolved(): number;
+    getIdsForMultipleFields(pairsJson: string): string[];
+    getIdsForRange(field: string, minJson: string | null, maxJson: string | null, includeMin: boolean, includeMax: boolean): string[];
+    getIdsForTextQuery(queryStr: string): string;
+    getFilterValues(field: string): string[];
+    getFilterFields(): string[];
+    extractFieldNames(entityJson: string): string[];
+    addToIndex(id: string, entityJson: string): string;
+    removeFromIndex(id: string, metadataJson?: string | null): string;
+    getEntityCountByType(typeName: string): number;
+    getTotalEntityCount(): number;
+    getTopNounTypes(n: number): string;
+    getTopVerbTypes(n: number): string;
+    getStats(): string;
+    /**
+     * O(1)-ish internal consistency probe. Samples a bounded set of fields/ints
+     * and returns `false` if a sampled int sits in >1 value bucket of an
+     * otherwise-single-valued field (a cross-bucket phantom), `true` otherwise.
+     * Never throws; empty index → `true`. Backs the wrapper's `probeConsistency`.
+     */
+    probeConsistency(): boolean;
+    /**
+     * Scan for the cross-bucket phantom signature (a query-visible int in >1
+     * value bucket of a field) and return up to `maxCandidates` (0 = unlimited)
+     * as a JSON array of `{ uuid, field }`. The `__words__` text index is
+     * skipped. Drives the state-level repair from `detectAndRepairCorruption`.
+     */
+    detectCrossBucketPhantoms(maxCandidates: number): string;
+    /**
+     * Tombstone `uuid`'s int out of every value bucket of `field` except those
+     * matching its current stored value(s) (`currentValuesJson`: a JSON array of
+     * raw values). Empty array → evict from every bucket (orphan purge). Returns
+     * `true` if anything was tombstoned.
+     */
+    repairEntityFieldPhantom(uuid: string, field: string, currentValuesJson: string): boolean;
+    clear(): void;
+}
+/**
+ * Construction options for {@link NativeLsmEngineInstance}.
+ *
+ * Every field is optional; defaults match production usage
+ * (`idSpace:"u32"`, bloom emit on at 10 bits/element, admission ratio
+ * 0.85). Test drivers may override `admissionThresholdRatio` to drive
+ * the admission gate under controlled budgets.
+ */
+export interface NativeLsmEngineOptions {
+    /** `"u32"` (default) or `"u64"`. */
+    idSpace?: string;
+    /** Emit bloom filters in flushed SSTables. Default `true`. */
+    emitBloom?: boolean;
+    /** Bits per element for the bloom filter. Default `10` (~1% FPR). */
+    bloomBitsPerElement?: number;
+    /**
+     * Admission threshold ratio (0.0..1.0). Default `0.85`. Hardcoded for
+     * production per the zero-config mandate — exposed here for test
+     * drivers only.
+     */
+    admissionThresholdRatio?: number;
+}
+/**
+ * Native LSM metadata-index engine.
+ *
+ * Owns the sharded memtable, the global epoch counter, the
+ * content-keyed reader cache, and the write admission-control gate.
+ * The sole metadata storage engine; the wrapper swaps the durable
+ * instance into a {@link NativeMetadataIndexInstance} via
+ * {@link NativeMetadataIndexInstance.setLsmEngine} during init().
+ *
+ * The `*Big` siblings of `insert`/`delete` accept `bigint` ids; the
+ * non-suffixed methods accept JS `number` and throw on U64 mode if the
+ * value exceeds `Number.MAX_SAFE_INTEGER`.
+ */
+export interface NativeLsmEngineInstance {
+    /** `"u32"` or `"u64"` — fixed at construction. */
+    idSpace(): string;
+    /** Add an entity int to `(field, value)`. */
+    insert(field: string, value: string, intId: number): void;
+    insertBig(field: string, value: string, intId: bigint): void;
+    /** Tombstone an entity int at `(field, value)`. */
+    delete(field: string, value: string, intId: number): void;
+    deleteBig(field: string, value: string, intId: bigint): void;
+    /**
+     * Drain the memtable and produce SSTable bytes + manifest entry JSON
+     * ready for `storage.saveBinaryBlob`. Returns `null` when there is
+     * nothing to flush.
+     */
+    flush(): NativeLsmFlushResult | null;
+    /**
+     * **Piece 7 / LSM durability.** Advance the flush watermark on every
+     * shard's memtable log so records with `epoch <= throughEpoch` are dropped
+     * from future replay. The wrapper calls this ONLY after the SSTable bytes
+     * returned by the preceding {@link flush} AND the manifest referencing them
+     * are durably persisted (and the SSTable registered) — at that point the
+     * data lives in both the log and the persisted SSTable, so the log copy is
+     * safe to retire. No-op for in-memory engines (constructed without
+     * `openWithDir`).
+     */
+    commitFlushThrough(throughEpoch: bigint): void;
+    /**
+     * Update the budget ceiling. Driven by the wrapper's
+     * `ResourceManager` subscriber callback. Pass `0xffffffffffffffffn`
+     * (`u64::MAX`) to disable admission control.
+     */
+    setAllowedBytes(bytes: bigint): void;
+    /** Current budget ceiling. */
+    allowedBytes(): bigint;
+    /** Estimated memtable resident bytes. */
+    memtableBytes(): bigint;
+    /** Outstanding admission-reserved bytes (diagnostic). */
+    reservedBytes(): bigint;
+    /** Distinct `(field, value)` keys buffered in the memtable. */
+    memtableEntryCount(): bigint;
+    /** Next epoch the engine will allocate. */
+    currentEpoch(): bigint;
+    /** Whether the next insert would block on admission control. */
+    isOverAdmissionThreshold(): boolean;
+    /**
+     * Combined native memory footprint (memtable + reader cache). Reported
+     * to `ResourceManager.reportNativeMemory` to keep the per-category
+     * accounting honest.
+     */
+    nativeMemoryBytes(): bigint;
+    /**
+     * Take a point-in-time snapshot for reading. Holds Arc clones of the
+     * memtable shards + the supplied SSTable readers; reads through this
+     * handle are valid for up to 30 seconds.
+     */
+    takeSnapshot(sstables: Buffer[]): NativeLsmSnapshotInstance;
+    /**
+     * Read a posting list for `(field, value)` across the live memtable +
+     * the supplied SSTable bytes. Returns croaring portable bytes; an
+     * empty Buffer means "no matches".
+     */
+    readPostingList(field: string, value: string, sstables: Buffer[]): Buffer;
+    /** Zero-copy mmap variant of {@link readPostingList}. */
+    readPostingListFromPaths(field: string, value: string, paths: string[]): Buffer;
+    /** Open an SSTable from disk into the reader cache (mmap). */
+    openSstablePath(path: string): void;
+    /**
+     * Open an SSTable from disk (mmap + SHA-256 verify) and register it
+     * into the engine's live-SSTable set so every subsequent read
+     * snapshot includes it. Unlike {@link openSstablePath} (which only
+     * warms the evictable cache), this grows the engine-owned read view.
+     */
+    registerSstablePath(path: string): void;
+    /** Number of SSTable readers currently in the engine's live set. */
+    liveSstableCount(): number;
+    /** Phase 5 hook — drop the cache entry for a path. */
+    evictReaderCacheByPath(path: string): void;
+    /** Walk every directory entry in an SSTable in sorted order. */
+    scanSstable(sstable: Buffer): NativeLsmScanEntry[];
+}
+/**
+ * Result of {@link NativeLsmEngineInstance.flush}.
+ */
+export interface NativeLsmFlushResult {
+    /** Raw SSTable bytes — hand to `storage.saveBinaryBlob`. */
+    sstable: Buffer;
+    /** `LsmSstableManifestEntry` JSON for the wrapper to splice in. */
+    manifestEntryJson: string;
+    /** Number of `(field, value)` keys in the flushed SSTable. */
+    entryCount: bigint;
+    /** New `last_durable_epoch` value to write into the manifest. */
+    lastDurableEpoch: bigint;
+}
+/**
+ * One entry materialized from {@link NativeLsmEngineInstance.scanSstable}.
+ */
+export interface NativeLsmScanEntry {
+    field: string;
+    value: string;
+    additionsBytes: Buffer;
+    deletionsBytes: Buffer;
+    additionCount: bigint;
+    deletionCount: bigint;
+    epoch: bigint;
+    isTombstone: boolean;
+}
+/**
+ * Point-in-time read handle returned by
+ * {@link NativeLsmEngineInstance.takeSnapshot}. Reads return
+ * `SnapshotExpired` after 30 seconds.
+ */
+export interface NativeLsmSnapshotInstance {
+    /** Read the posting list for `(field, value)` at this snapshot's epoch. */
+    readPostingList(field: string, value: string): Buffer;
+    /** Whether the snapshot has aged past its 30-second lifetime. */
+    isExpired(): boolean;
+    /** Number of SSTables held by this snapshot (diagnostic). */
+    sstableCount(): number;
+}
+/**
+ * Native column store instance.
+ *
+ * Owns per-field tail buffers + loaded `.cidx` segments and performs the
+ * sort/filter/range value operations in Rust. The TS wrapper
+ * (`utils/NativeColumnStore.ts`) bridges async storage I/O: it persists flushed
+ * segments as binary blobs and loads them back (zero-copy via mmap when a local
+ * path exists). All four brainy value types are native — `Number`/`Boolean`
+ * share the i64 path, `Float` is f64, `String` is length-prefixed UTF-8.
+ */
+export interface NativeColumnStoreInstance {
+    /** Load a segment from a buffer (remote storage, no local path). */
+    loadSegmentFromBuffer(field: string, segmentId: string, data: Buffer): void;
+    /** Load a segment by memory-mapping a file path (zero-copy reads). */
+    loadSegmentFromPath(field: string, segmentId: string, path: string): void;
+    /**
+     * Add an entry to the in-memory tail buffer for a numeric (i64) field.
+     *
+     * **Cor 3.0 Piece E**: `entityIntId` is now `bigint` (full u64 range).
+     * The pre-E `addNumericBig` alias was removed; this method accepts the
+     * full u64 range directly.
+     */
+    addNumeric(field: string, value: number, entityIntId: bigint): void;
+    /** Add an entry to the in-memory tail buffer for a float (f64) field. */
+    addFloat(field: string, value: number, entityIntId: bigint): void;
+    /** Add an entry to the in-memory tail buffer for a string field. */
+    addString(field: string, value: string, entityIntId: bigint): void;
+    /** Mark an entity as deleted for a specific field. */
+    deleteEntity(field: string, entityIntId: bigint): void;
+    /**
+     * Sort top-K entity ints by a field (auto-routed by field type).
+     *
+     * **Cor 3.0 Piece E**: returns `bigint[]` for full u64 fidelity. The
+     * pre-E `sortTopKBig` alias was removed.
+     */
+    sortTopK(field: string, order: 'asc' | 'desc', k: number): bigint[];
+    /**
+     * Point filter (numeric) → serialized portable Roaring64 bitmap.
+     *
+     * **Cor 3.0 Piece E**: result is now a Roaring64 (Treemap) portable
+     * bitmap, not the pre-E Roaring32 (Bitmap). Brainy 8.0 TS-side decoder
+     * must use the Roaring64 portable parser.
+     */
+    filterNumeric(field: string, value: number): Buffer;
+    /** Range filter (numeric, inclusive) → serialized portable Roaring64 bitmap. */
+    rangeQueryNumeric(field: string, lo: number, hi: number): Buffer;
+    /** Point filter (float) → serialized portable Roaring64 bitmap. */
+    filterFloat(field: string, value: number): Buffer;
+    /** Range filter (float, inclusive) → serialized portable Roaring64 bitmap. */
+    rangeQueryFloat(field: string, lo: number, hi: number): Buffer;
+    /** Point filter (string) → serialized portable Roaring64 bitmap. */
+    filterString(field: string, value: string): Buffer;
+    /** Range filter (string, inclusive) → serialized portable Roaring64 bitmap. */
+    rangeQueryString(field: string, lo: string, hi: string): Buffer;
+    /** Drain a field's tail buffer to a sorted `.cidx` segment buffer, or null if empty. */
+    flushTailBuffer(field: string, level: number, segmentId: number): Buffer | null;
+    /** Tail buffer entry count for a field. */
+    tailBufferSize(field: string): number;
+    /** Whether any segments or tail data exist for a field. */
+    hasField(field: string): boolean;
+    /** All distinct values for a field, as ascending strings. */
+    distinctValues(field: string): string[];
+}
+/**
+ * Result from eviction or clear operations.
+ */
+export interface NativeEvictionResult {
+    evictedKeys: string[];
+    bytesFreed: number;
+}
+/**
+ * Cache statistics including native memory tracking.
+ */
+export interface NativeCacheStats {
+    totalSize: number;
+    maxSize: number;
+    itemCount: number;
+    typeSizes: number[];
+    typeCounts: number[];
+    typeAccessCounts: number[];
+    totalAccessCount: number;
+    nativeMemory: number[];
+    totalManagedMemory: number;
+}
+/**
+ * Native unified cache instance.
+ * Manages eviction decisions and cache entry metadata.
+ * TS wrapper holds actual JS data in a Map.
+ */
+export interface NativeUnifiedCacheInstance {
+    recordAccess(key: string): void;
+    insert(key: string, cacheType: number, size: number, rebuildCost: number): NativeEvictionResult;
+    remove(key: string): number;
+    removeByPrefix(prefix: string): string[];
+    clear(cacheType?: number | null): string[];
+    checkFairness(): NativeEvictionResult;
+    evictForSize(bytesNeeded: number): NativeEvictionResult;
+    reportNativeMemory(hnsw: number, metadata: number, graph: number): void;
+    getStats(): NativeCacheStats;
+    has(key: string): boolean;
+    itemCount(): number;
+    saveAccessPatterns(): string;
+    loadAccessPatterns(json: string): void;
+}
+/**
+ * PQ codebook parameters.
+ */
+export interface PQParams {
+    m: number;
+    ksub: number;
+    dsub: number;
+    dim: number;
+}
+/**
+ * Native Product Quantization codebook instance.
+ */
+export interface NativePQCodebookInstance {
+    readonly params: PQParams;
+    encode(vector: number[]): Buffer;
+    encodeBatch(vectors: number[], dim: number): Buffer;
+    decode(code: Buffer): number[];
+    computeAdcTable(query: number[]): number[];
+    distanceAdc(table: number[], code: Buffer): number;
+    distanceAdcBatch(table: number[], codes: Buffer, n: number): number[];
+    serialize(): Buffer;
+}
+/**
+ * Native aggregation engine instance.
+ * Provides Rust-accelerated incremental aggregation with:
+ * - BTreeMap precise MIN/MAX (never stale after deletes)
+ * - Rayon parallel rebuild (100x on multi-core)
+ * - Welford's online stddev/variance
+ * - Integer timestamp bucketing (no Date allocation)
+ * - Compiled source filters (rebuild path)
+ */
+export interface NativeAggregationEngineInstance {
+    /** Register an aggregate definition (compiles and caches for hot path) */
+    defineAggregate(definitionJson: string): void;
+    /** Remove a registered aggregate definition and its state */
+    removeAggregate(name: string): void;
+    /**
+     * Incrementally update aggregation state when an entity changes.
+     * Entity is passed as serde_json::Value (NAPI converts JS objects directly).
+     * Returns JSON array of modified AggregateGroupState objects.
+     */
+    incrementalUpdate(name: string, entity: unknown, op: string, prev?: unknown): string;
+    /**
+     * Compute the group key for an entity given groupBy dimensions.
+     * Returns JSON string of the group key object.
+     */
+    computeGroupKey(entity: unknown, groupByJson: string): string;
+    /**
+     * Rebuild an entire aggregate from scratch using Rayon parallelism.
+     * Takes definition and entities as JSON strings.
+     * Returns JSON string of the state (array of AggregateGroupState).
+     */
+    rebuildAggregate(definitionJson: string, entitiesJson: string): string;
+    /**
+     * Query aggregate state with filtering/sorting/pagination.
+     * Takes state and params as JSON strings.
+     * Returns JSON array of AggregateResult objects.
+     */
+    queryAggregate(stateJson: string, paramsJson: string): string;
+    /** Serialize all internal state for persistence */
+    serializeState(): string;
+    /** Restore internal state from previously serialized data */
+    restoreState(stateJson: string): void;
+    /** Engine statistics (definition count, total groups, etc.) */
+    readonly stats: string;
+}
+//# sourceMappingURL=types.d.ts.map