@soulcraft/cortex 1.3.1

package/dist/native/NativeRoaringBitmap32.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Native Roaring Bitmap - Drop-in replacement for roaring-wasm
+ *
+ * Wraps the native Rust CRoaring module to provide the EXACT same API
+ * as roaring-wasm's RoaringBitmap32.
+ *
+ * CRoaring portable serialization format is binary-identical to
+ * roaring-wasm's portable format. Existing persisted indexes are
+ * readable without migration.
+ *
+ * All roaring bitmap consumers import from src/utils/roaring/index.ts —
+ * that module swaps the implementation to use this native wrapper.
+ */
+/**
+ * RoaringBitmap32 - native drop-in replacement for roaring-wasm.
+ *
+ * Same API surface:
+ *   Instance: .size, .isEmpty, .add(u32), .delete(u32), .tryAdd(u32), .has(u32),
+ *             .toArray(), .serialize('portable'), .deserialize(buf, 'portable'),
+ *             .getSerializationSizeInBytes('portable'), [Symbol.iterator]
+ *   Static:   RoaringBitmap32.and(a, b), .or(a, b), .orMany(arr)
+ *   Constructors: new RoaringBitmap32(), new RoaringBitmap32([1,2,3])
+ */
+export declare class RoaringBitmap32 {
+    private inner;
+    constructor(values?: Iterable<number>);
+    /** Create from an existing native instance (internal use) */
+    private static fromNative;
+    /** 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 */
+    delete(value: number): void;
+    /** Add a value, return true if newly added */
+    tryAdd(value: number): boolean;
+    /** Check if the bitmap contains a value */
+    has(value: number): boolean;
+    /** Convert to array of u32 values (sorted) */
+    toArray(): number[];
+    /**
+     * Serialize to portable format.
+     * The format parameter is accepted for roaring-wasm API compatibility
+     * but native always uses portable format (binary-identical).
+     */
+    serialize(_format?: 'portable' | boolean): Buffer;
+    /**
+     * Deserialize from portable format buffer (instance method).
+     * Replaces the contents of this bitmap with the deserialized data.
+     * Matches roaring-wasm instance method API.
+     */
+    deserialize(buffer: Buffer | Uint8Array, _format?: 'portable' | boolean): void;
+    /**
+     * Get serialization size in bytes.
+     * The format parameter is accepted for roaring-wasm API compatibility.
+     */
+    getSerializationSizeInBytes(_format?: 'portable' | boolean): number;
+    /** Get minimum value (undefined if empty) */
+    minimum(): number | undefined;
+    /** Get maximum value (undefined if empty) */
+    maximum(): number | undefined;
+    /** Iterator support for for...of loops */
+    [Symbol.iterator](): IterableIterator<number>;
+    /** Deserialize from portable format buffer */
+    static deserialize(buffer: Buffer | Uint8Array, _format?: 'portable' | boolean): RoaringBitmap32;
+    /** Compute intersection (AND) of two bitmaps */
+    static and(a: RoaringBitmap32, b: RoaringBitmap32): RoaringBitmap32;
+    /** Compute union (OR) of two bitmaps */
+    static or(a: RoaringBitmap32, b: RoaringBitmap32): RoaringBitmap32;
+    /** Compute union (OR) of multiple bitmaps */
+    static orMany(bitmaps: RoaringBitmap32[]): RoaringBitmap32;
+    /** Compute difference (AND NOT) */
+    static andNot(a: RoaringBitmap32, b: RoaringBitmap32): RoaringBitmap32;
+    /** Compute symmetric difference (XOR) */
+    static xor(a: RoaringBitmap32, b: RoaringBitmap32): RoaringBitmap32;
+}
+/**
+ * RoaringBitmap32Iterator - for roaring-wasm API compatibility.
+ * Uses the native toArray() under the hood.
+ */
+export declare class RoaringBitmap32Iterator implements IterableIterator<number> {
+    private values;
+    private index;
+    constructor(bitmap: RoaringBitmap32);
+    next(): IteratorResult<number>;
+    [Symbol.iterator](): IterableIterator<number>;
+}
+/**
+ * roaringLibraryInitialize - no-op for native (ready at load time).
+ * Kept for API compatibility with roaring-wasm.
+ */
+export declare function roaringLibraryInitialize(): Promise<void>;
+/**
+ * roaringLibraryIsReady - always true for native.
+ * Kept for API compatibility with roaring-wasm.
+ */
+export declare function roaringLibraryIsReady(): boolean;
+/**
+ * Serialization format enum - for API compatibility with roaring-wasm.
+ */
+export declare const SerializationFormat: {
+    readonly portable: "portable";
+    readonly croaring: "croaring";
+};
+/**
+ * Deserialization format enum - for API compatibility with roaring-wasm.
+ */
+export declare const DeserializationFormat: {
+    readonly portable: "portable";
+    readonly croaring: "croaring";
+};
+//# sourceMappingURL=NativeRoaringBitmap32.d.ts.map

