@soulcraft/cortex 2.7.2 → 2.7.3

package/dist/utils/nativeBinaryEntityIdMapper.d.ts

@@ -0,0 +1,199 @@
+/**
+ * @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 type { StorageAdapter } from '@soulcraft/brainy';
+import type { EntityIdMapperProvider } from '../providerContracts.js';
+export interface NativeBinaryEntityIdMapperOptions {
+    /** Storage adapter — required for binary blob path resolution. */
+    storage: StorageAdapter;
+    /**
+     * Override the relative path under storage for the uuid_to_int file.
+     * Default `_id_mapper/uuid_to_int.mkv`.
+     */
+    uuidToIntKey?: string;
+    /**
+     * Override the relative path under storage for the int_to_uuid file.
+     * Default `_id_mapper/int_to_uuid.bin`.
+     */
+    intToUuidKey?: string;
+    /** Sparse file size for int_to_uuid. Default 32 GB. */
+    intToUuidSize?: bigint;
+    /** Sparse file size for uuid_to_int. Default 32 GB. */
+    uuidToIntSize?: bigint;
+    /** Bucket capacity in the MmapKv. Default 16. */
+    bucketCapacity?: number;
+    /** Maximum extendible-hash directory depth. Default 28. */
+    maxGlobalDepth?: number;
+    /**
+     * Entity-int wire width. **`'u64'` is the default** for cor 3.0 —
+     * supports `u64::MAX - 1` entities with no measurable perf cost
+     * (audit: 4 extra bytes per int_to_uuid slot, no impact on the hot
+     * paths per `findPerfGates.test.ts`). `'u32'` is available for the
+     * brainy 7.x-compatible cap at 4.29 B entities but is no longer the
+     * default — cor 3.0's design floor of 1 B+ entities makes u32
+     * the wrong default for production.
+     *
+     * The `EntityIdMapperProvider` `number`-typed methods still work in
+     * U64 mode by routing through the BigInt napi siblings; entity ints
+     * above `Number.MAX_SAFE_INTEGER` (2^53 - 1) throw an explicit
+     * `EntityIdSpaceExceeded` error.
+     *
+     * Ignored on open when the underlying file's header disagrees: the
+     * on-disk format wins and any mismatch is surfaced as a hard error.
+     */
+    idSpace?: 'u32' | 'u64';
+}
+/**
+ * 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 declare class EntityIdSpaceExceeded extends Error {
+    /** The u64 entity int that exceeded the safe-integer ceiling. */
+    readonly value: bigint;
+    /** The method that was called (`'getOrAssign'`, `'getInt'`, etc.). */
+    readonly method: string;
+    constructor(method: string, value: bigint);
+}
+/**
+ * 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 declare class NativeBinaryEntityIdMapperWrapper implements EntityIdMapperProvider {
+    private storage;
+    private uuidToIntKey;
+    private intToUuidKey;
+    private intToUuidSize;
+    private uuidToIntSize;
+    private bucketCapacity;
+    private maxGlobalDepth;
+    private 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).
+     */
+    private resolvedIdSpace;
+    private native;
+    private initialized;
+    constructor(options: NativeBinaryEntityIdMapperOptions);
+    init(): Promise<void>;
+    /**
+     * 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(): 'u32' | 'u64';
+    /**
+     * 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: string): number;
+    /**
+     * 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: number): string | undefined;
+    /**
+     * 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: string): number | undefined;
+    remove(uuid: string): boolean;
+    flush(): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * 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(): number[];
+    intsIterableToUuids(ints: Iterable<number>): string[];
+    get size(): number;
+    /**
+     * 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: string): bigint;
+    /** Look up the entity int for `uuid` as a `bigint`. */
+    getIntBig(uuid: string): bigint | undefined;
+    /** Look up the UUID for `int` (passed as a `bigint`). */
+    getUuidBig(int: bigint): string | undefined;
+    /** Live (non-tombstone) entry count as a `bigint`. */
+    sizeBig(): bigint;
+    /** Largest int ever assigned + 1, as a `bigint`. */
+    nextIntBig(): bigint;
+    /**
+     * 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.
+     */
+    private encode;
+    /** Decode a 16-byte Buffer back to canonical UUID string. */
+    private decode;
+    private ensure;
+}
+//# sourceMappingURL=nativeBinaryEntityIdMapper.d.ts.map

package/dist/utils/nativeBinaryEntityIdMapper.js

@@ -0,0 +1,358 @@
+/**
+ * @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();
+        const u64 = this.resolvedIdSpace === 'u64';
+        const out = [];
+        for (const i of ints) {
+            const buf = u64 ? native.getUuidBig(BigInt(i)) : native.getUuid(i);
+            if (buf)
+                out.push(this.decode(buf));
+        }
+        return out;
+    }
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/cortex",
-  "version": "2.7.2",
+  "version": "2.7.3",
   "description": "Native Rust acceleration for Brainy — SIMD distance, vector quantization, zero-copy mmap, native embeddings. Free tier for storage, Pro license for compute acceleration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",