@soulcraft/cortex 1.3.1

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * @soulcraft/cortex — Native Rust acceleration for Brainy
+ *
+ * When installed alongside @soulcraft/brainy, this package automatically
+ * provides native Rust implementations for:
+ * - SIMD distance calculations (cosine, euclidean, manhattan, dot product)
+ * - Metadata index (full query/mutation engine in Rust)
+ * - Graph adjacency index (4 LSM-trees + verb tracking)
+ * - Entity ID mapper (UUID ↔ integer bidirectional mapping)
+ * - Roaring bitmaps (CRoaring bindings)
+ * - Embedding engine (Candle ML — CPU, CUDA, Metal)
+ * - Msgpack encoding/decoding
+ * - MmapFileSystemStorage adapter (zero-copy SSTables)
+ *
+ * Usage: `npm install @soulcraft/cortex` — auto-detected, zero config.
+ */
+// Default export: BrainyPlugin (auto-detected by brainy init())
+export { default } from './plugin.js';
+export { loadNativeModule, isNativeAvailable } from './native/index.js';
+// Re-export all native wrapper classes
+export { NativeEmbeddingEngine, nativeEmbeddingEngine, cosineSimilarity } from './native/NativeEmbeddingEngine.js';
+export { RoaringBitmap32, RoaringBitmap32Iterator, roaringLibraryInitialize, roaringLibraryIsReady, SerializationFormat, DeserializationFormat } from './native/NativeRoaringBitmap32.js';
+//# sourceMappingURL=index.js.map

package/dist/license.d.ts

@@ -0,0 +1,18 @@
+/**
+ * License validation for @soulcraft/cortex
+ *
+ * Validation order:
+ * 1. SOULCRAFT_LICENSE environment variable
+ * 2. ~/.soulcraft/license file
+ * 3. 14-day trial (tracked via ~/.soulcraft/.cortex-trial)
+ *
+ * License keys are Ed25519-signed tokens with embedded payload.
+ * Offline-only — no network calls. Soft enforcement for read-only
+ * filesystems (containers, CI).
+ */
+/**
+ * Validate the cortex license.
+ * Returns true if the license is valid or the trial is active.
+ */
+export declare function validateLicense(): Promise<boolean>;
+//# sourceMappingURL=license.d.ts.map

package/dist/license.js