package/dist/native/NativeRoaringBitmap32.js

@@ -0,0 +1,221 @@
+/**
+ * Native Roaring Bitmap - Drop-in replacement for roaring-wasm
+ *
+ * Wraps the native Rust CRoaring module to provide the EXACT same API
+ * as roaring-wasm's RoaringBitmap32.
+ *
+ * CRoaring portable serialization format is binary-identical to
+ * roaring-wasm's portable format. Existing persisted indexes are
+ * readable without migration.
+ *
+ * All roaring bitmap consumers import from src/utils/roaring/index.ts —
+ * that module swaps the implementation to use this native wrapper.
+ */
+import { loadNativeModule } from './index.js';
+// Lazily loaded native module
+let _native = null;
+function getNative() {
+    if (!_native) {
+        _native = loadNativeModule();
+    }
+    return _native;
+}
+/**
+ * RoaringBitmap32 - native drop-in replacement for roaring-wasm.
+ *
+ * Same API surface:
+ *   Instance: .size, .isEmpty, .add(u32), .delete(u32), .tryAdd(u32), .has(u32),
+ *             .toArray(), .serialize('portable'), .deserialize(buf, 'portable'),
+ *             .getSerializationSizeInBytes('portable'), [Symbol.iterator]
+ *   Static:   RoaringBitmap32.and(a, b), .or(a, b), .orMany(arr)
+ *   Constructors: new RoaringBitmap32(), new RoaringBitmap32([1,2,3])
+ */
+export class RoaringBitmap32 {
+    inner;
+    constructor(values) {
+        const native = getNative();
+        if (values) {
+            const arr = Array.isArray(values) ? values : Array.from(values);
+            this.inner = new native.NativeRoaringBitmap32(arr);
+        }
+        else {
+            this.inner = new native.NativeRoaringBitmap32();
+        }
+    }
+    /** Create from an existing native instance (internal use) */
+    static fromNative(inner) {
+        const bm = Object.create(RoaringBitmap32.prototype);
+        bm.inner = inner;
+        return bm;
+    }
+    // =========================================================================
+    // Instance properties
+    // =========================================================================
+    /** Number of values in the bitmap */
+    get size() {
+        return this.inner.size;
+    }
+    /** Whether the bitmap is empty */
+    get isEmpty() {
+        return this.inner.isEmpty;
+    }
+    // =========================================================================
+    // Instance methods
+    // =========================================================================
+    /** Add a value to the bitmap */
+    add(value) {
+        this.inner.add(value);
+    }
+    /** Remove a value from the bitmap */
+    delete(value) {
+        this.inner.delete(value);
+    }
+    /** Add a value, return true if newly added */
+    tryAdd(value) {
+        return this.inner.tryAdd(value);
+    }
+    /** Check if the bitmap contains a value */
+    has(value) {
+        return this.inner.has(value);
+    }
+    /** Convert to array of u32 values (sorted) */
+    toArray() {
+        return this.inner.toArray();
+    }
+    /**
+     * Serialize to portable format.
+     * The format parameter is accepted for roaring-wasm API compatibility
+     * but native always uses portable format (binary-identical).
+     */
+    serialize(_format) {
+        return this.inner.serialize();
+    }
+    /**
+     * Deserialize from portable format buffer (instance method).
+     * Replaces the contents of this bitmap with the deserialized data.
+     * Matches roaring-wasm instance method API.
+     */
+    deserialize(buffer, _format) {
+        const native = getNative();
+        const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer);
+        this.inner = native.NativeRoaringBitmap32.deserialize(buf);
+    }
+    /**
+     * Get serialization size in bytes.
+     * The format parameter is accepted for roaring-wasm API compatibility.
+     */
+    getSerializationSizeInBytes(_format) {
+        return this.inner.serializationSizeInBytes();
+    }
+    /** Get minimum value (undefined if empty) */
+    minimum() {
+        return this.inner.minimum();
+    }
+    /** Get maximum value (undefined if empty) */
+    maximum() {
+        return this.inner.maximum();
+    }
+    /** Iterator support for for...of loops */
+    *[Symbol.iterator]() {
+        const arr = this.inner.toArray();
+        for (const v of arr) {
+            yield v;
+        }
+    }
+    // =========================================================================
+    // Static methods (match roaring-wasm static API)
+    // =========================================================================
+    /** Deserialize from portable format buffer */
+    static deserialize(buffer, _format) {
+        const native = getNative();
+        const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer);
+        const inner = native.NativeRoaringBitmap32.deserialize(buf);
+        return RoaringBitmap32.fromNative(inner);
+    }
+    /** Compute intersection (AND) of two bitmaps */
+    static and(a, b) {
+        const native = getNative();
+        const inner = native.NativeRoaringBitmap32.and(a.inner, b.inner);
+        return RoaringBitmap32.fromNative(inner);
+    }
+    /** Compute union (OR) of two bitmaps */
+    static or(a, b) {
+        const native = getNative();
+        const inner = native.NativeRoaringBitmap32.or(a.inner, b.inner);
+        return RoaringBitmap32.fromNative(inner);
+    }
+    /** Compute union (OR) of multiple bitmaps */
+    static orMany(bitmaps) {
+        if (bitmaps.length === 0) {
+            return new RoaringBitmap32();
+        }
+        if (bitmaps.length === 1) {
+            return bitmaps[0];
+        }
+        const native = getNative();
+        const inner = native.NativeRoaringBitmap32.orMany(bitmaps.map(bm => bm.inner));
+        return RoaringBitmap32.fromNative(inner);
+    }
+    /** Compute difference (AND NOT) */
+    static andNot(a, b) {
+        const native = getNative();
+        const inner = native.NativeRoaringBitmap32.andNot(a.inner, b.inner);
+        return RoaringBitmap32.fromNative(inner);
+    }
+    /** Compute symmetric difference (XOR) */
+    static xor(a, b) {
+        const native = getNative();
+        const inner = native.NativeRoaringBitmap32.xor(a.inner, b.inner);
+        return RoaringBitmap32.fromNative(inner);
+    }
+}
+/**
+ * RoaringBitmap32Iterator - for roaring-wasm API compatibility.
+ * Uses the native toArray() under the hood.
+ */
+export class RoaringBitmap32Iterator {
+    values;
+    index = 0;
+    constructor(bitmap) {
+        this.values = bitmap.toArray();
+    }
+    next() {
+        if (this.index < this.values.length) {
+            return { value: this.values[this.index++], done: false };
+        }
+        return { value: undefined, done: true };
+    }
+    [Symbol.iterator]() {
+        return this;
+    }
+}
+/**
+ * roaringLibraryInitialize - no-op for native (ready at load time).
+ * Kept for API compatibility with roaring-wasm.
+ */
+export async function roaringLibraryInitialize() {
+    // Native module is ready at load time - no WASM compilation needed
+    return Promise.resolve();
+}
+/**
+ * roaringLibraryIsReady - always true for native.
+ * Kept for API compatibility with roaring-wasm.
+ */
+export function roaringLibraryIsReady() {
+    return true;
+}
+/**
+ * Serialization format enum - for API compatibility with roaring-wasm.
+ */
+export const SerializationFormat = {
+    portable: 'portable',
+    croaring: 'croaring',
+};
+/**
+ * Deserialization format enum - for API compatibility with roaring-wasm.
+ */
+export const DeserializationFormat = {
+    portable: 'portable',
+    croaring: 'croaring',
+};
+//# sourceMappingURL=NativeRoaringBitmap32.js.map

