@soulcraft/brainy 3.42.0 → 3.43.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [3.43.1](https://github.com/soulcraftlabs/brainy/compare/v3.43.0...v3.43.1) (2025-10-14)
+
+
+### 🐛 Bug Fixes
+
+* **dependencies**: migrate from roaring (native C++) to roaring-wasm for universal compatibility ([b2afcad](https://github.com/soulcraftlabs/brainy/commit/b2afcad))
+  - Eliminates native compilation requirements (no python, make, gcc/g++ needed)
+  - Works in all environments (Node.js, browsers, serverless, Docker, Lambda, Cloud Run)
+  - Same API and performance (100% compatible RoaringBitmap32 interface)
+  - 90% memory savings maintained vs JavaScript Sets
+  - Hardware-accelerated bitmap operations unchanged
+  - WebAssembly-based for cross-platform compatibility
+
+**Impact**: Fixes installation failures on systems without native build tools. Users can now `npm install @soulcraft/brainy` without any prerequisites.
+
 ### [3.41.1](https://github.com/soulcraftlabs/brainy/compare/v3.41.0...v3.41.1) (2025-10-13)
 
 - test: skip failing delete test temporarily (7c47de8)

package/dist/augmentations/KnowledgeAugmentation.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Knowledge Layer Augmentation for VFS
+ *
+ * Adds intelligent features to VFS without modifying core functionality:
+ * - Event recording for all operations
+ * - Semantic versioning based on content changes
+ * - Entity and concept extraction
+ * - Git bridge for import/export
+ *
+ * This is a TRUE augmentation - VFS works perfectly without it
+ */
+import { Brainy } from '../brainy.js';
+import { BaseAugmentation } from './brainyAugmentation.js';
+export declare class KnowledgeAugmentation extends BaseAugmentation {
+    name: string;
+    timing: 'after';
+    metadata: 'none';
+    operations: any;
+    priority: number;
+    constructor(config?: any);
+    execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
+    private eventRecorder?;
+    private semanticVersioning?;
+    private entitySystem?;
+    private conceptSystem?;
+    private gitBridge?;
+    private originalMethods;
+    initialize(context: any): Promise<void>;
+    augment(brain: Brainy): Promise<void>;
+    /**
+     * Wrap a VFS method to add Knowledge Layer functionality
+     */
+    private wrapMethod;
+    /**
+     * Add Knowledge Layer methods to VFS
+     */
+    private addKnowledgeMethods;
+    private isSemanticChange;
+    cleanup(brain: Brainy): Promise<void>;
+}

package/dist/augmentations/KnowledgeAugmentation.js

@@ -0,0 +1,251 @@
+/**
+ * Knowledge Layer Augmentation for VFS
+ *
+ * Adds intelligent features to VFS without modifying core functionality:
+ * - Event recording for all operations
+ * - Semantic versioning based on content changes
+ * - Entity and concept extraction
+ * - Git bridge for import/export
+ *
+ * This is a TRUE augmentation - VFS works perfectly without it
+ */
+import { BaseAugmentation } from './brainyAugmentation.js';
+import { EventRecorder } from '../vfs/EventRecorder.js';
+import { SemanticVersioning } from '../vfs/SemanticVersioning.js';
+import { PersistentEntitySystem } from '../vfs/PersistentEntitySystem.js';
+import { ConceptSystem } from '../vfs/ConceptSystem.js';
+import { GitBridge } from '../vfs/GitBridge.js';
+export class KnowledgeAugmentation extends BaseAugmentation {
+    constructor(config = {}) {
+        super(config);
+        this.name = 'knowledge';
+        this.timing = 'after'; // Process after VFS operations
+        this.metadata = 'none'; // No metadata access needed
+        this.operations = []; // VFS-specific augmentation, no operation interception
+        this.priority = 100; // Run last
+        this.originalMethods = new Map();
+    }
+    async execute(operation, params, next) {
+        // Pass through - this augmentation works at VFS level, not operation level
+        return await next();
+    }
+    async initialize(context) {
+        await this.augment(context.brain);
+    }
+    async augment(brain) {
+        // Only augment if VFS exists
+        const vfs = brain.vfs?.();
+        if (!vfs) {
+            console.warn('KnowledgeAugmentation: VFS not found, skipping');
+            return;
+        }
+        // Initialize Knowledge Layer components
+        this.eventRecorder = new EventRecorder(brain);
+        this.semanticVersioning = new SemanticVersioning(brain);
+        this.entitySystem = new PersistentEntitySystem(brain);
+        this.conceptSystem = new ConceptSystem(brain);
+        this.gitBridge = new GitBridge(vfs, brain);
+        // Wrap VFS methods to add intelligence WITHOUT slowing them down
+        this.wrapMethod(vfs, 'writeFile', async (original, path, data, options) => {
+            // Call original first (stays fast)
+            const result = await original.call(vfs, path, data, options);
+            // Knowledge processing in background (non-blocking)
+            setImmediate(async () => {
+                try {
+                    // Record event
+                    if (this.eventRecorder) {
+                        await this.eventRecorder.recordEvent({
+                            type: 'write',
+                            path,
+                            content: data,
+                            size: data.length,
+                            author: options?.author || 'system'
+                        });
+                    }
+                    // Check for semantic versioning
+                    if (this.semanticVersioning) {
+                        const existingContent = await vfs.readFile(path).catch(() => null);
+                        const shouldVersion = existingContent && this.isSemanticChange(existingContent, data);
+                        if (shouldVersion) {
+                            await this.semanticVersioning.createVersion(path, data, {
+                                message: 'Automatic semantic version'
+                            });
+                        }
+                    }
+                    // Extract concepts
+                    if (this.conceptSystem && options?.extractConcepts !== false) {
+                        await this.conceptSystem.extractAndLinkConcepts(path, data);
+                    }
+                    // Extract entities
+                    if (this.entitySystem && options?.extractEntities !== false) {
+                        await this.entitySystem.extractEntities(data.toString('utf8'), data);
+                    }
+                }
+                catch (error) {
+                    // Knowledge Layer errors should not affect VFS operations
+                    console.debug('KnowledgeLayer background processing error:', error);
+                }
+            });
+            return result;
+        });
+        this.wrapMethod(vfs, 'unlink', async (original, path) => {
+            const result = await original.call(vfs, path);
+            // Record deletion event
+            setImmediate(async () => {
+                if (this.eventRecorder) {
+                    await this.eventRecorder.recordEvent({
+                        type: 'delete',
+                        path,
+                        author: 'system'
+                    });
+                }
+            });
+            return result;
+        });
+        this.wrapMethod(vfs, 'rename', async (original, oldPath, newPath) => {
+            const result = await original.call(vfs, oldPath, newPath);
+            // Record rename event
+            setImmediate(async () => {
+                if (this.eventRecorder) {
+                    await this.eventRecorder.recordEvent({
+                        type: 'rename',
+                        path: oldPath,
+                        metadata: { newPath },
+                        author: 'system'
+                    });
+                }
+            });
+            return result;
+        });
+        // Add Knowledge Layer methods to VFS
+        this.addKnowledgeMethods(vfs);
+        console.log('✨ Knowledge Layer augmentation enabled');
+    }
+    /**
+     * Wrap a VFS method to add Knowledge Layer functionality
+     */
+    wrapMethod(vfs, methodName, wrapper) {
+        const original = vfs[methodName];
+        if (!original)
+            return;
+        // Store original for cleanup
+        this.originalMethods.set(methodName, original);
+        // Replace with wrapped version
+        vfs[methodName] = async (...args) => {
+            return await wrapper(original, ...args);
+        };
+    }
+    /**
+     * Add Knowledge Layer methods to VFS
+     */
+    addKnowledgeMethods(vfs) {
+        // Event history
+        vfs.getHistory = async (path, options) => {
+            if (!this.eventRecorder)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.eventRecorder.getHistory(path, options);
+        };
+        vfs.reconstructAtTime = async (path, timestamp) => {
+            if (!this.eventRecorder)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.eventRecorder.reconstructFileAtTime(path, timestamp);
+        };
+        // Semantic versioning
+        vfs.getVersions = async (path) => {
+            if (!this.semanticVersioning)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.semanticVersioning.getVersions(path);
+        };
+        vfs.restoreVersion = async (path, versionId) => {
+            if (!this.semanticVersioning)
+                throw new Error('Knowledge Layer not initialized');
+            const version = await this.semanticVersioning.getVersion(path, versionId);
+            if (version) {
+                await vfs.writeFile(path, version);
+            }
+        };
+        // Entities
+        vfs.findEntity = async (query) => {
+            if (!this.entitySystem)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.entitySystem.findEntity(query);
+        };
+        vfs.getEntityAppearances = async (entityId) => {
+            if (!this.entitySystem)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.entitySystem.getEvolution(entityId);
+        };
+        // Concepts
+        vfs.getConcepts = async (path) => {
+            if (!this.conceptSystem)
+                throw new Error('Knowledge Layer not initialized');
+            const concepts = await this.conceptSystem.findConcepts({ manifestedIn: path });
+            return concepts;
+        };
+        vfs.getConceptGraph = async (options) => {
+            if (!this.conceptSystem)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.conceptSystem.getConceptGraph(options);
+        };
+        // Git bridge
+        vfs.exportToGit = async (vfsPath, gitPath) => {
+            if (!this.gitBridge)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.gitBridge.exportToGit(vfsPath, gitPath);
+        };
+        vfs.importFromGit = async (gitPath, vfsPath) => {
+            if (!this.gitBridge)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.gitBridge.importFromGit(gitPath, vfsPath);
+        };
+        // Temporal coupling
+        vfs.findTemporalCoupling = async (path, windowMs) => {
+            if (!this.eventRecorder)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.eventRecorder.findTemporalCoupling(path, windowMs);
+        };
+    }
+    isSemanticChange(oldContent, newContent) {
+        // Simple heuristic - significant size change or different content
+        const oldStr = oldContent.toString('utf8');
+        const newStr = newContent.toString('utf8');
+        // Check for significant size change (>10%)
+        const sizeDiff = Math.abs(oldStr.length - newStr.length) / oldStr.length;
+        if (sizeDiff > 0.1)
+            return true;
+        // Check for structural changes (simplified)
+        const oldLines = oldStr.split('\n').filter(l => l.trim());
+        const newLines = newStr.split('\n').filter(l => l.trim());
+        // Different number of non-empty lines
+        return Math.abs(oldLines.length - newLines.length) > 5;
+    }
+    async cleanup(brain) {
+        const vfs = brain.vfs?.();
+        if (!vfs)
+            return;
+        // Restore original methods
+        for (const [methodName, original] of this.originalMethods) {
+            vfs[methodName] = original;
+        }
+        // Remove added methods
+        delete vfs.getHistory;
+        delete vfs.reconstructAtTime;
+        delete vfs.getVersions;
+        delete vfs.restoreVersion;
+        delete vfs.findEntity;
+        delete vfs.getEntityAppearances;
+        delete vfs.getConcepts;
+        delete vfs.getConceptGraph;
+        delete vfs.exportToGit;
+        delete vfs.importFromGit;
+        delete vfs.findTemporalCoupling;
+        // Clean up components
+        this.eventRecorder = undefined;
+        this.semanticVersioning = undefined;
+        this.entitySystem = undefined;
+        this.conceptSystem = undefined;
+        this.gitBridge = undefined;
+        console.log('Knowledge Layer augmentation removed');
+    }
+}
+//# sourceMappingURL=KnowledgeAugmentation.js.map

package/dist/brainy.js

@@ -100,6 +100,7 @@ export class Brainy {
             this.index = this.setupIndex();
             // Initialize core metadata index
             this.metadataIndex = new MetadataIndexManager(this.storage);
+            await this.metadataIndex.init();
             // Initialize core graph index
             this.graphIndex = new GraphAdjacencyIndex(this.storage);
             // Rebuild indexes if needed for existing data

package/dist/types/brainyDataInterface.d.ts

@@ -0,0 +1,52 @@
+/**
+ * BrainyInterface - Modern API Only
+ *
+ * This interface defines the MODERN methods from Brainy 3.0.
+ * Used to break circular dependencies while enforcing modern API usage.
+ *
+ * NO DEPRECATED METHODS - Only clean, modern API patterns.
+ */
+import { Vector } from '../coreTypes.js';
+import { AddParams, RelateParams, Result, Entity, FindParams, SimilarParams } from './brainy.types.js';
+export interface BrainyInterface<T = unknown> {
+    /**
+     * Initialize the database
+     */
+    init(): Promise<void>;
+    /**
+     * Modern add method - unified entity creation
+     * @param params Parameters for adding entities
+     * @returns The ID of the created entity
+     */
+    add(params: AddParams<T>): Promise<string>;
+    /**
+     * Modern relate method - unified relationship creation
+     * @param params Parameters for creating relationships
+     * @returns The ID of the created relationship
+     */
+    relate(params: RelateParams<T>): Promise<string>;
+    /**
+     * Modern find method - unified search and discovery
+     * @param query Search query or parameters object
+     * @returns Array of search results
+     */
+    find(query: string | FindParams<T>): Promise<Result<T>[]>;
+    /**
+     * Modern get method - retrieve entities by ID
+     * @param id The entity ID to retrieve
+     * @returns Entity or null if not found
+     */
+    get(id: string): Promise<Entity<T> | null>;
+    /**
+     * Modern similar method - find similar entities
+     * @param params Parameters for similarity search
+     * @returns Array of similar entities with scores
+     */
+    similar(params: SimilarParams<T>): Promise<Result<T>[]>;
+    /**
+     * Generate embedding vector from text
+     * @param text The text to embed
+     * @returns Vector representation of the text
+     */
+    embed(text: string): Promise<Vector>;
+}

package/dist/types/brainyDataInterface.js

@@ -0,0 +1,10 @@
+/**
+ * BrainyInterface - Modern API Only
+ *
+ * This interface defines the MODERN methods from Brainy 3.0.
+ * Used to break circular dependencies while enforcing modern API usage.
+ *
+ * NO DEPRECATED METHODS - Only clean, modern API patterns.
+ */
+export {};
+//# sourceMappingURL=brainyDataInterface.js.map

package/dist/utils/entityIdMapper.d.ts

@@ -0,0 +1,93 @@
+/**
+ * EntityIdMapper - Bidirectional mapping between UUID strings and integer IDs for roaring bitmaps
+ *
+ * Roaring bitmaps require 32-bit unsigned integers, but Brainy uses UUID strings as entity IDs.
+ * This class provides efficient bidirectional mapping with persistence support.
+ *
+ * Features:
+ * - O(1) lookup in both directions
+ * - Persistent storage via storage adapter
+ * - Atomic counter for next ID
+ * - Serialization/deserialization support
+ *
+ * @module utils/entityIdMapper
+ */
+import type { StorageAdapter } from '../coreTypes.js';
+export interface EntityIdMapperOptions {
+    storage: StorageAdapter;
+    storageKey?: string;
+}
+export interface EntityIdMapperData {
+    nextId: number;
+    uuidToInt: Record<string, number>;
+    intToUuid: Record<number, string>;
+}
+/**
+ * Maps entity UUIDs to integer IDs for use with Roaring Bitmaps
+ */
+export declare class EntityIdMapper {
+    private storage;
+    private storageKey;
+    private uuidToInt;
+    private intToUuid;
+    private nextId;
+    private dirty;
+    constructor(options: EntityIdMapperOptions);
+    /**
+     * Initialize the mapper by loading from storage
+     */
+    init(): Promise<void>;
+    /**
+     * Get integer ID for UUID, assigning a new ID if not exists
+     */
+    getOrAssign(uuid: string): number;
+    /**
+     * Get UUID for integer ID
+     */
+    getUuid(intId: number): string | undefined;
+    /**
+     * Get integer ID for UUID (without assigning if not exists)
+     */
+    getInt(uuid: string): number | undefined;
+    /**
+     * Check if UUID has been assigned an integer ID
+     */
+    has(uuid: string): boolean;
+    /**
+     * Remove mapping for UUID
+     */
+    remove(uuid: string): boolean;
+    /**
+     * Get total number of mappings
+     */
+    get size(): number;
+    /**
+     * Convert array of UUIDs to array of integers
+     */
+    uuidsToInts(uuids: string[]): number[];
+    /**
+     * Convert array of integers to array of UUIDs
+     */
+    intsToUuids(ints: number[]): string[];
+    /**
+     * Convert iterable of integers to array of UUIDs (for roaring bitmap iteration)
+     */
+    intsIterableToUuids(ints: Iterable<number>): string[];
+    /**
+     * Flush mappings to storage
+     */
+    flush(): Promise<void>;
+    /**
+     * Clear all mappings
+     */
+    clear(): Promise<void>;
+    /**
+     * Get statistics about the mapper
+     */
+    getStats(): {
+        mappings: number;
+        nextId: number;
+        dirty: boolean;
+        memoryEstimate: number;
+    };
+}

package/dist/utils/entityIdMapper.js

@@ -0,0 +1,169 @@
+/**
+ * EntityIdMapper - Bidirectional mapping between UUID strings and integer IDs for roaring bitmaps
+ *
+ * Roaring bitmaps require 32-bit unsigned integers, but Brainy uses UUID strings as entity IDs.
+ * This class provides efficient bidirectional mapping with persistence support.
+ *
+ * Features:
+ * - O(1) lookup in both directions
+ * - Persistent storage via storage adapter
+ * - Atomic counter for next ID
+ * - Serialization/deserialization support
+ *
+ * @module utils/entityIdMapper
+ */
+/**
+ * Maps entity UUIDs to integer IDs for use with Roaring Bitmaps
+ */
+export class EntityIdMapper {
+    constructor(options) {
+        // Bidirectional maps
+        this.uuidToInt = new Map();
+        this.intToUuid = new Map();
+        // Atomic counter for next ID
+        this.nextId = 1;
+        // Dirty flag for persistence
+        this.dirty = false;
+        this.storage = options.storage;
+        this.storageKey = options.storageKey || 'brainy:entityIdMapper';
+    }
+    /**
+     * Initialize the mapper by loading from storage
+     */
+    async init() {
+        try {
+            const data = await this.storage.getMetadata(this.storageKey);
+            if (data) {
+                this.nextId = data.nextId;
+                // Rebuild maps from serialized data
+                this.uuidToInt = new Map(Object.entries(data.uuidToInt).map(([k, v]) => [k, Number(v)]));
+                this.intToUuid = new Map(Object.entries(data.intToUuid).map(([k, v]) => [Number(k), v]));
+            }
+        }
+        catch (error) {
+            // First time initialization - maps are empty, nextId = 1
+        }
+    }
+    /**
+     * Get integer ID for UUID, assigning a new ID if not exists
+     */
+    getOrAssign(uuid) {
+        const existing = this.uuidToInt.get(uuid);
+        if (existing !== undefined) {
+            return existing;
+        }
+        // Assign new ID
+        const newId = this.nextId++;
+        this.uuidToInt.set(uuid, newId);
+        this.intToUuid.set(newId, uuid);
+        this.dirty = true;
+        return newId;
+    }
+    /**
+     * Get UUID for integer ID
+     */
+    getUuid(intId) {
+        return this.intToUuid.get(intId);
+    }
+    /**
+     * Get integer ID for UUID (without assigning if not exists)
+     */
+    getInt(uuid) {
+        return this.uuidToInt.get(uuid);
+    }
+    /**
+     * Check if UUID has been assigned an integer ID
+     */
+    has(uuid) {
+        return this.uuidToInt.has(uuid);
+    }
+    /**
+     * Remove mapping for UUID
+     */
+    remove(uuid) {
+        const intId = this.uuidToInt.get(uuid);
+        if (intId === undefined) {
+            return false;
+        }
+        this.uuidToInt.delete(uuid);
+        this.intToUuid.delete(intId);
+        this.dirty = true;
+        return true;
+    }
+    /**
+     * Get total number of mappings
+     */
+    get size() {
+        return this.uuidToInt.size;
+    }
+    /**
+     * Convert array of UUIDs to array of integers
+     */
+    uuidsToInts(uuids) {
+        return uuids.map(uuid => this.getOrAssign(uuid));
+    }
+    /**
+     * Convert array of integers to array of UUIDs
+     */
+    intsToUuids(ints) {
+        const result = [];
+        for (const intId of ints) {
+            const uuid = this.intToUuid.get(intId);
+            if (uuid) {
+                result.push(uuid);
+            }
+        }
+        return result;
+    }
+    /**
+     * Convert iterable of integers to array of UUIDs (for roaring bitmap iteration)
+     */
+    intsIterableToUuids(ints) {
+        const result = [];
+        for (const intId of ints) {
+            const uuid = this.intToUuid.get(intId);
+            if (uuid) {
+                result.push(uuid);
+            }
+        }
+        return result;
+    }
+    /**
+     * Flush mappings to storage
+     */
+    async flush() {
+        if (!this.dirty) {
+            return;
+        }
+        // Convert maps to plain objects for serialization
+        const data = {
+            nextId: this.nextId,
+            uuidToInt: Object.fromEntries(this.uuidToInt),
+            intToUuid: Object.fromEntries(this.intToUuid)
+        };
+        await this.storage.saveMetadata(this.storageKey, data);
+        this.dirty = false;
+    }
+    /**
+     * Clear all mappings
+     */
+    async clear() {
+        this.uuidToInt.clear();
+        this.intToUuid.clear();
+        this.nextId = 1;
+        this.dirty = true;
+        await this.flush();
+    }
+    /**
+     * Get statistics about the mapper
+     */
+    getStats() {
+        return {
+            mappings: this.uuidToInt.size,
+            nextId: this.nextId,
+            dirty: this.dirty,
+            memoryEstimate: this.uuidToInt.size * (36 + 8 + 4 + 8) // uuid string + map overhead + int + map overhead
+        };
+    }
+}
+//# sourceMappingURL=entityIdMapper.js.map