@soulcraft/brainy 5.2.1 → 5.3.1

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 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.
 
+### [5.3.0](https://github.com/soulcraftlabs/brainy/compare/v5.2.1...v5.3.0) (2025-11-04)
+
+- feat: add entity versioning system with critical bug fixes (v5.3.0) (c488fa8)
+
+
 ### [5.2.0](https://github.com/soulcraftlabs/brainy/compare/v5.1.2...v5.2.0) (2025-11-03)
 
 - fix: update VFS test for v5.2.0 BlobStorage architecture (b3e3e5c)

package/dist/augmentations/versioningAugmentation.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Versioning Augmentation (v5.3.0)
+ *
+ * Provides automatic entity versioning with configurable policies:
+ * - Auto-save on update()
+ * - Entity filtering
+ * - Retention policies
+ * - Event hooks
+ *
+ * NO MOCKS - Production implementation
+ */
+import { BaseAugmentation } from './brainyAugmentation.js';
+import { AugmentationManifest } from './manifest.js';
+import type { SaveVersionOptions } from '../versioning/VersionManager.js';
+export interface VersioningAugmentationConfig {
+    /** Enable auto-versioning */
+    enabled?: boolean;
+    /** Auto-save on update() operations */
+    onUpdate?: boolean;
+    /** Auto-save on add() operations (rarely needed) */
+    onAdd?: boolean;
+    /** Entity ID patterns to version (glob patterns) */
+    entities?: string[];
+    /** Entity ID patterns to exclude (glob patterns) */
+    excludeEntities?: string[];
+    /** Entity types to version */
+    types?: string[];
+    /** Entity types to exclude */
+    excludeTypes?: string[];
+    /** Retention policy: Keep N recent versions per entity */
+    keepRecent?: number;
+    /** Retention policy: Keep versions newer than timestamp */
+    keepAfter?: number;
+    /** Retention policy: Keep tagged versions (default: true) */
+    keepTagged?: boolean;
+    /** Tag prefix for auto-generated versions (default: 'auto-') */
+    tagPrefix?: string;
+    /** Auto-prune old versions after save */
+    autoPrune?: boolean;
+    /** Prune interval in milliseconds (default: 1 hour) */
+    pruneInterval?: number;
+    /** Event hooks */
+    hooks?: {
+        /** Called before saving version */
+        beforeSave?: (entityId: string, options: SaveVersionOptions) => Promise<SaveVersionOptions | null>;
+        /** Called after saving version */
+        afterSave?: (entityId: string, version: any) => Promise<void>;
+        /** Called before pruning */
+        beforePrune?: (entityId: string) => Promise<boolean>;
+        /** Called after pruning */
+        afterPrune?: (entityId: string, deleted: number) => Promise<void>;
+    };
+}
+/**
+ * Versioning Augmentation
+ *
+ * Automatically versions entities based on configurable policies.
+ */
+export declare class VersioningAugmentation extends BaseAugmentation {
+    readonly name = "versioning";
+    readonly timing: "after";
+    readonly metadata: "readonly";
+    operations: any;
+    readonly priority = 50;
+    readonly category: "core";
+    readonly description = "Automatic entity versioning with configurable retention policies";
+    private versioningAPI?;
+    private brain?;
+    private pruneTimer?;
+    private versionCount;
+    constructor(config?: VersioningAugmentationConfig);
+    getManifest(): AugmentationManifest;
+    onAttach(brain: any): Promise<void>;
+    onDetach(): Promise<void>;
+    /**
+     * Execute method (required by BaseAugmentation)
+     */
+    execute(operation: string, params: any[], context: any): Promise<any>;
+    /**
+     * After operation hook - auto-save versions
+     */
+    after(operation: string, params: any[], result: any): Promise<any>;
+    /**
+     * Extract entity ID from operation params
+     */
+    private extractEntityId;
+    /**
+     * Check if entity should be versioned based on filters
+     */
+    private shouldVersionEntity;
+    /**
+     * Simple glob pattern matching
+     */
+    private matchPattern;
+    /**
+     * Prune old versions for an entity
+     */
+    private pruneEntity;
+    /**
+     * Start auto-prune timer
+     */
+    private startAutoPrune;
+    /**
+     * Prune all versioned entities
+     */
+    private pruneAllEntities;
+    /**
+     * Get augmentation statistics
+     */
+    getStats(): {
+        enabled: boolean;
+        versionsCreated: number;
+        entitiesPattern: string[];
+        excludePattern: string[];
+        retention: number;
+    };
+}
+/**
+ * Factory function for easy augmentation creation
+ */
+export declare function createVersioningAugmentation(config?: VersioningAugmentationConfig): VersioningAugmentation;