package/dist/native/ffi.d.ts

@@ -0,0 +1,20 @@
+/**
+ * bun:ffi bindings loader
+ *
+ * Loads the native module via bun:ffi + dlopen for bun --compile on Linux.
+ * The .so file is embedded in the compiled binary via static import.
+ *
+ * This is the PREFERRED production deployment path:
+ *   bun build --compile my-app.ts --outfile my-app
+ *
+ * For development and other platforms, use napi.ts instead.
+ */
+import type { NativeBindings } from './types.js';
+/**
+ * Load the native module via bun:ffi.
+ *
+ * Only available on Linux with Bun.
+ * Falls back to napi-rs on other platforms or if FFI loading fails.
+ */
+export declare function loadViaFFI(): NativeBindings;
+//# sourceMappingURL=ffi.d.ts.map

package/dist/native/ffi.js

@@ -0,0 +1,48 @@
+/**
+ * bun:ffi bindings loader
+ *
+ * Loads the native module via bun:ffi + dlopen for bun --compile on Linux.
+ * The .so file is embedded in the compiled binary via static import.
+ *
+ * This is the PREFERRED production deployment path:
+ *   bun build --compile my-app.ts --outfile my-app
+ *
+ * For development and other platforms, use napi.ts instead.
+ */
+/**
+ * Load the native module via bun:ffi.
+ *
+ * Only available on Linux with Bun.
+ * Falls back to napi-rs on other platforms or if FFI loading fails.
+ */
+export function loadViaFFI() {
+    // bun:ffi is only available in Bun
+    if (typeof Bun === 'undefined') {
+        throw new Error('bun:ffi is only available in Bun runtime');
+    }
+    if (process.platform !== 'linux') {
+        throw new Error('bun:ffi native loading is only supported on Linux');
+    }
+    // Dynamic import of bun:ffi — this is a Bun built-in
+    // The .so file path is resolved at build time for bun --compile
+    // For runtime Bun, it falls back to the local build path
+    throw new Error('bun:ffi loader not yet implemented. ' +
+        'Requires native build output (libbrainy_native.so). ' +
+        'Use napi-rs loader instead.');
+    // Future implementation:
+    // import nativeLib from '../../native/target/release/libbrainy_native.so' with { type: 'file' }
+    // import { dlopen, FFIType } from 'bun:ffi'
+    //
+    // const lib = dlopen(nativeLib, {
+    //   brainy_engine_create: { returns: FFIType.ptr },
+    //   brainy_engine_load: { args: [...], returns: FFIType.i32 },
+    //   brainy_engine_embed: { args: [...], returns: FFIType.ptr },
+    //   brainy_roaring_create: { returns: FFIType.ptr },
+    //   brainy_roaring_add: { args: [FFIType.ptr, FFIType.u32], returns: FFIType.void },
+    //   brainy_cosine_distance: { args: [FFIType.ptr, FFIType.ptr, FFIType.u32], returns: FFIType.f64 },
+    //   // ... etc
+    // })
+    //
+    // return wrapFFIAsNativeBindings(lib)
+}
+//# sourceMappingURL=ffi.js.map

