@soulcraft/cortex 1.3.1

package/dist/graph/NativeGraphAdjacencyIndex.js

@@ -0,0 +1,671 @@
+/**
+ * NativeGraphAdjacencyIndex — Thin TS wrapper around the Rust graph engine
+ *
+ * Handles async storage I/O while the Rust engine handles all in-memory
+ * data operations (4 LSM-trees, verb tracking, relationship counts).
+ *
+ * Storage pattern: adapter-controlled I/O with 3-tier fallback.
+ * - Tier 1 (mmap): saveBinaryBlob + getBinaryBlobPath → zero-copy queries
+ * - Tier 2 (binary blob): saveBinaryBlob only → binary format in memory
+ * - Tier 3 (legacy): saveMetadata → base64 JSON
+ *
+ * UnifiedCache integration stays in TS (getVerbCached, getVerbsBatchCached)
+ * since it coordinates cross-subsystem caching and requires async storage access.
+ */
+import { loadNativeModule } from '../native/index.js';
+import { getGlobalCache, prodLog } from '@soulcraft/brainy/internals';
+// Storage prefixes for each tree
+const TREE_PREFIXES = {
+    'source': 'graph-lsm-source',
+    'target': 'graph-lsm-target',
+    'verbs-source': 'graph-lsm-verbs-source',
+    'verbs-target': 'graph-lsm-verbs-target',
+};
+export class GraphAdjacencyIndex {
+    storage;
+    native;
+    unifiedCache;
+    config;
+    initialized = false;
+    isRebuilding = false;
+    flushTimer;
+    rebuildStartTime = 0;
+    totalRelationshipsIndexed = 0;
+    isCompacting = {};
+    // Adapter capability detection (set in constructor)
+    hasBinaryBlobs;
+    hasMmapPaths;
+    get isInitialized() {
+        return this.initialized;
+    }
+    constructor(storage, config = {}) {
+        this.storage = storage;
+        this.config = {
+            maxIndexSize: config.maxIndexSize ?? 100000,
+            rebuildThreshold: config.rebuildThreshold ?? 0.1,
+            autoOptimize: config.autoOptimize ?? true,
+            flushInterval: config.flushInterval ?? 30000,
+            memTableThreshold: config.memTableThreshold ?? 100000,
+            maxSSTablesPerLevel: config.maxSSTablesPerLevel ?? 10,
+        };
+        const bindings = loadNativeModule();
+        this.native = new bindings.NativeGraphAdjacencyIndex({
+            memTableThreshold: this.config.memTableThreshold,
+            maxSstablesPerLevel: this.config.maxSSTablesPerLevel,
+        });
+        this.unifiedCache = getGlobalCache();
+        // Detect adapter capabilities via optional method presence
+        this.hasBinaryBlobs = typeof storage.saveBinaryBlob === 'function';
+        this.hasMmapPaths = typeof storage.getBinaryBlobPath === 'function';
+        if (this.hasMmapPaths) {
+            prodLog.info('GraphAdjacencyIndex initialized with native Rust engine (4 embedded LSM-trees, mmap SSTable I/O)');
+        }
+        else if (this.hasBinaryBlobs) {
+            prodLog.info('GraphAdjacencyIndex initialized with native Rust engine (4 embedded LSM-trees, binary blob I/O)');
+        }
+        else {
+            prodLog.info('GraphAdjacencyIndex initialized with native Rust engine (4 embedded LSM-trees)');
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Initialization
+    // ---------------------------------------------------------------------------
+    async ensureInitialized() {
+        if (this.initialized) {
+            return;
+        }
+        // Load manifests and SSTables for all 4 trees
+        const treeNames = this.native.treeNames();
+        for (const treeName of treeNames) {
+            await this.loadTreeFromStorage(treeName);
+        }
+        // Defensive check: if LSM-trees have data but verbIdSet is empty, populate
+        const sourceSize = this.native.size();
+        if (sourceSize > 0 && this.native.verbIdCount() === 0) {
+            prodLog.warn(`GraphAdjacencyIndex: LSM-trees have ${sourceSize} relationships but verbIdSet is empty. ` +
+                `Triggering auto-rebuild to restore consistency.`);
+            await this.populateVerbIdSetFromStorage();
+        }
+        this.startAutoFlush();
+        this.initialized = true;
+    }
+    async populateVerbIdSetFromStorage() {
+        prodLog.info('GraphAdjacencyIndex: Populating verbIdSet from storage...');
+        const startTime = Date.now();
+        let hasMore = true;
+        let cursor = undefined;
+        let count = 0;
+        while (hasMore) {
+            const result = await this.storage.getVerbs({
+                pagination: { limit: 10000, cursor }
+            });
+            for (const verb of result.items) {
+                const verbType = verb.verb || 'unknown';
+                this.native.trackVerbId(verb.id, verbType);
+                count++;
+            }
+            hasMore = result.hasMore;
+            cursor = result.nextCursor;
+        }
+        const elapsed = Date.now() - startTime;
+        prodLog.info(`GraphAdjacencyIndex: Populated verbIdSet with ${count} verb IDs in ${elapsed}ms`);
+    }
+    // ---------------------------------------------------------------------------
+    // Core graph operations
+    // ---------------------------------------------------------------------------
+    async getNeighbors(id, optionsOrDirection) {
+        await this.ensureInitialized();
+        const options = typeof optionsOrDirection === 'string'
+            ? { direction: optionsOrDirection }
+            : (optionsOrDirection || {});
+        const startTime = performance.now();
+        const direction = options.direction || 'both';
+        const limit = options.limit ?? null;
+        const offset = options.offset ?? null;
+        const result = this.native.getNeighbors(id, direction, limit, offset);
+        const elapsed = performance.now() - startTime;
+        if (elapsed > 5.0) {
+            prodLog.warn(`GraphAdjacencyIndex: Slow neighbor lookup for ${id}: ${elapsed.toFixed(2)}ms`);
+        }
+        return result;
+    }
+    async getVerbIdsBySource(sourceId, options) {
+        await this.ensureInitialized();
+        const startTime = performance.now();
+        const limit = options?.limit ?? null;
+        const offset = options?.offset ?? null;
+        const result = this.native.getVerbIdsBySource(sourceId, limit, offset);
+        const elapsed = performance.now() - startTime;
+        if (elapsed > 5.0) {
+            prodLog.warn(`GraphAdjacencyIndex: Slow getVerbIdsBySource for ${sourceId}: ${elapsed.toFixed(2)}ms`);
+        }
+        return result;
+    }
+    async getVerbIdsByTarget(targetId, options) {
+        await this.ensureInitialized();
+        const startTime = performance.now();
+        const limit = options?.limit ?? null;
+        const offset = options?.offset ?? null;
+        const result = this.native.getVerbIdsByTarget(targetId, limit, offset);
+        const elapsed = performance.now() - startTime;
+        if (elapsed > 5.0) {
+            prodLog.warn(`GraphAdjacencyIndex: Slow getVerbIdsByTarget for ${targetId}: ${elapsed.toFixed(2)}ms`);
+        }
+        return result;
+    }
+    async getVerbCached(verbId) {
+        const cacheKey = `graph:verb:${verbId}`;
+        const verb = await this.unifiedCache.get(cacheKey, async () => {
+            const loadedVerb = await this.storage.getVerb(verbId);
+            if (loadedVerb) {
+                this.unifiedCache.set(cacheKey, loadedVerb, 'other', 128, 50);
+            }
+            return loadedVerb;
+        });
+        return verb;
+    }
+    async getVerbsBatchCached(verbIds) {
+        const results = new Map();
+        const uncached = [];
+        for (const verbId of verbIds) {
+            const cacheKey = `graph:verb:${verbId}`;
+            const cached = this.unifiedCache.getSync(cacheKey);
+            if (cached) {
+                results.set(verbId, cached);
+            }
+            else {
+                uncached.push(verbId);
+            }
+        }
+        if (uncached.length > 0 && this.storage.getVerbsBatch) {
+            const loadedVerbs = await this.storage.getVerbsBatch(uncached);
+            for (const [verbId, verb] of loadedVerbs.entries()) {
+                const cacheKey = `graph:verb:${verbId}`;
+                this.unifiedCache.set(cacheKey, verb, 'other', 128, 50);
+                results.set(verbId, verb);
+            }
+        }
+        return results;
+    }
+    // ---------------------------------------------------------------------------
+    // Mutation operations
+    // ---------------------------------------------------------------------------
+    async addVerb(verb) {
+        await this.ensureInitialized();
+        const startTime = performance.now();
+        const verbType = verb.verb || 'unknown';
+        const flushNeeded = this.native.addVerb(verb.id, verb.source, verb.target, verbType);
+        // Flush any trees that hit their threshold
+        const flushPromises = [];
+        if (flushNeeded.needsFlushSource) {
+            flushPromises.push(this.flushTree('source'));
+        }
+        if (flushNeeded.needsFlushTarget) {
+            flushPromises.push(this.flushTree('target'));
+        }
+        if (flushNeeded.needsFlushVerbsSource) {
+            flushPromises.push(this.flushTree('verbs-source'));
+        }
+        if (flushNeeded.needsFlushVerbsTarget) {
+            flushPromises.push(this.flushTree('verbs-target'));
+        }
+        if (flushPromises.length > 0) {
+            await Promise.all(flushPromises);
+        }
+        const elapsed = performance.now() - startTime;
+        this.totalRelationshipsIndexed++;
+        if (elapsed > 10.0) {
+            prodLog.warn(`GraphAdjacencyIndex: Slow addVerb for ${verb.id}: ${elapsed.toFixed(2)}ms`);
+        }
+    }
+    async removeVerb(verbId) {
+        await this.ensureInitialized();
+        // Load verb to get type info
+        const verb = await this.getVerbCached(verbId);
+        if (!verb)
+            return;
+        const startTime = performance.now();
+        const verbType = verb.verb || 'unknown';
+        this.native.removeVerb(verbId, verbType);
+        const elapsed = performance.now() - startTime;
+        if (elapsed > 5.0) {
+            prodLog.warn(`GraphAdjacencyIndex: Slow removeVerb for ${verbId}: ${elapsed.toFixed(2)}ms`);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Size, counts, stats
+    // ---------------------------------------------------------------------------
+    size() {
+        return this.native.size();
+    }
+    getRelationshipCountByType(type) {
+        return this.native.getRelationshipCountByType(type);
+    }
+    getTotalRelationshipCount() {
+        return this.native.verbIdCount();
+    }
+    getAllRelationshipCounts() {
+        const json = this.native.getAllRelationshipCountsJson();
+        const obj = JSON.parse(json);
+        return new Map(Object.entries(obj));
+    }
+    getRelationshipStats() {
+        const json = this.native.getRelationshipStatsJson();
+        return JSON.parse(json);
+    }
+    getStats() {
+        const stats = this.native.getStats();
+        return {
+            totalRelationships: stats.totalRelationships,
+            sourceNodes: stats.sourceSstableCount,
+            targetNodes: stats.targetSstableCount,
+            memoryUsage: stats.sourceMemTableMemory + stats.targetMemTableMemory + (stats.verbIdCount * 8),
+            lastRebuild: this.rebuildStartTime,
+            rebuildTime: this.isRebuilding ? Date.now() - this.rebuildStartTime : 0,
+        };
+    }
+    isHealthy() {
+        if (!this.initialized) {
+            return false;
+        }
+        return !this.isRebuilding && this.native.isHealthy();
+    }
+    // ---------------------------------------------------------------------------
+    // Rebuild
+    // ---------------------------------------------------------------------------
+    async rebuild() {
+        await this.ensureInitialized();
+        if (this.isRebuilding) {
+            prodLog.warn('GraphAdjacencyIndex: Rebuild already in progress');
+            return;
+        }
+        this.isRebuilding = true;
+        this.rebuildStartTime = Date.now();
+        try {
+            prodLog.info('GraphAdjacencyIndex: Starting rebuild...');
+            // Clear verb tracking (LSM-trees rebuild from storage via addVerb)
+            this.native.clearVerbTracking();
+            this.totalRelationshipsIndexed = 0;
+            const storageType = this.storage?.constructor.name || '';
+            const isLocalStorage = storageType === 'FileSystemStorage' ||
+                storageType === 'MmapFileSystemStorage' ||
+                storageType === 'MemoryStorage';
+            let totalVerbs = 0;
+            if (isLocalStorage) {
+                prodLog.info(`GraphAdjacencyIndex: Using optimized strategy (${storageType})`);
+                const result = await this.storage.getVerbs({
+                    pagination: { limit: 10000000 }
+                });
+                for (const verb of result.items) {
+                    const v = verb;
+                    const graphVerb = {
+                        id: v.id,
+                        source: v.source || v.sourceId,
+                        target: v.target || v.targetId,
+                        verb: v.verb,
+                        createdAt: typeof v.createdAt === 'number'
+                            ? { seconds: Math.floor(v.createdAt / 1000), nanoseconds: (v.createdAt % 1000) * 1000000 }
+                            : v.createdAt || { seconds: 0, nanoseconds: 0 },
+                        updatedAt: typeof v.updatedAt === 'number'
+                            ? { seconds: Math.floor(v.updatedAt / 1000), nanoseconds: (v.updatedAt % 1000) * 1000000 }
+                            : v.updatedAt || { seconds: 0, nanoseconds: 0 },
+                        createdBy: v.createdBy || { augmentation: 'unknown', version: '0.0.0' },
+                        service: v.service,
+                        data: v.data,
+                        embedding: v.vector || v.embedding,
+                        confidence: v.confidence,
+                        weight: v.weight
+                    };
+                    await this.addVerb(graphVerb);
+                    totalVerbs++;
+                }
+                prodLog.info(`GraphAdjacencyIndex: Loaded ${totalVerbs.toLocaleString()} verbs (local storage)`);
+            }
+            else {
+                prodLog.info(`GraphAdjacencyIndex: Using cloud pagination strategy (${storageType})`);
+                let hasMore = true;
+                let cursor = undefined;
+                const batchSize = 1000;
+                while (hasMore) {
+                    const result = await this.storage.getVerbs({
+                        pagination: { limit: batchSize, cursor }
+                    });
+                    for (const verb of result.items) {
+                        const v = verb;
+                        const graphVerb = {
+                            id: v.id,
+                            source: v.source || v.sourceId,
+                            target: v.target || v.targetId,
+                            verb: v.verb,
+                            createdAt: typeof v.createdAt === 'number'
+                                ? { seconds: Math.floor(v.createdAt / 1000), nanoseconds: (v.createdAt % 1000) * 1000000 }
+                                : v.createdAt || { seconds: 0, nanoseconds: 0 },
+                            updatedAt: typeof v.updatedAt === 'number'
+                                ? { seconds: Math.floor(v.updatedAt / 1000), nanoseconds: (v.updatedAt % 1000) * 1000000 }
+                                : v.updatedAt || { seconds: 0, nanoseconds: 0 },
+                            createdBy: v.createdBy || { augmentation: 'unknown', version: '0.0.0' },
+                            service: v.service,
+                            data: v.data,
+                            embedding: v.vector || v.embedding,
+                            confidence: v.confidence,
+                            weight: v.weight
+                        };
+                        await this.addVerb(graphVerb);
+                        totalVerbs++;
+                    }
+                    hasMore = result.hasMore;
+                    cursor = result.nextCursor;
+                    if (totalVerbs % 10000 === 0) {
+                        prodLog.info(`GraphAdjacencyIndex: Indexed ${totalVerbs} verbs...`);
+                    }
+                }
+                prodLog.info(`GraphAdjacencyIndex: Loaded ${totalVerbs.toLocaleString()} verbs (cloud storage)`);
+            }
+            const rebuildTime = Date.now() - this.rebuildStartTime;
+            const memoryUsage = this.calculateMemoryUsage();
+            prodLog.info(`GraphAdjacencyIndex: Rebuild complete in ${rebuildTime}ms`);
+            prodLog.info(`  - Total relationships: ${totalVerbs}`);
+            prodLog.info(`  - Memory usage: ${(memoryUsage / 1024 / 1024).toFixed(1)}MB`);
+            prodLog.info(`  - Stats:`, this.native.getStats());
+        }
+        finally {
+            this.isRebuilding = false;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Flush and close
+    // ---------------------------------------------------------------------------
+    async flush() {
+        if (!this.initialized) {
+            return;
+        }
+        const startTime = Date.now();
+        const treeNames = this.native.treeNames();
+        const flushPromises = treeNames
+            .filter(name => !this.native.memTableIsEmpty(name))
+            .map(name => this.flushTree(name));
+        if (flushPromises.length > 0) {
+            await Promise.all(flushPromises);
+        }
+        const elapsed = Date.now() - startTime;
+        prodLog.debug(`GraphAdjacencyIndex: Flush completed in ${elapsed}ms`);
+    }
+    async close() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        if (this.initialized) {
+            // Flush all trees that have pending data
+            await this.flush();
+        }
+        prodLog.info('GraphAdjacencyIndex: Shutdown complete');
+    }
+    // ---------------------------------------------------------------------------
+    // Private: Per-tree storage I/O (adapter-controlled)
+    // ---------------------------------------------------------------------------
+    /** Blob key for an SSTable: "graph-lsm/{treeName}/{sstableId}" */
+    blobKey(treeName, sstableId) {
+        return `graph-lsm/${treeName}/${sstableId}`;
+    }
+    async loadTreeFromStorage(treeName) {
+        const prefix = TREE_PREFIXES[treeName];
+        if (!prefix)
+            return;
+        try {
+            const metadata = await this.storage.getMetadata(`${prefix}-manifest`);
+            if (metadata && metadata.data) {
+                const data = metadata.data;
+                const manifestJson = JSON.stringify({
+                    sstables: data.sstables || {},
+                    lastCompaction: data.lastCompaction || Date.now(),
+                    totalRelationships: data.totalRelationships || 0,
+                });
+                this.native.loadManifestJson(treeName, manifestJson);
+                await this.loadTreeSSTables(treeName, prefix);
+            }
+        }
+        catch {
+            prodLog.debug(`GraphAdjacencyIndex: No existing manifest for ${treeName}, starting fresh`);
+        }
+    }
+    async loadTreeSSTables(treeName, prefix) {
+        const ids = this.native.getManifestSstableIds(treeName);
+        let mmapLoaded = 0;
+        let binaryLoaded = 0;
+        let legacyLoaded = 0;
+        const loadPromises = ids.map(async (sstableId) => {
+            try {
+                const level = this.native.getManifestSstableLevel(treeName, sstableId);
+                if (level === null || level === undefined) {
+                    return;
+                }
+                const key = this.blobKey(treeName, sstableId);
+                // Tier 1: Try mmap path (getBinaryBlobPath → loadSstableFromFile)
+                if (this.hasMmapPaths) {
+                    const filePath = this.storage.getBinaryBlobPath(key);
+                    if (filePath) {
+                        try {
+                            this.native.loadSstableFromFile(treeName, sstableId, level, filePath);
+                            mmapLoaded++;
+                            return;
+                        }
+                        catch {
+                            // File may not exist yet (first run), fall through
+                        }
+                    }
+                }
+                // Tier 2: Try binary blob (loadBinaryBlob → loadSstableFromBinary)
+                if (this.hasBinaryBlobs) {
+                    const blobData = await this.storage.loadBinaryBlob(key);
+                    if (blobData) {
+                        this.native.loadSstableFromBinary(treeName, sstableId, level, blobData);
+                        binaryLoaded++;
+                        return;
+                    }
+                }
+                // Tier 3: Legacy (base64 in JSON metadata)
+                const storageKey = `${prefix}-${sstableId}`;
+                const metadata = await this.storage.getMetadata(storageKey);
+                if (metadata && metadata.data) {
+                    const data = metadata.data;
+                    if (data.type === 'native-lsm-sstable' && data.data) {
+                        const buffer = Buffer.from(data.data, 'base64');
+                        this.native.loadSstable(treeName, sstableId, level, buffer);
+                        legacyLoaded++;
+                    }
+                    else if (data.type === 'lsm-sstable' && data.data) {
+                        prodLog.warn(`GraphAdjacencyIndex: Skipping legacy SSTable ${sstableId} (old TS format)`);
+                    }
+                }
+            }
+            catch (error) {
+                prodLog.warn(`GraphAdjacencyIndex: Failed to load SSTable ${sstableId} for ${treeName}`, error);
+            }
+        });
+        await Promise.all(loadPromises);
+        const parts = [];
+        if (mmapLoaded > 0)
+            parts.push(`${mmapLoaded} mmap`);
+        if (binaryLoaded > 0)
+            parts.push(`${binaryLoaded} binary`);
+        if (legacyLoaded > 0)
+            parts.push(`${legacyLoaded} legacy`);
+        const detail = parts.length > 0 ? ` (${parts.join(', ')})` : '';
+        prodLog.info(`GraphAdjacencyIndex: Loaded ${ids.length} SSTables for ${treeName}${detail}`);
+    }
+    async flushTree(treeName) {
+        if (this.native.memTableIsEmpty(treeName)) {
+            return;
+        }
+        const prefix = TREE_PREFIXES[treeName];
+        if (!prefix)
+            return;
+        const startTime = Date.now();
+        try {
+            // Binary blob flush (adapter-controlled): Rust serializes → adapter writes
+            if (this.hasBinaryBlobs) {
+                const result = this.native.flushTreeToBinary(treeName);
+                if (!result)
+                    return;
+                const key = this.blobKey(treeName, result.sstableId);
+                await this.storage.saveBinaryBlob(key, Buffer.from(result.data));
+                // If adapter supports mmap, upgrade InMemory → Mapped
+                if (this.hasMmapPaths) {
+                    const filePath = this.storage.getBinaryBlobPath(key);
+                    if (filePath) {
+                        try {
+                            this.native.registerMmapSstable(treeName, result.sstableId, result.level, filePath);
+                        }
+                        catch {
+                            // Non-fatal: InMemory variant still works
+                        }
+                    }
+                }
+                await this.saveTreeManifest(treeName, prefix);
+                const elapsed = Date.now() - startTime;
+                prodLog.info(`GraphAdjacencyIndex: Flushed ${treeName} in ${elapsed}ms (${result.entryCount} entries, ${result.relationshipCount} relationships, binary blob)`);
+                if (this.native.needsCompaction(treeName, 0)) {
+                    setImmediate(() => this.compactTree(treeName, 0));
+                }
+                return;
+            }
+            // Legacy flush (base64 in JSON)
+            const result = this.native.flushTree(treeName);
+            if (!result) {
+                return;
+            }
+            // Persist SSTable via storage adapter (base64 in JSON)
+            const storageKey = `${prefix}-${result.sstableId}`;
+            await this.storage.saveMetadata(storageKey, {
+                noun: 'thing',
+                data: {
+                    type: 'native-lsm-sstable',
+                    data: Buffer.from(result.data).toString('base64'),
+                },
+            });
+            // Save manifest
+            await this.saveTreeManifest(treeName, prefix);
+            const elapsed = Date.now() - startTime;
+            prodLog.info(`GraphAdjacencyIndex: Flushed ${treeName} in ${elapsed}ms (${result.entryCount} entries, ${result.relationshipCount} relationships)`);
+            // Check if compaction needed
+            if (this.native.needsCompaction(treeName, 0)) {
+                setImmediate(() => this.compactTree(treeName, 0));
+            }
+        }
+        catch (error) {
+            prodLog.error(`GraphAdjacencyIndex: Failed to flush ${treeName}`, error);
+            throw error;
+        }
+    }
+    async compactTree(treeName, level) {
+        if (this.isCompacting[treeName]) {
+            return;
+        }
+        this.isCompacting[treeName] = true;
+        const prefix = TREE_PREFIXES[treeName];
+        if (!prefix)
+            return;
+        const startTime = Date.now();
+        try {
+            // Binary blob compaction (adapter-controlled)
+            if (this.hasBinaryBlobs) {
+                const result = this.native.compactTreeToBinary(treeName, level);
+                if (!result)
+                    return;
+                prodLog.info(`GraphAdjacencyIndex: Compacting ${treeName} L${level} → L${result.newLevel} (binary blob)`);
+                // Save new merged SSTable via adapter
+                const newKey = this.blobKey(treeName, result.newSstableId);
+                await this.storage.saveBinaryBlob(newKey, Buffer.from(result.data));
+                // If adapter supports mmap, upgrade InMemory → Mapped
+                if (this.hasMmapPaths) {
+                    const filePath = this.storage.getBinaryBlobPath(newKey);
+                    if (filePath) {
+                        try {
+                            this.native.registerMmapSstable(treeName, result.newSstableId, result.newLevel, filePath);
+                        }
+                        catch {
+                            // Non-fatal: InMemory variant still works
+                        }
+                    }
+                }
+                // Delete old blobs (best-effort)
+                for (const oldId of result.oldIds) {
+                    const oldBlobKey = this.blobKey(treeName, oldId);
+                    this.storage.deleteBinaryBlob(oldBlobKey).catch(() => { });
+                }
+                await this.saveTreeManifest(treeName, prefix);
+                const elapsed = Date.now() - startTime;
+                prodLog.info(`GraphAdjacencyIndex: Compaction ${treeName} L${level} → L${result.newLevel} complete in ${elapsed}ms`);
+                if (result.newLevel < 6 && this.native.needsCompaction(treeName, result.newLevel)) {
+                    setImmediate(() => this.compactTree(treeName, result.newLevel));
+                }
+                return;
+            }
+            // Legacy compaction (base64 in JSON)
+            const result = this.native.compactTree(treeName, level);
+            if (!result) {
+                return;
+            }
+            prodLog.info(`GraphAdjacencyIndex: Compacting ${treeName} L${level} → L${result.newLevel}`);
+            // Save new merged SSTable
+            const storageKey = `${prefix}-${result.newSstableId}`;
+            await this.storage.saveMetadata(storageKey, {
+                noun: 'thing',
+                data: {
+                    type: 'native-lsm-sstable',
+                    data: Buffer.from(result.newData).toString('base64'),
+                },
+            });
+            // Best-effort cleanup of old SSTables
+            for (const oldId of result.oldIds) {
+                const oldKey = `${prefix}-${oldId}`;
+                this.storage.saveMetadata(oldKey, {
+                    noun: 'thing',
+                    data: { type: 'deleted' },
+                }).catch(() => { });
+            }
+            await this.saveTreeManifest(treeName, prefix);
+            const elapsed = Date.now() - startTime;
+            prodLog.info(`GraphAdjacencyIndex: Compaction ${treeName} L${level} → L${result.newLevel} complete in ${elapsed}ms`);
+            // Check next level
+            if (result.newLevel < 6 && this.native.needsCompaction(treeName, result.newLevel)) {
+                setImmediate(() => this.compactTree(treeName, result.newLevel));
+            }
+        }
+        catch (error) {
+            prodLog.error(`GraphAdjacencyIndex: Compaction failed for ${treeName} L${level}`, error);
+        }
+        finally {
+            this.isCompacting[treeName] = false;
+        }
+    }
+    async saveTreeManifest(treeName, prefix) {
+        try {
+            const manifestJson = this.native.getManifestJson(treeName);
+            const manifestData = JSON.parse(manifestJson);
+            await this.storage.saveMetadata(`${prefix}-manifest`, {
+                noun: 'thing',
+                data: manifestData,
+            });
+        }
+        catch (error) {
+            prodLog.error(`GraphAdjacencyIndex: Failed to save manifest for ${treeName}`, error);
+            throw error;
+        }
+    }
+    startAutoFlush() {
+        this.flushTimer = setInterval(async () => {
+            await this.flush();
+        }, this.config.flushInterval);
+    }
+    calculateMemoryUsage() {
+        const stats = this.native.getStats();
+        let bytes = 0;
+        bytes += stats.sourceMemTableMemory;
+        bytes += stats.targetMemTableMemory;
+        bytes += stats.verbIdCount * 8;
+        return bytes;
+    }
+}
+//# sourceMappingURL=NativeGraphAdjacencyIndex.js.map

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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.
+ */
+export { default } from './plugin.js';
+export { loadNativeModule, isNativeAvailable } from './native/index.js';
+export type { NativeBindings } from './native/types.js';
+export { NativeEmbeddingEngine, nativeEmbeddingEngine, cosineSimilarity } from './native/NativeEmbeddingEngine.js';
+export { RoaringBitmap32, RoaringBitmap32Iterator, roaringLibraryInitialize, roaringLibraryIsReady, SerializationFormat, DeserializationFormat } from './native/NativeRoaringBitmap32.js';
+//# sourceMappingURL=index.d.ts.map