package/dist/augmentations/versioningAugmentation.js

@@ -0,0 +1,418 @@
+/**
+ * Versioning Augmentation (v5.3.0)
+ *
+ * Provides automatic entity versioning with configurable policies:
+ * - Auto-save on update()
+ * - Entity filtering
+ * - Retention policies
+ * - Event hooks
+ *
+ * NO MOCKS - Production implementation
+ */
+import { BaseAugmentation } from './brainyAugmentation.js';
+/**
+ * Versioning Augmentation
+ *
+ * Automatically versions entities based on configurable policies.
+ */
+export class VersioningAugmentation extends BaseAugmentation {
+    constructor(config = {}) {
+        super(config);
+        this.name = 'versioning';
+        this.timing = 'after'; // Run after operations complete
+        this.metadata = 'readonly';
+        this.operations = ['update', 'add']; // Version on update/add
+        this.priority = 50; // Medium priority
+        // Augmentation metadata
+        this.category = 'core';
+        this.description = 'Automatic entity versioning with configurable retention policies';
+        this.versionCount = 0;
+        // Merge with defaults
+        this.config = {
+            enabled: config.enabled ?? true,
+            onUpdate: config.onUpdate ?? true,
+            onAdd: config.onAdd ?? false,
+            entities: config.entities ?? ['*'], // Version all entities by default
+            excludeEntities: config.excludeEntities ?? ['_version:*'], // Exclude version metadata entities
+            types: config.types ?? [], // Empty = all types
+            excludeTypes: config.excludeTypes ?? [], // No need to exclude types (versions use 'state' type)
+            keepRecent: config.keepRecent ?? 10,
+            keepTagged: config.keepTagged ?? true,
+            tagPrefix: config.tagPrefix ?? 'auto-',
+            autoPrune: config.autoPrune ?? true,
+            pruneInterval: config.pruneInterval ?? 60 * 60 * 1000, // 1 hour
+            hooks: config.hooks ?? {}
+        };
+    }
+    getManifest() {
+        return {
+            id: 'versioning',
+            name: 'Entity Versioning',
+            version: '5.3.0',
+            description: 'Automatic entity versioning with retention policies',
+            longDescription: 'Provides automatic versioning of entities on update/add operations with configurable retention policies, entity filtering, and event hooks.',
+            category: 'storage',
+            configSchema: {
+                type: 'object',
+                properties: {
+                    enabled: {
+                        type: 'boolean',
+                        default: true,
+                        description: 'Enable automatic versioning'
+                    },
+                    onUpdate: {
+                        type: 'boolean',
+                        default: true,
+                        description: 'Auto-save version on update()'
+                    },
+                    onAdd: {
+                        type: 'boolean',
+                        default: false,
+                        description: 'Auto-save version on add()'
+                    },
+                    entities: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: ['*'],
+                        description: 'Entity ID patterns to version (glob patterns)'
+                    },
+                    excludeEntities: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: ['_version:*'],
+                        description: 'Entity ID patterns to exclude (version metadata IDs start with _version:)'
+                    },
+                    types: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                        description: 'Entity types to version (empty = all)'
+                    },
+                    excludeTypes: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                        description: 'Entity types to exclude (versions use standard state type)'
+                    },
+                    keepRecent: {
+                        type: 'number',
+                        default: 10,
+                        minimum: 1,
+                        description: 'Keep N recent versions per entity'
+                    },
+                    keepTagged: {
+                        type: 'boolean',
+                        default: true,
+                        description: 'Keep tagged versions during pruning'
+                    },
+                    tagPrefix: {
+                        type: 'string',
+                        default: 'auto-',
+                        description: 'Tag prefix for auto-generated versions'
+                    },
+                    autoPrune: {
+                        type: 'boolean',
+                        default: true,
+                        description: 'Automatically prune old versions'
+                    },
+                    pruneInterval: {
+                        type: 'number',
+                        default: 3600000,
+                        description: 'Prune interval in milliseconds (default: 1 hour)'
+                    }
+                }
+            },
+            configDefaults: {
+                enabled: true,
+                onUpdate: true,
+                onAdd: false,
+                entities: ['*'],
+                excludeEntities: ['_version:*'],
+                types: [],
+                excludeTypes: [],
+                keepRecent: 10,
+                keepTagged: true,
+                tagPrefix: 'auto-',
+                autoPrune: true,
+                pruneInterval: 3600000
+            },
+            minBrainyVersion: '5.3.0',
+            keywords: ['versioning', 'history', 'audit', 'backup'],
+            documentation: 'https://docs.brainy.dev/versioning',
+            status: 'stable',
+            performance: {
+                memoryUsage: 'low',
+                cpuUsage: 'low',
+                networkUsage: 'none'
+            },
+            features: [
+                'auto-versioning',
+                'retention-policies',
+                'entity-filtering',
+                'event-hooks'
+            ],
+            enhancedOperations: ['update', 'add'],
+            metrics: [
+                {
+                    name: 'versions_created',
+                    type: 'counter',
+                    description: 'Total versions created by augmentation'
+                },
+                {
+                    name: 'versions_pruned',
+                    type: 'counter',
+                    description: 'Total versions pruned by retention policies'
+                }
+            ]
+        };
+    }
+    async onAttach(brain) {
+        // Store brain instance for entity fetching
+        this.brain = brain;
+        // Get VersioningAPI instance
+        this.versioningAPI = brain.versions;
+        // Start auto-prune timer if enabled
+        if (this.config.autoPrune && this.config.pruneInterval) {
+            this.startAutoPrune();
+        }
+    }
+    async onDetach() {
+        // Stop auto-prune timer
+        if (this.pruneTimer) {
+            clearInterval(this.pruneTimer);
+            this.pruneTimer = undefined;
+        }
+    }
+    /**
+     * Execute method (required by BaseAugmentation)
+     */
+    async execute(operation, params, context) {
+        // Versioning augmentation only runs in 'after' mode
+        // Actual logic is in after() method
+        return context.originalResult;
+    }
+    /**
+     * After operation hook - auto-save versions
+     */
+    async after(operation, params, result) {
+        if (!this.config.enabled || !this.versioningAPI) {
+            return result;
+        }
+        // Check if we should version this operation
+        if (operation === 'update' && !this.config.onUpdate) {
+            return result;
+        }
+        if (operation === 'add' && !this.config.onAdd) {
+            return result;
+        }
+        // Extract entity ID from params
+        const entityId = this.extractEntityId(operation, params);
+        if (!entityId) {
+            return result;
+        }
+        // Check if entity should be versioned
+        if (!(await this.shouldVersionEntity(entityId))) {
+            return result;
+        }
+        try {
+            // Prepare save options
+            let saveOptions = {
+                tag: `${this.config.tagPrefix}${Date.now()}`,
+                description: `Auto-saved after ${operation}`,
+                metadata: {
+                    augmentation: 'versioning',
+                    operation,
+                    timestamp: Date.now()
+                }
+            };
+            // Call before-save hook
+            if (this.config.hooks?.beforeSave) {
+                const modifiedOptions = await this.config.hooks.beforeSave(entityId, saveOptions);
+                if (modifiedOptions === null) {
+                    // Hook cancelled the save
+                    return result;
+                }
+                saveOptions = modifiedOptions;
+            }
+            // Save version
+            const version = await this.versioningAPI.save(entityId, saveOptions);
+            this.versionCount++;
+            // Call after-save hook
+            if (this.config.hooks?.afterSave) {
+                await this.config.hooks.afterSave(entityId, version);
+            }
+            // Auto-prune if enabled
+            if (this.config.autoPrune) {
+                await this.pruneEntity(entityId);
+            }
+        }
+        catch (error) {
+            // Don't fail the operation if versioning fails
+            console.error(`Versioning augmentation error for ${entityId}:`, error);
+        }
+        return result;
+    }
+    /**
+     * Extract entity ID from operation params
+     */
+    extractEntityId(operation, params) {
+        if (operation === 'update') {
+            // update(id, data) or update({ id, ... })
+            if (typeof params[0] === 'string') {
+                return params[0];
+            }
+            if (params[0]?.id) {
+                return params[0].id;
+            }
+        }
+        if (operation === 'add') {
+            // add(data) - ID might be in data or result
+            if (params[0]?.id) {
+                return params[0].id;
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if entity should be versioned based on filters
+     */
+    async shouldVersionEntity(entityId) {
+        // Check exclude patterns first (ID-based)
+        if (this.config.excludeEntities) {
+            for (const pattern of this.config.excludeEntities) {
+                if (this.matchPattern(entityId, pattern)) {
+                    return false;
+                }
+            }
+        }
+        // Check include patterns (ID-based)
+        if (this.config.entities && this.config.entities.length > 0) {
+            let matched = false;
+            for (const pattern of this.config.entities) {
+                if (this.matchPattern(entityId, pattern)) {
+                    matched = true;
+                    break;
+                }
+            }
+            if (!matched)
+                return false;
+        }
+        // Check entity type filters (requires fetching entity)
+        if ((this.config.types && this.config.types.length > 0) ||
+            (this.config.excludeTypes && this.config.excludeTypes.length > 0)) {
+            try {
+                const entity = await this.brain?.getNounMetadata?.(entityId);
+                if (!entity)
+                    return true; // If can't fetch, allow versioning
+                const entityType = entity.type;
+                // Check exclude types
+                if (this.config.excludeTypes && this.config.excludeTypes.includes(entityType)) {
+                    return false;
+                }
+                // Check include types
+                if (this.config.types && this.config.types.length > 0) {
+                    if (!this.config.types.includes(entityType)) {
+                        return false;
+                    }
+                }
+            }
+            catch (error) {
+                // If can't fetch entity, allow versioning (fail open)
+                console.error(`Failed to fetch entity ${entityId} for type filtering:`, error);
+                return true;
+            }
+        }
+        return true;
+    }
+    /**
+     * Simple glob pattern matching
+     */
+    matchPattern(value, pattern) {
+        if (pattern === '*')
+            return true;
+        if (!pattern.includes('*'))
+            return value === pattern;
+        // Convert glob to regex
+        const regex = new RegExp('^' + pattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+        return regex.test(value);
+    }
+    /**
+     * Prune old versions for an entity
+     */
+    async pruneEntity(entityId) {
+        if (!this.versioningAPI)
+            return;
+        try {
+            // Call before-prune hook
+            if (this.config.hooks?.beforePrune) {
+                const shouldPrune = await this.config.hooks.beforePrune(entityId);
+                if (!shouldPrune)
+                    return;
+            }
+            // Prune versions
+            const result = await this.versioningAPI.prune(entityId, {
+                keepRecent: this.config.keepRecent,
+                keepAfter: this.config.keepAfter,
+                keepTagged: this.config.keepTagged
+            });
+            // Call after-prune hook
+            if (result.deleted > 0 && this.config.hooks?.afterPrune) {
+                await this.config.hooks.afterPrune(entityId, result.deleted);
+            }
+        }
+        catch (error) {
+            console.error(`Failed to prune versions for ${entityId}:`, error);
+        }
+    }
+    /**
+     * Start auto-prune timer
+     */
+    startAutoPrune() {
+        if (this.pruneTimer) {
+            clearInterval(this.pruneTimer);
+        }
+        this.pruneTimer = setInterval(async () => {
+            await this.pruneAllEntities();
+        }, this.config.pruneInterval);
+    }
+    /**
+     * Prune all versioned entities
+     */
+    async pruneAllEntities() {
+        if (!this.versioningAPI)
+            return;
+        try {
+            // Get all versioned entities
+            const versionIndex = this.versioningAPI.manager.versionIndex;
+            const entities = await versionIndex.getVersionedEntities();
+            // Prune each entity
+            for (const entityId of entities) {
+                if (await this.shouldVersionEntity(entityId)) {
+                    await this.pruneEntity(entityId);
+                }
+            }
+        }
+        catch (error) {
+            console.error('Auto-prune failed:', error);
+        }
+    }
+    /**
+     * Get augmentation statistics
+     */
+    getStats() {
+        return {
+            enabled: this.config.enabled,
+            versionsCreated: this.versionCount,
+            entitiesPattern: this.config.entities || [],
+            excludePattern: this.config.excludeEntities || [],
+            retention: this.config.keepRecent || 10
+        };
+    }
+}
+/**
+ * Factory function for easy augmentation creation
+ */
+export function createVersioningAugmentation(config = {}) {
+    return new VersioningAugmentation(config);
+}
+//# sourceMappingURL=versioningAugmentation.js.map

package/dist/brainy.d.ts

@@ -10,6 +10,7 @@ import { NaturalLanguageProcessor } from './neural/naturalLanguageProcessor.js';
 import { ExtractedEntity } from './neural/entityExtractor.js';
 import { TripleIntelligenceSystem } from './triple/TripleIntelligenceSystem.js';
 import { VirtualFileSystem } from './vfs/VirtualFileSystem.js';
+import { VersioningAPI } from './versioning/VersioningAPI.js';
 import { Entity, Relation, Result, AddParams, UpdateParams, RelateParams, FindParams, SimilarParams, GetRelationsParams, AddManyParams, DeleteManyParams, RelateManyParams, BatchResult, BrainyConfig } from './types/brainy.types.js';
 import { NounType, VerbType } from './types/graphTypes.js';
 import { BrainyInterface } from './types/brainyInterface.js';
@@ -39,6 +40,7 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     private _nlp?;
     private _extractor?;
     private _tripleIntelligence?;
+    private _versions?;
     private _vfs?;
     private initialized;
     private dimensions?;
@@ -956,6 +958,32 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * Neural API - Advanced AI operations
      */
     neural(): ImprovedNeuralAPI;
+    /**
+     * 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(): VersioningAPI;
     /**
      * Natural Language Processing API
      */

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';
@@ -2026,7 +2027,7 @@ export class Brainy {
             const blobStorage = this.storage.blobStorage;
             const currentBranch = await this.getCurrentBranch();
             // Get current HEAD commit (parent)
-            const currentCommitHash = await refManager.resolveRef(`heads/${currentBranch}`);
+            const currentCommitHash = await refManager.resolveRef(currentBranch);
             // Get current state statistics
             const entityCount = await this.getNounCount();
             const relationshipCount = await this.getVerbCount();
@@ -2051,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'
             });
@@ -2440,7 +2441,7 @@ export class Brainy {
                 throw new Error('Cannot delete current branch');
             }
             const refManager = this.storage.refManager;
-            await refManager.deleteRef(`heads/${branch}`);
+            await refManager.deleteRef(branch);
         });
     }
     /**
@@ -2465,7 +2466,7 @@ export class Brainy {
             const commitLog = this.storage.commitLog;
             const currentBranch = await this.getCurrentBranch();
             // Get commit history for current branch
-            const commits = await commitLog.getHistory(`heads/${currentBranch}`, {
+            const commits = await commitLog.getHistory(currentBranch, {
                 maxCount: options?.limit || 10
             });
             // Map to expected format (compute hash for each commit)
@@ -2504,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
      */