@soulcraft/brainy 5.2.0 → 5.3.0

package/dist/brainy.js

@@ -16,6 +16,7 @@ import { NaturalLanguageProcessor } from './neural/naturalLanguageProcessor.js';
 import { NeuralEntityExtractor } from './neural/entityExtractor.js';
 import { TripleIntelligenceSystem } from './triple/TripleIntelligenceSystem.js';
 import { VirtualFileSystem } from './vfs/VirtualFileSystem.js';
+import { VersioningAPI } from './versioning/VersioningAPI.js';
 import { MetadataIndexManager } from './utils/metadataIndex.js';
 import { GraphAdjacencyIndex } from './graph/graphAdjacencyIndex.js';
 import { CommitBuilder } from './storage/cow/CommitObject.js';
@@ -1868,7 +1869,20 @@ export class Brainy {
             }
             const refManager = this.storage.refManager;
             const currentBranch = this.storage.currentBranch || 'main';
-            // Step 1: Copy storage ref (COW layer - instant!)
+            // Step 1: Ensure initial commit exists (required for fork)
+            const currentRef = await refManager.getRef(currentBranch);
+            if (!currentRef) {
+                // Auto-create initial commit if none exists
+                await this.commit({
+                    message: `Initial commit on ${currentBranch}`,
+                    author: options?.author || 'Brainy',
+                    metadata: { timestamp: Date.now() }
+                });
+                if (!this.config.silent) {
+                    console.log(`📝 Auto-created initial commit on ${currentBranch} (required for fork)`);
+                }
+            }
+            // Step 2: Copy storage ref (COW layer - instant!)
             await refManager.copyRef(currentBranch, branchName);
             // Step 2: Create new Brainy instance pointing to fork branch
             const forkConfig = {
@@ -2038,7 +2052,7 @@ export class Brainy {
             // Build and persist commit (returns hash directly)
             const commitHash = await builder.build();
             // Update branch ref to point to new commit
-            await refManager.setRef(`heads/${currentBranch}`, commitHash, {
+            await refManager.setRef(currentBranch, commitHash, {
                 author: options?.author || 'unknown',
                 message: options?.message || 'Snapshot commit'
             });
@@ -2491,6 +2505,37 @@ export class Brainy {
         }
         return this._neural;
     }
+    /**
+     * Versioning API - Entity version control (v5.3.0)
+     *
+     * Provides entity-level versioning with:
+     * - save() - Create version of entity
+     * - restore() - Restore entity to specific version
+     * - list() - List all versions of entity
+     * - compare() - Deep diff between versions
+     * - prune() - Remove old versions (retention policies)
+     *
+     * @example
+     * ```typescript
+     * // Save current state
+     * const version = await brain.versions.save('user-123', { tag: 'v1.0' })
+     *
+     * // List versions
+     * const versions = await brain.versions.list('user-123')
+     *
+     * // Restore to previous version
+     * await brain.versions.restore('user-123', 5)
+     *
+     * // Compare versions
+     * const diff = await brain.versions.compare('user-123', 2, 5)
+     * ```
+     */
+    get versions() {
+        if (!this._versions) {
+            this._versions = new VersioningAPI(this);
+        }
+        return this._versions;
+    }
     /**
      * Natural Language Processing API
      */
@@ -3711,12 +3756,19 @@ export class Brainy {
             const graphIndexSize = await this.graphIndex.size();
             const needsRebuild = metadataStats.totalEntries === 0 ||
                 hnswIndexSize === 0 ||
-                graphIndexSize === 0 ||
-                this.config.disableAutoRebuild === false; // Explicitly enabled
+                graphIndexSize === 0;
             if (!needsRebuild) {
                 // All indexes already populated, no rebuild needed
                 return;
             }
+            // BUG FIX: If disableAutoRebuild is truthy, skip rebuild even if indexes are empty
+            // Indexes will load lazily on first query
+            if (this.config.disableAutoRebuild) {
+                if (!this.config.silent) {
+                    console.log('⚡ Indexes empty but auto-rebuild disabled - using lazy loading');
+                }
+                return;
+            }
             // Small dataset: Rebuild all indexes for best performance
             if (totalCount < AUTO_REBUILD_THRESHOLD || this.config.disableAutoRebuild === false) {
                 if (!this.config.silent) {

package/dist/versioning/VersionDiff.d.ts

@@ -0,0 +1,112 @@
+/**
+ * VersionDiff - Deep Object Comparison for Entity Versions (v5.3.0)
+ *
+ * Provides deep diff between entity versions:
+ * - Field-level change detection
+ * - Nested object comparison
+ * - Array diffing
+ * - Type change detection
+ * - Human-readable diff output
+ *
+ * NO MOCKS - Production implementation
+ */
+import type { NounMetadata } from '../coreTypes.js';
+/**
+ * Types of changes in a diff
+ */
+export type ChangeType = 'added' | 'removed' | 'modified' | 'type-changed';
+/**
+ * A single field change in a diff
+ */
+export interface FieldChange {
+    /** Path to the field (e.g., 'metadata.user.name') */
+    path: string;
+    /** Type of change */
+    type: ChangeType;
+    /** Old value (undefined for 'added') */
+    oldValue?: any;
+    /** New value (undefined for 'removed') */
+    newValue?: any;
+    /** Old type (for 'type-changed') */
+    oldType?: string;
+    /** New type (for 'type-changed') */
+    newType?: string;
+}
+/**
+ * Complete diff between two versions
+ */
+export interface VersionDiff {
+    /** Entity ID being compared */
+    entityId: string;
+    /** From version number */
+    fromVersion: number;
+    /** To version number */
+    toVersion: number;
+    /** Fields that were added */
+    added: FieldChange[];
+    /** Fields that were removed */
+    removed: FieldChange[];
+    /** Fields that were modified */
+    modified: FieldChange[];
+    /** Fields whose type changed */
+    typeChanged: FieldChange[];
+    /** Total number of changes */
+    totalChanges: number;
+    /** Whether versions are identical */
+    identical: boolean;
+}
+/**
+ * Options for diff comparison
+ */
+export interface DiffOptions {
+    /** Entity ID (for context in output) */
+    entityId: string;
+    /** From version number */
+    fromVersion: number;
+    /** To version number */
+    toVersion: number;
+    /** Ignore these fields in comparison */
+    ignoreFields?: string[];
+    /** Maximum depth for nested object comparison (default: 10) */
+    maxDepth?: number;
+    /** Include unchanged fields in output (default: false) */
+    includeUnchanged?: boolean;
+}
+/**
+ * Compare two entity versions and generate diff
+ *
+ * @param from Old version entity
+ * @param to New version entity
+ * @param options Diff options
+ * @returns Diff between versions
+ */
+export declare function compareEntityVersions(from: NounMetadata, to: NounMetadata, options: DiffOptions): VersionDiff;
+/**
+ * Format diff as human-readable string
+ *
+ * @param diff Diff to format
+ * @returns Formatted string
+ */
+export declare function formatDiff(diff: VersionDiff): string;
+/**
+ * Get summary statistics about a diff
+ */
+export declare function getDiffStats(diff: VersionDiff): {
+    changedFields: number;
+    addedFields: number;
+    removedFields: number;
+    modifiedFields: number;
+    typeChangedFields: number;
+};
+/**
+ * Check if diff has any changes
+ */
+export declare function hasChanges(diff: VersionDiff): boolean;
+/**
+ * Get all changed field paths
+ */
+export declare function getChangedPaths(diff: VersionDiff): string[];
+/**
+ * Filter diff to only include specific paths
+ */
+export declare function filterDiff(diff: VersionDiff, paths: string[]): VersionDiff;

package/dist/versioning/VersionDiff.js

@@ -0,0 +1,320 @@
+/**
+ * VersionDiff - Deep Object Comparison for Entity Versions (v5.3.0)
+ *
+ * Provides deep diff between entity versions:
+ * - Field-level change detection
+ * - Nested object comparison
+ * - Array diffing
+ * - Type change detection
+ * - Human-readable diff output
+ *
+ * NO MOCKS - Production implementation
+ */
+/**
+ * Compare two entity versions and generate diff
+ *
+ * @param from Old version entity
+ * @param to New version entity
+ * @param options Diff options
+ * @returns Diff between versions
+ */
+export function compareEntityVersions(from, to, options) {
+    const added = [];
+    const removed = [];
+    const modified = [];
+    const typeChanged = [];
+    const ignoreFields = new Set(options.ignoreFields || []);
+    const maxDepth = options.maxDepth ?? 10;
+    // Compare objects recursively
+    compareObjects(from, to, '', added, removed, modified, typeChanged, ignoreFields, 0, maxDepth);
+    const totalChanges = added.length + removed.length + modified.length + typeChanged.length;
+    const identical = totalChanges === 0;
+    return {
+        entityId: options.entityId,
+        fromVersion: options.fromVersion,
+        toVersion: options.toVersion,
+        added,
+        removed,
+        modified,
+        typeChanged,
+        totalChanges,
+        identical
+    };
+}
+/**
+ * Recursively compare two objects
+ */
+function compareObjects(from, to, path, added, removed, modified, typeChanged, ignoreFields, depth, maxDepth) {
+    if (depth >= maxDepth) {
+        // Hit max depth - treat as single value
+        if (!deepEqual(from, to)) {
+            modified.push({
+                path,
+                type: 'modified',
+                oldValue: from,
+                newValue: to
+            });
+        }
+        return;
+    }
+    // Get all keys from both objects
+    const fromKeys = new Set(Object.keys(from || {}));
+    const toKeys = new Set(Object.keys(to || {}));
+    const allKeys = new Set([...fromKeys, ...toKeys]);
+    for (const key of allKeys) {
+        const fieldPath = path ? `${path}.${key}` : key;
+        // Skip ignored fields
+        if (ignoreFields.has(fieldPath) || ignoreFields.has(key)) {
+            continue;
+        }
+        const fromHas = fromKeys.has(key);
+        const toHas = toKeys.has(key);
+        if (!fromHas && toHas) {
+            // Field added
+            added.push({
+                path: fieldPath,
+                type: 'added',
+                newValue: to[key]
+            });
+        }
+        else if (fromHas && !toHas) {
+            // Field removed
+            removed.push({
+                path: fieldPath,
+                type: 'removed',
+                oldValue: from[key]
+            });
+        }
+        else {
+            // Field exists in both - check for changes
+            const fromValue = from[key];
+            const toValue = to[key];
+            const fromType = getValueType(fromValue);
+            const toType = getValueType(toValue);
+            if (fromType !== toType) {
+                // Type changed
+                typeChanged.push({
+                    path: fieldPath,
+                    type: 'type-changed',
+                    oldValue: fromValue,
+                    newValue: toValue,
+                    oldType: fromType,
+                    newType: toType
+                });
+            }
+            else if (fromType === 'object' && toType === 'object') {
+                // Recursively compare nested objects
+                compareObjects(fromValue, toValue, fieldPath, added, removed, modified, typeChanged, ignoreFields, depth + 1, maxDepth);
+            }
+            else if (fromType === 'array' && toType === 'array') {
+                // Compare arrays
+                if (!arraysEqual(fromValue, toValue)) {
+                    modified.push({
+                        path: fieldPath,
+                        type: 'modified',
+                        oldValue: fromValue,
+                        newValue: toValue
+                    });
+                }
+            }
+            else {
+                // Primitive value comparison
+                if (!deepEqual(fromValue, toValue)) {
+                    modified.push({
+                        path: fieldPath,
+                        type: 'modified',
+                        oldValue: fromValue,
+                        newValue: toValue
+                    });
+                }
+            }
+        }
+    }
+}
+/**
+ * Get human-readable type of a value
+ */
+function getValueType(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * Deep equality check
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (a === undefined || b === undefined)
+        return false;
+    const typeA = getValueType(a);
+    const typeB = getValueType(b);
+    if (typeA !== typeB)
+        return false;
+    if (typeA === 'array') {
+        return arraysEqual(a, b);
+    }
+    if (typeA === 'object') {
+        return objectsEqual(a, b);
+    }
+    // Primitive comparison
+    return a === b;
+}
+/**
+ * Compare arrays for equality
+ */
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (!deepEqual(a[i], b[i])) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Compare objects for equality
+ */
+function objectsEqual(a, b) {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const key of keysA) {
+        if (!keysB.includes(key))
+            return false;
+        if (!deepEqual(a[key], b[key]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Format diff as human-readable string
+ *
+ * @param diff Diff to format
+ * @returns Formatted string
+ */
+export function formatDiff(diff) {
+    const lines = [];
+    lines.push(`Diff: ${diff.entityId} v${diff.fromVersion} → v${diff.toVersion}`);
+    lines.push('');
+    if (diff.identical) {
+        lines.push('No changes');
+        return lines.join('\n');
+    }
+    lines.push(`Total changes: ${diff.totalChanges}`);
+    lines.push('');
+    if (diff.added.length > 0) {
+        lines.push(`Added (${diff.added.length}):`);
+        for (const change of diff.added) {
+            lines.push(`  + ${change.path}: ${formatValue(change.newValue)}`);
+        }
+        lines.push('');
+    }
+    if (diff.removed.length > 0) {
+        lines.push(`Removed (${diff.removed.length}):`);
+        for (const change of diff.removed) {
+            lines.push(`  - ${change.path}: ${formatValue(change.oldValue)}`);
+        }
+        lines.push('');
+    }
+    if (diff.modified.length > 0) {
+        lines.push(`Modified (${diff.modified.length}):`);
+        for (const change of diff.modified) {
+            lines.push(`  ~ ${change.path}:`);
+            lines.push(`      ${formatValue(change.oldValue)}`);
+            lines.push(`    → ${formatValue(change.newValue)}`);
+        }
+        lines.push('');
+    }
+    if (diff.typeChanged.length > 0) {
+        lines.push(`Type Changed (${diff.typeChanged.length}):`);
+        for (const change of diff.typeChanged) {
+            lines.push(`  ! ${change.path}: ${change.oldType} → ${change.newType}`);
+            lines.push(`      ${formatValue(change.oldValue)}`);
+            lines.push(`    → ${formatValue(change.newValue)}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Format value for display
+ */
+function formatValue(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'string')
+        return `"${value}"`;
+    if (typeof value === 'object') {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return '[Object]';
+        }
+    }
+    return String(value);
+}
+/**
+ * Get summary statistics about a diff
+ */
+export function getDiffStats(diff) {
+    return {
+        changedFields: diff.totalChanges,
+        addedFields: diff.added.length,
+        removedFields: diff.removed.length,
+        modifiedFields: diff.modified.length,
+        typeChangedFields: diff.typeChanged.length
+    };
+}
+/**
+ * Check if diff has any changes
+ */
+export function hasChanges(diff) {
+    return !diff.identical;
+}
+/**
+ * Get all changed field paths
+ */
+export function getChangedPaths(diff) {
+    const paths = new Set();
+    for (const change of diff.added)
+        paths.add(change.path);
+    for (const change of diff.removed)
+        paths.add(change.path);
+    for (const change of diff.modified)
+        paths.add(change.path);
+    for (const change of diff.typeChanged)
+        paths.add(change.path);
+    return Array.from(paths).sort();
+}
+/**
+ * Filter diff to only include specific paths
+ */
+export function filterDiff(diff, paths) {
+    const pathSet = new Set(paths);
+    const filterChanges = (changes) => changes.filter((c) => pathSet.has(c.path) || paths.some((p) => c.path.startsWith(p + '.')));
+    const added = filterChanges(diff.added);
+    const removed = filterChanges(diff.removed);
+    const modified = filterChanges(diff.modified);
+    const typeChanged = filterChanges(diff.typeChanged);
+    return {
+        ...diff,
+        added,
+        removed,
+        modified,
+        typeChanged,
+        totalChanges: added.length + removed.length + modified.length + typeChanged.length,
+        identical: added.length + removed.length + modified.length + typeChanged.length === 0
+    };
+}
+//# sourceMappingURL=VersionDiff.js.map

package/dist/versioning/VersionIndex.d.ts

@@ -0,0 +1,126 @@
+/**
+ * VersionIndex - Fast Version Lookup Using Existing Index Infrastructure (v5.3.0)
+ *
+ * Integrates with Brainy's existing index system:
+ * - Uses MetadataIndexManager for field indexing
+ * - Leverages UnifiedCache for memory management
+ * - Uses EntityIdMapper for efficient ID handling
+ * - Uses ChunkManager for adaptive chunking
+ * - Leverages Roaring Bitmaps for fast set operations
+ *
+ * Version metadata is stored as regular entities with type='_version'
+ * This allows us to use existing index infrastructure without modification!
+ *
+ * Fields indexed:
+ * - versionEntityId: Entity being versioned
+ * - versionBranch: Branch version was created on
+ * - versionNumber: Version number
+ * - versionTag: Optional user tag
+ * - versionTimestamp: Creation timestamp
+ * - versionCommitHash: Commit hash
+ *
+ * NO MOCKS - Production implementation
+ */
+import type { EntityVersion } from './VersionManager.js';
+import type { VersionQuery } from './VersionManager.js';
+/**
+ * VersionIndex - Version lookup and querying using existing indexes
+ *
+ * Strategy: Store version metadata as special entities with type='_version'
+ * This leverages ALL existing index infrastructure automatically!
+ */
+export declare class VersionIndex {
+    private brain;
+    private initialized;
+    constructor(brain: any);
+    /**
+     * Initialize version index
+     *
+     * No special setup needed - we use existing entity storage and indexes!
+     */
+    initialize(): Promise<void>;
+    /**
+     * Add version to index
+     *
+     * Stores version metadata as a special entity with type='_version'
+     * This automatically indexes it using existing MetadataIndexManager!
+     *
+     * @param version Version metadata
+     */
+    addVersion(version: EntityVersion): Promise<void>;
+    /**
+     * Get versions for an entity
+     *
+     * Uses existing MetadataIndexManager to query efficiently!
+     *
+     * @param query Version query
+     * @returns List of versions (newest first)
+     */
+    getVersions(query: VersionQuery): Promise<EntityVersion[]>;
+    /**
+     * Get specific version
+     *
+     * @param entityId Entity ID
+     * @param version Version number
+     * @param branch Branch name
+     * @returns Version metadata or null
+     */
+    getVersion(entityId: string, version: number, branch: string): Promise<EntityVersion | null>;
+    /**
+     * Get version by tag
+     *
+     * @param entityId Entity ID
+     * @param tag Version tag
+     * @param branch Branch name
+     * @returns Version metadata or null
+     */
+    getVersionByTag(entityId: string, tag: string, branch: string): Promise<EntityVersion | null>;
+    /**
+     * Get version count for entity
+     *
+     * @param entityId Entity ID
+     * @param branch Branch name
+     * @returns Number of versions
+     */
+    getVersionCount(entityId: string, branch: string): Promise<number>;
+    /**
+     * Remove version from index
+     *
+     * @param entityId Entity ID
+     * @param version Version number
+     * @param branch Branch name
+     */
+    removeVersion(entityId: string, version: number, branch: string): Promise<void>;
+    /**
+     * Convert entity to EntityVersion format
+     *
+     * @param entity Entity from storage
+     * @returns EntityVersion or null if invalid
+     */
+    private entityToVersion;
+    /**
+     * Generate unique ID for version entity
+     *
+     * Format: _version:{entityId}:{version}:{branch}
+     *
+     * @param entityId Entity ID
+     * @param version Version number
+     * @param branch Branch name
+     * @returns Version entity ID
+     */
+    private getVersionEntityId;
+    /**
+     * Get all versioned entities (for cleanup/debugging)
+     *
+     * @returns List of entity IDs that have versions
+     */
+    getVersionedEntities(): Promise<string[]>;
+    /**
+     * Clear all versions for an entity
+     *
+     * @param entityId Entity ID
+     * @param branch Branch name
+     * @returns Number of versions deleted
+     */
+    clearVersions(entityId: string, branch: string): Promise<number>;
+}