@soulcraft/cor 3.0.0-rc.1

package/dist/utils/nativeBinaryEntityIdMapper.js

@@ -0,0 +1,381 @@
+/**
+ * @module utils/nativeBinaryEntityIdMapper
+ * @description TypeScript wrapper around cor's native binary
+ * `BinaryIdMapper`. Implements brainy's `EntityIdMapperProvider` so the
+ * mmap-backed billion-scale mapper is a drop-in for the existing
+ * JSON-persisted one.
+ *
+ * ## When this engages
+ *
+ * The cor plugin registers this wrapper as the `'entityIdMapper'`
+ * provider when the storage adapter exposes `getBinaryBlobPath()` (i.e.
+ * filesystem-backed storage with cor's 2.4.0 #2 mmap-vector layer).
+ * Cloud-storage adapters fall back to the JSON variant
+ * (`NativeEntityIdMapperWrapper`) since they have no local-path concept.
+ *
+ * ## UUID format conversion
+ *
+ * Brainy passes UUIDs as strings (typically the canonical 36-char
+ * `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`). The native side works in
+ * 16-byte Buffers. This wrapper converts at the boundary. Non-canonical
+ * UUID strings (any other 32-hex-digit form) are also accepted.
+ *
+ * ## Concurrency
+ *
+ * `getOrAssign` is atomic across concurrent callers for the same UUID
+ * (256 sharded per-UUID mutexes in the native layer). Lookups are
+ * lock-free. The wrapper holds no JS-side mutable state besides the
+ * native handle.
+ *
+ * ## IdSpace (Piece 10)
+ *
+ * The wrapper supports two entity-int wire widths:
+ *
+ * - `'u32'` (default): cortex 2.x compatible — JS `number` throughout,
+ *   capped at 4.29 B entities. Persists in the legacy `int_to_uuid.bin`
+ *   v1 header.
+ * - `'u64'`: opt-in via `idSpace: 'u64'`. The native layer's `number`
+ *   surface throws in this mode, so the wrapper transparently routes
+ *   the `EntityIdMapperProvider` methods through the BigInt napi
+ *   siblings and converts BigInt → number at the boundary. Entity ints
+ *   above `Number.MAX_SAFE_INTEGER` (2^53 - 1 = ~9 PB of entities)
+ *   throw a clear `EntityIdSpaceExceeded` error so callers get a loud
+ *   failure rather than a silent precision loss.
+ *
+ * The `getOrAssignBig` / `getIntBig` / `getUuidBig` / `sizeBig`
+ * sibling methods are available on both modes and always return
+ * `bigint` losslessly — use them in u64-aware code paths that need
+ * the full u64 range.
+ */
+import { existsSync } from 'node:fs';
+import { loadNativeModule } from '../native/index.js';
+import { prodLog } from '@soulcraft/brainy/internals';
+const UUID_BYTES = 16;
+/**
+ * Thrown when a U64-mode mapper allocates or returns an entity int
+ * above `Number.MAX_SAFE_INTEGER` (2^53 - 1). At this point a JS
+ * `number` can no longer represent the value losslessly; callers must
+ * switch to the BigInt sibling methods (`getOrAssignBig`,
+ * `getIntBig`, `getUuidBig`).
+ */
+export class EntityIdSpaceExceeded extends Error {
+    /** The u64 entity int that exceeded the safe-integer ceiling. */
+    value;
+    /** The method that was called (`'getOrAssign'`, `'getInt'`, etc.). */
+    method;
+    constructor(method, value) {
+        super(`${method}: entity int ${value} exceeds Number.MAX_SAFE_INTEGER ` +
+            `(2^53 - 1). Switch to the BigInt sibling method (${method}Big) ` +
+            `for entity ints above 9.007 PB.`);
+        this.name = 'EntityIdSpaceExceeded';
+        this.method = method;
+        this.value = value;
+    }
+}
+const MAX_SAFE_INTEGER_BIG = BigInt(Number.MAX_SAFE_INTEGER);
+/**
+ * Convert a `bigint` entity int to a JS `number`. Throws
+ * {@link EntityIdSpaceExceeded} if the value exceeds the JS safe-integer
+ * range.
+ */
+function bigToSafeNumber(value, method) {
+    if (value > MAX_SAFE_INTEGER_BIG) {
+        throw new EntityIdSpaceExceeded(method, value);
+    }
+    return Number(value);
+}
+const DEFAULT_UUID_TO_INT_KEY = '_id_mapper/uuid_to_int.mkv';
+const DEFAULT_INT_TO_UUID_KEY = '_id_mapper/int_to_uuid.bin';
+/**
+ * Drop-in `EntityIdMapperProvider` backed by the native `BinaryIdMapper`.
+ *
+ * @example
+ * ```typescript
+ * const mapper = new NativeBinaryEntityIdMapperWrapper({ storage })
+ * await mapper.init()
+ * const intId = mapper.getOrAssign('12345678-1234-5678-1234-567812345678')
+ * const uuid = mapper.getUuid(intId)
+ * ```
+ */
+export class NativeBinaryEntityIdMapperWrapper {
+    storage;
+    uuidToIntKey;
+    intToUuidKey;
+    intToUuidSize;
+    uuidToIntSize;
+    bucketCapacity;
+    maxGlobalDepth;
+    requestedIdSpace;
+    /**
+     * The actual IdSpace of the open mapper, sourced from the native
+     * binding's `idSpace()` reflection after `init()`. The on-disk
+     * header wins over `requestedIdSpace` (which may be ignored at
+     * `openExisting` time).
+     */
+    resolvedIdSpace = 'u32';
+    native = null;
+    initialized = false;
+    constructor(options) {
+        this.storage = options.storage;
+        this.uuidToIntKey = options.uuidToIntKey ?? DEFAULT_UUID_TO_INT_KEY;
+        this.intToUuidKey = options.intToUuidKey ?? DEFAULT_INT_TO_UUID_KEY;
+        this.intToUuidSize = options.intToUuidSize ?? BigInt(32) * BigInt(1024) ** BigInt(3);
+        this.uuidToIntSize = options.uuidToIntSize ?? BigInt(32) * BigInt(1024) ** BigInt(3);
+        this.bucketCapacity = options.bucketCapacity ?? 16;
+        this.maxGlobalDepth = options.maxGlobalDepth ?? 28;
+        this.requestedIdSpace = options.idSpace ?? 'u64';
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        const storage = this.storage;
+        if (!storage.getBinaryBlobPath) {
+            throw new Error('NativeBinaryEntityIdMapperWrapper requires a storage adapter that ' +
+                'exposes getBinaryBlobPath() (filesystem-backed). For cloud adapters, ' +
+                'use NativeEntityIdMapperWrapper (JSON variant) instead.');
+        }
+        const uuidToIntPath = storage.getBinaryBlobPath(this.uuidToIntKey);
+        const intToUuidPath = storage.getBinaryBlobPath(this.intToUuidKey);
+        if (!uuidToIntPath || !intToUuidPath) {
+            throw new Error(`NativeBinaryEntityIdMapperWrapper: getBinaryBlobPath returned null for ` +
+                `${this.uuidToIntKey} or ${this.intToUuidKey}`);
+        }
+        const bindings = loadNativeModule();
+        const NativeBinaryIdMapper = bindings.NativeBinaryIdMapper;
+        if (!NativeBinaryIdMapper) {
+            throw new Error('NativeBinaryIdMapper binding missing from cor native module — ' +
+                'this build of cor is older than the BinaryIdMapper feature');
+        }
+        const config = {
+            uuidToIntPath,
+            intToUuidPath,
+            intToUuidSize: this.intToUuidSize,
+            uuidToIntSize: this.uuidToIntSize,
+            bucketCapacity: this.bucketCapacity,
+            maxGlobalDepth: this.maxGlobalDepth,
+            idSpace: this.requestedIdSpace,
+        };
+        // Explicitly distinguish "fresh install" from "existing files".
+        // Both files must exist together (paired write semantics) — a
+        // half-present state is corruption from a crash between file
+        // creations and is surfaced as an error rather than silently
+        // recreated.
+        const uuidFileExists = existsSync(uuidToIntPath);
+        const intFileExists = existsSync(intToUuidPath);
+        if (uuidFileExists && intFileExists) {
+            this.native = NativeBinaryIdMapper.openExisting(config);
+        }
+        else if (!uuidFileExists && !intFileExists) {
+            this.native = NativeBinaryIdMapper.create(config);
+        }
+        else {
+            throw new Error(`NativeBinaryEntityIdMapperWrapper: half-present file pair — ` +
+                `${this.uuidToIntKey} ${uuidFileExists ? 'exists' : 'missing'}, ` +
+                `${this.intToUuidKey} ${intFileExists ? 'exists' : 'missing'}. ` +
+                `Refusing to silently recreate; investigate manually.`);
+        }
+        // Reflect the on-disk IdSpace — authoritative over the requested
+        // value when openExisting opens a file with a different mode.
+        this.resolvedIdSpace = this.native.idSpace();
+        this.initialized = true;
+        if (prodLog?.debug) {
+            prodLog.debug(`[cor] BinaryIdMapper wired: paths=[${uuidToIntPath}, ${intToUuidPath}], idSpace=${this.resolvedIdSpace}`);
+        }
+    }
+    /**
+     * Report the mapper's actual IdSpace mode. Returns `'u32'` before
+     * `init()` (the default the wrapper assumes); after init, returns the
+     * mode reported by the native binding (which is authoritative).
+     */
+    getIdSpace() {
+        return this.resolvedIdSpace;
+    }
+    // -- EntityIdMapperProvider surface (number-typed, brainy contract) --
+    /**
+     * Allocate or retrieve the entity int for `uuid`. Returns a JS
+     * `number`. In U64 mode, routes through the BigInt sibling and
+     * throws {@link EntityIdSpaceExceeded} if the allocated int exceeds
+     * `Number.MAX_SAFE_INTEGER` — at that point the caller MUST switch
+     * to `getOrAssignBig` for the full u64 range.
+     */
+    getOrAssign(uuid) {
+        const native = this.ensure();
+        if (this.resolvedIdSpace === 'u64') {
+            return bigToSafeNumber(native.getOrAssignBig(this.encode(uuid)), 'getOrAssign');
+        }
+        return native.getOrAssign(this.encode(uuid));
+    }
+    /**
+     * Look up the UUID for `intId`. Accepts a JS `number` — in U64 mode
+     * this is a lossy conversion above 2^53; use {@link getUuidBig} for
+     * the full u64 range.
+     */
+    getUuid(intId) {
+        const native = this.ensure();
+        const buf = this.resolvedIdSpace === 'u64'
+            ? native.getUuidBig(BigInt(intId))
+            : native.getUuid(intId);
+        if (!buf)
+            return undefined;
+        return this.decode(buf);
+    }
+    /**
+     * Look up the entity int for `uuid`. Returns a JS `number`. In U64
+     * mode throws {@link EntityIdSpaceExceeded} if the int exceeds
+     * `Number.MAX_SAFE_INTEGER`.
+     */
+    getInt(uuid) {
+        const native = this.ensure();
+        if (this.resolvedIdSpace === 'u64') {
+            const big = native.getIntBig(this.encode(uuid));
+            return big == null ? undefined : bigToSafeNumber(big, 'getInt');
+        }
+        const out = native.getInt(this.encode(uuid));
+        return out == null ? undefined : out;
+    }
+    remove(uuid) {
+        const native = this.ensure();
+        return native.remove(this.encode(uuid));
+    }
+    async flush() {
+        const native = this.ensure();
+        native.flush();
+    }
+    async clear() {
+        // Reset by recreating the files. Atomicity caveat: any concurrent
+        // reader holds a stale mmap. Brainy calls clear() during clear()
+        // operations that already block other access; this is fine.
+        this.initialized = false;
+        this.native = null;
+        await this.init();
+    }
+    /**
+     * Materialise every live int id into a JS `number[]`. **U32 mode
+     * only.** U64 mode throws — the native binding refuses to allocate
+     * a giant JS array at the scale a U64 brain implies. Iterate via
+     * the BigInt sibling iterator (TBD — a follow-up surfaces it on the
+     * wrapper) for U64 brains.
+     */
+    getAllIntIds() {
+        const native = this.ensure();
+        if (this.resolvedIdSpace === 'u64') {
+            throw new Error('getAllIntIds: not supported in U64 mode — the materialised ' +
+                'number[] would risk OOM at billion scale. Use the BigInt ' +
+                'streaming iterator on the underlying native binding instead.');
+        }
+        return native.getAllIntIds();
+    }
+    intsIterableToUuids(ints) {
+        const native = this.ensure();
+        // ONE native call via the batched binding (which works in both u32 and u64
+        // modes), not a per-row `getUuid`/`getUuidBig` FFI crossing. The per-row
+        // loop is the pattern performance-budget.md forbids — it cost ~5ms to
+        // hydrate a 1K-row find() result (10× the batched path) on EVERY query, at
+        // every scale. Unmapped ints (`null`) are dropped, matching prior behaviour.
+        const bigInts = [];
+        for (const i of ints)
+            bigInts.push(BigInt(i));
+        const out = [];
+        for (const buf of native.intsToUuidsBig(bigInts)) {
+            if (buf)
+                out.push(this.decode(buf));
+        }
+        return out;
+    }
+    /**
+     * @description Batch-resolve entity ints to their UUIDs in one native
+     * call (ADR-006 Q5) — the provider path brainy uses to hydrate a
+     * `Subgraph`'s `nodes` column. One boundary crossing instead of N
+     * per-int `getUuidBig` calls when a viz/export renders many rows. An
+     * unmapped int yields `''` so the result stays index-aligned with the
+     * input.
+     * @param ints - The entity ints to resolve (a `BigInt64Array`, the
+     *   `Subgraph.nodes` column).
+     * @returns UUID strings index-aligned with `ints` (`''` for unmapped).
+     */
+    entityIntsToUuids(ints) {
+        const native = this.ensure();
+        return native
+            .intsToUuidsBig(Array.from(ints))
+            .map((buf) => (buf ? this.decode(buf) : ''));
+    }
+    get size() {
+        if (!this.initialized || !this.native)
+            return 0;
+        if (this.resolvedIdSpace === 'u64') {
+            return bigToSafeNumber(this.native.sizeBig(), 'size');
+        }
+        return this.native.size();
+    }
+    // -- BigInt sibling surface (u64-safe, works in both modes) -------
+    /**
+     * Allocate or retrieve the entity int for `uuid` as a `bigint`.
+     * Lossless across the full u64 range; safe to call in either mode.
+     */
+    getOrAssignBig(uuid) {
+        const native = this.ensure();
+        return native.getOrAssignBig(this.encode(uuid));
+    }
+    /** Look up the entity int for `uuid` as a `bigint`. */
+    getIntBig(uuid) {
+        const native = this.ensure();
+        const out = native.getIntBig(this.encode(uuid));
+        return out == null ? undefined : out;
+    }
+    /** Look up the UUID for `int` (passed as a `bigint`). */
+    getUuidBig(int) {
+        const native = this.ensure();
+        const buf = native.getUuidBig(int);
+        if (!buf)
+            return undefined;
+        return this.decode(buf);
+    }
+    /** Live (non-tombstone) entry count as a `bigint`. */
+    sizeBig() {
+        if (!this.initialized || !this.native)
+            return 0n;
+        return this.native.sizeBig();
+    }
+    /** Largest int ever assigned + 1, as a `bigint`. */
+    nextIntBig() {
+        return this.ensure().nextIntBig();
+    }
+    // ---------------------------------------------------------------
+    // UUID string ↔ Buffer conversion
+    // ---------------------------------------------------------------
+    /**
+     * Encode a UUID string into a 16-byte Buffer. Accepts canonical
+     * 36-char form (with hyphens) or any 32-hex-digit form. Throws on
+     * malformed input.
+     */
+    encode(uuid) {
+        const hex = uuid.replace(/-/g, '').toLowerCase();
+        if (hex.length !== 32 || !/^[0-9a-f]{32}$/.test(hex)) {
+            throw new Error(`NativeBinaryEntityIdMapperWrapper: invalid UUID string "${uuid}"`);
+        }
+        return Buffer.from(hex, 'hex');
+    }
+    /** Decode a 16-byte Buffer back to canonical UUID string. */
+    decode(buf) {
+        if (buf.length !== UUID_BYTES) {
+            throw new Error(`NativeBinaryEntityIdMapperWrapper: native returned ${buf.length}-byte uuid (expected ${UUID_BYTES})`);
+        }
+        const hex = buf.toString('hex');
+        return (hex.slice(0, 8) +
+            '-' +
+            hex.slice(8, 12) +
+            '-' +
+            hex.slice(12, 16) +
+            '-' +
+            hex.slice(16, 20) +
+            '-' +
+            hex.slice(20, 32));
+    }
+    ensure() {
+        if (!this.initialized || !this.native) {
+            throw new Error('NativeBinaryEntityIdMapperWrapper: call init() before any operation');
+        }
+        return this.native;
+    }
+}
+//# sourceMappingURL=nativeBinaryEntityIdMapper.js.map