package/dist/native/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Native Module - Public API
+ *
+ * Auto-detects the best loading strategy:
+ * 1. Bun --compile on Linux: bun:ffi with embedded .so (fastest)
+ * 2. All platforms: napi-rs .node file (universal)
+ *
+ * Exports the unified NativeBindings interface that all consumers use.
+ */
+import type { NativeBindings } from './types.js';
+/**
+ * Load the native module using the best available strategy.
+ *
+ * Returns a cached reference on subsequent calls.
+ *
+ * Loading priority:
+ * 1. Bun --compile on Linux → bun:ffi + embedded .so
+ * 2. All platforms → napi-rs .node file
+ */
+export declare function loadNativeModule(): NativeBindings;
+/**
+ * Check if the native module is available.
+ * Does not throw - returns false if loading fails.
+ */
+export declare function isNativeAvailable(): boolean;
+export type { NativeBindings, NativeEmbeddingEngineInstance, NativeRoaringBitmap32Instance, EmbeddingResult, EngineStats, DeviceInfo, } from './types.js';
+export { MODEL_CONSTANTS } from './types.js';
+export { NativeEmbeddingEngine, nativeEmbeddingEngine, cosineSimilarity, } from './NativeEmbeddingEngine.js';
+export { RoaringBitmap32, RoaringBitmap32Iterator, roaringLibraryInitialize, roaringLibraryIsReady, SerializationFormat, DeserializationFormat, } from './NativeRoaringBitmap32.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/native/index.js

