@soulcraft/cor 3.0.0-rc.1

package/native/index.d.ts

@@ -0,0 +1,3916 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * NativeAggregationEngine — napi wrapper for the Rust aggregation engine.
+ *
+ * Cor owns compute, Brainy owns storage. All metric calculations happen
+ * in Rust; results are returned to TS for state merging and persistence.
+ */
+export declare class NativeAggregationEngine {
+  constructor()
+  /** 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.
+   *
+   * Returns JSON array of modified AggregateGroupState objects.
+   * Entity/prev are passed as serde_json::Value (NAPI converts JS objects directly).
+   */
+  incrementalUpdate(name: string, entity: any, op: string, prev?: any | undefined | null): string
+  /**
+   * Compute the group key for an entity given groupBy dimensions.
+   * Returns JSON string of the group key object.
+   */
+  computeGroupKey(entity: any, groupByJson: string): string
+  /**
+   * Rebuild an entire aggregate from scratch using Rayon parallelism.
+   *
+   * Takes definition and entities as JSON strings.
+   * Returns JSON string of Map<serializedGroupKey, 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
+  /** Get engine statistics as JSON string. */
+  get stats(): string
+}
+
+/** JS-exposed binary EntityIdMapper. */
+export declare class NativeBinaryIdMapper {
+  constructor()
+  /** Create a fresh mapper (truncates existing files at the paths). */
+  static create(config: BinaryIdMapperConfig): NativeBinaryIdMapper
+  /**
+   * Open an existing mapper. Runs the consistency check between
+   * uuid_to_int and int_to_uuid; surfaces crash-induced
+   * inconsistencies as errors.
+   */
+  static openExisting(config: BinaryIdMapperConfig): NativeBinaryIdMapper
+  /**
+   * Current id-mapper generation across both substrates
+   * (uuid_to_int + int_to_uuid). Returned as BigInt — fits the
+   * brainy generation contract; lossless across the JS bridge
+   * regardless of value range.
+   */
+  currentGeneration(): bigint
+  /**
+   * Pin a generation across BOTH substrates. The returned
+   * `NativeBinaryIdMapperPin` MUST be `release()`d (or dropped
+   * by the JS GC) for compaction to resume; while alive, both
+   * substrates retain the on-disk base files at that
+   * generation.
+   *
+   * Use this to back `brain.db().asOf(g)` /
+   * `brain.db().with(...)` time-travel views (Datomic-style
+   * immutable Db API, Piece 17). brainy holds one Pin per
+   * substrate per view; when the view drops, every Pin
+   * releases together.
+   *
+   * Throws if `generation` is strictly newer than the current
+   * generation (the brain hasn't advanced to that point yet).
+   */
+  pin(generation: bigint): NativeBinaryIdMapperPin
+  /**
+   * Smallest currently-pinned generation across both
+   * substrates, or `null` when no pins are held. Diagnostic;
+   * compaction queries each substrate independently.
+   */
+  minPinnedGeneration(): bigint | null
+  /**
+   * **Phase D step 5b — point-in-time lookup.** Returns the
+   * int assigned to `uuid` as it existed at brainy generation
+   * `at_gen`. Caller must hold a [`NativeBinaryIdMapperPin`]
+   * at `at_gen` for the result to be stable across concurrent
+   * compaction. Throws in U64 mode — use `getIntAtGenerationBig`.
+   */
+  getIntAtGeneration(uuid: Buffer, atGen: bigint): number | null
+  /**
+   * **Phase D step 5b — BigInt sibling.** Returns the int
+   * assigned to `uuid` at brainy generation `at_gen` as a
+   * `BigInt`. Use in U64 mode; the u32 sibling is
+   * `getIntAtGeneration`.
+   */
+  getIntAtGenerationBig(uuid: Buffer, atGen: bigint): bigint | null
+  /**
+   * **Phase D step 5d — int → UUID point-in-time lookup.**
+   * Returns the UUID assigned to `int` as it existed at
+   * brainy generation `at_gen`. Throws in U64 mode — use
+   * `getUuidAtGenerationBig`.
+   */
+  getUuidAtGeneration(int: number, atGen: bigint): Buffer | null
+  /** **Phase D step 5d — BigInt sibling for U64 mode.** */
+  getUuidAtGenerationBig(int: bigint, atGen: bigint): Buffer | null
+  /**
+   * Retrieve the int previously assigned to `uuid`, or allocate a
+   * fresh one. Idempotent across concurrent callers for the same
+   * UUID (256 sharded per-UUID mutexes enforce single assignment).
+   *
+   * Returns a JS `number`. Throws if this brain is `IdSpace::U64`
+   * — use [`get_or_assign_big`] in that case.
+   */
+  getOrAssign(uuid: Buffer): number
+  /**
+   * Lookup the int for `uuid`. Returns null if not present. Throws
+   * in `IdSpace::U64` mode — use [`get_int_big`].
+   */
+  getInt(uuid: Buffer): number | null
+  /**
+   * Lookup the UUID for `int`. Returns a 16-byte Buffer or null.
+   * Accepts a JS `number`. Throws in `IdSpace::U64` mode — use
+   * [`get_uuid_big`].
+   */
+  getUuid(int: number): Buffer | null
+  /**
+   * Live (non-tombstone) entry count as a JS `number`. Throws in
+   * `IdSpace::U64` mode — use [`size_big`].
+   */
+  size(): number
+  /**
+   * Largest int ever assigned + 1, as a JS `number`. Throws in
+   * `IdSpace::U64` mode — use [`next_int_big`].
+   */
+  nextInt(): number
+  /**
+   * Materialise every live int into a single Vec. **Avoid at
+   * billion scale** — at U32 the cap is 100 M (~400 MB array on
+   * the V8 heap); above the cap throws and points at the streaming
+   * `iterator` API. U64 mode disables this method unconditionally;
+   * use `iterator()` instead.
+   */
+  getAllIntIds(): Array<number>
+  /**
+   * BigInt sibling of [`get_or_assign`]. Works in both `IdSpace`
+   * modes — U32 brains return a BigInt that fits in 4 bytes; U64
+   * brains may return values > 2^53 (lossless via BigInt, lossy as
+   * a JS number).
+   */
+  getOrAssignBig(uuid: Buffer): bigint
+  /** BigInt sibling of [`get_int`]. */
+  getIntBig(uuid: Buffer): bigint | null
+  /** BigInt sibling of [`get_uuid`]. */
+  getUuidBig(int: bigint): Buffer | null
+  /**
+   * **Batch sibling of [`get_uuid_big`] (cor 3.0 Phase A, ADR-006 Q5).**
+   * Resolve many entity ints to their UUID bytes in ONE boundary
+   * crossing — the `entityIntsToUuids` provider path brainy uses to
+   * hydrate a `Subgraph`'s `nodes` column (one crossing beats N
+   * per-int `getUuidBig` calls when a viz/export renders many rows).
+   * Returns a parallel vector: `Some(16-byte UUID Buffer)` for a
+   * mapped int, `None` for an unmapped one, so the result stays
+   * index-aligned with the input (the TS wrapper stringifies each /
+   * fills gaps).
+   */
+  intsToUuidsBig(ints: Array<bigint>): Array<Buffer | undefined | null>
+  /** BigInt sibling of [`size`]. */
+  sizeBig(): bigint
+  /** BigInt sibling of [`next_int`]. */
+  nextIntBig(): bigint
+  /**
+   * Construct a streaming iterator over every live `(int, uuid)`
+   * pair. The iterator snapshots `next_int` at construction time —
+   * allocations performed after the iterator was created are NOT
+   * visible. Tombstoned slots are skipped.
+   *
+   * Returns a [`NativeBinaryIdMapperIter`] with [`next_batch`]
+   * yielding BigInt ints (uniform across IdSpace modes).
+   */
+  iterator(): NativeBinaryIdMapperIter
+  /** Tombstone an entry. The int is NEVER reused (stability contract). */
+  remove(uuid: Buffer): boolean
+  /** Flush dirty mmap pages to disk. */
+  flush(): void
+  /** Convenience: filesystem paths to the underlying files. */
+  paths(): Array<string>
+  /**
+   * IdSpace as a string — `"u32"` or `"u64"`. The TS layer uses
+   * this for the dispatch in [`BinaryIdMapperConfig::id_space`].
+   */
+  idSpace(): string
+  /**
+   * Algorithmic capabilities — exposed for diagnostics and parity
+   * tests against the JS reference mapper.
+   *
+   * The u32-typed `size` and `next_int` fields throw in
+   * `IdSpace::U64` mode (use `size_big` / `next_int_big`); the
+   * BigInt fields work in both modes.
+   */
+  diagnostics(): BinaryIdMapperDiagnostics
+}
+
+/**
+ * Streaming iterator over `(int, uuid)` pairs. Snapshots `next_int`
+ * at construction time; tombstoned slots are skipped during
+ * iteration. Returned by [`NativeBinaryIdMapper::iterator`].
+ *
+ * JS callers drive iteration via [`next_batch`]. Each batch returns
+ * up to `max_batch` BigInt ints. The iterator is exhausted when
+ * `next_batch` returns `null` (the snapshot range has been fully
+ * walked).
+ */
+export declare class NativeBinaryIdMapperIter {
+  /**
+   * Read the next batch of live ints (tombstones skipped). Returns
+   * `null` when the iterator is exhausted. `max_batch` is an upper
+   * bound on the number of SLOTS scanned per call, not the number
+   * of live ints returned — heavily tombstoned regions yield small
+   * batches.
+   */
+  nextBatch(maxBatch: number): Array<bigint> | null
+  /**
+   * Snapshot upper bound (exclusive) of the iteration range, fixed
+   * at iterator construction time.
+   */
+  rangeEnd(): bigint
+  /**
+   * Current cursor position. Useful for resumable iteration and
+   * progress reporting.
+   */
+  cursor(): bigint
+  /** True when the iterator is exhausted (cursor >= range_end). */
+  isDone(): boolean
+}
+
+/**
+ * JS handle to a BinaryIdMapperPin. Holds both substrates' pins
+ * (uuid_to_int + int_to_uuid) at the same generation; releasing
+ * drops both atomically.
+ *
+ * JS has no RAII, so callers must call `release()` explicitly to
+ * allow compaction to resume. If the JS GC reaps the handle
+ * first, Drop runs the same release path — but relying on GC
+ * timing is not recommended for production code.
+ */
+export declare class NativeBinaryIdMapperPin {
+  /**
+   * The pinned generation. Stable for the lifetime of the
+   * handle.
+   */
+  generation(): bigint
+  /**
+   * Release the pin. Idempotent: calling twice is a no-op.
+   * After release, the brain may compact past the pinned
+   * generation; any read against the pinned view becomes
+   * undefined.
+   */
+  release(): void
+  /**
+   * Whether the pin is still held. `false` after `release()`
+   * or after the JS GC has reaped a backing Rust handle that
+   * internally released.
+   */
+  isHeld(): boolean
+}
+
+/**
+ * Native column store exposed to TypeScript via napi-rs.
+ *
+ * Each instance manages segments for one or more fields. The TypeScript
+ * wrapper (`NativeColumnStore.ts`) bridges storage I/O: it loads segment
+ * data from the storage adapter and passes it to Rust for mmap-based
+ * querying. All four brainy value types are fully native: `Number` and
+ * `Boolean` share the i64 path, `Float` uses an f64 path, and `String`
+ * uses length-prefixed UTF-8. A field's type is inferred from its tail
+ * buffer or loaded segment headers.
+ */
+export declare class NativeColumnStore {
+  constructor()
+  /**
+   * **Piece 6 generation counter — accessor.** See
+   * `native/src/metadata_index/core.rs` for the ordering
+   * rationale shared across all native indexes.
+   */
+  currentGeneration(): bigint
+  /** Load a segment from a buffer (in-memory storage). */
+  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**: consolidated to a single BigInt API.
+   * The legacy `addNumericBig` alias was removed; this method now
+   * accepts the full u64 range. Cortex 2.x callers passing a JS
+   * number must wrap as BigInt (`BigInt(n)`) at the call site.
+   */
+  addNumeric(field: string, value: number, entityIntId: bigint): void
+  /**
+   * Add an entry to the in-memory tail buffer for a float (f64) field.
+   *
+   * Float values are stored as full IEEE 754 doubles (not rounded to
+   * i64), so non-integer values like `19.99` are preserved and ordered
+   * correctly. On flush this becomes a [`ValueType::Float`] `.cidx` segment.
+   */
+  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 (numeric, float, or string —
+   * auto-routed by field type). Returns BigInts for full u64
+   * fidelity at billion scale.
+   *
+   * The k-way merge requires each cursor to be sorted, so the live
+   * tail buffer (in insertion order) is sorted into a per-query
+   * copy first. Segments are already sorted on disk; the tail is
+   * bounded by the flush threshold, so the copy+sort is cheap.
+   */
+  sortTopK(field: string, order: string, k: number): Array<bigint>
+  /** Filter: entity IDs where the numeric field equals the value (serialized roaring bitmap). */
+  filterNumeric(field: string, value: number): Buffer
+  /** Range query: entity IDs where numeric value is in [lo, hi] (serialized roaring bitmap). */
+  rangeQueryNumeric(field: string, lo: number, hi: number): Buffer
+  /** Filter: entity IDs where the float (f64) field equals the value (serialized roaring bitmap). */
+  filterFloat(field: string, value: number): Buffer
+  /** Range query: entity IDs where float (f64) value is in [lo, hi] (serialized roaring bitmap). */
+  rangeQueryFloat(field: string, lo: number, hi: number): Buffer
+  /** Filter: entity IDs where the string field equals the value (serialized roaring bitmap). */
+  filterString(field: string, value: string): Buffer
+  /** Range query: entity IDs where string value is in [lo, hi] (serialized roaring bitmap). */
+  rangeQueryString(field: string, lo: string, hi: string): Buffer
+  /**
+   * Write a field's tail buffer to a sorted `.cidx` segment buffer (numeric, float, or string).
+   * Returns the segment content as Buffer, or None if empty.
+   *
+   * **Cor 3.0 Piece E**: now always writes the u64-keyed segment
+   * variant (`write_*_segment_u64`). The pre-E u32-keyed writers
+   * (`write_*_segment`) stay available for crash-recovery readers
+   * of legacy data, but new flushes are exclusively u64. Tail-
+   * buffer ids are u64 throughout post-E.
+   */
+  flushTailBuffer(field: string, level: number, segmentId: number): Buffer | null
+  /** Get tail buffer entry count for a field (numeric, float, or string). */
+  tailBufferSize(field: string): number
+  /** Check if any segments or tail data exist for a field. */
+  hasField(field: string): boolean
+  /**
+   * All distinct values for a field across segments + tail buffer, as
+   * strings in ascending order (numeric by value, string by code point).
+   * Backs the `getFilterValues` provider method. Deleted entities are not
+   * excluded — values are reported if any (live or tombstoned) entity holds
+   * them, matching brainy's segment-derived value enumeration.
+   */
+  distinctValues(field: string): Array<string>
+}
+
+/** Napi-exposed DiskANN index. */
+export declare class NativeDiskAnn {
+  /** Construct via static factories. */
+  constructor()
+  /**
+   * Build a fresh DiskANN index from a flat f32 vector buffer and
+   * write it to `output_path`. Returns the opened searcher.
+   *
+   * `vectors` is a Buffer of `node_count × dim × 4` little-endian
+   * f32 bytes. For datasets that don't fit in a single Buffer, use
+   * [`build_from_file`](Self::build_from_file).
+   */
+  static build(vectors: Buffer, dim: number, outputPath: string, config?: DiskAnnConfig | undefined | null): NativeDiskAnn
+  /**
+   * Build a fresh DiskANN index, streaming vectors from a flat file
+   * at `vectors_path`. The file contains `header_skip` arbitrary
+   * leading bytes followed by `node_count × dim × 4` LE f32 bytes.
+   *
+   * This is the billion-scale entry point: the source dataset stays
+   * mmap'd, so 1.5 TB of vectors never touches the JS heap.
+   */
+  static buildFromFile(vectorsPath: string, headerSkip: number, dim: number, outputPath: string, config?: DiskAnnConfig | undefined | null): NativeDiskAnn
+  /**
+   * Build a fresh DiskANN index from a BIGANN/SIFT `.bvecs` base file
+   * — the SIFT100M / SIFT1B verification entry point.
+   *
+   * `.bvecs` stores each vector as a 4-byte LE dimension prefix + `dim`
+   * `u8` components, the canonical billion-scale benchmark layout that
+   * [`build_from_file`](Self::build_from_file) (flat f32) can't read
+   * directly. This factory streams the first `node_count` records of
+   * `bvecs_path` into a flat-f32 sidecar at `f32_cache_path`, then
+   * builds from that sidecar via the mmap'd source — so the 512 GB of
+   * SIFT1B f32 vectors never touch the JS heap or physical RAM.
+   *
+   * The sidecar is reused when it already exists at the exact expected
+   * size (`node_count × dim × 4` bytes); converting the 132 GB SIFT1B
+   * base is slow, so re-runs at the same scale skip it. Pass distinct
+   * `f32_cache_path`s for distinct scales (the SIFT100M sidecar is a
+   * strict prefix of the SIFT1B one, but the harness keys them by
+   * subset for clarity).
+   *
+   * `node_count` is `u32`: a single DiskANN shard addresses at most
+   * `u32::MAX − 1` slots by construction (see the module-level slot-ID
+   * note), and SIFT1B (1e9) fits comfortably.
+   */
+  static buildFromBvecsFile(bvecsPath: string, dim: number, nodeCount: number, f32CachePath: string, outputPath: string, config?: DiskAnnConfig | undefined | null): NativeDiskAnn
+  /**
+   * Rebuild a DiskANN index by merging a subset of an existing index
+   * (the "live" slots — typically existing minus tombstones) with a
+   * freshly-inserted delta buffer. **Critical for billion-scale
+   * rebuild correctness**: the existing vectors stay mmap'd; only
+   * the delta crosses the FFI boundary. At 1B × 1536 × 4 bytes
+   * (= ~6 TB) of existing vector data, this is the difference
+   * between "rebuild works" and "rebuild OOMs every time".
+   *
+   * ## Slot layout in the new index
+   *
+   * New slot `i` maps to:
+   * - `live_old_slots[i]` in the OLD index (for `i < live_old_slots.len()`)
+   * - `delta_vectors[i - live_old_slots.len()]` (for the tail)
+   *
+   * The caller is responsible for rebuilding the UUID↔slot maps
+   * using this invariant; the napi layer doesn't carry UUIDs.
+   *
+   * ## Path handling
+   *
+   * If `output_path == existing_path` (in-place rebuild), the new
+   * index is written to `<output_path>.rebuild-tmp` first, the old
+   * mmap is dropped, then the temp file is atomically renamed over
+   * the original. This avoids mmap'ing a file we're concurrently
+   * writing.
+   */
+  static rebuildFromExisting(params: DiskAnnRebuildFromExistingParams): NativeDiskAnn
+  /**
+   * Async sibling of [`Self::rebuild_from_existing`] — identical build
+   * semantics, but the fold runs on a Node worker thread
+   * ([`AsyncTask`] → the libuv pool) so the JS event loop keeps
+   * serving reads/writes for the entire build. This is the "serving
+   * never freezes" primitive: at billion scale the synchronous
+   * factory blocks the loop for hours-to-days; this variant blocks
+   * nothing. Resolves to the reopened new index once the on-disk
+   * artifacts (index + slotmap sidecars) are durably in place.
+   *
+   * Input buffers are copied out of JS memory on the calling thread
+   * (bounded by the wrapper's delta budget), so the task owns plain
+   * `Send` data and the JS side may freely mutate its buffers after
+   * the call returns.
+   */
+  static rebuildFromExistingAsync(params: DiskAnnRebuildFromExistingParams): Promise<NativeDiskAnn>
+  /**
+   * Read a contiguous chunk of vectors from the underlying mmap'd
+   * index. Zero-copy on the Rust side (the returned Buffer is a
+   * fresh allocation, but the read from the mmap is direct). Useful
+   * for diagnostic tooling + small-scale rebuilds that don't go
+   * through [`rebuild_from_existing`].
+   *
+   * Returns a Buffer of `count * dim * 4` LE f32 bytes. If
+   * `start + count` exceeds the index size, the trailing slots are
+   * silently truncated.
+   */
+  readVectorChunk(start: number, count: number): Buffer
+  /**
+   * Open an existing DiskANN file for search-only access.
+   *
+   * `mode` selects the per-section madvise profile applied at open
+   * time — one of `"in-memory" | "hybrid" | "on-disk"`. When
+   * omitted, the file header drives the choice: `pq_m == 0`
+   * (Mode 1 marker) → in-memory hints; PQ-enabled → hybrid hints.
+   * The mode never changes correctness; it only biases the OS
+   * page cache toward the right residency for the operating
+   * regime. See [`OpenMode`] for the full hint table.
+   */
+  static openExisting(path: string, mode?: string | undefined | null): NativeDiskAnn
+  /**
+   * k-NN search. `l_search` controls the greedy-walk candidate set;
+   * the DiskANN paper recommends `l_search ≥ 2k`. `padding_factor`
+   * is the **optional** re-rank cap: when omitted, the searcher
+   * re-ranks the **full walked candidate list** with exact vectors
+   * (canonical DiskANN, best recall — the mmap-resident vectors make
+   * it near-free). Pass an explicit value to bound the re-rank to
+   * `ceil(k × padding_factor)` for the cold-NVMe random-read case.
+   */
+  search(query: Array<number>, k: number, lSearch?: number | undefined | null, paddingFactor?: number | undefined | null): Array<DiskAnnHit>
+  /**
+   * Filtered k-NN search — **predicate pushdown** (#10). `allowed_slots`
+   * are the graph-internal slot IDs the result may contain; the TS
+   * wrapper translates the metadata∩graph entity universe → slots and
+   * inflates `l_search` by the predicate selectivity. The walk traverses
+   * through all nodes but only collects allowed slots, so this returns
+   * far higher recall than post-filtering the unfiltered top-k when the
+   * predicate is selective. An empty `allowed_slots` returns no hits.
+   */
+  searchFiltered(query: Array<number>, k: number, allowedSlots: Array<number>, lSearch?: number | undefined | null, paddingFactor?: number | undefined | null): Array<DiskAnnHit>
+  /**
+   * Exact top-k over an explicit slot set — **brute-force pushdown** for
+   * extreme-selectivity filters. The TS wrapper routes here (instead of
+   * `searchFiltered`) when `k / selectivity` would exceed the walk's
+   * `l_search` cap: a bounded walk can't reach scattered allowed points, so
+   * scanning the (tiny) allowed set is both faster AND exact. `slots` are
+   * graph-internal slot ids; out-of-range ids are skipped.
+   */
+  searchExactSlots(query: Array<number>, k: number, slots: Array<number>): Array<DiskAnnHit>
+  /** Number of vectors in the index. */
+  size(): number
+  /** Header introspection. */
+  header(): DiskAnnHeader
+  /** On-disk file path. */
+  filePath(): string
+  /**
+   * Whether a valid forward (`slot → int`) slotmap is attached. The TS
+   * wrapper discards a cold-opened index whose slotmap failed to load
+   * (missing / stale) so it never resolves slot ids as entity ids.
+   */
+  slotmapReady(): boolean
+  /**
+   * Read the entity ints for a set of slots from the forward slotmap.
+   * Index-aligned with the input (out-of-range slots fall back to the
+   * slot value). The TS rebuild path uses this to recover the stable
+   * entity ints of retained ("live old") slots without a resident
+   * `slot → int` map — they pass straight back into the new slotmap.
+   */
+  slotIdsForSlots(slots: Array<number>): Array<bigint>
+  /**
+   * Translate a set of entity ints to the slots that hold them in this
+   * shard via the reverse (`int → slot`) slotmap. Entity ints not in
+   * this shard are dropped (the result is the present subset, NOT
+   * index-aligned) — exactly the `allowedSlots` set the predicate-
+   * pushdown walk consumes. Empty when no slotmap is attached.
+   */
+  slotsForInts(ints: Array<bigint>): Array<number>
+  /**
+   * Whether an entity int is present in this shard (reverse slotmap
+   * membership). Backs `removeItem` + the tombstone count. `false`
+   * when no slotmap is attached.
+   */
+  hasInt(int: bigint): boolean
+}
+export type NativeDiskANN = NativeDiskAnn
+
+/**
+ * Native embedding engine (napi-rs class).
+ *
+ * Pooling is always mean over token embeddings, weighted by the
+ * attention mask — the canonical sentence-embedding shape for the
+ * MiniLM model family. We hardcode it rather than carry a
+ * strategy enum because (1) only mean-pooling is ever used and
+ * (2) adding CLS / max-pool later costs a few lines plus a
+ * matching test, not a field that lies dormant in every engine.
+ */
+export declare class NativeEmbeddingEngine {
+  /** Create a new embedding engine instance (not yet loaded). */
+  constructor()
+  /**
+   * Load the model and tokenizer from byte buffers.
+   *
+   * Arguments:
+   * - model_bytes: SafeTensors format model weights
+   * - tokenizer_bytes: tokenizer.json contents
+   * - config_bytes: config.json contents
+   */
+  load(modelBytes: Buffer, tokenizerBytes: Buffer, configBytes: Buffer): void
+  /** Check if the engine has a loaded model and tokenizer. */
+  isReady(): boolean
+  /** Generate embedding for a single text. Returns Vec<f64> of 384 dimensions. */
+  embed(text: string): Array<number>
+  /**
+   * Generate embeddings for multiple texts.
+   * Returns Vec<Vec<f64>>.
+   */
+  embedBatch(texts: Array<string>): Array<Array<number>>
+  /** Get the embedding dimension (384 for all-MiniLM-L6-v2). */
+  dimension(): number
+  /** Get the maximum sequence length. */
+  maxSequenceLength(): number
+  /** Get engine statistics. */
+  getStats(): EngineStats
+}
+
+/**
+ * Bidirectional UUID ↔ integer mapper for roaring bitmap integration.
+ *
+ * All methods are synchronous (O(1) HashMap lookups).
+ * Persistence is handled by the TypeScript wrapper via load_from_json/save_to_json.
+ */
+export declare class NativeEntityIdMapper {
+  /** Create a new empty mapper in `IdSpace::U32` mode. */
+  constructor(idSpace?: string | undefined | null)
+  /**
+   * Load state from JSON string (storage format). Replaces all
+   * current state. Sets dirty = false. The loader auto-detects
+   * IdSpace from the envelope (v1 / missing → U32).
+   */
+  loadFromJson(json: string): void
+  /**
+   * Serialize state to JSON string for storage persistence.
+   * Format depends on this mapper's IdSpace — see the module-level
+   * docstring for the v1 / v2 envelopes.
+   */
+  saveToJson(): string
+  /** IdSpace as a string — `"u32"` or `"u64"`. */
+  idSpace(): string
+  /**
+   * Get integer ID for UUID, assigning a new one if not mapped.
+   * Throws in `IdSpace::U64` mode — use [`get_or_assign_big`].
+   */
+  getOrAssign(uuid: string): number
+  /**
+   * Get UUID for integer ID. Returns null if not found. Throws in
+   * `IdSpace::U64` mode — use [`get_uuid_big`].
+   */
+  getUuid(intId: number): string | null
+  /**
+   * Get integer ID for UUID without assigning. Throws in
+   * `IdSpace::U64` mode — use [`get_int_big`].
+   */
+  getInt(uuid: string): number | null
+  /**
+   * Total number of mappings as a JS `number`. Throws in
+   * `IdSpace::U64` mode — use [`size_big`].
+   */
+  get size(): number
+  /**
+   * Convert UUIDs → ints, assigning new IDs as needed. Throws in
+   * `IdSpace::U64` mode — use [`uuids_to_ints_big`].
+   */
+  uuidsToInts(uuids: Array<string>): Array<number>
+  /**
+   * Convert ints → UUIDs. Throws in `IdSpace::U64` mode — use
+   * [`ints_to_uuids_big`].
+   */
+  intsToUuids(ints: Array<number>): Array<string>
+  /** BigInt sibling of [`get_or_assign`]. Works in both IdSpace modes. */
+  getOrAssignBig(uuid: string): bigint
+  /** BigInt sibling of [`get_uuid`]. */
+  getUuidBig(intId: bigint): string | null
+  /** BigInt sibling of [`get_int`]. */
+  getIntBig(uuid: string): bigint | null
+  /** BigInt sibling of [`size`]. */
+  sizeBig(): bigint
+  /** BigInt sibling of [`uuids_to_ints`]. */
+  uuidsToIntsBig(uuids: Array<string>): Array<bigint>
+  /** BigInt sibling of [`ints_to_uuids`]. */
+  intsToUuidsBig(ints: Array<bigint>): Array<string>
+  /** 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
+  /** Whether there are unsaved changes. */
+  isDirty(): boolean
+  /** Clear all mappings and reset counter. Preserves IdSpace. */
+  clear(): void
+  /**
+   * Get statistics about the mapper. The legacy u32 fields cap at
+   * `u32::MAX`; the `*_big` fields are overflow-safe.
+   */
+  getStats(): NativeEntityIdMapperStats
+}
+
+export declare class NativeGraphAdjacencyIndex {
+  constructor(config: GraphAdjacencyConfig)
+  /**
+   * **Piece 6 generation counter — accessor.** Returns the current
+   * generation as a BigInt (u64). The TS wrapper polls this on
+   * every read entry and invalidates its caches when the value
+   * changes. See `native/src/metadata_index/core.rs` for the
+   * memory-ordering rationale.
+   */
+  currentGeneration(): bigint
+  /**
+   * **Cor 3.0 + brainy 8.0.** Add a verb to the graph with its
+   * `(source_int, target_int)` endpoint pair. The pair indexes:
+   * - the `verb_endpoints` store (`verb_int → (source_int, target_int)`),
+   * - the `source` LSM tree (`source_int → target_int`),
+   * - the `target` LSM tree (`target_int → source_int`),
+   * - the `verbs_source` LSM tree (`source_int → (verb_int, target_int)`),
+   * - the `verbs_target` LSM tree (`target_int → (verb_int, source_int)`).
+   *
+   * `subtype` is optional — when `Some(value)` the verb also lands
+   * in the per-`(type, subtype)` membership bitmap + count slot.
+   *
+   * **Endpoints are u64 BigInts** for fidelity at 10B+ scale (U64
+   * brains). U32 brains pass the same channel with zeroed high
+   * bits — no separate API needed.
+   *
+   * `generation` is brainy's commit generation for this write —
+   * the same value brainy threads into the LSM `insert(...,gen)`.
+   * It records the endpoint pair in the per-`verb_id` version
+   * chain at that generation so `getVerbEndpointsAtGeneration`
+   * resolves historical edges for `db.asOf(g)` (graph time travel).
+   */
+  addVerbWithEndpoints(verbId: string, sourceInt: bigint, targetInt: bigint, verbType: string, subtype: string, generation: bigint): GraphAddVerbResult
+  /**
+   * **Strict variant.** Combines pre-resolved verb-type index with
+   * the canonical u64 endpoint pair. Happy path for brainy 8.0
+   * callers — they have the index from `TypeUtils.getVerbIndex` and
+   * the ints from the brain's `BinaryIdMapper`.
+   */
+  addVerbWithEndpointsByIndex(verbId: string, sourceInt: bigint, targetInt: bigint, verbTypeIndex: number, subtype: string, generation: bigint): GraphAddVerbResult
+  /**
+   * Remove a verb (tombstone deletion). LSM-tree edges persist —
+   * removed verbs are filtered out by the membership bitmap on
+   * query. Endpoint slot is tombstoned too so a future
+   * `getVerbEndpoints` returns `None`.
+   *
+   * `verb_type_index` and `subtype` are required for the per-
+   * `(type, subtype)` bookkeeping (decrement the count slot, drop
+   * from the per-pair membership bitmap). Pass an empty string for
+   * `subtype` to skip the subtype-specific bookkeeping (legacy
+   * pre-brainy-8.0 verbs without a subtype). Brainy 8.0's
+   * `verbSubtypeByIdCache` is the source of truth for "which subtype
+   * did this verb have?" and passes the value back on remove.
+   *
+   * **Cor 3.0 / brainy 8.0 lockstep tightening (handoff I.1):**
+   * `subtype` is `String` (not `Option<String>`) at the napi boundary.
+   * Brainy 8.0's enforcement layer guarantees every verb write
+   * supplies a non-empty subtype; the empty-string escape exists
+   * solely for legacy-data remove paths.
+   */
+  removeVerb(verbId: string, verbTypeIndex: number, subtype: string, generation: bigint): void
+  /**
+   * **Look up a verb's endpoints by verb-ID.** Returns
+   * `{sourceInt, targetInt}` (as u64 BigInts) when the verb was
+   * added via one of the `addVerbWithEndpoints*` variants AND is
+   * currently live (not tombstoned via `removeVerb`). Returns
+   * `None` (JS `null`) when:
+   *
+   * - The verb-ID was never interned (`addVerb` never called for
+   *   it).
+   * - The verb was added via a back-compat `addVerb` /
+   *   `addVerbBy*` / `addVerb*WithSubtype` variant that didn't
+   *   carry endpoint info — those verbs are in the membership
+   *   bitmap and LSM trees but not in the endpoint map.
+   * - The verb was removed.
+   *
+   * Brainy 8.0's multi-hop subtype BFS uses this lookup to resolve
+   * each filtered verb-ID to its (source, target) for the next hop;
+   * verbs with no endpoint info are skipped (the only correct
+   * fallback — guessing endpoints could pollute traversal results
+   * at billion-scale).
+   */
+  getVerbEndpoints(verbId: string): VerbEndpointsResult | null
+  /**
+   * **Phase D step 5f/5g — point-in-time endpoint lookup
+   * (membership-at-generation correct).**
+   * Returns the (source, target) pair for `verb_id` as it
+   * existed at brainy generation `at_gen`. Caller must hold
+   * the verb-endpoints substrate's `PinGuard` at `at_gen`
+   * for the result to be stable across concurrent compaction.
+   *
+   * **Membership-at-generation semantics (5g).** This path
+   * trusts the endpoint store's per-`verb_id` version chain
+   * as the single source of truth for *both* the endpoints
+   * *and* the liveness of the verb at `at_gen`. The chain
+   * records `Some((src,tgt))` at the generation a verb was
+   * (re)written and `None` at the generation it was
+   * tombstoned; `get_at_generation` walks
+   * `range(..=at_gen).next_back()`, so:
+   *
+   *   - added g1, removed g5, read g3 → `Some` (live then) ✓
+   *   - added g1, removed g5, read g7 → `None` (gone then) ✓
+   *   - added g5, read g3            → chain-miss → falls to
+   *     the compacted base, valid only while a pin at `at_gen`
+   *     keeps history from collapsing below it (the contract).
+   *
+   * The current-live `verb_id_membership` bitmap is
+   * deliberately **not** consulted here — it reflects the
+   * present, not `at_gen`. (It still gates the hot-path
+   * [`get_verb_endpoints`], which is a current-state read.)
+   * Consulting it here was the old 5f limitation: a verb
+   * removed after `at_gen` would wrongly read as absent at
+   * `at_gen`. The chain already encodes liveness per
+   * generation, so the bitmap check is both unnecessary and
+   * incorrect for historical reads.
+   *
+   * Note: this resolves a single edge's endpoints at `at_gen`.
+   * Historical *enumeration* of a node's edges
+   * ([`get_neighbors`]/[`get_verb_ids_by_source`]) is
+   * current-state; brainy's `db.asOf(g)` composition
+   * intersects the graph hop with the generation-filtered
+   * metadata candidate set (the LSM, which IS at-generation),
+   * so edges to entities that did not exist at `at_gen` are
+   * dropped by that intersection.
+   */
+  getVerbEndpointsAtGeneration(verbId: string, atGen: bigint): VerbEndpointsResult | null
+  /**
+   * **Diagnostic.** Returns the number of verb-IDs currently
+   * carrying endpoint info. Useful for tests + ops dashboards
+   * (counts how many verbs are "brainy-8.0-ready" vs back-compat
+   * without endpoints).
+   *
+   * At billion-scale this is a single HashMap.len() — O(1).
+   */
+  verbEndpointsCount(): bigint
+  /**
+   * Get neighbor entity ints for an entity.
+   *
+   * `direction`: `"in"`, `"out"`, or `"both"`.
+   *
+   * **Cor 3.0 Piece D**: all entity ids cross as `BigInt` (the
+   * canonical u64 from brainy's `BinaryIdMapper`). Brainy 8.0
+   * handles UUID ↔ int conversion on its side via the same mapper.
+   */
+  getNeighbors(id: bigint, direction: string, limit?: number | undefined | null, offset?: number | undefined | null): Array<bigint>
+  /**
+   * Get verb ints by source entity, filtered by the live-membership
+   * bitmap (tombstone filtering).
+   *
+   * **Cor 3.0 Piece D**: the verbs_source LSM tree carries
+   * `(verb_int, target_int)` pairs. This method extracts the verb_int
+   * from each pair, dedupes (a verb_int can show up under the same
+   * source if multiple add cycles tombstoned and re-added it), then
+   * filters by the membership bitmap.
+   *
+   * The return type is `Vec<BigInt>` of verb ints — brainy 8.0
+   * owns the verb_int ↔ verb_id_string mapping on its side
+   * (cor's `verb_id_namespace` interns via SHA-256 fingerprint
+   * so the original string is unrecoverable from cor).
+   */
+  getVerbIdsBySource(sourceInt: bigint, limit?: number | undefined | null, offset?: number | undefined | null): Array<bigint>
+  /**
+   * Get verb ints by target entity, filtered by the live-membership
+   * bitmap. See [`get_verb_ids_by_source`].
+   */
+  getVerbIdsByTarget(targetInt: bigint, limit?: number | undefined | null, offset?: number | undefined | null): Array<bigint>
+  /**
+   * Get verb ints by source entity, filtered by both the
+   * live-membership bitmap AND the per-`(verb_type, subtype)`
+   * membership bitmap. When `verb_type_index` or `subtype` is
+   * `None` that dimension is unfiltered. Both `None` reduces to
+   * [`get_verb_ids_by_source`](#method.get_verb_ids_by_source).
+   */
+  getVerbIdsBySourceWithSubtype(sourceInt: bigint, verbTypeIndex?: number | undefined | null, subtype?: string | undefined | null, limit?: number | undefined | null, offset?: number | undefined | null): Array<bigint>
+  /**
+   * Get verb ints by target entity, filtered by both the
+   * live-membership bitmap AND the per-`(verb_type, subtype)`
+   * membership bitmap. See
+   * [`get_verb_ids_by_source_with_subtype`](#method.get_verb_ids_by_source_with_subtype).
+   */
+  getVerbIdsByTargetWithSubtype(targetInt: bigint, verbTypeIndex?: number | undefined | null, subtype?: string | undefined | null, limit?: number | undefined | null, offset?: number | undefined | null): Array<bigint>
+  /**
+   * Per-`(verb_type, subtype)` relationship count. Returns the
+   * current value of the `relationship_subtype_counts` slot (0 if
+   * the pair has no entries). Used by brainy 8.0's
+   * `brain.counts.byRelationshipSubtype(verb, subtype)` to read
+   * the native rollup instead of brainy's TS map — same
+   * architectural transition as the noun-side
+   * `getEntityCountByType` already does for noun counts.
+   */
+  getRelationshipSubtypeCount(verbTypeIndex: number, subtype: string): bigint
+  /**
+   * List the distinct subtype values currently observed for the
+   * given verb-type. Order is unspecified. Returns empty when the
+   * verb-type has no subtyped edges.
+   *
+   * Mirrors brainy 7.30's `brain.relationshipSubtypesOf(verb)` —
+   * brainy 8.0 can route the call through cor once the byte-for-
+   * byte JSON parity work lands.
+   */
+  listVerbSubtypes(verbTypeIndex: number): Array<string>
+  /**
+   * **Cor 3.0 Piece D.3 — multi-hop subtype-filtered BFS.**
+   *
+   * Walks the graph starting from `source_int`, expanding through
+   * edges that match `(verb_type_index, subtype)`, up to `depth`
+   * hops, returning the deduplicated set of reachable neighbor ints.
+   *
+   * # Algorithm
+   *
+   * Standard layer-by-layer BFS using the `verbs_source` LSM tree's
+   * new pair value (`(verb_int, target_int)`) — D.2's whole reason
+   * for being. Each frontier `s` queries `verbs_source.get(s)` →
+   * `Vec<(verb_int, target_int)>`; surviving verb_ints (live + matching
+   * the type/subtype filter) contribute their target_int to the next
+   * frontier. A visited HashSet prevents cycle re-traversal.
+   *
+   * # Filter semantics
+   *
+   * - `verb_type_index` is required. Out-of-range indices return
+   *   an empty result (strict — matches `getRelationshipCountByIndex`).
+   * - `subtype = Some(value)`: edges must be in the specific
+   *   `(verb_type, subtype)` PostingList bitmap.
+   * - `subtype = None`: edges must be in SOME subtype bitmap of
+   *   `verb_type_index`. Non-subtyped verbs are excluded — same
+   *   pattern as [`filter_verb_ints_by_subtype`]'s `(Some(ti), None)`
+   *   arm. A future piece can add a per-type "all verbs" bitmap if
+   *   we want non-subtyped edges to participate in BFS.
+   *
+   * # Bounds
+   *
+   * - `depth = 0` returns an empty result (no expansion requested).
+   * - `depth > 0` runs the standard frontier expansion. Each iteration
+   *   processes the previous frontier and builds the next.
+   * - `limit = Some(n)` short-circuits as soon as `n` distinct
+   *   neighbors have been added — partial results in BFS order.
+   * - `source_int` is NEVER included in the result, even if a cycle
+   *   would visit it on a later hop (the visited set guards it from
+   *   the start).
+   */
+  findConnectedSubtype(sourceInt: bigint, verbTypeIndex: number, subtype: string | undefined | null, depth: number, limit?: number | undefined | null): Array<bigint>
+  /**
+   * **Native multi-hop traversal from explicit id seeds (ADR-006 Phase A).**
+   * `seeds` are entity ints (BigInts). The optional trailing
+   * `generation` selects as-of-`g` time-travel (omit for a live read).
+   * See [`traverse_core`] for the traversal semantics and the columnar
+   * [`NativeSubgraph`] result.
+   */
+  traverse(seeds: Array<bigint>, opts: TraverseOptions, generation?: bigint | undefined | null): NativeSubgraph
+  /**
+   * **Native traversal seeded from a `find()`-result `OpaqueIdSet`
+   * (ADR-006 Phase A — the query→expand fusion).**
+   *
+   * The seed node set crosses as cor's opaque, version-tagged id-set
+   * envelope (see [`crate::opaque_id_set`]); brainy forwards it straight
+   * from `find()` without ever materializing the ids in TS, so "find
+   * entities matching X, then everything they're related to" stays one
+   * boundary crossing. Fails loud (`BufferFormatMismatch`) on a
+   * stale/foreign buffer. See [`traverse_core`] for traversal semantics.
+   */
+  traverseFromOpaqueIdSet(seed: Buffer, opts: TraverseOptions, generation?: bigint | undefined | null): NativeSubgraph
+  /**
+   * **Open a streaming graph cursor (ADR-006 Phase B).** Pins a
+   * generation (`options.generation`, else the current generation) and
+   * returns a handle for [`graph_cursor_next`] / [`graph_cursor_close`].
+   * Omit `seeds`/`seeds_opaque` for a whole-graph export; supply them
+   * for an incident-edge export of a seeded region. Pass
+   * `options.cursor` (a prior chunk's resume token) to resume after a
+   * `SnapshotExpired`.
+   */
+  graphCursorOpen(options: GraphCursorOpenOptions): string
+  /**
+   * **Pull the next chunk from an open cursor (ADR-006 Phase B).**
+   * Returns up to `chunk_size` edges (a single high-degree node may
+   * span chunks) plus a resume token. `done: true` once exhausted. A
+   * handle idle past the TTL is reaped and rejected with
+   * `SnapshotExpired` — reopen with the last chunk's token to resume.
+   */
+  graphCursorNext(handle: string, chunkSize: number): NativeGraphCursorChunk
+  /**
+   * **Release a cursor's pinned generation + server-side state
+   * (ADR-006 Phase B).** Idempotent — closing an unknown / already-
+   * closed handle is a no-op. Dropping the registry entry drops its
+   * `PinGuard`, unblocking compaction reclamation of that view.
+   */
+  graphCursorClose(handle: string): void
+  /**
+   * **PageRank over the as-of-`g` graph (ADR-006 Phase C).** Power iteration
+   * with damping, dangling-mass redistribution, L1 convergence. Returns
+   * per-node scores (descending; `top_k` truncates). `excludeVisibility` is
+   * intentionally absent — brainy post-filters on hydrate.
+   */
+  pageRank(options: NativePageRankOptions, generation?: bigint | undefined | null): NativeGraphScores
+  /**
+   * **Connected components over the as-of-`g` graph (ADR-006 Phase C).**
+   * `"weak"` (default) = union-find on the undirected CSR; `"strong"` =
+   * iterative Tarjan (explicit stacks — no recursion) on the directed CSR.
+   */
+  connectedComponents(options: NativeComponentsOptions, generation?: bigint | undefined | null): NativeGraphComponents
+  /**
+   * **Shortest path between two nodes as-of-`g` (ADR-006 Phase C).** BFS
+   * (hops — cor stores no edge weights), bounded by `max_depth`; honors
+   * direction + `verb_types`. `None` when unreachable. No CSR (frontier
+   * walk via `out_edges_at_g`/`in_edges_at_g`).
+   */
+  shortestPath(fromInt: bigint, toInt: bigint, options: NativeShortestPathOptions, generation?: bigint | undefined | null): NativeGraphPath | null
+  /**
+   * **Deterministic, seeded neighborhood sample as-of-`g` (ADR-006 Phase C).**
+   * Bounded BFS from `seeds` (ints or an OpaqueIdSet) with a per-node fanout
+   * cap, depth + node caps; a seeded SplitMix64 (keyed per node) makes a
+   * given `(seeds, opts, seed)` byte-reproducible. Returns a columnar
+   * `NativeSubgraph` (no CSR).
+   */
+  neighborhoodSample(seeds: Array<bigint>, seedsOpaque: Buffer | undefined | null, options: NativeNeighborhoodSampleOptions, generation?: bigint | undefined | null): NativeSubgraph
+  /**
+   * **Top-K nodes by degree as-of-`g` (ADR-006 Phase C).** Degree-only CSR
+   * fast path (no `out_targets`) + a bounded min-heap. `direction` selects
+   * out / in / both degree. Returns per-node degree scores, descending.
+   */
+  topByDegree(options: NativeTopByDegreeOptions, generation?: bigint | undefined | null): NativeGraphScores
+  /**
+   * Track a verb ID without adding to LSM-trees. Used during
+   * rebuild when LSM-trees already have the data on disk.
+   *
+   * Brainy walks its own persisted verbs (which carry their original
+   * verb-type strings + verb-IDs) and calls this once per verb to
+   * repopulate the membership bitmap + per-type counts. The LSM
+   * trees themselves don't need to be touched — they're already
+   * loaded via `loadSstableFromBinary` / `loadSstableFromFile`.
+   *
+   * **Cor 3.0 Piece D**: the legacy `trackVerbIdByIndex` variant
+   * is deleted along with the other strict-index variants. Brainy
+   * 8.0's rebuild calls this with the verb-type string from storage.
+   * The fallback-to-`relatedTo` behavior for unknown strings is
+   * acceptable for rebuild (matches the addVerb-time behavior so
+   * counts converge to the same totals).
+   */
+  trackVerbId(verbId: string, verbType: string): void
+  /**
+   * Clear membership bitmap + relationship counts. Used before
+   * rebuild to ensure clean state. The verb-ID namespace's
+   * interning assignments are intentionally preserved — Piece 12
+   * stability contract: an int once assigned is never reused.
+   * Re-adding the same verb-ID after a clear returns the same
+   * interned id (intern is idempotent), so the bitmap rebuilds to
+   * identical contents.
+   *
+   * **Why this DOESN'T clear endpoints / subtypes / subtype
+   * counts**: the rebuild path (`populateVerbIdSetFromStorage` →
+   * `trackVerbIdByIndex`) walks the LSM trees and re-tracks each
+   * verb. The track call only carries `(verb_id, verb_type_index)`
+   * — it does NOT carry endpoint or subtype info, which only
+   * arrive via explicit `addVerbWithEndpoints` / `addVerbWithSubtype`
+   * calls. So if `clearVerbTracking` flushed endpoints + subtypes,
+   * the rebuild couldn't restore them and the brain would
+   * permanently lose that data.
+   *
+   * The endpoint / subtype state IS managed correctly for
+   * per-verb removes (see [`remove_verb_internal`]) — that path
+   * tombstones the endpoint slot + drops the subtype bitmap entry.
+   * Stale slots that survive a `clear_verb_tracking` rebuild are
+   * invisible to readers because [`get_verb_endpoints`] and the
+   * subtype-filtering paths check the membership bitmap first.
+   * They consume a bit of extra disk for the lifetime of the
+   * orphan; explicit compaction is a future piece.
+   */
+  clearVerbTracking(): void
+  /**
+   * Check if a specific tree's level needs compaction.
+   * `tree_name`: `"source"`, `"target"`, `"verbs-source"`, `"verbs-target"`.
+   */
+  needsCompaction(treeName: string, level: number): boolean
+  /**
+   * Flush a tree's MemTable to binary .sst format (no disk I/O).
+   * Returns binary data for the adapter to persist.
+   */
+  flushTreeToBinary(treeName: string): NativeBinaryFlushResult | null
+  /**
+   * Compact a tree's level to binary .sst format (no disk I/O).
+   * Returns binary data + old IDs for the adapter to handle.
+   */
+  compactTreeToBinary(treeName: string, level: number): NativeBinaryCompactResult | null
+  /**
+   * Mmap an adapter-written file, replacing the matching InMemory
+   * variant with a zero-copy `Mapped` variant.
+   */
+  registerMmapSstable(treeName: string, sstableId: string, level: number, filePath: string): void
+  /**
+   * Load an SSTable from binary `.sst` data (for adapters that
+   * round-trip bytes rather than file paths).
+   */
+  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
+  /** Get manifest JSON for a specific tree. */
+  getManifestJson(treeName: string): string
+  /** Load manifest JSON for a specific tree. */
+  loadManifestJson(treeName: string, json: string): void
+  /** Get SSTable IDs from a tree's manifest. */
+  getManifestSstableIds(treeName: string): Array<string>
+  /** Get the level for an SSTable ID in a tree's manifest. */
+  getManifestSstableLevel(treeName: string, id: string): number | null
+  /** Check if a specific tree's MemTable is empty. */
+  memTableIsEmpty(treeName: string): boolean
+  /**
+   * Total relationship count from the source tree (narrowed u32 —
+   * caps at [`u32::MAX`]; use [`size_big`] at billion scale).
+   */
+  size(): number
+  /**
+   * BigInt sibling of [`size`]. Overflow-safe at billion scale.
+   * Cor 3.0 Piece D widened `LSMTreeCoreU64::total_relationships()`
+   * to u64 (was u32 in the legacy `LSMTreeCore`), so this returns
+   * the full u64 without further widening.
+   */
+  sizeBig(): bigint
+  /**
+   * Number of tracked verb IDs (narrowed u32 — caps at
+   * [`u32::MAX`]; use [`verb_id_count_big`] at billion scale).
+   * Piece 12: reads the Roaring32 membership bitmap's cardinality,
+   * constant-time regardless of the bitmap's contents.
+   */
+  verbIdCount(): number
+  /**
+   * BigInt sibling of [`verb_id_count`]. Returns the full u64
+   * cardinality of the live-verb bitmap — overflow-safe at
+   * billion scale.
+   */
+  verbIdCountBig(): bigint
+  /**
+   * **Batch verb-int reverse resolver** (brainy 8.0 lockstep
+   * `GraphIndexProvider.verbIntsToIds`, handoff L.7).
+   *
+   * Given a batch of `verb_int` BigInts, return the corresponding
+   * canonical UUID string for each — `null` for any int that has
+   * no entry in the namespace's persistent reverse map.
+   *
+   * This is brainy 8.0's single source of truth for "what was this
+   * verb-int's original verb-id?" — brainy keeps only a bounded
+   * in-memory LRU warm cache fed by `addVerb` returns + resolver
+   * hits; the durable mapping lives in cor's `verb-int-to-uuid.bin`
+   * (a direct-indexed sparse file, O(1) random access per lookup).
+   *
+   * **Identity-fingerprint design** (L.7): brainy enforces that
+   * every verb-id is a canonical UUID, so cor's namespace
+   * stores the raw 16 UUID bytes (identity, not a hash). The
+   * reverse lookup format the 16 bytes back to the canonical
+   * lowercase 8-4-4-4-12 hex string — round-trips exactly.
+   *
+   * The in-memory namespace variant doesn't persist a reverse map
+   * (it's transient + test-only); returns `null` for every input
+   * when the namespace is in-memory.
+   */
+  verbIntsToUuids(verbInts: Array<bigint>): Array<string | undefined | null>
+  /**
+   * Get relationship count for a specific type (narrowed u32 — see
+   * [`get_relationship_count_by_type_big`] for the overflow-safe
+   * sibling that does NOT cap at `u32::MAX`).
+   *
+   * Unknown verb-type strings collapse to `VerbType.RelatedTo`'s
+   * counter (brainy contract), so a caller querying a custom type
+   * will see the count of `relatedTo` edges. Use
+   * [`get_relationship_count_by_index`] when you have the
+   * canonical index and want strict semantics.
+   */
+  getRelationshipCountByType(verbType: string): number
+  /**
+   * BigInt sibling of [`get_relationship_count_by_type`]. Returns
+   * the full u64 per-type count. Required at scale: a single hot
+   * verb type ("follows", "likes") in a billion-entity graph can
+   * exceed `u32::MAX` even though the count of distinct types
+   * stays small.
+   */
+  getRelationshipCountByTypeBig(verbType: string): bigint
+  /**
+   * **Piece 12.** Strict count lookup by canonical verb-type index.
+   * Out-of-range indices return `0n` (treated as "no edges of an
+   * unknown type") rather than falling back to the `relatedTo`
+   * slot — strict callers want to see the violation, not silently
+   * read someone else's count.
+   */
+  getRelationshipCountByIndex(verbTypeIndex: number): bigint
+  /**
+   * Get all relationship counts as JSON. Returns a `{type_name:
+   * count}` map keyed by canonical verb-type strings. Zero-count
+   * types are omitted to keep the payload small in sparse graphs
+   * (a brain that only ever uses `follows` shouldn't have 127
+   * entries of zero in its stats).
+   */
+  getAllRelationshipCountsJson(): string
+  /**
+   * Get relationship statistics as JSON. `totalRelationships` is a
+   * u64 (cor 3.0 Piece D widening); JS consumers must parse it
+   * as a string for billion-scale fidelity (BigInt isn't valid 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) consults this right after `init()`:
+   * `true` means the durable cold-load already restored the adjacency, so
+   * brainy SKIPS its O(E) rebuild-from-storage; `false` means the graph is
+   * empty (a fresh brain with nothing persisted) and brainy should build
+   * it.
+   *
+   * **Edges-loaded semantics — never membership.** Returns `true` iff the
+   * graph actually holds edges through a durable or live path: the
+   * cold-load latch (set when an SSTable loads from binary/file, a manifest
+   * names ≥1 SSTable, or a memtable flushes to a persisted SSTable), or a
+   * currently non-empty memtable on any of the four trees. The verb-id
+   * membership bitmap — whose population is the deferred O(N) fast-follow —
+   * is deliberately NOT consulted, so a slow membership walk can never make
+   * a graph with queryable edges report "not ready".
+   */
+  isReady(): boolean
+  /**
+   * Get comprehensive statistics. Both the legacy u32 fields and
+   * the Piece-10 BigInt sibling fields are populated; callers
+   * should prefer the `*_big` fields at billion scale and treat
+   * the u32 fields as best-effort summaries that cap at
+   * [`u32::MAX`].
+   */
+  getStats(): GraphAdjacencyStats
+  /** List all tree names (for iteration in TS wrapper) */
+  treeNames(): Array<string>
+  /**
+   * **Piece B.** Wire width of the verb-ID interning namespace +
+   * the live-verb / per-`(type, subtype)` membership bitmaps.
+   * Returns `"U32"` (cortex 2.x-compatible, ~4.29 B verb-ID
+   * ceiling) or `"U64"` (cor 3.0, ~1.8 × 10^19 verb-ID
+   * ceiling).
+   *
+   * JS callers introspect this for diagnostics — e.g. a brainy 8.0
+   * `brain.diagnostics()` panel showing whether the brain is on
+   * the wide wire width. Set at construction via
+   * [`GraphAdjacencyConfig::verb_id_space`]; immutable for the
+   * life of the index.
+   */
+  verbIdSpace(): string
+}
+
+/** napi-exposed engine. */
+export declare class NativeLsmEngine {
+  /** Construct a fresh engine. */
+  constructor(options?: NativeLsmEngineOptions | undefined | null)
+  /**
+   * Construct an engine and seed the epoch counter from an existing
+   * manifest. Used on engine restart so new mutations always outrank
+   * every persisted epoch.
+   */
+  static openWithManifest(manifestJson: string, options?: NativeLsmEngineOptions | undefined | null): NativeLsmEngine
+  /**
+   * **Piece 7.** Construct an engine whose memtable is backed by
+   * mmap'd per-shard append logs under `dir/memtable/`. On open,
+   * every surviving record in each shard's log replays into the
+   * BTreeMap before the engine accepts new writes — so a process
+   * crash between inserts and the next `flush()` is recovered
+   * transparently. Optionally seeds the epoch counter from a
+   * manifest (when reopening alongside persisted SSTables); when
+   * omitted, the post-replay epoch is `max(log_max_epoch) + 1`.
+   */
+  static openWithDir(dir: string, manifestJson?: string | undefined | null, options?: NativeLsmEngineOptions | undefined | null): NativeLsmEngine
+  /**
+   * G4.2 redo step 3: snapshot-replay opener. Equivalent to
+   * [`openWithDir`](Self::open_with_dir) except every shard's
+   * memtable log replay filters records to
+   * `generation <= atGeneration`. The caller supplies the
+   * brainy snapshot generation from the snapshot's manifest;
+   * any post-snapshot writes that leaked through the
+   * hard-linked active-log inode are excluded.
+   *
+   * Use this when opening cor against a brainy
+   * `db.persist()` snapshot directory; use `openWithDir`
+   * (no filter) for live-restart recovery where every
+   * durable record must replay regardless of generation.
+   */
+  static openWithDirAtGeneration(dir: string, atGeneration: bigint, manifestJson?: string | undefined | null, options?: NativeLsmEngineOptions | undefined | null): NativeLsmEngine
+  /**
+   * **Piece 7.** Whether this engine's memtable is backed by
+   * persistent logs (i.e. constructed via
+   * [`openWithDir`](#method.open_with_dir)). Diagnostic surface
+   * for tests + brainy callers wanting to confirm the durability
+   * path is wired.
+   */
+  isPersistent(): boolean
+  /**
+   * **Piece 7.** Advance the flush watermark on every shard's
+   * memtable log so records with `epoch <= throughEpoch` are
+   * dropped from future replay. The wrapper calls this AFTER it
+   * has durably persisted the SSTable bytes returned by the
+   * preceding `flush()` — at that point the data is in two
+   * places (the log + the persisted SSTable) and the log copy
+   * is safe to retire.
+   *
+   * No-op for in-memory engines (constructed without
+   * `openWithDir`).
+   */
+  commitFlushThrough(throughEpoch: bigint): void
+  /** `"u32"` or `"u64"`. */
+  idSpace(): string
+  /**
+   * Add an entity int to `(field, value)`. JS `number` path; throws
+   * on U64 mode if you exceed `Number.MAX_SAFE_INTEGER`. Prefer
+   * [`insert_big`](Self::insert_big) for U64 mode.
+   *
+   * **G4.2 redo**: optional `generation` argument carries the
+   * caller's MVCC generation. When omitted (the historical
+   * signature), the record is tagged with generation = 0 —
+   * the no-coordination default that matches every
+   * `at_generation >= 0` snapshot replay filter. Brainy
+   * callers can flip the field on when their Phase 3b
+   * generation plumbing is ready; cor's behaviour is
+   * unchanged for callers that don't pass it.
+   */
+  insert(field: string, value: string, intId: number, generation?: bigint | undefined | null): void
+  /** BigInt variant of [`insert`](Self::insert). */
+  insertBig(field: string, value: string, intId: bigint, generation?: bigint | undefined | null): void
+  /**
+   * Tombstone an entity int at `(field, value)`. See
+   * [`insert`](Self::insert) re the optional `generation` arg.
+   */
+  delete(field: string, value: string, intId: number, generation?: bigint | undefined | null): void
+  /** BigInt variant of [`delete`](Self::delete). */
+  deleteBig(field: string, value: string, intId: bigint, generation?: bigint | undefined | null): void
+  /** Drain the memtable. Returns `null` if there was nothing to flush. */
+  flush(): NativeLsmFlushResult | null
+  /**
+   * Update the budget ceiling. Phase 6's ResourceManager subscriber
+   * drives this from the TS wrapper layer. Pass `Number.MAX_SAFE_INTEGER`
+   * or higher (mapped to `u64::MAX`) to disable admission control.
+   */
+  setAllowedBytes(bytes: bigint): void
+  /** Current budget ceiling as `bigint`. */
+  allowedBytes(): bigint
+  /** Memtable footprint estimate. */
+  memtableBytes(): bigint
+  /**
+   * Bytes currently reserved by in-flight inserts (the atomic
+   * admission counter). Diagnostic / telemetry — production code
+   * usually queries [`isOverAdmissionThreshold`](Self::is_over_admission_threshold)
+   * which already includes this value.
+   */
+  reservedBytes(): bigint
+  /**
+   * **Test-only** harness exposing the engine's internal multi-
+   * thread admission stress: spawn `nThreads` real OS threads, each
+   * performing `perThread` inserts, with a background flusher
+   * running at a 50% trigger. Returns `{ peakMemtableBytes,
+   * nBlocked }`.
+   *
+   * The atomic admission invariant is verified externally by the
+   * caller: `peakMemtableBytes ≤ budget × 1.05`. The 5% margin
+   * covers the in-flight reservations during the burst. With the
+   * pre-fix soft threshold, the same workload would observe peaks
+   * well above 2× budget under heavy contention.
+   */
+  _testStressConcurrentAdmission(nThreads: number, perThread: number, budget: bigint): NativeLsmStressResult
+  /** Distinct `(field, value)` keys currently buffered. */
+  memtableEntryCount(): bigint
+  /** Next epoch the engine will allocate. */
+  currentEpoch(): bigint
+  /** Whether the next insert would block on admission control. */
+  isOverAdmissionThreshold(): boolean
+  /**
+   * **Test-only** — probe an SSTable's bloom filter directly.
+   * Returns the fraction of `(field, value)` probes the bloom
+   * rejected (a value in `[0.0, 1.0]`). Used by the Phase 4
+   * closeout A1 test to prove the bloom short-circuit is wired:
+   * for keys NEVER inserted into the SSTable, the rejection
+   * fraction should approach 1.0 (modulo the bloom's false-
+   * positive rate, ~1% at 10 bits/element). For keys that ARE in
+   * the SSTable, the fraction should be 0.0 (bloom must never
+   * false-negative).
+   *
+   * Accepts a single SSTable Buffer and a list of `(field, value)`
+   * pairs to probe.
+   */
+  _testBloomRejectionRate(sstable: Buffer, field: string, values: Array<string>): number
+  /**
+   * **Test-only** — whether the SSTable has a bloom filter wired.
+   * Used by the Phase 4 closeout test to assert that `emitBloom:
+   * true` actually produces a reader with a bloom (and that
+   * `emitBloom: false` does not).
+   */
+  _testHasBloom(sstable: Buffer): boolean
+  /**
+   * Read a posting list for `(field, value)` across the live
+   * memtable + the supplied SSTable bytes.
+   *
+   * SSTables are looked up through the engine's content-keyed
+   * LRU reader cache. The first call for a given SSTable pays
+   * the full parse + SHA-256 + bloom-deserialization cost;
+   * subsequent calls return the cached parsed reader after a
+   * re-verification SHA-256 over the candidate body (forge-proof,
+   * per A4 INV-1).
+   *
+   * Returns the merged posting list as croaring portable bytes.
+   * The TS wrapper materializes them via
+   * `NativeRoaringBitmap32.deserialize` (U32 mode) or
+   * `NativeRoaringBitmap64.deserialize` (U64 mode). Returns an
+   * empty Buffer when no entries match (NOT null — an empty
+   * PostingList is the correct semantic "no matches").
+   *
+   * Each `sstable` Buffer MUST be a complete, undamaged SSTable
+   * produced by [`flush`](Self::flush) (or a Phase 5 compaction).
+   * SHA-256 mismatches throw.
+   */
+  readPostingList(field: string, value: string, sstables: Array<Buffer>): Buffer
+  /**
+   * Zero-copy variant of [`read_posting_list`]: SSTables are
+   * opened directly from filesystem paths via `mmap`. The body
+   * bytes live in the OS page cache (`RssFile`, kernel-reclaimable)
+   * and do NOT grow process anonymous RSS — the production path
+   * for billion-entity scale where SSTables exceed RAM.
+   *
+   * Identical semantics to [`read_posting_list`] otherwise:
+   * memtable + SSTable merge, returns the merged PostingList as
+   * croaring portable bytes.
+   *
+   * Path strings MUST be UTF-8. Cor stores SSTables under
+   * sha256-hex names so this is not a practical limitation
+   * (per spec test #25 + minor concern #11).
+   */
+  readPostingListFromPaths(field: string, value: string, paths: Array<string>): Buffer
+  /**
+   * Open an SSTable from the given filesystem path through the
+   * reader cache (mmap zero-copy). The cache retains its own
+   * `Arc<LsmSstableReader>`; the next `readPostingListFromPaths`
+   * for the same path hits the warm cache without re-stat'ing
+   * the file beyond the path_hint validation.
+   *
+   * Idempotent: repeated calls for the same path are warm-cache
+   * hits and do not re-validate SHA-256.
+   */
+  openSstablePath(path: string): void
+  /**
+   * Open the SSTable at `path` through the reader cache (mmap +
+   * SHA-256 verify) and register the resulting reader into the
+   * engine's live-SSTable set, so every subsequent read snapshot
+   * includes it. Distinct from [`open_sstable_path`], which only
+   * warms the evictable reader cache without growing the live set.
+   *
+   * The TS wrapper calls this on cold start (once per manifest
+   * SSTable entry) and after each flush, AFTER the `.sst` bytes and
+   * the manifest entry that references them are durably persisted.
+   */
+  registerSstablePath(path: string): void
+  /**
+   * Number of SSTable readers currently in the engine's live set.
+   * Diagnostic used by the integration tests to assert that a
+   * `flush` + `registerSstablePath` cycle actually grew the read
+   * view.
+   */
+  liveSstableCount(): number
+  /**
+   * Phase 5 hook (exposed now for A5 test coverage of INV-A5-12):
+   * drops the path_hint + cache entry for the given path WITHOUT
+   * invalidating snapshot Arcs already handed out. The caller may
+   * `unlink(path)` after this returns; held Arc clones continue
+   * to serve reads from the unlink'd mmap until the last reader
+   * drops, per POSIX unlink-while-mapped semantics.
+   */
+  evictReaderCacheByPath(path: string): void
+  /**
+   * Combined native memory footprint reported to ResourceManager
+   * (memtable + reader cache). See `LsmEngine::native_memory_bytes`.
+   */
+  nativeMemoryBytes(): bigint
+  /**
+   * **Test-only.** Cache hit counter — incremented on every
+   * `get_or_open` that returns a previously-inserted entry.
+   */
+  _testReaderCacheHits(): bigint
+  /**
+   * **Test-only.** Cache miss counter — incremented when a parse
+   * + insert occurs. Passthrough mode (sub-floor budget) does NOT
+   * increment.
+   */
+  _testReaderCacheMisses(): bigint
+  /** **Test-only.** Current resident bytes across cached entries. */
+  _testReaderCacheBytes(): bigint
+  /** **Test-only.** Current cache budget after the INV-8 clamp. */
+  _testReaderCacheBudget(): bigint
+  /** **Test-only.** Number of cached entries. */
+  _testReaderCacheLen(): number
+  /**
+   * **Test-only.** Wipes every cached entry. Snapshots holding
+   * Arc clones survive.
+   */
+  _testReaderCacheClear(): void
+  /**
+   * **Test-only.** Delta of `LsmSstableReader::open()` invocations
+   * since this engine's cache was constructed. Used to prove the
+   * cache short-circuits repeat parses without wall-clock
+   * measurements (replaces the flaky perf test from earlier drafts).
+   */
+  _testReaderCacheOpenInvocations(): bigint
+  /**
+   * **Test-only.** Current pinned overshoot (bytes by which
+   * pinned entries exceed the budget). Cleared after eviction
+   * succeeds.
+   */
+  _testReaderCachePinnedOvershootBytes(): bigint
+  /**
+   * **Test-only.** Highest pinned overshoot ever observed
+   * (diagnostic high-water mark).
+   */
+  _testReaderCachePinnedOvershootHighWater(): bigint
+  /**
+   * **Test-only.** Number of SHA-256 walks the cache has executed
+   * across all entry points. Bumped on the Buffer-path body re-hash
+   * (every `readPostingList` call) and on the mmap cold path
+   * (`openSstablePath` / `readPostingListFromPaths` miss). Warm
+   * mmap hits do NOT bump it — that's the observable the A5
+   * closeout gate uses to prove the warm path skipped validation
+   * (spec test #13).
+   */
+  _testReaderCacheSha256Walks(): bigint
+  /**
+   * **Test-only.** Whether the reader for the given path is mmap-
+   * backed (`true`) or heap-resident (`false`). Used by A5 spec
+   * tests #15 + #16 (variant-of-winner accounting) and #19 + #20
+   * (RSS contribution check). Returns `false` if the path is not
+   * in the cache.
+   */
+  _testReaderCacheIsMmap(path: string): boolean
+  /**
+   * **Test-only.** Measure writer throughput at `nWriters`
+   * concurrent threads. Closes P3-1 (≥ 4× speedup from N=1 to
+   * N=16). Returns `{elapsedNs, totalInserts}`; the caller
+   * computes inserts/sec.
+   */
+  _testWriterThroughput(nWriters: number, perWriter: number): NativeLsmThroughputResult
+  /**
+   * **Test-only.** Per-insert latency distribution under
+   * admission pressure. Closes P3-2 (admission p99 ≤ 200 ms).
+   * Returns the SORTED distribution in MICROSECONDS so the
+   * caller can compute any percentile.
+   */
+  _testAdmissionLatencyDistribution(nWriters: number, perWriter: number, budget: bigint): Array<bigint>
+  /**
+   * **Test-only.** Measure SSTable flush throughput including
+   * write + fsync to a real filesystem path. Closes P3-4
+   * (≥ 150 MB/s on NVMe).
+   */
+  _testFlushThroughputWithFsync(targetPayloadMb: number, path: string): NativeLsmFlushThroughputResult
+  /**
+   * **Test-only.** Drive concurrent readers + writers + a
+   * flusher to validate snapshot point-in-time isolation under
+   * contention. Closes Phase 3 gate P3-3 + Phase 4 gate P4-4.
+   *
+   * Workers run on real OS threads (`std::thread`) so the CAS +
+   * mutex contention paths are actually exercised. The hard
+   * invariant: `torn_reads == 0` — a snapshot's cardinality for
+   * its target key must NEVER change for the snapshot's lifetime,
+   * regardless of concurrent writes or flushes.
+   */
+  _testStressReaderWriterFlusher(nReaders: number, readsPerReader: number, nWriters: number, writesPerWriter: number, nPreloadKeys: number, flushIntervalMicros: number): NativeLsmReaderWriterStressResult
+  /**
+   * Walk every directory entry in an SSTable in sorted `(field,
+   * value)` order, returning one summary per entry. This is the
+   * production-quality SSTable inspection API: useful for
+   * diagnostics, manifest validation, backup verification,
+   * migration tooling, and dump-and-reload flows.
+   *
+   * Each summary carries:
+   *   - `field` / `value` — the directory key
+   *   - `additionsBytes` / `deletionsBytes` — croaring portable
+   *     serializations of the per-entry PostingLists (deserialize
+   *     with `NativeRoaringBitmap32` in U32 mode or
+   *     `NativeRoaringBitmap64` in U64 mode)
+   *   - `additionCount` / `deletionCount` — cardinalities
+   *     (cheaper to consume than re-deserializing the Buffers)
+   *   - `epoch` — the SSTable's per-entry epoch
+   *   - `isTombstone` — `true` when the entry is a pure delete
+   *
+   * SHA-256 + bloom + length checks all run inside the cache (or
+   * `open` on miss), so a malformed Buffer throws before any
+   * entry is materialized.
+   */
+  scanSstable(sstable: Buffer): Array<NativeLsmScanEntry>
+  /**
+   * Take a point-in-time snapshot of the engine for reading.
+   * The returned handle holds Arc clones of the memtable shards +
+   * the supplied SSTable readers (opened through the content-keyed
+   * reader cache). Reads through this handle are valid for up to
+   * 30 seconds from creation; after that the snapshot returns
+   * `SnapshotExpired` errors and the caller must re-acquire.
+   *
+   * The 30-second lifetime is hardcoded per the zero-config
+   * mandate — operator knobs introduce footgun surface for almost
+   * no benefit. See [`SNAPSHOT_LIFETIME`](super::snapshot::SNAPSHOT_LIFETIME).
+   */
+  takeSnapshot(sstables: Array<Buffer>): NativeLsmSnapshot
+}
+
+/**
+ * A point-in-time read handle on an `LsmEngine`. Cheap to clone
+ * (`Arc<LsmSnapshotInner>` internally). Reads return
+ * `SnapshotExpired` after the 30-second lifetime; callers re-acquire
+ * via [`NativeLsmEngine::take_snapshot`].
+ *
+ * The snapshot model mirrors LMDB read transactions: writes happen
+ * against the live engine while the snapshot continues to see the
+ * memtable + SSTable state at the moment of acquisition.
+ */
+export declare class NativeLsmSnapshot {
+  /**
+   * Read the posting list for `(field, value)` at this snapshot's
+   * point in time. Throws `SnapshotExpired` if the snapshot was
+   * created more than 30 seconds ago.
+   */
+  readPostingList(field: string, value: string): Buffer
+  /**
+   * Whether the snapshot has aged past its 30-second lifetime.
+   * Returns `true` once it is no longer usable for reads.
+   */
+  isExpired(): boolean
+  /** Number of SSTables this snapshot holds (diagnostic). */
+  sstableCount(): number
+}
+
+/**
+ * NativeMetadataIndex — napi wrapper for the Rust metadata index.
+ *
+ * All query and mutation operations execute synchronously in Rust against
+ * the attached LSM engine. The TS wrapper handles async storage I/O (the LSM
+ * SSTable/manifest durability, the value-enumeration field indexes, and the
+ * field registry).
+ */
+export declare class NativeMetadataIndex {
+  /**
+   * Create a new metadata index with optional configuration.
+   *
+   * `idSpace` opts into the entity-int wire width: `"u32"` (the
+   * brainy 7.x-compatible 4.29 B-capped mode) or `"u64"` (cor
+   * 3.0 billion-scale mode). Omitted defaults to U32 at the
+   * raw napi surface to keep this constructor's API stable;
+   * production callers (`MetadataIndexManager` in
+   * `src/utils/NativeMetadataIndex.ts`) pass `"u64"` explicitly
+   * per the cor 3.0 zero-config production default. Every
+   * chunk created via the mutate path inherits this brain's
+   * IdSpace so the entire index stays variant-consistent.
+   */
+  constructor(configJson?: string | undefined | null, idSpace?: string | undefined | null)
+  /**
+   * IdSpace as a string — `"u32"` or `"u64"`. Mirrors the field on
+   * [`MetadataIndexCore`].
+   */
+  idSpace(): string
+  /**
+   * **The durable-engine swap.** 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 calls this once during
+   * `init()` (after seeding the engine's epoch from the on-disk manifest)
+   * to swap in the persistent engine before any mutation.
+   *
+   * The engine's `IdSpace` MUST match the metadata index's (both
+   * `"u32"` or both `"u64"`) — a mismatch would corrupt the
+   * `PostingList` algebra at the LSM ↔ metadata boundary. The
+   * method rejects mismatched pairings with an explicit error.
+   *
+   * The previous engine's Arc is released on replacement (its memtable +
+   * reader cache stay alive as long as anyone else holds an Arc). The
+   * index always has a working engine, so there is no "detached" state.
+   */
+  setLsmEngine(engine: NativeLsmEngine): 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 tests
+   * + TS-side telemetry that assert the dispatch is engaged.
+   */
+  isLsmEnabled(): boolean
+  /**
+   * **#72 Phase C.** Inject the shared mmap `BinaryIdMapper` as this
+   * metadata index's canonical UUID ↔ entity-int allocator. The napi
+   * core is constructed with no storage path (the `id_mapper` starts
+   * empty); the TS layer derives the `_id_mapper/*` paths from
+   * storage, builds the mapper, and calls this once during `init()`
+   * before any mutation, and again (with a freshly-`create`d, i.e.
+   * truncated, mapper) at the start of a full rebuild.
+   *
+   * The mapper's `IdSpace` MUST match the metadata index's (both
+   * `"u32"` or both `"u64"`) — a mismatch would corrupt the
+   * `PostingList` algebra, which keys bitmaps by the int this mapper
+   * assigns. Rejected with an explicit error.
+   *
+   * This replaces the legacy JSON entity-id-mapper path
+   * (`loadEntityIdMapper` / `saveEntityIdMapper`), whose two resident
+   * HashMaps cost ~56 GB at 1 B entities and whose serialize/parse
+   * threw at the V8 ~512 MB / ~13 M-UUID cliff.
+   */
+  setIdMapper(mapper: NativeBinaryIdMapper): void
+  /**
+   * Get entity ID mapper size (saturates at u32::MAX; use
+   * [`entity_id_mapper_size_big`] for the overflow-safe BigInt
+   * sibling).
+   */
+  entityIdMapperSize(): number
+  /**
+   * BigInt sibling of [`entity_id_mapper_size`]. Overflow-safe at
+   * billion scale; preferred by brainy 8.0 consumers.
+   */
+  entityIdMapperSizeBig(): bigint
+  /**
+   * **Piece 6 generation counter — accessor.** Returns the current
+   * generation as a BigInt (u64). Bumped by every read-visible
+   * mutation (`add_to_index` / `remove_from_index`). The TS
+   * wrapper caches the last-seen value and compares on every
+   * query; an observed bump invalidates `loadedFields` so the
+   * next query re-reads the current state.
+   *
+   * Cheap call: a single atomic `load(Acquire)` — fine to invoke
+   * before every read without measurable overhead.
+   */
+  currentGeneration(): bigint
+  /**
+   * **Piece 15 — per-field generation accessor.** Returns the
+   * current generation for a single field as a BigInt (u64).
+   * Bumped by every mutation in `add_to_index` / `remove_from_index`
+   * that touches the field's data. Returns `0n` for fields that
+   * have never been registered (the cold-boot semantic — a TS
+   * reader probing a never-seen field gets `0n` and records it
+   * without invalidating anything).
+   *
+   * Brainy 8.0+ wrappers use this to ask "did field X change since
+   * I last looked?" without invalidating every loaded field on
+   * every mutation. The index-wide
+   * [`currentGeneration`](#method.current_generation) still
+   * bumps on every mutation — brainy 7.x callers keep working
+   * unchanged.
+   *
+   * Cheap call: HashMap lookup + atomic `load(Acquire)` — fine to
+   * invoke per-field on every read entry point. See `MetadataIndexCore::
+   * field_generation` for the memory-ordering rationale.
+   */
+  fieldGeneration(field: string): bigint
+  /**
+   * Resolve an entity's integer id from its UUID (no assignment). Used to
+   * populate the column store after `add_to_index` has assigned the id, and
+   * to locate an entity on removal. O(1).
+   */
+  uuidToInt(uuid: string): number | null
+  /**
+   * BigInt sibling of [`uuid_to_int`]. Works for both U32 and U64
+   * brains; preferred by brainy 8.0 consumers.
+   */
+  uuidToIntBig(uuid: string): bigint | null
+  /**
+   * Resolve a UUID from an entity's integer id. Backs `getIdMapper().getUuid`
+   * for the `orderBy` path. O(1).
+   */
+  intToUuid(intId: number): string | null
+  /**
+   * BigInt sibling of [`int_to_uuid`]. Works for both U32 and U64
+   * brains.
+   */
+  intToUuidBig(intId: bigint): string | null
+  /**
+   * Batch-resolve UUIDs from integer ids (skips unknown ids). Backs
+   * `getIdMapper().intsIterableToUuids` for paginating sorted results.
+   */
+  intsToUuids(ints: Array<number>): Array<string>
+  /**
+   * BigInt sibling of [`ints_to_uuids`]. Accepts a Vec<BigInt> so
+   * the dispatch is uniform across U32 and U64 brains.
+   */
+  intsToUuidsBig(ints: Array<bigint>): Array<string>
+  /** Load field registry from JSON string. */
+  loadFieldRegistry(json: string): void
+  /** Save field registry to JSON string. */
+  saveFieldRegistry(): string
+  /** Load a field index from JSON string. */
+  loadFieldIndex(field: string, json: string): void
+  /** Save a field index to JSON string. */
+  saveFieldIndex(field: string): string | null
+  /** Get IDs for a single field-value pair. */
+  getIds(field: string, valueJson: string): Array<string>
+  /**
+   * Count IDs for a single field-value pair WITHOUT materializing the UUID
+   * strings. Equals `get_ids(field, value).length` exactly (counts only
+   * mapped ints), but allocates nothing — the count-only fast path used by
+   * `NativeMetadataIndex` at 10B scale (#78 pt2). Returned as i64 (napi has
+   * no u64); counts are non-negative and well under 2^53.
+   */
+  getIdsCount(field: string, valueJson: string): number
+  /**
+   * Get IDs for a filter expression.
+   *
+   * - `all_ids_json`: optional JSON array of all entity IDs (needed for
+   *   ne/exists:false).
+   * - `limit` / `offset`: optional **page bound** (#75). When `limit` is
+   *   supplied, only the `[offset, offset + limit)` window of the sorted
+   *   match set is produced — the posting-list → UUID conversion
+   *   short-circuits at `offset + limit` mapped ids instead of
+   *   materializing the full list and slicing, removing the O(N) FFI
+   *   marshal for broad-filter single-page `find()` at billion scale. This
+   *   is the producer half of brainy's
+   *   `MetadataIndexProvider.getIdsForFilter(filter, {limit, offset})`
+   *   contract; brainy passes `{limit: pageEnd, offset: 0}` and re-windows
+   *   the prefix itself. Omitting `limit` returns the FULL match set
+   *   (cortex 2.x back-compat).
+   */
+  getIdsForFilter(filterJson: string, allIdsJson?: string | undefined | null, limit?: number | undefined | null, offset?: number | undefined | null): Array<string>
+  /**
+   * Cumulative count of id-mapper resolutions performed by the filter
+   * producer ([`get_ids_for_filter`](#method.get_ids_for_filter)) since
+   * construction (#75 observability).
+   *
+   * The page-bounded path keeps this at `offset + limit` per call instead
+   * of the full match cardinality — so a delta after a windowed call proves
+   * the producer short-circuited at production time rather than
+   * materializing the whole list then slicing. Returned as i64 (napi has no
+   * u64); monotonic and well under 2^53 in practice.
+   */
+  filterIdsResolved(): number
+  /** Get IDs for multiple field-value pairs (AND intersection). */
+  getIdsForMultipleFields(pairsJson: string): Array<string>
+  /** Get IDs for a range query on a field. */
+  getIdsForRange(field: string, minJson: string | undefined | null, maxJson: string | undefined | null, includeMin: boolean, includeMax: boolean): Array<string>
+  /** Get IDs for a text query. Returns JSON array of {id, matchCount}. */
+  getIdsForTextQuery(queryStr: string): string
+  /** Get all unique values for a field (for filter discovery). */
+  getFilterValues(field: string): Array<string>
+  /** Get all indexed field names (for filter discovery). */
+  getFilterFields(): Array<string>
+  /** Extract field names from entity JSON (for lazy loading). */
+  extractFieldNames(entityJson: string): Array<string>
+  /** Add an entity to the index. Returns MutationResult JSON. */
+  addToIndex(id: string, entityJson: string): string
+  /** Remove an entity from the index. Returns MutationResult JSON. */
+  removeFromIndex(id: string, metadataJson?: string | undefined | null): string
+  /**
+   * **Brainy rc.6 cold-open self-heal (matrix 7.7).** An O(1)-ish
+   * consistency probe brainy calls ONCE on the first read; on `false` it
+   * runs `detectAndRepairCorruption()`.
+   *
+   * The check is fully internal — it needs NO entity re-read. It samples a
+   * bounded set of fields (`noun` first — the canonical single-valued type
+   * field — then a few others, skipping the inherently multi-valued
+   * `__words__` text index), draws a bounded sample of ints from each
+   * field's value buckets, and counts how many buckets each sampled int
+   * occupies. A single-valued field carrying a phantom shows the tell-tale
+   * MIX of single-bucket ints (the healthy majority) AND ≥1 multi-bucket
+   * int (the phantom) → returns `false`. A field whose sampled ints are
+   * UNIFORMLY multi-bucket is genuinely multi-valued (e.g. `tags`) and is
+   * NOT flagged, so the probe does not false-positive on array fields.
+   *
+   * Panic-free and never throws: returns `true` on an empty index or when
+   * no field is confidently inconsistent. The TS wrapper additionally wraps
+   * the call so any error degrades to `true` — a probe must never break the
+   * read path.
+   */
+  probeConsistency(): boolean
+  /**
+   * **Phantom triad — state-level scan (matrix 7.8b).** Find every
+   * query-visible int that sits in MORE THAN ONE value bucket of a field —
+   * the cross-bucket phantom signature — and return them as a JSON array of
+   * `{ uuid, field }` for the TS wrapper to repair against each entity's
+   * stored value(s).
+   *
+   * Enumerates each field's value buckets from the value-enumeration
+   * surface (`field_indexes`) and counts per-int bucket membership through
+   * the LSM snapshot. The inherently multi-valued `__words__` text index is
+   * skipped. Only ints the id mapper still resolves to a UUID are returned:
+   * an unmapped int is invisible to `getIds` (it cannot produce a wrong
+   * result), so it needs no repair. `max_candidates` (0 = unlimited) caps
+   * the result so a massively corrupt index can be handled by the wrapper's
+   * rebuild fallback instead of an unbounded list. This is the heavyweight
+   * repair path — only reached after `probeConsistency()` flagged the index.
+   */
+  detectCrossBucketPhantoms(maxCandidates: number): string
+  /**
+   * **Phantom triad — state-level purge (matrix 7.8b).** Tombstone the
+   * entity `uuid`'s int out of every value bucket of `field` EXCEPT the
+   * buckets matching its CURRENT stored value(s), supplied as a JSON array
+   * in `current_values_json` (brainy's source of truth, read from storage by
+   * the wrapper — never from the index being repaired).
+   *
+   * The raw values are normalized exactly as `add_to_index` would, forming
+   * the `keep` set, then [`mutate::evict_stale_postings`] removes the rest.
+   * An empty `current_values_json` (entity gone, or the field dropped)
+   * evicts the int from EVERY bucket of the field — purging an orphan
+   * phantom entirely. Returns `true` if any stale posting was tombstoned.
+   * Unmapped `uuid` (already removed) is a no-op returning `false`.
+   */
+  repairEntityFieldPhantom(uuid: string, field: string, currentValuesJson: string): boolean
+  /** Get entity count by type name. */
+  getEntityCountByType(typeName: string): number
+  /** Get total entity count. */
+  getTotalEntityCount(): number
+  /** Get top N noun types by count. Returns JSON. */
+  getTopNounTypes(n: number): string
+  /** Get top N verb types by count. Returns JSON. */
+  getTopVerbTypes(n: number): string
+  /** Get comprehensive statistics. Returns JSON. */
+  getStats(): string
+  /** Clear all in-memory state. */
+  clear(): void
+}
+
+/**
+ * A trained PQ codebook.
+ *
+ * Contains M×ksub centroids, each of dimension dsub = dim/M.
+ * Stored as a flat f32 array: centroids[m][k][d] = data[m * ksub * dsub + k * dsub + d]
+ */
+export declare class NativePqCodebook {
+  /** Create a PQ codebook. Use `NativePQCodebook.train()` or `NativePQCodebook.deserialize()` instead. */
+  constructor()
+  /**
+   * Train a PQ codebook from a set of training vectors.
+   *
+   * Parameters:
+   * - vectors: training data (flat array, each vector is `dim` f64 values)
+   * - dim: vector dimension
+   * - m: number of subspaces (must divide dim evenly)
+   * - ksub: centroids per subspace (typically 256)
+   * - iterations: k-means iterations (typically 20-50)
+   */
+  static train(vectors: Array<number>, dim: number, m: number, ksub: number, iterations: number): NativePqCodebook
+  /**
+   * Encode a single vector to a PQ code (M bytes).
+   *
+   * Each byte is the index of the nearest centroid in the corresponding subspace.
+   */
+  encode(vector: Array<number>): Buffer
+  /**
+   * Encode multiple vectors to PQ codes.
+   * Returns flat buffer: n * m bytes.
+   */
+  encodeBatch(vectors: Array<number>, dim: number): Buffer
+  /** Decode a PQ code back to an approximate vector. */
+  decode(code: Buffer): Array<number>
+  /**
+   * Precompute the ADC (Asymmetric Distance Computation) lookup table.
+   *
+   * Returns a flat f64 array of m * ksub distances.
+   * table[sub_idx * ksub + k] = squared distance from query subvector to centroid k.
+   */
+  computeAdcTable(query: Array<number>): Array<number>
+  /**
+   * Compute approximate distance from a precomputed ADC table to a single PQ code.
+   *
+   * Returns squared Euclidean distance (sum of M table lookups).
+   */
+  distanceAdc(table: Array<number>, code: Buffer): number
+  /**
+   * Batch compute ADC distances from a precomputed table to multiple PQ codes.
+   *
+   * codes: flat buffer of n * m bytes.
+   * Returns n distances.
+   */
+  distanceAdcBatch(table: Array<number>, codes: Buffer, n: number): Array<number>
+  /**
+   * Serialize the codebook to a binary format for persistence.
+   *
+   * Format: [m:u32][ksub:u32][dsub:u32][dim:u32][centroids:f32×(m×ksub×dsub)]
+   */
+  serialize(): Buffer
+  /** Deserialize a codebook from binary format. */
+  static deserialize(data: Buffer): NativePqCodebook
+  /** Get codebook parameters. */
+  get params(): PQParams
+}
+export type NativePQCodebook = NativePqCodebook
+
+/** Native roaring bitmap (drop-in replacement for roaring-wasm RoaringBitmap32). */
+export declare class NativeRoaringBitmap32 {
+  /** Create a new empty bitmap, or from an array of u32 values. */
+  constructor(values?: Array<number> | undefined | null)
+  /** Number of values in the bitmap. */
+  get size(): number
+  /** Whether the bitmap is empty. */
+  get isEmpty(): boolean
+  /** Add a value to the bitmap. */
+  add(value: number): void
+  /** Remove a value from the bitmap (called `delete` in roaring-wasm API). */
+  delete(value: number): void
+  /** Add a value, return true if it was newly added (false if already present). */
+  tryAdd(value: number): boolean
+  /** Check if the bitmap contains a value. */
+  has(value: number): boolean
+  /** Convert bitmap to an array of u32 values. */
+  toArray(): Array<number>
+  /** Serialize to portable format (binary-identical to roaring-wasm portable format). */
+  serialize(): Buffer
+  /** Get serialization size in bytes (portable format). */
+  serializationSizeInBytes(): number
+  /** Deserialize from portable format buffer. */
+  static deserialize(buffer: Buffer): NativeRoaringBitmap32
+  /** Minimum value in the bitmap. Returns undefined if empty. */
+  minimum(): number | null
+  /** Maximum value in the bitmap. Returns undefined if empty. */
+  maximum(): number | null
+  /** Compute intersection (AND) of two bitmaps. */
+  static and(a: NativeRoaringBitmap32, b: NativeRoaringBitmap32): NativeRoaringBitmap32
+  /** Compute union (OR) of two bitmaps. */
+  static or(a: NativeRoaringBitmap32, b: NativeRoaringBitmap32): NativeRoaringBitmap32
+  /** Compute union (OR) of multiple bitmaps. */
+  static orMany(bitmaps: Array<NativeRoaringBitmap32>): NativeRoaringBitmap32
+  /** Compute difference (AND NOT) of two bitmaps. */
+  static andNot(a: NativeRoaringBitmap32, b: NativeRoaringBitmap32): NativeRoaringBitmap32
+  /** Compute symmetric difference (XOR) of two bitmaps. */
+  static xor(a: NativeRoaringBitmap32, b: NativeRoaringBitmap32): NativeRoaringBitmap32
+}
+
+/**
+ * 64-bit roaring bitmap backed by `croaring::Treemap`. Used by
+ * `IdSpace::U64` brains where entity ints may exceed `u32::MAX`.
+ *
+ * The JS surface uses `BigInt` exclusively so values above 2^53 cross
+ * the napi boundary losslessly. The Portable serialization format is
+ * the croaring `Treemap` Portable format — **NOT** compatible with
+ * `NativeRoaringBitmap32`'s Portable buffers. Callers select between
+ * the two types via the enclosing index's `IdSpace` discriminator.
+ */
+export declare class NativeRoaringBitmap64 {
+  /** Create a new empty bitmap, or from an array of BigInt values. */
+  constructor(values?: Array<bigint> | undefined | null)
+  /**
+   * Number of values in the bitmap (BigInt because cardinality may
+   * exceed u32 in a 64-bit-keyed bitmap).
+   */
+  get size(): bigint
+  /** Whether the bitmap is empty. */
+  get isEmpty(): boolean
+  /** Add a value to the bitmap. */
+  add(value: bigint): void
+  /**
+   * Add many values in one call. Cheaper than repeated `add` for
+   * bulk insertion because the napi crossing is amortized.
+   */
+  addMany(values: Array<bigint>): void
+  /**
+   * Remove a value from the bitmap. Named `delete` to mirror the
+   * 32-bit sibling and roaring-wasm's API.
+   */
+  delete(value: bigint): void
+  /**
+   * Add a value, return true if it was newly added (false if
+   * already present).
+   */
+  tryAdd(value: bigint): boolean
+  /** Check if the bitmap contains a value. */
+  has(value: bigint): boolean
+  /**
+   * Materialise the bitmap as a sorted `BigInt[]`. **Avoid at
+   * billion scale** — `toArray` allocates one BigInt per entry.
+   * For large bitmaps prefer streaming consumption from the
+   * enclosing posting-list API.
+   */
+  toArray(): Array<bigint>
+  /**
+   * Serialize to the Treemap Portable format. Not interchangeable
+   * with `NativeRoaringBitmap32` Portable buffers (different
+   * underlying container layout).
+   */
+  serialize(): Buffer
+  /** Get serialization size in bytes. */
+  serializationSizeInBytes(): bigint
+  /** Deserialize from a Treemap Portable buffer. */
+  static deserialize(buffer: Buffer): NativeRoaringBitmap64
+  /** Minimum value in the bitmap. Returns undefined if empty. */
+  minimum(): bigint | null
+  /** Maximum value in the bitmap. Returns undefined if empty. */
+  maximum(): bigint | null
+  /** Clear all values (in-place). */
+  clear(): void
+  /** Compute intersection (AND) of two bitmaps. */
+  static and(a: NativeRoaringBitmap64, b: NativeRoaringBitmap64): NativeRoaringBitmap64
+  /** Compute union (OR) of two bitmaps. */
+  static or(a: NativeRoaringBitmap64, b: NativeRoaringBitmap64): NativeRoaringBitmap64
+  /**
+   * Compute union (OR) of multiple bitmaps. `Treemap` has no
+   * dedicated `or_many` primitive in croaring 2.5; we fold pairwise.
+   */
+  static orMany(bitmaps: Array<NativeRoaringBitmap64>): NativeRoaringBitmap64
+  /** Compute difference (AND NOT) of two bitmaps. */
+  static andNot(a: NativeRoaringBitmap64, b: NativeRoaringBitmap64): NativeRoaringBitmap64
+  /** Compute symmetric difference (XOR) of two bitmaps. */
+  static xor(a: NativeRoaringBitmap64, b: NativeRoaringBitmap64): NativeRoaringBitmap64
+}
+
+/**
+ * JS-side handle to a [`ShardMigrationManifest`]. Owns the Rust
+ * value; state transitions mutate in place. Use
+ * [`to_bytes`](NativeShardMigrationManifest::to_bytes) to get JSON
+ * bytes for atomic persistence via brainy's storage adapter.
+ */
+export declare class NativeShardMigrationManifest {
+  /**
+   * Construct a new manifest in `Idle` state for a brain with
+   * `currentDepth` (2 or 3).
+   */
+  constructor(currentDepth: number)
+  /**
+   * Load an existing manifest from its JSON bytes (the canonical
+   * form written via [`to_bytes`]).
+   */
+  static fromBytes(bytes: Buffer): NativeShardMigrationManifest
+  /**
+   * Serialize the current manifest state to pretty-printed JSON
+   * bytes for atomic-write via brainy's storage adapter
+   * (`saveBinaryBlob(path, buffer)` uses tmp+rename inside the
+   * adapter).
+   */
+  toBytes(): Buffer
+  /**
+   * Manifest format version. Bumped when the on-disk JSON shape
+   * changes incompatibly.
+   */
+  get version(): number
+  /**
+   * Current shard depth — the layout entities are stored under.
+   * Equals the migration target after `finalizeCommit`.
+   */
+  get currentDepth(): number
+  /**
+   * Read-only summary of the migration state. Returns
+   * `{stateKind: 'idle'}` when no migration is in flight.
+   */
+  stateSummary(): ShardMigrationStateSummary
+  /**
+   * Begin a migration to `targetDepth`. Throws if a migration is
+   * already in progress or if `targetDepth` equals `currentDepth`.
+   */
+  startMigration(targetDepth: number, totalUuids: bigint, nowMs: bigint): void
+  /**
+   * Update the cumulative `scanned` count and the
+   * last-progress timestamp. Throws if state is not `Migrating`.
+   */
+  recordProgress(scanned: bigint, nowMs: bigint): void
+  /**
+   * Enter the `Committing` barrier — all entities are moved;
+   * about to flip `currentDepth` on disk. Throws if state is not
+   * `Migrating`.
+   */
+  beginCommit(nowMs: bigint): void
+  /**
+   * Atomic flip: `currentDepth` becomes the migration's target,
+   * state returns to `Idle`. Throws if state is not `Committing`.
+   * Caller must then serialize + atomically write the new
+   * manifest bytes.
+   */
+  finalizeCommit(): void
+  /**
+   * Abort an in-flight migration. State returns to `Idle` with
+   * `currentDepth` unchanged. Brainy is responsible for cleaning
+   * up any already-migrated entity files at the target paths.
+   * No-op when state is already `Idle`.
+   */
+  cancelMigration(): void
+  /**
+   * Storage paths brainy should consult for `uuid`. Returns ONE
+   * path when `Idle`, TWO paths when `Migrating` / `Committing`
+   * (target layout first, current as fallback). Caller tries
+   * them in order.
+   */
+  resolveLayoutPaths(uuid: string): Array<string>
+}
+
+/**
+ * Native unified cache engine.
+ * Manages eviction decisions and metadata; TS wrapper holds actual JS data.
+ */
+export declare class NativeUnifiedCache {
+  /** Create a new cache with the given maximum size in bytes. */
+  constructor(maxSize: number)
+  /** Record a cache hit — increment access count for the key. */
+  recordAccess(key: string): void
+  /**
+   * Insert a cache entry. Returns keys that were evicted to make room.
+   * cache_type: 0=hnsw, 1=metadata, 2=embedding, 3=other
+   */
+  insert(key: string, cacheType: number, size: number, rebuildCost: number): NativeEvictionResult
+  /** Remove a specific key. Returns freed bytes. */
+  remove(key: string): number
+  /** Remove all entries matching a key prefix. Returns list of removed keys. */
+  removeByPrefix(prefix: string): Array<string>
+  /**
+   * Clear all entries or entries of a specific type. Returns removed keys.
+   * Pass null/undefined to clear all.
+   */
+  clear(cacheType?: number | undefined | null): Array<string>
+  /** Evict entries to free at least `bytes_needed` bytes. */
+  evictForSize(bytesNeeded: number): NativeEvictionResult
+  /**
+   * Fairness check: detect types using >70% cache with <15% access.
+   * Returns keys evicted during fairness correction.
+   */
+  checkFairness(): NativeEvictionResult
+  /** Report native subsystem memory usage (called periodically by TS). */
+  reportNativeMemory(hnsw: number, metadata: number, graph: number): void
+  /** Get comprehensive statistics. */
+  getStats(): NativeCacheStats
+  /** Check if a key exists in the cache metadata. */
+  has(key: string): boolean
+  /** Number of entries in the cache. */
+  itemCount(): number
+  /** Save access patterns as JSON for warm start persistence. */
+  saveAccessPatterns(): string
+  /** Load access patterns from JSON for warm start. */
+  loadAccessPatterns(json: string): void
+}
+
+/**
+ * JS-exposed configuration. All fields optional; defaults match the
+ * cor 3.0 billion-scale target (32 GB sparse files per side).
+ */
+export interface BinaryIdMapperConfig {
+  /** Path for `uuid_to_int.mkv` (extendible-hash KV file). REQUIRED. */
+  uuidToIntPath: string
+  /** Path for `int_to_uuid.bin` (direct-indexed sparse file). REQUIRED. */
+  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 (extendible-hash directory depth cap).
+   * Default 28 (supports ~12 B entries).
+   */
+  maxGlobalDepth?: number
+  /**
+   * Entity-int wire-width: `"u32"` (default — cortex 2.x compatible,
+   * caps at 4.29 B entries) or `"u64"` (Piece 10 — required for
+   * >4.29 B brains, persists 8-byte ints + bumps `int_to_uuid.bin`
+   * to v2 header). Ignored at open time: the on-disk format
+   * dictates the IdSpace and any user-provided value is
+   * cross-checked against the header (mismatch is a hard error).
+   */
+  idSpace?: string
+}
+
+/**
+ * Diagnostic snapshot returned by [`NativeBinaryIdMapper::diagnostics`].
+ *
+ * The u32-typed `size` / `next_int` fields are zero in `IdSpace::U64`
+ * mode (use the BigInt siblings); `int_size` and `id_space` always
+ * reflect the brain's actual IdSpace.
+ */
+export interface BinaryIdMapperDiagnostics {
+  uuidSize: number
+  intSize: number
+  intToUuidEntrySize: number
+  assignShards: number
+  size: number
+  nextInt: number
+  sizeBig: bigint
+  nextIntBig: bigint
+  idSpace: string
+}
+
+/**
+ * Cosine distance between two vectors.
+ * Range: 0 (identical) to 2 (opposite).
+ * Lower values indicate higher similarity.
+ */
+export declare function cosineDistance(a: Array<number>, b: Array<number>): number
+
+/**
+ * Batch cosine distance: compute distances from a query to multiple vectors.
+ * Uses Rayon parallelism for large batches.
+ * Returns array of distances.
+ */
+export declare function cosineDistanceBatch(query: Array<number>, vectors: Array<Array<number>>): Array<number>
+
+/**
+ * Compute approximate cosine distance between two SQ4-quantized vectors.
+ *
+ * Unpacks nibbles to u8 values, then uses the same integer accumulation
+ * approach as SQ8 but with 4-bit precision.
+ */
+export declare function cosineDistanceSq4(a: Buffer, aMin: number, aMax: number, aDim: number, b: Buffer, bMin: number, bMax: number, bDim: number): number
+
+/** Batch cosine distance from an SQ4 query to multiple SQ4 vectors. */
+export declare function cosineDistanceSq4Batch(query: Buffer, queryMin: number, queryMax: number, queryDim: number, vectors: Array<Buffer>, mins: Array<number>, maxs: Array<number>, dims: Array<number>): Array<number>
+
+/**
+ * Compute approximate cosine distance between two SQ8-quantized vectors.
+ *
+ * Operates directly on uint8 values using integer arithmetic in the inner loop.
+ * Avoids full dequantization by reconstructing the dot product and norms from
+ * integer sums and the per-vector scale factors.
+ *
+ * The accumulation loop auto-vectorizes with AVX2/NEON.
+ */
+export declare function cosineDistanceSq8(a: Buffer, aMin: number, aMax: number, b: Buffer, bMin: number, bMax: number): number
+
+/**
+ * Batch cosine distance from an SQ8 query to multiple SQ8 vectors.
+ * Uses Rayon parallelism for large batches.
+ */
+export declare function cosineDistanceSq8Batch(query: Buffer, queryMin: number, queryMax: number, vectors: Array<Buffer>, mins: Array<number>, maxs: Array<number>): Array<number>
+
+/** Calculate cosine similarity between two embedding vectors. */
+export declare function cosineSimilarity(a: Array<number>, b: Array<number>): number
+
+/** Decode delta-varint compressed bytes back to connection list. */
+export declare function decodeConnections(data: Buffer): Array<number>
+
+/**
+ * **Piece 3.** Number of shard buckets at the given depth.
+ *
+ * - `shardDepth = 2` → `256` (16² distinct two-hex prefixes)
+ * - `shardDepth = 3` → `16777216` (256³ three-level prefixes)
+ *
+ * Returns the value as a JS `number`. Returns `0` for unsupported
+ * depths (the napi surface validates strictly elsewhere — this
+ * accessor is loose to keep the JS-side branchless).
+ */
+export declare function deepShardBucketCount(shardDepth: number): number
+
+/**
+ * **Piece 3.** Compute the filesystem-relative path for a UUID at
+ * the given shard depth. Returns the path as a `/`-separated
+ * string ready to pass to the storage adapter.
+ *
+ * Examples:
+ * - `layoutPath("ab123456-1234-5678-9abc-def012345678", 2)` →
+ *   `"ab/ab12345612345678 9abcdef012345678"` (single shard dir)
+ * - `layoutPath(same, 3)` →
+ *   `"ab/12/34/ab12345612345678 9abcdef012345678"` (three shard dirs)
+ *
+ * Throws on invalid input — see {@link deep_shard_normalize_uuid}.
+ */
+export declare function deepShardLayoutPath(uuid: string, shardDepth: number): string
+
+/**
+ * **Piece 3.** Normalize a UUID — strip hyphens, lowercase, validate
+ * as 32 hex chars. Mirrors brainy's `getShardIdFromUuid`
+ * normalization so cor-side callers (verb-ID interning, future
+ * Piece 14 migration worker) and brainy-side callers see the
+ * identical normalized form.
+ *
+ * Throws on empty input, wrong length after normalization, or
+ * non-hex characters — same error shape as
+ * `layoutPath`/`shardPrefix`.
+ */
+export declare function deepShardNormalizeUuid(uuid: string): string
+
+/**
+ * **Piece 3.** Compute JUST the shard-prefix portion (no filename
+ * component). Useful for `mkdir -p`-style preparation before
+ * writing.
+ */
+export declare function deepShardPrefix(uuid: string, shardDepth: number): string
+
+/**
+ * **Piece 3.** Number of hex characters the prefix consumes —
+ * `2` for two-level layouts, `6` for three-level.
+ */
+export declare function deepShardPrefixLen(shardDepth: number): number
+
+/** Dequantize SQ4 packed bytes back to float64 vector. */
+export declare function dequantizeSq4(quantized: Buffer, min: number, max: number, dim: number): Array<number>
+
+/** Dequantize SQ8 bytes back to float64 vector. */
+export declare function dequantizeSq8(quantized: Buffer, min: number, max: number): Array<number>
+
+/** Deserialize SQ8 data from compact binary format. */
+export declare function deserializeSq8(data: Buffer): Sq8QuantizeResult
+
+/** Device information returned to JavaScript */
+export interface DeviceInfo {
+  /** Active device name: "cpu", "cuda", or "metal" */
+  device: string
+  /** Whether CUDA is available (compiled with cuda feature and GPU detected) */
+  cudaAvailable: boolean
+  /** Whether Metal is available (compiled with metal feature and GPU detected) */
+  metalAvailable: boolean
+}
+
+/**
+ * Choice of adjacency backend at build time. The mmap variant is
+ * required for >~100 M node builds; the RAM variant is faster for
+ * smaller workloads.
+ */
+export interface DiskAnnAdjacencyBackend {
+  /** `"ram"` or `"mmap"`. Defaults to `"ram"` when omitted. */
+  kind: string
+  /**
+   * Required when `kind = "mmap"`: scratch file path for the build's
+   * concurrent adjacency. Recommended location is a fast local SSD.
+   */
+  mmapPath?: string
+}
+
+/**
+ * Top-level build config bundle. Any field can be omitted; defaults
+ * are filled in to match the DiskANN paper's published parameters.
+ *
+ * ## Operating modes
+ *
+ * `mode` selects which DiskANN flavour to build:
+ *
+ * - `"in-memory"` — **Mode 1**: skip PQ entirely. The codebook +
+ *   codes sections collapse to zero bytes; search walks the graph
+ *   using exact full-vector distance. RAM-resident vectors give
+ *   sub-ms latency. Pieces G of the cor 3.0 plan.
+ * - `"hybrid"` (default) — **Mode 2**: PQ codes in RAM, full vectors
+ *   mmap'd, PQ-greedy walk with full-vector re-rank. Today's
+ *   default behaviour.
+ * - `"on-disk"` — **Mode 3**: same as hybrid but with explicit
+ *   madvise hints biased toward SSD-resident vectors. Piece H.
+ *
+ * When `mode = "in-memory"`, the `pq` and `adjacency` fields are
+ * ignored — Mode 1 forces no PQ and RAM-resident build adjacency.
+ */
+export interface DiskAnnConfig {
+  vamana?: DiskAnnVamanaConfig
+  pq?: DiskAnnPqConfig
+  adjacency?: DiskAnnAdjacencyBackend
+  /**
+   * `"in-memory" | "hybrid" | "on-disk"`. Defaults to `"hybrid"`
+   * (today's behaviour) when omitted.
+   */
+  mode?: string
+}
+
+/**
+ * Header introspection — exposes the on-disk metadata so JS can
+ * reason about index shape (dim, node count, PQ params).
+ */
+export interface DiskAnnHeader {
+  version: number
+  dim: number
+  nodeCount: number
+  pqM: number
+  pqKsub: number
+  pqDsub: number
+  maxDegree: number
+  entryPoint: number
+}
+
+/**
+ * Single search hit returned to JS.
+ *
+ * IMPORTANT: `slot` is a **per-shard graph-internal slot ID**, NOT a
+ * brain-wide entity ID. Slots are NOT stable across rebuilds; the
+ * TS wrapper translates `slot ↔ entity-id` through the brain's
+ * `BinaryIdMapper` (see the module-level doc + Step 14 commit for
+ * the layering rationale). Slot stays `u32` in both `IdSpace::U32`
+ * and `IdSpace::U64` brains.
+ */
+export interface DiskAnnHit {
+  /**
+   * **Per-shard graph-internal slot ID** — NOT an entity ID. Translate
+   * through `BinaryIdMapper` in the TS wrapper before exposing to
+   * brainy / consumer code. Stays `u32` even in U64 brains because
+   * a single DiskANN shard addresses at most `u32::MAX − 1` nodes
+   * by construction.
+   */
+  slot: number
+  /** Exact (full-vector) squared distance to the query. */
+  distance: number
+  /**
+   * **#72 Phase A** — the brain-wide **entity int** for this hit,
+   * resolved O(1) from the `main.slotmap` sidecar (or `slot` itself
+   * when the searcher was opened without a slotmap). The TS wrapper
+   * resolves this int → UUID through the canonical id-mapper, so it
+   * never needs a resident `slot → uuid` map. BigInt so it stays
+   * exact above `u32::MAX` in U64 brains.
+   */
+  id: bigint
+}
+
+/**
+ * PQ knobs exposed to JS. Sensible defaults are filled in by
+ * [`NativeDiskANN.build`] when fields are absent.
+ */
+export interface DiskAnnPqConfig {
+  /**
+   * Number of PQ subspaces. dim must be divisible by m. **`0` =
+   * auto-derive from the observed dimension** (target dsub ≈ 8, via
+   * `pqDeriveM`) — the zero-config default the wrapper sends. Any
+   * non-zero value is an explicit pin and is used verbatim.
+   */
+  m: number
+  /** Centroids per subspace. 256 = 8-bit codes (the standard). Default 256. */
+  ksub: number
+  /** k-means iterations during codebook training. Default 25. */
+  iterations: number
+  /** How many training vectors to sample. 0 = use all of them. Default 200_000. */
+  trainingSample: number
+}
+
+/**
+ * Parameters for [`NativeDiskANN::rebuild_from_existing`]. Lets the TS
+ * wrapper drive an in-place rebuild without ever copying the existing
+ * vector dataset across the FFI boundary.
+ *
+ * (No `Clone`/`Debug` derives because `napi::Buffer` doesn't implement
+ * them — the napi runtime owns the buffer's lifetime, not Rust.)
+ */
+export interface DiskAnnRebuildFromExistingParams {
+  /**
+   * Path to the prior index on disk. Omit (or pass `None`) for a
+   * delta-only first-time build via this path.
+   */
+  existingPath?: string
+  /**
+   * **Graph-internal slot IDs** (NOT entity IDs — see the module
+   * doc) in the existing index to retain. Caller filters out
+   * tombstoned slots; this list IS the live set. Each entry must
+   * be `< existing.header().node_count`. Empty when rebuilding
+   * from delta only.
+   */
+  liveOldSlots: Array<number>
+  /**
+   * Flat f32 buffer of newly-inserted vectors,
+   * `delta_count × dim × 4` bytes LE. Omit when there are no new
+   * inserts (compaction-only rebuild).
+   */
+  deltaVectors?: Buffer
+  /**
+   * Number of vectors in `delta_vectors`. Must be `0` when
+   * `delta_vectors` is omitted.
+   */
+  deltaCount: number
+  /**
+   * Vector dimensionality. Must match the existing index when one
+   * is provided.
+   */
+  dim: number
+  /**
+   * Where to write the new index. May equal `existing_path` for
+   * in-place rebuild — the binding writes to a temp file and
+   * atomic-renames over the original.
+   */
+  outputPath: string
+  /** Build knobs. Defaults match the DiskANN paper when omitted. */
+  cfg?: DiskAnnConfig
+  /**
+   * **#72 Phase A+B** — per-slot entity ints for the new index, as a
+   * flat little-endian `u64` buffer of exactly `node_count × 8` bytes
+   * (`node_count = live_old_slots.len() + delta_count`). Element `i`
+   * is the brain-wide entity int of new slot `i`. When present, the
+   * binding writes the `main.slotmap` (slot → int) + `main.slotrev`
+   * (int → slot) sidecars atomically with the new index, so the TS
+   * wrapper never keeps a resident `slot ↔ uuid` map. Omit only for
+   * the slot-only benchmark paths that don't carry entity ids.
+   */
+  slotIds?: Buffer
+}
+
+/** Vamana graph build knobs exposed to JS. */
+export interface DiskAnnVamanaConfig {
+  /** Max out-degree per node (R). Default 64. */
+  maxDegree: number
+  /** Candidate list size during build (L). Default 100. */
+  searchListSize: number
+  /** Density parameter for the second pass. Default 1.2. */
+  alpha: number
+  /** RNG seed for deterministic builds. */
+  seed: bigint
+  /** Build with rayon parallelism. Default true. */
+  parallel: boolean
+  /** Nodes per rayon batch. Default 64. */
+  parallelBatch: number
+}
+
+/**
+ * Dot product distance between two vectors.
+ * Converted to distance metric (lower is better): returns -dot_product.
+ */
+export declare function dotProductDistance(a: Array<number>, b: Array<number>): number
+
+/**
+ * Encode a connection list (neighbor IDs) as delta-varint compressed bytes.
+ *
+ * 1. Sort the IDs
+ * 2. Compute deltas between consecutive values
+ * 3. Encode each delta as a variable-length integer (LEB128)
+ *
+ * Achieves 2-3x compression for typical HNSW neighbor lists.
+ */
+export declare function encodeConnections(ids: Array<number>): Buffer
+
+/** Engine statistics returned to JavaScript. */
+export interface EngineStats {
+  initialized: boolean
+  embedCount: number
+  totalProcessingTimeMs: number
+  avgProcessingTimeMs: number
+  modelName: string
+}
+
+/**
+ * **Piece 4.** Standalone sort-latency estimator. Returns the
+ * estimated microseconds to sort `n` items using the documented
+ * per-comparison constant. Useful for ad-hoc cost queries from
+ * brainy (e.g. "should I sort this list of N candidates before
+ * issuing a deep-shard read?").
+ *
+ * Returns `0` for `n` of 0 or 1.
+ */
+export declare function estimateSortLatencyUs(n: number): number
+
+/**
+ * Euclidean distance between two vectors.
+ * Lower values indicate higher similarity.
+ */
+export declare function euclideanDistance(a: Array<number>, b: Array<number>): number
+
+/** Batch euclidean distance: compute distances from a query to multiple vectors. */
+export declare function euclideanDistanceBatch(query: Array<number>, vectors: Array<Array<number>>): Array<number>
+
+/**
+ * Outcome of raising the open-file limit. Field names cross to JS as
+ * camelCase (`softBefore`, `softAfter`, `hard`, `raised`).
+ */
+export interface FileLimitInfo {
+  /** Soft `RLIMIT_NOFILE` before the call. */
+  softBefore: number
+  /** Soft `RLIMIT_NOFILE` after the call (== `hard` on success). */
+  softAfter: number
+  /**
+   * Hard cap — the ceiling this process cannot exceed without the
+   * deployment raising it.
+   */
+  hard: number
+  /** Whether the soft limit was actually raised. */
+  raised: boolean
+  /**
+   * Linux `vm.max_map_count` (max mmap regions per process), read from
+   * `/proc/sys/vm/max_map_count`. A process CANNOT raise this itself
+   * (global sysctl) — it must be set by the deployment. `0` if not
+   * readable (non-Linux). At 1000+ small brains, each mmapping its
+   * SSTables/index/id-mappers, this can bind as brains scale up.
+   */
+  vmMaxMapCount: number
+}
+
+/** Get information about the active compute device. */
+export declare function getDeviceInfo(): DeviceInfo
+
+/**
+ * Result from addVerb — indicates which trees need flushing
+ * and (cor 3.0 brainy-8.0 lockstep) returns the verb's
+ * interned `u64` integer ID.
+ */
+export interface GraphAddVerbResult {
+  /** Whether the source tree MemTable needs flush */
+  needsFlushSource: boolean
+  /** Whether the target tree MemTable needs flush */
+  needsFlushTarget: boolean
+  /** Whether the verbs-source tree MemTable needs flush */
+  needsFlushVerbsSource: boolean
+  /** Whether the verbs-target tree MemTable needs flush */
+  needsFlushVerbsTarget: boolean
+  /**
+   * **Brainy 8.0 lockstep** (PLATFORM-HANDOFF
+   * BRAINY-8.0-RENAME-COORDINATION A.3): the verb's interned
+   * `u64` integer ID, returned here so brainy 8.0's sidecar
+   * `verb_int ↔ verb_id_string` map can be populated without
+   * the prior extra FFI round-trip through
+   * `getVerbIntForString`. Saves one boundary crossing per
+   * add at billion-scale ingest.
+   */
+  verbInt: bigint
+}
+
+/** Configuration for NativeGraphAdjacencyIndex */
+export interface GraphAdjacencyConfig {
+  /** 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 (`verb-uuid-to-int.mkv` +
+   * `verb-int-to-uuid.bin`). When set, verb-ID assignments survive
+   * process restart and the namespace shares the directory with
+   * any other artifacts the wrapper persists there. When omitted,
+   * the namespace falls back to a 64-shard in-memory interner —
+   * adequate for tests + transient brains, but tombstones are lost
+   * on exit. Production callers always provide this.
+   */
+  persistenceDir?: string
+  /**
+   * **Piece B (cor 3.0).** Wire width of the verb-ID interning
+   * namespace + the live-verb / per-(type, subtype) membership
+   * bitmaps. `"U32"` (default, cortex 2.x-compatible) caps at
+   * ~4.29 B unique verb-IDs and uses Roaring32 bitmaps. `"U64"`
+   * (cor 3.0 widening) lifts the cap to `u64::MAX - 1` and
+   * uses Treemap (Roaring64) bitmaps.
+   *
+   * The choice is independent of the brain's *entity* IdSpace —
+   * a U32-entity brain can run U64-verb if its edge-to-noun
+   * fan-out is unusually high, and vice versa.
+   *
+   * **Persistence contract**: when `persistence_dir` is set, the
+   * chosen width is stamped into the underlying `BinaryIdMapper`'s
+   * file header and is immutable post-create. Re-opening a
+   * directory with a mismatched value raises an error rather than
+   * silently mis-reading the bitmap geometry — wire-width
+   * migrations need the offline migrator (Piece E).
+   *
+   * Accepted values: `"U32"`, `"U64"` (case-sensitive). Anything
+   * else raises a config error at construction.
+   */
+  verbIdSpace?: string
+}
+
+/**
+ * Statistics for the graph adjacency index.
+ *
+ * The legacy u32 counters (`total_relationships`, `verb_id_count`,
+ * `relationship_type_count`) are preserved for cortex 2.x-compatible
+ * callers — they narrow internally via `as u32` and cap at
+ * [`u32::MAX`]. New BigInt sibling fields (`*_big`) carry the same
+ * values losslessly at billion scale and should be preferred by any
+ * brainy 8.0 / cor 3.0 consumer.
+ *
+ * Per-tree fields (`source_mem_table_size`, `*_sstable_count`,
+ * `*_mem_table_memory`) stay u32 because they are bounded by the
+ * LSM flush threshold (default 100 K entries) — they cannot reach
+ * the u32 ceiling by construction.
+ */
+export interface GraphAdjacencyStats {
+  /**
+   * Total relationships in source tree (narrowed u32 — see
+   * `total_relationships_big` for the BigInt sibling).
+   */
+  totalRelationships: number
+  /**
+   * Total verb IDs tracked (narrowed u32 — see
+   * `verb_id_count_big`).
+   */
+  verbIdCount: number
+  /**
+   * Number of relationship types (narrowed u32 — see
+   * `relationship_type_count_big`).
+   */
+  relationshipTypeCount: number
+  /** Source tree MemTable size */
+  sourceMemTableSize: number
+  /** Target tree MemTable size */
+  targetMemTableSize: number
+  /** Source tree SSTable count */
+  sourceSstableCount: number
+  /** Target tree SSTable count */
+  targetSstableCount: number
+  /** Source tree MemTable memory estimate */
+  sourceMemTableMemory: number
+  /** Target tree MemTable memory estimate */
+  targetMemTableMemory: number
+  /**
+   * Total relationships in source tree as a `BigInt`. Use this
+   * field instead of `total_relationships` at billion scale.
+   */
+  totalRelationshipsBig: bigint
+  /** Total verb IDs tracked as a `BigInt`. */
+  verbIdCountBig: bigint
+  /** Number of relationship types as a `BigInt`. */
+  relationshipTypeCountBig: bigint
+}
+
+/**
+ * Options for opening a streaming graph cursor
+ * ([`graph_cursor_open`](NativeGraphAdjacencyIndex::graph_cursor_open)).
+ * Mirrors brainy's `GraphCursorOptions` (+ the trailing `generation`),
+ * flattened so the seed set can arrive either as explicit ints or as
+ * cor's opaque id-set envelope (the `find()`→export fusion).
+ */
+export interface GraphCursorOpenOptions {
+  /**
+   * `"out"`, `"in"`, or `"both"` (default). Honored for a **seeded**
+   * cursor; ignored for a whole-graph walk, which emits every edge
+   * exactly once via its source's out-list regardless.
+   */
+  direction?: string
+  /**
+   * `"light"` (default) omits the `edge_verb_ints` column — topology
+   * + edge-type only, the viz default. `"full"` includes it (brainy
+   * resolves verb-id strings from the ints lazily).
+   */
+  projection?: string
+  /**
+   * Seed set as explicit entity ints. Omitted **and** `seeds_opaque`
+   * omitted = a whole-graph walk. Mutually exclusive with
+   * `seeds_opaque` (if both are set, `seeds_opaque` wins).
+   */
+  seeds?: Array<bigint>
+  /**
+   * Seed set as cor's [`OpaqueIdSet`](crate::opaque_id_set) envelope
+   * — a `find()` universe forwarded with no id materialization.
+   */
+  seedsOpaque?: Buffer
+  /**
+   * Resume token from a prior chunk — reopen after a `SnapshotExpired`
+   * to continue the walk from where it left off (at the same pinned
+   * generation). Overrides `generation` and the seed/whole-graph mode.
+   */
+  cursor?: string
+  /**
+   * Explicit as-of generation to pin. Omitted = pin the current
+   * generation at open.
+   */
+  generation?: bigint
+}
+
+/**
+ * Fallback noun-type index (`NounType.Thing`, 3). Used when an unknown
+ * string is coerced via the loose lookup.
+ */
+export declare function graphNounFallbackIndex(): number
+
+/** Strict noun-index → string lookup. Returns `null` on out-of-range. */
+export declare function graphNounFromIndex(i: number): string | null
+
+/** Index → string with brainy-parity fallback to `"thing"`. */
+export declare function graphNounFromIndexOrFallback(i: number): string
+
+/**
+ * Strict noun-string → index lookup. Returns `null` on unknown
+ * strings — caller decides whether to surface a vocabulary violation
+ * or coerce. Mirror of brainy's `TypeUtils.getNounIndex` minus the
+ * silent fallback.
+ */
+export declare function graphNounIndex(s: string): number | null
+
+/**
+ * Lookup with brainy-parity fallback to `NounType.Thing` (3). Mirrors
+ * `TypeUtils.getNounIndex`'s runtime behavior.
+ */
+export declare function graphNounIndexOrFallback(s: string): number
+
+/** Number of standard noun types (42). Mirrors brainy's `NOUN_TYPE_COUNT`. */
+export declare function graphNounTypeCount(): number
+
+/** Fallback verb-type index (`VerbType.RelatedTo`, 3). */
+export declare function graphVerbFallbackIndex(): number
+
+/** Strict verb-index → string lookup. Returns `null` on out-of-range. */
+export declare function graphVerbFromIndex(i: number): string | null
+
+/** Index → string with brainy-parity fallback to `"relatedTo"`. */
+export declare function graphVerbFromIndexOrFallback(i: number): string
+
+/** Strict verb-string → index lookup. Returns `null` on unknown. */
+export declare function graphVerbIndex(s: string): number | null
+
+/** Lookup with brainy-parity fallback to `VerbType.RelatedTo` (3). */
+export declare function graphVerbIndexOrFallback(s: string): number
+
+/** Number of standard verb types (127). Mirrors brainy's `VERB_TYPE_COUNT`. */
+export declare function graphVerbTypeCount(): number
+
+/**
+ * **Piece 4.** Migration-recommended threshold (microseconds). Echoed
+ * so wrappers + monitoring don't have to hardcode the value
+ * independently.
+ */
+export declare function hydrationMigrationThresholdUs(): number
+
+/**
+ * **Piece 4.** Per-comparison nanosecond cost constant used by the
+ * sort estimate. Exposed for observability (so wrappers can
+ * surface the assumption in dashboards) — NOT a runtime knob.
+ */
+export declare function hydrationNsPerCompare(): number
+
+/**
+ * Top-level hydration plan, JS-friendly form. See
+ * [`crate::io_batch_entities::HydrationPlan`].
+ */
+export interface HydrationPlan {
+  /** Echo of the input shard depth. */
+  shardDepth: number
+  /** Echo of `uuids.len()`. */
+  totalUuidCount: number
+  /**
+   * Per-shard breakdown. Vec ordering is unspecified — the
+   * wrapper iterates to issue reads in whatever order makes
+   * sense for its workload.
+   */
+  shards: Array<ShardHydrationPlan>
+  /** Highest single-shard estimated sort latency, in microseconds. */
+  maxShardSortUs: number
+  /**
+   * Threshold (in microseconds) the wrapper compared against —
+   * echoed so JS-side logs can include it without a separate
+   * lookup.
+   */
+  migrationThresholdUs: number
+  /**
+   * `true` when `maxShardSortUs > migrationThresholdUs`. The
+   * wrapper passes this hint to Piece 14's migration worker
+   * asynchronously; it does NOT block the current query.
+   */
+  migrationRecommended: boolean
+}
+
+export interface LicenseResult {
+  valid: boolean
+  tier: string
+  email: string
+  expiresAt: number
+  error?: string
+}
+
+/** JSON shape for a directory entry on the napi boundary. */
+export interface LsmDirectoryEntryJson {
+  fieldLen: number
+  valueLen: number
+  fieldOffset: number
+  valueOffset: number
+  payloadOffset: bigint
+  payloadLen: bigint
+  epoch: bigint
+  flags: number
+}
+
+/**
+ * Assemble a full SSTable byte buffer from structured inputs. Returns
+ * the bytes ready to be hashed + asserted against a golden SHA-256.
+ *
+ * The directory entries' `field_offset` / `value_offset` are computed
+ * automatically as cumulative offsets into the keys section. The
+ * `payload_offset` / `payload_len` are computed from the cumulative
+ * per-entry payload sizes. The header's SHA-256 is computed over the
+ * concatenation of directory + keys + payload + bloom sections.
+ */
+export declare function lsmFormatBuildSstable(spec: LsmSstableBuildSpec): Buffer
+
+/** Parse a 40-byte directory entry. */
+export declare function lsmFormatDecodeDirectoryEntry(bytes: Buffer): LsmDirectoryEntryJson
+
+/** Parse a 128-byte buffer into structured header fields. */
+export declare function lsmFormatDecodeHeader(bytes: Buffer): LsmHeaderJson
+
+/**
+ * Inverse of `lsmFormatEncodePayload`. Splits a payload into its
+ * additions + deletions bitmap byte slices.
+ */
+export declare function lsmFormatDecodePayload(bytes: Buffer): LsmPayloadParts
+
+/** Build a 40-byte directory entry buffer. */
+export declare function lsmFormatEncodeDirectoryEntry(spec: LsmDirectoryEntryJson): Buffer
+
+/** Build a 128-byte SSTable header buffer from structured inputs. */
+export declare function lsmFormatEncodeHeader(spec: LsmHeaderJson): Buffer
+
+/**
+ * Encode a per-entry payload: `additions_len:u64 LE | additions bytes
+ * | deletions_len:u64 LE | deletions bytes`.
+ */
+export declare function lsmFormatEncodePayload(additions: Buffer, deletions: Buffer): Buffer
+
+/**
+ * Parse a full SSTable byte buffer. Verifies the SHA-256 implicitly
+ * by returning the computed hash alongside the stored hash; callers
+ * (golden tests) assert equality.
+ */
+export declare function lsmFormatParseSstable(bytes: Buffer): LsmSstableParseResult
+
+/** JSON shape for an LSM header on the napi boundary. */
+export interface LsmHeaderJson {
+  /** `"u32"` or `"u64"`. */
+  idSpace: string
+  /** Defaults to `0`. */
+  headerFlags: number
+  entryCount: bigint
+  keysSize: bigint
+  payloadSize: bigint
+  bloomSize: bigint
+  minEpoch: bigint
+  maxEpoch: bigint
+  /** Lowercase hex (64 chars). */
+  sha256Hex: string
+}
+
+/**
+ * Decoded payload split (used as the napi return of
+ * [`lsm_format_decode_payload`]).
+ */
+export interface LsmPayloadParts {
+  additions: Buffer
+  deletions: Buffer
+}
+
+/**
+ * Input for [`lsm_format_build_sstable`]. Each entry's `(field, value)`
+ * is appended to a flat keys section in directory order; the
+ * `field_offset` and `value_offset` are computed automatically so the
+ * caller doesn't have to track them.
+ */
+export interface LsmSstableBuildEntry {
+  field: string
+  value: string
+  additions: Buffer
+  deletions: Buffer
+  epoch: bigint
+  /**
+   * Set to `true` to mark this entry as a posting-list-wide
+   * tombstone (sets the `FLAG_ENTRY_TOMBSTONE` bit). `additions`
+   * should be empty in this case; the deletion bitmap carries the
+   * removed ints.
+   */
+  tombstone: boolean
+}
+
+/**
+ * Inputs for assembling a whole SSTable. Entries are NOT pre-sorted by
+ * this helper — golden fixtures must pass them already in
+ * `(field, value)` order so the on-disk layout is deterministic.
+ */
+export interface LsmSstableBuildSpec {
+  idSpace: string
+  entries: Array<LsmSstableBuildEntry>
+  /**
+   * Optional bloom-filter bytes — appended verbatim after the
+   * payload section. Pass an empty Buffer to skip the bloom section
+   * entirely (`bloom_size = 0`).
+   */
+  bloom: Buffer
+  minEpoch: bigint
+  maxEpoch: bigint
+}
+
+/** One parsed entry from an SSTable. */
+export interface LsmSstableParsedEntry {
+  field: string
+  value: string
+  additions: Buffer
+  deletions: Buffer
+  epoch: bigint
+  tombstone: boolean
+}
+
+/** Decoded SSTable representation returned by [`lsm_format_parse_sstable`]. */
+export interface LsmSstableParseResult {
+  header: LsmHeaderJson
+  entries: Array<LsmSstableParsedEntry>
+  bloom: Buffer
+  /**
+   * SHA-256 of the body (directory + keys + payload + bloom) as the
+   * reader recomputed it — must equal `header.sha256_hex` for an
+   * uncorrupted file.
+   */
+  computedSha256Hex: string
+}
+
+/**
+ * Manhattan (L1) distance between two vectors.
+ * Lower values indicate higher similarity.
+ */
+export declare function manhattanDistance(a: Array<number>, b: Array<number>): number
+
+/** Decode msgpack bytes to a JSON value. */
+export declare function msgpackDecode(buffer: Buffer): any
+
+/**
+ * Batch decode multiple msgpack buffers to JSON values.
+ * Uses Rayon parallelism for large batches.
+ */
+export declare function msgpackDecodeBatch(buffers: Array<Buffer>): Array<any>
+
+/** Encode a JSON value to msgpack bytes. */
+export declare function msgpackEncode(value: any): Buffer
+
+/**
+ * Batch encode multiple JSON values to msgpack.
+ * Uses Rayon parallelism for large batches.
+ */
+export declare function msgpackEncodeBatch(values: Array<any>): Array<Buffer>
+
+/** Result from compacting a tree to binary .sst format (adapter-controlled) */
+export interface NativeBinaryCompactResult {
+  /** Which tree was compacted */
+  treeName: string
+  /** New merged SSTable ID */
+  newSstableId: string
+  /** Binary .sst data for the adapter to persist */
+  data: Buffer
+  /** Target level */
+  newLevel: number
+  /** Old SSTable IDs to remove from manifest/storage */
+  oldIds: Array<string>
+}
+
+/**
+ * Result from flushing a tree's MemTable to binary .sst format (adapter-controlled).
+ *
+ * **Cor 3.0 Piece D**: the legacy msgpack-based `GraphFlushResult` /
+ * `GraphCompactResult` types were dropped along with the msgpack-only
+ * `LSMTreeCore.flush_mem_table` / `compact` API path. The binary `.sst`
+ * format ([`crate::mmap_sstable_u64::MmapSSTableU64`]) is the only
+ * on-disk shape now — same durability bar (SHA-256 + fsync), faster
+ * reads, smaller files (no string table).
+ *
+ * `entry_count` / `value_count` are narrowed `u32` for napi-visible
+ * per-SSTable totals. The underlying `LSMTreeCoreU64` tracks them as
+ * `u64`; a single SSTable would need >4B entries to overflow which is
+ * impractical (4 B × 20-byte entry index = 80 GB per SSTable).
+ */
+export interface NativeBinaryFlushResult {
+  /** Which tree was flushed */
+  treeName: string
+  /** SSTable ID */
+  sstableId: string
+  /** Binary .sst data for the adapter to persist */
+  data: Buffer
+  /** Compaction level (always 0 for flush) */
+  level: number
+  /** Number of unique entries */
+  entryCount: number
+  /** Total value count (sum of values across all entries) */
+  valueCount: number
+}
+
+/** Cache statistics including native memory tracking. */
+export interface NativeCacheStats {
+  totalSize: number
+  maxSize: number
+  itemCount: number
+  typeSizes: Array<number>
+  typeCounts: Array<number>
+  typeAccessCounts: Array<number>
+  totalAccessCount: number
+  nativeMemory: Array<number>
+  totalManagedMemory: number
+}
+
+/** Options for `connectedComponents`. */
+export interface NativeComponentsOptions {
+  /**
+   * `"weak"` (default; ignores direction) or `"strong"` (SCCs, honors
+   * direction). Any other value is treated as `"weak"` (lenient).
+   */
+  mode?: string
+  /**
+   * **Contextual scoping.** When set, label only the induced subgraph
+   * reachable from these seeds (O(scope)). Omitted = global.
+   */
+  seeds?: Array<bigint>
+  /** Scope seeds as cor's OpaqueIdSet envelope. */
+  seedsOpaque?: Buffer
+  /** Hop bound for the scope neighborhood (default 2). */
+  scopeDepth?: number
+}
+
+/**
+ * Statistics about the mapper state. Legacy u32 fields (`mappings`,
+ * `next_id`, `memory_estimate`) cap at [`u32::MAX`]; Piece-10 BigInt
+ * fields (`*_big`) carry the same values losslessly and should be
+ * preferred at billion scale.
+ */
+export interface NativeEntityIdMapperStats {
+  /** Number of active UUID ↔ integer mappings (caps at u32::MAX). */
+  mappings: number
+  /** Next integer ID to assign (caps at u32::MAX). */
+  nextId: number
+  /** Whether there are unsaved changes */
+  dirty: boolean
+  /** Estimated memory usage in bytes (caps at u32::MAX). */
+  memoryEstimate: number
+  /** IdSpace as a string — `"u32"` or `"u64"`. */
+  idSpace: string
+  /** Number of mappings as BigInt (overflow-safe). */
+  mappingsBig: bigint
+  /** Next integer ID as BigInt (overflow-safe). */
+  nextIdBig: bigint
+  /** Estimated memory usage as BigInt (overflow-safe). */
+  memoryEstimateBig: bigint
+}
+
+/** Result from eviction or clear operations. */
+export interface NativeEvictionResult {
+  evictedKeys: Array<string>
+  bytesFreed: number
+}
+
+/**
+ * Connected-component labelling — the columnar result of
+ * `connectedComponents`. `component_ids[i]` is the (dense `0..count`)
+ * component of `node_ints[i]`. Decoded to brainy's `GraphComponents`.
+ */
+export interface NativeGraphComponents {
+  /** Entity ints, `u64` LE. */
+  nodeInts: Buffer
+  /**
+   * Component label per node, `u32` LE (4 bytes each), parallel to
+   * `node_ints`. Labels are arbitrary-but-stable for a fixed
+   * `(graph, generation, mode)` — only the PARTITION is meaningful;
+   * values renumber across mutations (do not cache as a key).
+   */
+  componentIds: Buffer
+  /** Distinct component total (a SEPARATE field, not `max(component_ids)`). */
+  componentCount: number
+}
+
+/**
+ * One streamed chunk from a graph cursor
+ * ([`graph_cursor_next`](NativeGraphAdjacencyIndex::graph_cursor_next)).
+ */
+export interface NativeGraphCursorChunk {
+  /**
+   * This chunk's nodes + edges, columnar (same wire format as
+   * [`NativeSubgraph`]; `node_depth` is always empty for a flat
+   * export, and `edge_verb_ints` is empty under `"light"`).
+   */
+  subgraph: NativeSubgraph
+  /**
+   * Opaque resume token — pass to `graphCursorOpen({ cursor })` after
+   * a `SnapshotExpired` to resume. `None` once the walk is exhausted.
+   */
+  cursor?: string
+  /**
+   * `true` once the walk is exhausted; do not call `graphCursorNext`
+   * again (a redundant call returns an empty, `done: true` chunk).
+   */
+  done: boolean
+}
+
+/**
+ * A shortest path — the result of `shortestPath` (`None` ⇒ unreachable).
+ * Decoded to brainy's `GraphPath`.
+ */
+export interface NativeGraphPath {
+  /** The path's node sequence (from → to), `u64` LE. */
+  nodeInts: Buffer
+  /**
+   * Edge verb ints, `u64` LE. CONTRACT: `len == node_ints.len() - 1`
+   * (parallel to the GAPS between nodes, not to the nodes).
+   */
+  edgeVerbInts: Buffer
+  /** Hop count (cor stores no edge weights → hops-only weighting). */
+  cost: number
+}
+
+/**
+ * Per-node scalar scores — the columnar result of `pageRank` and
+ * `topByDegree` (ADR-006 Phase C). Two parallel little-endian columns,
+ * descending by score; decoded zero-copy to brainy's `GraphScores`
+ * (`nodeInts: BigInt64Array`, `scores: Float64Array`).
+ */
+export interface NativeGraphScores {
+  /** Entity ints, `u64` LE (8 bytes each). */
+  nodeInts: Buffer
+  /** Per-node score, `f64` LE (8 bytes each), parallel to `node_ints`. */
+  scores: Buffer
+}
+
+/**
+ * JS options bag for the engine constructor. Every field optional with
+ * sensible defaults per the [[zero-config-dynamic-adaptation]] mandate.
+ */
+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`. Below
+   * `threshold × allowed_bytes` the engine accepts writes
+   * immediately; at or above, new writes block on the flush
+   * condvar. Per the plan this is hardcoded at 0.85 — exposing
+   * it here is for TEST DRIVERS only (legitimate production use
+   * always sticks with the default).
+   */
+  admissionThresholdRatio?: number
+}
+
+/** One flushed SSTable's structured result, paired with its raw bytes. */
+export interface NativeLsmFlushResult {
+  /** Raw SSTable bytes — hand to `storage.saveBinaryBlob`. */
+  sstable: Buffer
+  /**
+   * `LsmSstableManifestEntry` JSON — the wrapper splices this into
+   * the manifest after a successful disk write.
+   */
+  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
+}
+
+/**
+ * Result of the test-only `_testFlushThroughputWithFsync` harness.
+ * Backs Phase 3 gate P3-4.
+ */
+export interface NativeLsmFlushThroughputResult {
+  /**
+   * Wall-clock elapsed nanoseconds for: `flush()` + `write_all` +
+   * `fsync`. The measured "flush throughput" is `sstable_bytes /
+   * elapsed_ns × 1e9`.
+   */
+  elapsedNs: bigint
+  /**
+   * Size of the SSTable bytes produced by `flush()` and written
+   * to disk.
+   */
+  sstableBytes: bigint
+  /** Memtable resident bytes just before the flush — diagnostic. */
+  memtableBytesPre: bigint
+}
+
+/**
+ * Result of the test-only `_testStressReaderWriterFlusher` harness.
+ * Closes Phase 3 gate P3-3 (flush during concurrent reader → no
+ * torn reads) and Phase 4 gate P4-4 (4r/1w/1f stress 100/100 → no
+ * panics, no torn reads).
+ */
+export interface NativeLsmReaderWriterStressResult {
+  /** Total reads completed across all reader threads. */
+  readsDone: bigint
+  /** Total inserts completed across all writer threads. */
+  writesDone: bigint
+  /** Total flushes the flusher executed. */
+  flushesDone: bigint
+  /**
+   * Number of torn-read events — MUST be 0 for the gate to PASS.
+   * A torn read is one where a snapshot's cardinality for its
+   * target key changed mid-snapshot. Point-in-time isolation
+   * guarantees this cannot happen.
+   */
+  tornReads: bigint
+}
+
+/**
+ * One entry materialized from an SSTable scan. Returned by
+ * [`NativeLsmEngine::scan_sstable`].
+ *
+ * `additionsBytes` / `deletionsBytes` are croaring portable
+ * serializations of the per-entry PostingLists. Cardinalities
+ * are also surfaced so consumers that only need counts don't
+ * pay the deserialize cost.
+ */
+export interface NativeLsmScanEntry {
+  field: string
+  value: string
+  additionsBytes: Buffer
+  deletionsBytes: Buffer
+  additionCount: bigint
+  deletionCount: bigint
+  epoch: bigint
+  isTombstone: boolean
+}
+
+/** Result of the test-only `_testStressConcurrentAdmission` harness. */
+export interface NativeLsmStressResult {
+  /**
+   * Highest memtable byte count observed across the run. Compare
+   * against `budget × 1.05` to verify the atomic admission
+   * guarantee held.
+   */
+  peakMemtableBytes: bigint
+  /**
+   * How many writer iterations OBSERVED `isOverAdmissionThreshold`
+   * returning true (telemetry; meant to confirm backpressure
+   * actually engaged under load).
+   */
+  nBlocked: bigint
+}
+
+/**
+ * Result of the test-only `_testWriterThroughput` harness.
+ * Backs Phase 3 gate P3-1.
+ */
+export interface NativeLsmThroughputResult {
+  /** Wall-clock elapsed nanoseconds for the workload. */
+  elapsedNs: bigint
+  /**
+   * `n_writers × per_writer` — the total number of inserts
+   * completed.
+   */
+  totalInserts: bigint
+}
+
+/** Options for `neighborhoodSample`. */
+export interface NativeNeighborhoodSampleOptions {
+  /** `"out"`, `"in"`, or `"both"` (default). */
+  direction?: string
+  /** Max hop distance from any seed (required). */
+  depth: number
+  /** Max neighbors sampled per node (required; deterministic, seeded). */
+  fanout: number
+  /**
+   * RNG seed so `(seeds, opts, seed)` yields a stable sample. Narrowed
+   * to `u64` (NaN/negative → 0); brainy passes a JS `number`.
+   */
+  seed?: number
+  /** Cap on returned nodes (sets `truncated`). */
+  maxNodes?: number
+  /** Populate `node_depth` (default true). */
+  includeDepth?: boolean
+}
+
+/**
+ * Options for `pageRank` (ADR-006 Phase C). Mirrors brainy's `PageRankOptions`
+ * (minus `excludeVisibility`, which brainy applies on hydrate — cor's graph
+ * layer has no node-visibility data).
+ */
+export interface NativePageRankOptions {
+  /** Damping factor (default 0.85). */
+  damping?: number
+  /** Max power-iterations (default 20). */
+  maxIterations?: number
+  /** L1 convergence tolerance (default 1e-6). */
+  tolerance?: number
+  /** Treat the graph as undirected (default false). */
+  undirected?: boolean
+  /** Return only the top-K by score (default: all, descending). */
+  topK?: number
+  /**
+   * **Contextual scoping (ADR-006 Phase C).** When set, rank only the
+   * induced subgraph reachable from these seed ints — "importance within
+   * this context" in O(scope) instead of O(whole graph). Omitted = global.
+   */
+  seeds?: Array<bigint>
+  /** Scope seeds as cor's OpaqueIdSet envelope (the `find()`→scope fusion). */
+  seedsOpaque?: Buffer
+  /** Hop bound for the scope neighborhood (default 2). Ignored when global. */
+  scopeDepth?: number
+}
+
+/**
+ * Options for `shortestPath`. **No `weight` field** — cor stores no edge
+ * weights, so native shortest-path is hops-only; brainy keeps `weight:'edge'`
+ * TS-side and routes only `weight:'hops'`/omitted here.
+ */
+export interface NativeShortestPathOptions {
+  /** `"out"`, `"in"`, or `"both"` (default). */
+  direction?: string
+  /** Restrict to these `VerbType` indices (empty/omitted = all). */
+  verbTypes?: Array<number>
+  /** Abandon the search past this many hops. */
+  maxDepth?: number
+}
+
+/**
+ * Columnar subgraph result — parallel typed columns packed as
+ * little-endian [`Buffer`]s, never an array of objects (ADR-006 wire
+ * format). The TS wrapper views each Buffer as a typed array
+ * (`BigInt64Array` / `Uint16Array` / `Uint8Array`) with zero element
+ * copies; brainy resolves the u64 ints to UUIDs lazily, only for the
+ * rows it renders.
+ */
+export interface NativeSubgraph {
+  /**
+   * Distinct node ints in deterministic BFS-discovery order (seeds
+   * first), `u64` little-endian (8 bytes each).
+   */
+  nodes: Buffer
+  /**
+   * Per-node BFS depth (`0` = seed), `u8`, parallel to `nodes`. Empty
+   * when `include_depth` is `false`.
+   */
+  nodeDepth: Buffer
+  /**
+   * Per-edge source node int (`u64` LE), parallel to the other edge
+   * columns. Empty when `include_edges` is `false`.
+   */
+  edgeSources: Buffer
+  /** Per-edge target node int (`u64` LE). */
+  edgeTargets: Buffer
+  /**
+   * Per-edge interned verb int (`u64` LE) — brainy maps these to
+   * verb-id strings via the existing `verbIntsToIds`.
+   */
+  edgeVerbInts: Buffer
+  /** Per-edge verb-type index (`u16` LE; `VerbType` ≪ 65535). */
+  edgeTypes: Buffer
+  /**
+   * `true` if a `max_nodes`/`max_edges` cap stopped expansion before
+   * the full `depth` was reached — the returned columns are a
+   * deterministic BFS-order prefix (page the rest via the cursor).
+   */
+  truncated: boolean
+}
+
+/** Options for `topByDegree`. */
+export interface NativeTopByDegreeOptions {
+  /** `"out"` (default), `"in"`, or `"both"`. */
+  direction?: string
+  /** Number of top nodes to return (required). */
+  topK: number
+  /**
+   * **Contextual scoping.** When set, rank degrees only within the induced
+   * subgraph reachable from these seeds (O(scope)). Omitted = global.
+   */
+  seeds?: Array<bigint>
+  /** Scope seeds as cor's OpaqueIdSet envelope. */
+  seedsOpaque?: Buffer
+  /** Hop bound for the scope neighborhood (default 2). */
+  scopeDepth?: number
+}
+
+/**
+ * **napi: build an `OpaqueIdSet` from explicit entity ints.** Constructs
+ * the `find()` → `traverse`/`search` payload from a materialized id list.
+ * `id_space` selects the bitmap width — `"U64"` for billion-scale brains,
+ * `"U32"` for ≤4 B (U32 errors on an int above `u32::MAX`). Used by cor's
+ * own emission paths and by tests; the production fusion path composes the
+ * payload via cor's roaring provider, but the envelope is identical.
+ */
+export declare function opaqueIdSetFromInts(ints: Array<bigint>, idSpace: string): Buffer
+
+/**
+ * **napi: decode an `OpaqueIdSet` back to its entity ints.** Inverse of
+ * [`opaque_id_set_from_ints`]; fails loud on a malformed envelope. For
+ * round-trip tests and any caller that needs the materialized ids.
+ */
+export declare function opaqueIdSetToInts(buf: Buffer): Array<bigint>
+
+/**
+ * Parity helper: compare two strings by UTF-8 byte order (== code-point order
+ * == brainy's `compareCodePoints`). Returns `-1`, `0`, or `1`.
+ */
+export declare function parityCompareCodePoints(a: string, b: string): number
+
+/**
+ * Parity helper: long-value hash, identical to brainy's `hashValue`
+ * (`__HASH_<base36>`). See [`hash_value`].
+ */
+export declare function parityHashValue(value: string): string
+
+/**
+ * Parity helper: FNV-1a word hash, identical to brainy's `hashWord` (signed i32).
+ * See [`hash_word`].
+ */
+export declare function parityHashWord(word: string): number
+
+/**
+ * Parity helper: normalize a JSON-encoded value exactly as brainy's
+ * `normalizeValue` with a fresh manager (default config, empty field stats so the
+ * precision strategy never fires). `value_json` is the value as JSON (e.g. `42`,
+ * `"café"`, `true`, `null`, `[1,2,3]`), matching how brainy receives raw values.
+ * See [`normalize_value`].
+ */
+export declare function parityNormalizeValue(valueJson: string): string
+
+/**
+ * Parity helper: load a `.cidx` segment from a Buffer and read
+ * every entity ID via `entity_id_big` (the IdSpace-agnostic
+ * accessor). Returns BigInt[] so values above 2^53 survive the
+ * napi crossing losslessly. The returned IDs are in the segment's
+ * stored order (the same order the writer received them).
+ */
+export declare function parityReadSegmentEntityIdsBig(buffer: Buffer): Array<bigint>
+
+/**
+ * Parity helper: load a segment, inspect its header flag, and
+ * report whether it was written with `FLAG_U64_IDS`. Used by the
+ * gap-C wire-format fixture to assert the on-disk bit assignment
+ * matches the brainy 8.0 reader's expectation.
+ */
+export declare function paritySegmentIsU64Ids(buffer: Buffer): boolean
+
+/**
+ * Parity helper: sort strings by the native column-store order (UTF-8 byte /
+ * code-point order). The returned order must equal a JS sort by
+ * `compareCodePoints`.
+ */
+export declare function paritySortStrings(values: Array<string>): Array<string>
+
+/**
+ * Parity helper: tokenize text exactly as brainy's `MetadataIndexManager.tokenize`.
+ * Returns the ordered, deduped, ASCII-only token set. See [`tokenize`].
+ */
+export declare function parityTokenize(text: string): Array<string>
+
+/**
+ * Parity helper: write a U64 float `.cidx` segment from a list
+ * of (f64 value, BigInt entity-id) pairs.
+ */
+export declare function parityWriteU64FloatSegment(field: string, values: Array<number>, entityIds: Array<bigint>): Buffer
+
+/**
+ * Parity helper: write a U64 numeric `.cidx` segment from a list
+ * of (timestamp, BigInt entity-id) pairs. Returns the segment
+ * bytes for direct inspection / round-trip verification.
+ */
+export declare function parityWriteU64NumericSegment(field: string, timestamps: Array<number>, entityIds: Array<bigint>): Buffer
+
+/**
+ * Parity helper: write a U64 string `.cidx` segment from a list
+ * of (UTF-8 string, BigInt entity-id) pairs.
+ */
+export declare function parityWriteU64StringSegment(field: string, values: Array<string>, entityIds: Array<bigint>): Buffer
+
+/**
+ * **Piece 4.** Plan a batched entity hydration for `uuids` at the
+ * given shard depth. Returns a [`HydrationPlanJs`] grouping UUIDs
+ * by shard + per-shard estimated sort cost + the
+ * migration-recommended hint.
+ *
+ * Inputs:
+ * - `uuids` — entity UUIDs to hydrate (any format normalize_uuid
+ *   accepts — hyphenated or compact, mixed case).
+ * - `shardDepth` — `2` (256 buckets, brainy default) or `3`
+ *   (16.7M buckets, cor 3.0 deep-shard layout).
+ *
+ * Throws on:
+ * - Invalid `shardDepth` (anything other than 2 or 3).
+ * - Any UUID failing normalization (empty, wrong length, non-hex).
+ *
+ * Cost: O(n) HashMap inserts where n = `uuids.len()`. The per-shard
+ * sort estimate is constant-time arithmetic. Plan cost is well under
+ * 1 µs per UUID, so brainy can call this on every query without
+ * concern.
+ */
+export declare function planHydration(uuids: Array<string>, shardDepth: number): HydrationPlan
+
+/**
+ * **Piece 13.** Plan a PQ configuration for the given entity count.
+ * Returns the recommended config — typically the input unchanged
+ * for sub-billion brains; for billion-scale brains the autotune
+ * downshifts to 4-bit codes (and lowers `ksub` to 16 accordingly).
+ * `maxBytes = 0n` uses the cor 3.0 plan's
+ * `PQ_AUTO_TUNE_MAX_CODES_BYTES` (8 GiB) default; pass an explicit
+ * value to override (e.g., for tighter / looser per-deployment
+ * budgets).
+ *
+ * **Important**: the recommended config is a PLANNING-TIME signal.
+ * Today's `NativeDiskANN.build` only implements 8-bit codes; when
+ * the autotune recommends 4-bit, brainy should surface a warning
+ * + build with 8-bit until Piece 13B's encoder lands. The
+ * `downshifted_to_4bit` field makes this branch trivial.
+ */
+export declare function pqAutoTuneConfig(numVectors: bigint, m: number, ksub: number, iterations: number, trainingSample: number, currentBitsPerCode: number, maxCodesBytes: bigint): PqAutoTuneResult
+
+/**
+ * **Piece 13.** Expose the cor 3.0 plan's autotune threshold —
+ * the codes-section size above which the autotune downshifts to
+ * 4-bit codes. Default 8 GiB. Exposed so brainy callers can
+ * surface the active threshold in operator diagnostics.
+ */
+export declare function pqAutoTuneMaxCodesBytes(): bigint
+
+/**
+ * **Piece 13.** Result of a `pqAutoTuneConfig` call — the
+ * recommended PQ configuration plus the estimated codes-section
+ * size at that configuration. Brainy callers consume this BEFORE
+ * `NativeDiskANN.build` to decide whether the recommended config
+ * is acceptable (e.g., 4-bit when the 8-bit encoder is the only
+ * one available).
+ */
+export interface PqAutoTuneResult {
+  /**
+   * `m` — number of PQ subspaces. Preserved from the input
+   * (autotune never adjusts m; see commit 1's rationale).
+   */
+  m: number
+  /**
+   * `ksub` — adjusted down to 16 when the autotune recommended
+   * 4-bit codes.
+   */
+  ksub: number
+  /** k-means iterations (preserved from input). */
+  iterations: number
+  /** Training sample (preserved from input). */
+  trainingSample: number
+  /**
+   * **Piece 13.** `4` or `8`. Bit width of the per-subspace
+   * codes. `8` is the only width the current encoder
+   * implements; `4` is the planning-time recommendation for
+   * configurations that would exceed the codes-section budget.
+   */
+  bitsPerCode: number
+  /**
+   * Estimated codes-section bytes at the returned configuration.
+   * Brainy uses this to decide whether to admit the build.
+   */
+  estimatedCodesBytes: bigint
+  /**
+   * Whether the autotune downshifted to 4-bit codes. When
+   * `true`, the recommended config is the 4-bit one; brainy
+   * today should still build with 8-bit and surface a warning
+   * (the encoder lands in Piece 13B).
+   */
+  downshiftedTo4Bit: boolean
+  /**
+   * Whether the recommended config STILL exceeds `maxBytes`.
+   * Happens at 10B+ scale where even 4-bit codes don't fit; the
+   * caller must reduce `m` or scale up the hardware. Surface,
+   * don't auto-adjust.
+   */
+  stillOverBudget: boolean
+}
+
+/**
+ * **Piece 14 (zero-config PQ).** Derive the recommended PQ subspace
+ * count `m` for a given vector `dim`, targeting `dsub ≈ 8` — the same
+ * derivation the build path applies when `m` is left at the `0`
+ * auto-sentinel. `m` always divides `dim`; for the common
+ * multiple-of-8 embedding sizes this is `dim / 8` (a clean 32×
+ * compression at 8-bit codes). Exposed as a pure planning surface so
+ * brainy can preview / log the `m` a build will choose without
+ * triggering one. Errors when `dim == 0`.
+ */
+export declare function pqDeriveM(dim: number): number
+
+/**
+ * **Piece 13.** Estimate the codes-section size in bytes for a
+ * given PQ configuration + entity count. Cheap call: integer
+ * arithmetic only. Used by brainy's pre-build admission gate +
+ * the autotune planning surface.
+ */
+export declare function pqEstimateCodesBytes(numVectors: bigint, m: number, bitsPerCode: number): bigint
+
+/** PQ codebook parameters. */
+export interface PqParams {
+  m: number
+  ksub: number
+  dsub: number
+  dim: number
+}
+
+/**
+ * Quantize a float64 vector to SQ4 (4-bit, two values per byte).
+ *
+ * Each dimension is mapped to [0, 15]. Pairs of values are packed into
+ * single bytes (high nibble first). 8x compression vs float32.
+ */
+export declare function quantizeSq4(vector: Array<number>): Sq4QuantizeResult
+
+/**
+ * Quantize a float64 vector to SQ8 (uint8 with per-vector min/max).
+ *
+ * Each dimension is mapped to [0, 255] using the vector's value range.
+ * Returns the quantized bytes plus min/max for reconstruction.
+ */
+export declare function quantizeSq8(vector: Array<number>): Sq8QuantizeResult
+
+/**
+ * Raise the soft `RLIMIT_NOFILE` to the hard limit. Idempotent + safe
+ * (no privilege needed to raise the soft limit toward the hard cap).
+ * Called once by the TS native loader on startup so the multi-tenant
+ * pool gets the full available fd headroom with zero configuration.
+ * No-op on non-Unix platforms (returns `raised: false`).
+ */
+export declare function raiseOpenFileLimit(): FileLimitInfo
+
+/**
+ * Serialize SQ8 data to compact binary format: [min:f32][max:f32][quantized bytes].
+ * Total size: 8 + dim bytes.
+ */
+export declare function serializeSq8(quantized: Buffer, min: number, max: number): Buffer
+
+/**
+ * One shard's slice of the hydration plan, JS-friendly form. See
+ * [`crate::io_batch_entities::ShardPlan`].
+ */
+export interface ShardHydrationPlan {
+  /**
+   * Filesystem-relative shard prefix. JS callers concatenate
+   * this with the storage adapter's root to produce the
+   * directory to read from.
+   */
+  shardPrefix: string
+  /**
+   * UUIDs in this shard, in original input order. The wrapper
+   * is expected to sort these before calling
+   * `storage.getNounsBatch` if the adapter benefits from
+   * sorted-key reads.
+   */
+  uuids: Array<string>
+  /**
+   * Estimated nanoseconds to sort `uuids.len()` items in this
+   * shard. `0` for shards of size 0 or 1.
+   */
+  estimatedSortNs: number
+  /**
+   * Same value, microseconds (echoed for convenience —
+   * wrappers commonly format in microseconds).
+   */
+  estimatedSortUs: number
+}
+
+/**
+ * On-disk manifest format version. Echoed so callers can pin the
+ * version in tests + diagnostics without hardcoding.
+ */
+export declare function shardMigrationManifestVersion(): number
+
+/**
+ * Read-only view of [`ShardMigrationState`] for JS callers.
+ *
+ * `stateKind` discriminates: `"idle"` / `"migrating"` /
+ * `"committing"`. Other fields are populated only when relevant to
+ * the state.
+ */
+export interface ShardMigrationStateSummary {
+  stateKind: string
+  targetDepth?: number
+  scanned?: bigint
+  total?: bigint
+  startedAtMs?: bigint
+  lastProgressAtMs?: bigint
+}
+
+/**
+ * Number of consecutive `migrationRecommended=true` hints required
+ * before [`shouldStartShardMigration`] returns `true`. Cor 3.0
+ * default = 10.
+ */
+export declare function shardMigrationSustainedThreshold(): number
+
+/**
+ * Anti-flap trigger. Returns `true` only when the tail of
+ * `recentHints` contains at least
+ * [`shardMigrationSustainedThreshold`] consecutive `true` values.
+ * Any single `false` resets the consecutive counter.
+ *
+ * Brainy maintains the sliding window (typically the last N hints
+ * from per-query `HydrationPlan.migrationRecommended` values) and
+ * calls this when deciding whether to schedule migration.
+ */
+export declare function shouldStartShardMigration(recentHints: Array<boolean>): boolean
+
+/**
+ * Select the indices of the top-K elements of `scores`, in ranked order.
+ *
+ * Runs in **O(N log K)** via a bounded max-heap of the K best candidates seen
+ * so far (vs. O(N log N) for a full sort). When `k >= scores.len()` it performs
+ * a single full sort instead, which is optimal in that regime.
+ *
+ * # Arguments
+ * * `scores` - The score for each result row, indexed 0..N.
+ * * `k` - How many top indices to return. `0` → empty; values `>= N` → all N.
+ * * `descending` - `true` ranks the highest score first; `false` the lowest.
+ *
+ * # Returns
+ * A vector of length `min(k, scores.len())` containing indices into `scores`,
+ * ordered best-first per `descending`. Ties broken by index ascending; `NaN`
+ * scores treated as worst (see the module docs for the full contract).
+ *
+ * # Example
+ * ```ignore
+ * // scores: a=0.1, b=0.9, c=0.5 ; want the best 2 (descending)
+ * let top = sort_top_k_scores(vec![0.1, 0.9, 0.5], 2, true);
+ * assert_eq!(top, vec![1, 2]); // index 1 (0.9) then index 2 (0.5)
+ * ```
+ */
+export declare function sortTopKScores(scores: Array<number>, k: number, descending: boolean): Array<number>
+
+/** Result of SQ4 quantization. */
+export interface Sq4QuantizeResult {
+  /** Packed nibbles: two 4-bit values per byte. Length = ceil(dim / 2). */
+  quantized: Buffer
+  min: number
+  max: number
+  /** Original vector dimension (needed because packed length rounds up). */
+  dim: number
+}
+
+/** Result of SQ8 quantization. */
+export interface Sq8QuantizeResult {
+  quantized: Buffer
+  min: number
+  max: number
+}
+
+/**
+ * Options for [`NativeGraphAdjacencyIndex::traverse`] — one native
+ * multi-hop BFS over the live u64 adjacency that returns the whole
+ * subgraph (nodes + edges + per-node depth) in a single boundary
+ * crossing, replacing brainy's per-node-per-hop TS BFS. See
+ * `cor/docs/ADR-006`.
+ */
+export interface TraverseOptions {
+  /**
+   * `"out"` (source→target), `"in"` (target→source), or `"both"`
+   * (union). Any other value is treated as `"both"`.
+   */
+  direction: string
+  /**
+   * Maximum hop count from the seed set. `0` returns just the seeds
+   * (no edges). Each hop expands the current frontier one level.
+   */
+  depth: number
+  /**
+   * Restrict to these `verb_type` indices (brainy's `VerbTypeEnum`
+   * index, `0..VERB_TYPE_COUNT`). `None`/empty = every verb type.
+   * Out-of-range indices are dropped. A captured edge's `edge_types`
+   * entry is the matched type.
+   */
+  verbTypes?: Array<number>
+  /**
+   * Cap on distinct nodes in the result (seeds included). When hit,
+   * expansion stops and `truncated` is set.
+   */
+  maxNodes?: number
+  /**
+   * Cap on edges in the result. When hit, expansion stops and
+   * `truncated` is set.
+   */
+  maxEdges?: number
+  /**
+   * Capture edges (default `true`). `false` returns nodes only — the
+   * cheap "who is reachable" projection.
+   */
+  includeEdges?: boolean
+  /** Populate `node_depth` (default `true`). */
+  includeDepth?: boolean
+}
+
+/**
+ * Validate a v2 license key.
+ *
+ * Steps:
+ * 1. Strip `sc_cor_` prefix (or legacy `sc_cortex_`)
+ * 2. Split JWT into header.payload.signature
+ * 3. Base64url-decode each part
+ * 4. Verify Ed25519 signature over "header.payload"
+ * 5. Parse payload JSON
+ * 6. Check product == "cor" (or legacy "cortex")
+ * 7. Check expiry (0 = perpetual, else compare to now)
+ * 8. Return result with tier info
+ */
+export declare function validateLicenseKey(token: string): LicenseResult
+
+/**
+ * **Cor 3.0.** Result from
+ * [`get_verb_endpoints`](NativeGraphAdjacencyIndex::get_verb_endpoints).
+ * 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 {
+  /**
+   * Source entity's canonical u64 int (from the brain's
+   * `BinaryIdMapper`). Same value brainy passed to
+   * `addVerbWithEndpoints*` at add time.
+   */
+  sourceInt: bigint
+  /**
+   * Target entity's canonical u64 int (from the brain's
+   * `BinaryIdMapper`).
+   */
+  targetInt: bigint
+  /**
+   * The verb's `VerbType` index (generation-stable; ADR-006 Phase A).
+   * Carried on the endpoint record so as-of-`g` reads can type an
+   * edge whose verb was removed after `g`.
+   */
+  verbType: number
+}