package/dist/utils/nativeEntityIdMapper.d.ts

@@ -0,0 +1,111 @@
+/**
+ * EntityIdMapper — Bidirectional UUID ↔ integer mapping for roaring bitmaps
+ *
+ * Thin TypeScript wrapper around the native Rust NativeEntityIdMapper.
+ * All mapping operations execute synchronously in Rust (O(1) HashMap lookups).
+ * This wrapper handles async storage I/O (load from storage, persist to storage).
+ */
+import type { StorageAdapter } from '@soulcraft/brainy';
+import type { EntityIdMapperProvider } from '../providerContracts.js';
+export interface NativeEntityIdMapperWrapperOptions {
+    storage: StorageAdapter;
+    storageKey?: string;
+}
+/**
+ * Bidirectional UUID ↔ integer mapping for roaring bitmap integration.
+ * Delegates to native Rust implementation for all mapping operations.
+ *
+ * Implements {@link EntityIdMapperProvider} so a compile error fires the moment
+ * this wrapper drops or drifts a member brainy's `MetadataIndexManager` calls on
+ * an injected native mapper (incl. `getAllIntIds`).
+ */
+export declare class NativeEntityIdMapperWrapper implements EntityIdMapperProvider {
+    private storage;
+    private storageKey;
+    private native;
+    constructor(options: NativeEntityIdMapperWrapperOptions);
+    /**
+     * Initialize the mapper by loading from storage
+     */
+    init(): Promise<void>;
+    /**
+     * Get integer ID for UUID, assigning a new ID if not exists
+     */
+    getOrAssign(uuid: string): number;
+    /**
+     * Get integer ID for UUID with immediate persistence guarantee
+     */
+    getOrAssignSync(uuid: string): Promise<number>;
+    /**
+     * Get UUID for integer ID
+     */
+    getUuid(intId: number): string | undefined;
+    /**
+     * Get integer ID for UUID (without assigning if not exists)
+     */
+    getInt(uuid: string): number | undefined;
+    /**
+     * Check if UUID has been assigned an integer ID
+     */
+    has(uuid: string): boolean;
+    /**
+     * Remove mapping for UUID
+     */
+    remove(uuid: string): boolean;
+    /**
+     * Get total number of mappings
+     */
+    get size(): number;
+    /**
+     * Convert array of UUIDs to array of integers
+     */
+    uuidsToInts(uuids: string[]): number[];
+    /**
+     * Convert array of integers to array of UUIDs
+     */
+    intsToUuids(ints: number[]): string[];
+    /**
+     * Convert iterable of integers to array of UUIDs (for roaring bitmap iteration)
+     */
+    intsIterableToUuids(ints: Iterable<number>): string[];
+    /**
+     * @description Batch-resolve entity ints to their UUIDs in one native
+     * call (ADR-006 Q5) — the provider path brainy uses to hydrate a
+     * `Subgraph`'s `nodes` column. One boundary crossing instead of N
+     * per-int `getUuid` calls when a viz/export renders many rows.
+     * @param ints - The entity ints to resolve (a `BigInt64Array`, the
+     *   `Subgraph.nodes` column).
+     * @returns UUID strings index-aligned with `ints`.
+     */
+    entityIntsToUuids(ints: BigInt64Array): string[];
+    /**
+     * @description Return every assigned integer ID. This is the "all-ids universe"
+     * brainy's `MetadataIndexManager` uses to evaluate negation / `exists:false` /
+     * `missing:true` filters (the set of all known entities minus the matching set)
+     * when a native EntityIdMapper is injected into the TypeScript metadata index.
+     * Ids come from the native `int → uuid` map, so the universe is sourced from the
+     * same canonical assignment `getOrAssign` produces — no storage scan.
+     * @returns All assigned integer IDs, in unspecified order.
+     * @example
+     * const allUuids = mapper.intsIterableToUuids(mapper.getAllIntIds())
+     */
+    getAllIntIds(): number[];
+    /**
+     * Flush mappings to storage
+     */
+    flush(): Promise<void>;
+    /**
+     * Clear all mappings
+     */
+    clear(): Promise<void>;
+    /**
+     * Get statistics about the mapper
+     */
+    getStats(): {
+        mappings: number;
+        nextId: number;
+        dirty: boolean;
+        memoryEstimate: number;
+    };
+}
+//# sourceMappingURL=nativeEntityIdMapper.d.ts.map