@@ -0,0 +1,58 @@
+/**
+ * Native Module - Public API
+ *
+ * Auto-detects the best loading strategy:
+ * 1. Bun --compile on Linux: bun:ffi with embedded .so (fastest)
+ * 2. All platforms: napi-rs .node file (universal)
+ *
+ * Exports the unified NativeBindings interface that all consumers use.
+ */
+import { loadViaNapi } from './napi.js';
+import { loadViaFFI } from './ffi.js';
+// Cached module reference
+let cachedModule = null;
+/**
+ * Load the native module using the best available strategy.
+ *
+ * Returns a cached reference on subsequent calls.
+ *
+ * Loading priority:
+ * 1. Bun --compile on Linux → bun:ffi + embedded .so
+ * 2. All platforms → napi-rs .node file
+ */
+export function loadNativeModule() {
+    if (cachedModule) {
+        return cachedModule;
+    }
+    // Strategy 1: Bun --compile on Linux (bun:ffi)
+    if (process.platform === 'linux' && typeof Bun !== 'undefined') {
+        try {
+            cachedModule = loadViaFFI();
+            return cachedModule;
+        }
+        catch {
+            // Fall through to napi-rs (Bun runtime, not compiled binary)
+        }
+    }
+    // Strategy 2: All platforms (napi-rs)
+    cachedModule = loadViaNapi();
+    return cachedModule;
+}
+/**
+ * Check if the native module is available.
+ * Does not throw - returns false if loading fails.
+ */
+export function isNativeAvailable() {
+    try {
+        loadNativeModule();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export { MODEL_CONSTANTS } from './types.js';
+// Re-export engine and roaring wrappers
+export { NativeEmbeddingEngine, nativeEmbeddingEngine, cosineSimilarity, } from './NativeEmbeddingEngine.js';
+export { RoaringBitmap32, RoaringBitmap32Iterator, roaringLibraryInitialize, roaringLibraryIsReady, SerializationFormat, DeserializationFormat, } from './NativeRoaringBitmap32.js';
+//# sourceMappingURL=index.js.map

package/dist/native/napi.d.ts

@@ -0,0 +1,21 @@
+/**
+ * napi-rs bindings loader
+ *
+ * Loads the native module via napi-rs .node files.
+ * Works with: Node.js, Bun runtime, Bun --compile (all platforms).
+ *
+ * Resolution order:
+ * 1. Bundled platform binary: native/brainy-native.{platform-key}.node (shipped in npm package)
+ * 2. Local dev build: native/brainy-native.node (for development, no platform suffix)
+ * 3. Clear error with supported platforms list
+ */
+import type { NativeBindings } from './types.js';
+/**
+ * Load the native module via napi-rs.
+ *
+ * Tries multiple resolution strategies:
+ * 1. Bundled platform binary (native/brainy-native.{platform-key}.node)
+ * 2. Local dev build (native/brainy-native.node)
+ */
+export declare function loadViaNapi(): NativeBindings;
+//# sourceMappingURL=napi.d.ts.map

package/dist/native/napi.js

@@ -0,0 +1,88 @@
+/**
+ * napi-rs bindings loader
+ *
+ * Loads the native module via napi-rs .node files.
+ * Works with: Node.js, Bun runtime, Bun --compile (all platforms).
+ *
+ * Resolution order:
+ * 1. Bundled platform binary: native/brainy-native.{platform-key}.node (shipped in npm package)
+ * 2. Local dev build: native/brainy-native.node (for development, no platform suffix)
+ * 3. Clear error with supported platforms list
+ */
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+let cachedBindings = null;
+/** Platform keys matching napi-rs build output */
+const PLATFORM_KEY_MAP = {
+    'linux-x64': 'linux-x64-gnu',
+    'linux-arm64': 'linux-arm64-gnu',
+    'darwin-arm64': 'darwin-arm64',
+    'darwin-x64': 'darwin-x64',
+    'win32-x64': 'win32-x64-msvc'
+};
+const SUPPORTED_PLATFORMS = Object.keys(PLATFORM_KEY_MAP);
+/**
+ * Load the native module via napi-rs.
+ *
+ * Tries multiple resolution strategies:
+ * 1. Bundled platform binary (native/brainy-native.{platform-key}.node)
+ * 2. Local dev build (native/brainy-native.node)
+ */
+export function loadViaNapi() {
+    if (cachedBindings) {
+        return cachedBindings;
+    }
+    const platform = process.platform;
+    const arch = process.arch;
+    const key = `${platform}-${arch}`;
+    const platformKey = PLATFORM_KEY_MAP[key];
+    if (!platformKey) {
+        throw new Error(`Unsupported platform: ${key}. ` +
+            `Brainy native module supports: ${SUPPORTED_PLATFORMS.join(', ')}`);
+    }
+    const { createRequire } = loadModule('node:module');
+    const require = createRequire(import.meta.url);
+    // Resolve native/ directory relative to package root
+    // This file lives at dist/native/napi.js → package root is ../../
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const nativeDir = join(__dirname, '..', '..', 'native');
+    // Strategy 1: Bundled platform binary (shipped in npm package)
+    try {
+        const binaryPath = join(nativeDir, `brainy-native.${platformKey}.node`);
+        const bindings = require(binaryPath);
+        cachedBindings = bindings;
+        return bindings;
+    }
+    catch {
+        // Fall through to strategy 2
+    }
+    // Strategy 2: Local dev build (no platform suffix)
+    try {
+        const devPath = join(nativeDir, 'brainy-native.node');
+        const bindings = require(devPath);
+        cachedBindings = bindings;
+        return bindings;
+    }
+    catch {
+        // Fall through to error
+    }
+    throw new Error(`Failed to load Brainy native module for ${key}.\n` +
+        `Looked for:\n` +
+        `  - native/brainy-native.${platformKey}.node (bundled binary)\n` +
+        `  - native/brainy-native.node (local dev build)\n` +
+        `Build locally: cd native && npm run build`);
+}
+/**
+ * Synchronously load a Node.js built-in module.
+ * Workaround for ESM dynamic import restrictions.
+ */
+function loadModule(moduleName) {
+    if (typeof require === 'function') {
+        return require(moduleName);
+    }
+    if (typeof process !== 'undefined' && process.getBuiltinModule) {
+        return process.getBuiltinModule(moduleName);
+    }
+    throw new Error(`Cannot synchronously load module: ${moduleName}`);
+}
+//# sourceMappingURL=napi.js.map