@@ -0,0 +1,172 @@
+/**
+ * License validation for @soulcraft/cortex
+ *
+ * Validation order:
+ * 1. SOULCRAFT_LICENSE environment variable
+ * 2. ~/.soulcraft/license file
+ * 3. 14-day trial (tracked via ~/.soulcraft/.cortex-trial)
+ *
+ * License keys are Ed25519-signed tokens with embedded payload.
+ * Offline-only — no network calls. Soft enforcement for read-only
+ * filesystems (containers, CI).
+ */
+import { createPublicKey, verify } from 'node:crypto';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const TRIAL_DAYS = 14;
+const SOULCRAFT_DIR = '.soulcraft';
+const LICENSE_FILE = 'license';
+const TRIAL_FILE = '.cortex-trial';
+// Ed25519 public key for license verification (private key is NOT in this repo)
+const PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAKaoTwRGx57o0yHgpdB6ESEf0+9p5stIifvbKXoxCHuQ=
+-----END PUBLIC KEY-----`;
+// Ed25519 signature is always 64 bytes
+const ED25519_SIG_SIZE = 64;
+/**
+ * Validate the cortex license.
+ * Returns true if the license is valid or the trial is active.
+ */
+export async function validateLicense() {
+    // 1. Check environment variable
+    const envLicense = process.env.SOULCRAFT_LICENSE;
+    if (envLicense) {
+        const result = verifyLicenseToken(envLicense);
+        if (result.valid) {
+            return true;
+        }
+        console.warn(`[cortex] Invalid license key${result.reason ? ': ' + result.reason : ''}. ` +
+            `Get a valid license at https://soulcraft.com/pricing?focus=pro`);
+        // Fall through to trial if env key is invalid
+    }
+    // 2. Check license file
+    const soulcraftDir = join(homedir(), SOULCRAFT_DIR);
+    try {
+        const fileContent = await readFile(join(soulcraftDir, LICENSE_FILE), 'utf-8');
+        const token = fileContent.trim();
+        if (token) {
+            const result = verifyLicenseToken(token);
+            if (result.valid) {
+                return true;
+            }
+            console.warn(`[cortex] License file invalid${result.reason ? ': ' + result.reason : ''}. ` +
+                `Get a valid license at https://soulcraft.com/pricing?focus=pro`);
+        }
+    }
+    catch {
+        // No license file — fall through to trial
+    }
+    // 3. Check/create trial
+    return checkTrial(soulcraftDir);
+}
+/**
+ * Verify an Ed25519-signed license token.
+ *
+ * Token format: sc_cortex_<base64url(json_payload + ed25519_signature)>
+ * - Payload: JSON with sub, tier, exp, iat fields
+ * - Signature: 64-byte Ed25519 signature over the payload bytes
+ */
+function verifyLicenseToken(token) {
+    if (!token.startsWith('sc_cortex_')) {
+        return { valid: false, reason: 'invalid prefix' };
+    }
+    const encoded = token.slice('sc_cortex_'.length);
+    if (encoded.length < 20) {
+        return { valid: false, reason: 'token too short' };
+    }
+    let decoded;
+    try {
+        decoded = Buffer.from(encoded, 'base64url');
+    }
+    catch {
+        return { valid: false, reason: 'invalid encoding' };
+    }
+    if (decoded.length <= ED25519_SIG_SIZE) {
+        return { valid: false, reason: 'token too short' };
+    }
+    // Split: payload (everything except last 64 bytes) + signature (last 64 bytes)
+    const payloadBytes = decoded.subarray(0, decoded.length - ED25519_SIG_SIZE);
+    const signature = decoded.subarray(decoded.length - ED25519_SIG_SIZE);
+    // Verify Ed25519 signature
+    let signatureValid;
+    try {
+        const publicKey = createPublicKey(PUBLIC_KEY_PEM);
+        signatureValid = verify(null, payloadBytes, publicKey, signature);
+    }
+    catch {
+        return { valid: false, reason: 'signature verification failed' };
+    }
+    if (!signatureValid) {
+        return { valid: false, reason: 'invalid signature' };
+    }
+    // Parse payload
+    let payload;
+    try {
+        payload = JSON.parse(payloadBytes.toString('utf8'));
+    }
+    catch {
+        return { valid: false, reason: 'invalid payload' };
+    }
+    // Check expiry (empty exp = perpetual / internal keys)
+    if (payload.exp) {
+        const expiry = new Date(payload.exp);
+        if (isNaN(expiry.getTime())) {
+            return { valid: false, reason: 'invalid expiry date' };
+        }
+        if (expiry < new Date()) {
+            return { valid: false, reason: 'license expired' };
+        }
+    }
+    return { valid: true };
+}
+/**
+ * Check if the trial period is still active.
+ * Creates a trial marker file on first run.
+ */
+async function checkTrial(soulcraftDir) {
+    const trialPath = join(soulcraftDir, TRIAL_FILE);
+    try {
+        const content = await readFile(trialPath, 'utf-8');
+        const startDate = new Date(content.trim());
+        if (isNaN(startDate.getTime())) {
+            // Corrupted trial file — reset
+            return createTrial(soulcraftDir, trialPath);
+        }
+        const elapsed = Date.now() - startDate.getTime();
+        const daysElapsed = elapsed / (1000 * 60 * 60 * 24);
+        const daysRemaining = Math.ceil(TRIAL_DAYS - daysElapsed);
+        if (daysElapsed <= TRIAL_DAYS) {
+            if (daysRemaining <= 3) {
+                console.warn(`[cortex] Trial expires in ${daysRemaining} day${daysRemaining === 1 ? '' : 's'}. ` +
+                    `Purchase a license at https://soulcraft.com/pricing?focus=pro`);
+            }
+            return true;
+        }
+        // Trial expired
+        console.warn(`[cortex] Trial expired. ` +
+            `Purchase a license at https://soulcraft.com/pricing?focus=pro`);
+        return false;
+    }
+    catch {
+        // No trial file — create one (first run)
+        return createTrial(soulcraftDir, trialPath);
+    }
+}
+/**
+ * Create a new trial marker file.
+ * Soft enforcement: returns true even if filesystem is read-only.
+ */
+async function createTrial(soulcraftDir, trialPath) {
+    console.log(`[cortex] Starting 14-day trial. ` +
+        `Purchase a license at https://soulcraft.com/pricing?focus=pro`);
+    try {
+        await mkdir(soulcraftDir, { recursive: true });
+        await writeFile(trialPath, new Date().toISOString(), 'utf-8');
+    }
+    catch {
+        // Read-only filesystem (Docker, CI, etc.) — allow silently
+    }
+    return true;
+}
+//# sourceMappingURL=license.js.map