package/dist/utils/nativeEntityIdMapper.js

@@ -0,0 +1,170 @@
+/**
+ * EntityIdMapper — Bidirectional UUID ↔ integer mapping for roaring bitmaps
+ *
+ * Thin TypeScript wrapper around the native Rust NativeEntityIdMapper.
+ * All mapping operations execute synchronously in Rust (O(1) HashMap lookups).
+ * This wrapper handles async storage I/O (load from storage, persist to storage).
+ */
+import { loadNativeModule } from '../native/index.js';
+/**
+ * Bidirectional UUID ↔ integer mapping for roaring bitmap integration.
+ * Delegates to native Rust implementation for all mapping operations.
+ *
+ * Implements {@link EntityIdMapperProvider} so a compile error fires the moment
+ * this wrapper drops or drifts a member brainy's `MetadataIndexManager` calls on
+ * an injected native mapper (incl. `getAllIntIds`).
+ */
+export class NativeEntityIdMapperWrapper {
+    storage;
+    storageKey;
+    native;
+    constructor(options) {
+        this.storage = options.storage;
+        this.storageKey = options.storageKey || 'brainy:entityIdMapper';
+        const bindings = loadNativeModule();
+        this.native = new bindings.NativeEntityIdMapper();
+    }
+    /**
+     * Initialize the mapper by loading from storage
+     */
+    async init() {
+        try {
+            const metadata = await this.storage.getMetadata(this.storageKey);
+            if (metadata && metadata.nextId !== undefined) {
+                this.native.loadFromJson(JSON.stringify(metadata));
+            }
+        }
+        catch {
+            // First time initialization — native mapper starts empty
+        }
+    }
+    /**
+     * Get integer ID for UUID, assigning a new ID if not exists
+     */
+    getOrAssign(uuid) {
+        return this.native.getOrAssign(uuid);
+    }
+    /**
+     * Get integer ID for UUID with immediate persistence guarantee
+     */
+    async getOrAssignSync(uuid) {
+        const id = this.native.getOrAssign(uuid);
+        if (this.native.isDirty()) {
+            await this.flush();
+        }
+        return id;
+    }
+    /**
+     * Get UUID for integer ID
+     */
+    getUuid(intId) {
+        return this.native.getUuid(intId) ?? undefined;
+    }
+    /**
+     * Get integer ID for UUID (without assigning if not exists)
+     */
+    getInt(uuid) {
+        return this.native.getInt(uuid) ?? undefined;
+    }
+    /**
+     * Check if UUID has been assigned an integer ID
+     */
+    has(uuid) {
+        return this.native.has(uuid);
+    }
+    /**
+     * Remove mapping for UUID
+     */
+    remove(uuid) {
+        return this.native.remove(uuid);
+    }
+    /**
+     * Get total number of mappings
+     */
+    get size() {
+        return this.native.size;
+    }
+    /**
+     * Convert array of UUIDs to array of integers
+     */
+    uuidsToInts(uuids) {
+        return this.native.uuidsToInts(uuids);
+    }
+    /**
+     * Convert array of integers to array of UUIDs
+     */
+    intsToUuids(ints) {
+        return this.native.intsToUuids(ints);
+    }
+    /**
+     * Convert iterable of integers to array of UUIDs (for roaring bitmap iteration)
+     */
+    intsIterableToUuids(ints) {
+        return this.native.intsToUuids(Array.from(ints));
+    }
+    /**
+     * @description Batch-resolve entity ints to their UUIDs in one native
+     * call (ADR-006 Q5) — the provider path brainy uses to hydrate a
+     * `Subgraph`'s `nodes` column. One boundary crossing instead of N
+     * per-int `getUuid` calls when a viz/export renders many rows.
+     * @param ints - The entity ints to resolve (a `BigInt64Array`, the
+     *   `Subgraph.nodes` column).
+     * @returns UUID strings index-aligned with `ints`.
+     */
+    entityIntsToUuids(ints) {
+        return this.native.intsToUuidsBig(Array.from(ints));
+    }
+    /**
+     * @description Return every assigned integer ID. This is the "all-ids universe"
+     * brainy's `MetadataIndexManager` uses to evaluate negation / `exists:false` /
+     * `missing:true` filters (the set of all known entities minus the matching set)
+     * when a native EntityIdMapper is injected into the TypeScript metadata index.
+     * Ids come from the native `int → uuid` map, so the universe is sourced from the
+     * same canonical assignment `getOrAssign` produces — no storage scan.
+     * @returns All assigned integer IDs, in unspecified order.
+     * @example
+     * const allUuids = mapper.intsIterableToUuids(mapper.getAllIntIds())
+     */
+    getAllIntIds() {
+        const snapshot = JSON.parse(this.native.saveToJson());
+        const intToUuid = snapshot.intToUuid ?? {};
+        const ids = [];
+        for (const key of Object.keys(intToUuid)) {
+            ids.push(Number(key));
+        }
+        return ids;
+    }
+    /**
+     * Flush mappings to storage
+     */
+    async flush() {
+        if (!this.native.isDirty()) {
+            return;
+        }
+        const json = this.native.saveToJson();
+        const data = JSON.parse(json);
+        await this.storage.saveMetadata(this.storageKey, data);
+        // Reload to clear dirty flag (native sets dirty=false on load)
+        this.native.loadFromJson(json);
+    }
+    /**
+     * Clear all mappings
+     */
+    async clear() {
+        this.native.clear();
+        await this.flush();
+    }
+    /**
+     * Get statistics about the mapper
+     */
+    getStats() {
+        const stats = this.native.getStats();
+        return {
+            mappings: stats.mappings,
+            nextId: stats.nextId,
+            dirty: stats.dirty,
+            memoryEstimate: stats.memoryEstimate,
+        };
+    }
+}
+//# sourceMappingURL=nativeEntityIdMapper.js.map