package/dist/native/NativeEmbeddingEngine.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Native Embedding Engine
+ *
+ * TypeScript wrapper matching the CandleEmbeddingEngine / WASMEmbeddingEngine API.
+ * Uses the native Rust module (napi-rs or bun:ffi) instead of WASM.
+ *
+ * Drop-in replacement: same singleton pattern, same method signatures,
+ * same model loading flow. Consumers don't need to change.
+ */
+import type { EmbeddingResult, EngineStats } from './types.js';
+/**
+ * Native embedding engine using Rust (Candle) via napi-rs.
+ *
+ * Replaces WASMEmbeddingEngine and CandleEmbeddingEngine.
+ * Same API surface for backward compatibility.
+ */
+export declare class NativeEmbeddingEngine {
+    private engine;
+    private initialized;
+    private embedCount;
+    private totalProcessingTimeMs;
+    private constructor();
+    /**
+     * Get the singleton instance
+     */
+    static getInstance(): NativeEmbeddingEngine;
+    /**
+     * Initialize the embedding engine
+     */
+    initialize(): Promise<void>;
+    /**
+     * Perform actual initialization.
+     *
+     * Loads the native module and model assets.
+     * Native module loads in <100ms (vs 3-5s for WASM compilation).
+     */
+    private performInit;
+    /**
+     * Load model assets from filesystem.
+     * Same resolution logic as the WASM modelLoader.ts.
+     */
+    private loadModelAssets;
+    private loadBunAssets;
+    private loadNodeAssets;
+    /**
+     * Generate embedding for text
+     */
+    embed(text: string): Promise<number[]>;
+    /**
+     * Generate embedding with metadata
+     */
+    embedWithMetadata(text: string): Promise<EmbeddingResult>;
+    /**
+     * Batch embed multiple texts
+     */
+    embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Check if initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get engine statistics
+     */
+    getStats(): EngineStats;
+    /**
+     * Dispose and free resources
+     */
+    dispose(): Promise<void>;
+    /**
+     * Reset singleton (for testing)
+     */
+    static resetInstance(): void;
+}
+/**
+ * Calculate cosine similarity between two embeddings (native)
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+export declare const nativeEmbeddingEngine: NativeEmbeddingEngine;
+//# sourceMappingURL=NativeEmbeddingEngine.d.ts.map

package/dist/native/NativeEmbeddingEngine.js

@@ -0,0 +1,302 @@
+/**
+ * Native Embedding Engine
+ *
+ * TypeScript wrapper matching the CandleEmbeddingEngine / WASMEmbeddingEngine API.
+ * Uses the native Rust module (napi-rs or bun:ffi) instead of WASM.
+ *
+ * Drop-in replacement: same singleton pattern, same method signatures,
+ * same model loading flow. Consumers don't need to change.
+ */
+import { MODEL_CONSTANTS } from './types.js';
+import { loadNativeModule } from './index.js';
+// Global singleton
+let globalInstance = null;
+let globalInitPromise = null;
+/**
+ * Native embedding engine using Rust (Candle) via napi-rs.
+ *
+ * Replaces WASMEmbeddingEngine and CandleEmbeddingEngine.
+ * Same API surface for backward compatibility.
+ */
+export class NativeEmbeddingEngine {
+    engine = null;
+    initialized = false;
+    embedCount = 0;
+    totalProcessingTimeMs = 0;
+    constructor() {
+        // Private constructor for singleton
+    }
+    /**
+     * Get the singleton instance
+     */
+    static getInstance() {
+        if (!globalInstance) {
+            globalInstance = new NativeEmbeddingEngine();
+        }
+        return globalInstance;
+    }
+    /**
+     * Initialize the embedding engine
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        if (globalInitPromise) {
+            await globalInitPromise;
+            return;
+        }
+        globalInitPromise = this.performInit();
+        try {
+            await globalInitPromise;
+        }
+        finally {
+            globalInitPromise = null;
+        }
+    }
+    /**
+     * Perform actual initialization.
+     *
+     * Loads the native module and model assets.
+     * Native module loads in <100ms (vs 3-5s for WASM compilation).
+     */
+    async performInit() {
+        const startTime = Date.now();
+        console.log('Initializing Native Embedding Engine...');
+        try {
+            // 1. Load native module
+            console.log('Loading native module...');
+            const native = loadNativeModule();
+            this.engine = new native.NativeEmbeddingEngine();
+            const nativeTime = Date.now() - startTime;
+            console.log(`   Native module loaded in ${nativeTime}ms`);
+            // 2. Load model assets (same flow as WASM version)
+            console.log('Loading model assets (~88MB)...');
+            const modelStartTime = Date.now();
+            const assets = await this.loadModelAssets();
+            const modelTime = Date.now() - modelStartTime;
+            console.log(`   Model loaded in ${modelTime}ms`);
+            // 3. Initialize engine with model
+            console.log('Initializing embedding engine...');
+            this.engine.load(assets.model, assets.tokenizer, assets.config);
+            if (!this.engine.isReady()) {
+                throw new Error('Engine failed to initialize');
+            }
+            this.initialized = true;
+            const initTime = Date.now() - startTime;
+            console.log(`Native Embedding Engine ready in ${initTime}ms`);
+        }
+        catch (error) {
+            this.initialized = false;
+            this.engine = null;
+            throw new Error(`Failed to initialize Native Embedding Engine: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Load model assets from filesystem.
+     * Same resolution logic as the WASM modelLoader.ts.
+     */
+    async loadModelAssets() {
+        const isBun = typeof Bun !== 'undefined';
+        if (isBun) {
+            return this.loadBunAssets();
+        }
+        return this.loadNodeAssets();
+    }
+    async loadBunAssets() {
+        const pathsToTry = [];
+        // Strategy 1: URL-resolved paths (works in Bun runtime)
+        try {
+            const modelPath = new URL('../../assets/models/all-MiniLM-L6-v2/model.safetensors', import.meta.url).pathname;
+            const tokenizerPath = new URL('../../assets/models/all-MiniLM-L6-v2/tokenizer.json', import.meta.url).pathname;
+            const configPath = new URL('../../assets/models/all-MiniLM-L6-v2/config.json', import.meta.url).pathname;
+            pathsToTry.push([modelPath, tokenizerPath, configPath]);
+        }
+        catch {
+            // skip
+        }
+        // Strategy 2: node_modules path (installed packages)
+        const nmPath = './node_modules/@soulcraft/brainy/assets/models/all-MiniLM-L6-v2';
+        pathsToTry.push([
+            `${nmPath}/model.safetensors`,
+            `${nmPath}/tokenizer.json`,
+            `${nmPath}/config.json`,
+        ]);
+        // Strategy 3: assets folder relative to CWD (local development)
+        pathsToTry.push([
+            './assets/models/all-MiniLM-L6-v2/model.safetensors',
+            './assets/models/all-MiniLM-L6-v2/tokenizer.json',
+            './assets/models/all-MiniLM-L6-v2/config.json',
+        ]);
+        for (const [modelPath, tokenizerPath, configPath] of pathsToTry) {
+            try {
+                const [model, tokenizer, config] = await Promise.all([
+                    Bun.file(modelPath).arrayBuffer(),
+                    Bun.file(tokenizerPath).arrayBuffer(),
+                    Bun.file(configPath).arrayBuffer(),
+                ]);
+                if (model.byteLength > 0 && tokenizer.byteLength > 0 && config.byteLength > 0) {
+                    return {
+                        model: Buffer.from(model),
+                        tokenizer: Buffer.from(tokenizer),
+                        config: Buffer.from(config),
+                    };
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        throw new Error('Could not load model assets. Ensure model files are accessible:\n' +
+            '  Option 1: npm install @soulcraft/brainy (includes assets)\n' +
+            '  Option 2: Copy assets/ folder to your working directory\n' +
+            '  Option 3: For bun --compile, use --asset flag');
+    }
+    async loadNodeAssets() {
+        const fs = await import('node:fs');
+        const nodePath = await import('node:path');
+        const { fileURLToPath } = await import('node:url');
+        const thisDir = nodePath.dirname(fileURLToPath(import.meta.url));
+        const assetsDir = nodePath.resolve(thisDir, '../../assets/models/all-MiniLM-L6-v2');
+        if (!fs.existsSync(assetsDir)) {
+            throw new Error(`Model assets not found: ${assetsDir}\n` +
+                `Ensure @soulcraft/brainy is installed correctly.`);
+        }
+        const [model, tokenizer, config] = await Promise.all([
+            fs.promises.readFile(nodePath.join(assetsDir, 'model.safetensors')),
+            fs.promises.readFile(nodePath.join(assetsDir, 'tokenizer.json')),
+            fs.promises.readFile(nodePath.join(assetsDir, 'config.json')),
+        ]);
+        return {
+            model: Buffer.from(model),
+            tokenizer: Buffer.from(tokenizer),
+            config: Buffer.from(config),
+        };
+    }
+    /**
+     * Generate embedding for text
+     */
+    async embed(text) {
+        const result = await this.embedWithMetadata(text);
+        return result.embedding;
+    }
+    /**
+     * Generate embedding with metadata
+     */
+    async embedWithMetadata(text) {
+        if (!this.initialized) {
+            await this.initialize();
+        }
+        if (!this.engine) {
+            throw new Error('Engine not properly initialized');
+        }
+        try {
+            const startTime = Date.now();
+            const embedding = this.engine.embed(text);
+            const processingTimeMs = Date.now() - startTime;
+            this.embedCount++;
+            this.totalProcessingTimeMs += processingTimeMs;
+            return {
+                embedding,
+                tokenCount: 0, // Candle handles tokenization internally
+                processingTimeMs,
+            };
+        }
+        catch (error) {
+            console.error('Native embed failed, marking engine for re-initialization:', error);
+            this.initialized = false;
+            this.engine = null;
+            throw error;
+        }
+    }
+    /**
+     * Batch embed multiple texts
+     */
+    async embedBatch(texts) {
+        if (!this.initialized) {
+            await this.initialize();
+        }
+        if (!this.engine) {
+            throw new Error('Engine not properly initialized');
+        }
+        if (texts.length === 0) {
+            return [];
+        }
+        try {
+            const embeddings = this.engine.embedBatch(texts);
+            this.embedCount += texts.length;
+            return embeddings;
+        }
+        catch (error) {
+            console.error('Native embedBatch failed, marking engine for re-initialization:', error);
+            this.initialized = false;
+            this.engine = null;
+            throw error;
+        }
+    }
+    /**
+     * Check if initialized
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Get engine statistics
+     */
+    getStats() {
+        if (this.engine) {
+            return this.engine.getStats();
+        }
+        return {
+            initialized: this.initialized,
+            embedCount: this.embedCount,
+            totalProcessingTimeMs: this.totalProcessingTimeMs,
+            avgProcessingTimeMs: this.embedCount > 0 ? this.totalProcessingTimeMs / this.embedCount : 0,
+            modelName: MODEL_CONSTANTS.MODEL_NAME,
+        };
+    }
+    /**
+     * Dispose and free resources
+     */
+    async dispose() {
+        // napi-rs handles cleanup via GC; just clear references
+        this.engine = null;
+        this.initialized = false;
+    }
+    /**
+     * Reset singleton (for testing)
+     */
+    static resetInstance() {
+        if (globalInstance) {
+            globalInstance.dispose();
+        }
+        globalInstance = null;
+        globalInitPromise = null;
+    }
+}
+/**
+ * Calculate cosine similarity between two embeddings (native)
+ */
+export function cosineSimilarity(a, b) {
+    try {
+        const native = loadNativeModule();
+        return native.cosineSimilarity(a, b);
+    }
+    catch {
+        // Fallback to JS implementation
+        if (a.length !== b.length || a.length === 0)
+            return 0;
+        let dot = 0, normA = 0, normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dot += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        if (normA === 0 || normB === 0)
+            return 0;
+        return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+    }
+}
+// Export singleton access
+export const nativeEmbeddingEngine = NativeEmbeddingEngine.getInstance();
+//# sourceMappingURL=NativeEmbeddingEngine.js.map