@soulcraft/brainy 5.2.1 → 5.3.0

package/dist/versioning/VersionManager.js

@@ -0,0 +1,352 @@
+/**
+ * VersionManager - Entity-Level Versioning Engine (v5.3.0)
+ *
+ * Provides entity-level version control with:
+ * - save() - Create entity version
+ * - restore() - Restore entity to specific version
+ * - list() - List all versions of an entity
+ * - compare() - Deep diff between versions
+ * - prune() - Remove old versions (retention policies)
+ *
+ * Architecture:
+ * - Hybrid storage: COW commits for full snapshots + version index for fast queries
+ * - Content-addressable: SHA-256 hashing for deduplication
+ * - Space-efficient: Only stores changed data
+ * - Branch-aware: Versions tied to current branch
+ *
+ * NO MOCKS - Production implementation
+ */
+import { VersionStorage } from './VersionStorage.js';
+import { VersionIndex } from './VersionIndex.js';
+import { compareEntityVersions } from './VersionDiff.js';
+/**
+ * VersionManager - Core versioning engine
+ */
+export class VersionManager {
+    constructor(brain) {
+        this.initialized = false;
+        this.brain = brain;
+        this.versionStorage = new VersionStorage(brain);
+        this.versionIndex = new VersionIndex(brain);
+    }
+    /**
+     * Initialize versioning system (lazy)
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        await this.versionStorage.initialize();
+        await this.versionIndex.initialize();
+        this.initialized = true;
+    }
+    /**
+     * Save a version of an entity
+     *
+     * Creates a version snapshot of the current entity state.
+     * If createCommit is true, also creates a commit containing this version.
+     *
+     * @param entityId Entity ID to version
+     * @param options Save options
+     * @returns Created version metadata
+     */
+    async save(entityId, options = {}) {
+        await this.initialize();
+        // Get current entity state
+        const entity = await this.brain.getNounMetadata(entityId);
+        if (!entity) {
+            throw new Error(`Entity ${entityId} not found`);
+        }
+        // Get current branch
+        const currentBranch = this.brain.currentBranch;
+        // Get next version number
+        const existingVersions = await this.versionIndex.getVersions({
+            entityId,
+            branch: currentBranch
+        });
+        const nextVersion = existingVersions.length + 1;
+        // Calculate content hash
+        const contentHash = this.versionStorage.hashEntity(entity);
+        // Check for duplicate (same content as last version)
+        if (existingVersions.length > 0) {
+            const lastVersion = existingVersions[existingVersions.length - 1];
+            if (lastVersion.contentHash === contentHash) {
+                // Content unchanged - return last version instead of creating duplicate
+                return lastVersion;
+            }
+        }
+        // Create commit if requested
+        let commitHash;
+        if (options.createCommit) {
+            const commitMessage = options.commitMessage || `Version ${nextVersion} of entity ${entityId}`;
+            // Use brain's commit method (note: single options object)
+            await this.brain.commit({
+                message: commitMessage,
+                author: options.author,
+                metadata: {
+                    versionedEntity: entityId,
+                    version: nextVersion,
+                    ...options.metadata
+                }
+            });
+            // Get the commit hash that was just created
+            const refManager = this.brain.refManager;
+            const ref = await refManager.getRef(currentBranch);
+            commitHash = ref;
+        }
+        else {
+            // Use current HEAD commit
+            const refManager = this.brain.refManager;
+            const ref = await refManager.getRef(currentBranch);
+            if (!ref) {
+                throw new Error(`No commit exists on branch ${currentBranch}. Create a commit first or use createCommit: true`);
+            }
+            commitHash = ref;
+        }
+        // Create version metadata
+        const version = {
+            version: nextVersion,
+            entityId,
+            branch: currentBranch,
+            commitHash,
+            timestamp: Date.now(),
+            contentHash,
+            tag: options.tag,
+            description: options.description,
+            author: options.author,
+            metadata: options.metadata
+        };
+        // Store version
+        await this.versionStorage.saveVersion(version, entity);
+        await this.versionIndex.addVersion(version);
+        return version;
+    }
+    /**
+     * Get all versions of an entity
+     *
+     * @param entityId Entity ID
+     * @param query Optional query filters
+     * @returns List of versions (newest first)
+     */
+    async list(entityId, query = {}) {
+        await this.initialize();
+        const currentBranch = this.brain.currentBranch;
+        return this.versionIndex.getVersions({
+            entityId,
+            branch: query.branch || currentBranch,
+            limit: query.limit,
+            offset: query.offset,
+            tag: query.tag,
+            startDate: query.startDate,
+            endDate: query.endDate
+        });
+    }
+    /**
+     * Get a specific version of an entity
+     *
+     * @param entityId Entity ID
+     * @param version Version number (1-indexed)
+     * @returns Version metadata
+     */
+    async getVersion(entityId, version) {
+        await this.initialize();
+        const currentBranch = this.brain.currentBranch;
+        return this.versionIndex.getVersion(entityId, version, currentBranch);
+    }
+    /**
+     * Get version by tag
+     *
+     * @param entityId Entity ID
+     * @param tag Version tag
+     * @returns Version metadata
+     */
+    async getVersionByTag(entityId, tag) {
+        await this.initialize();
+        const currentBranch = this.brain.currentBranch;
+        return this.versionIndex.getVersionByTag(entityId, tag, currentBranch);
+    }
+    /**
+     * Restore entity to a specific version
+     *
+     * Overwrites current entity state with the specified version.
+     * Optionally creates a snapshot before restoring for undo capability.
+     *
+     * @param entityId Entity ID
+     * @param version Version number or tag
+     * @param options Restore options
+     * @returns Restored version metadata
+     */
+    async restore(entityId, version, options = {}) {
+        await this.initialize();
+        // Create snapshot before restoring (for undo)
+        if (options.createSnapshot) {
+            await this.save(entityId, {
+                tag: options.snapshotTag || 'before-restore',
+                description: `Snapshot before restoring to version ${version}`,
+                metadata: { restoringTo: version }
+            });
+        }
+        // Get target version
+        let targetVersion;
+        if (typeof version === 'number') {
+            targetVersion = await this.getVersion(entityId, version);
+        }
+        else {
+            targetVersion = await this.getVersionByTag(entityId, version);
+        }
+        if (!targetVersion) {
+            throw new Error(`Version ${version} not found for entity ${entityId}`);
+        }
+        // Load versioned entity data
+        const versionedEntity = await this.versionStorage.loadVersion(targetVersion);
+        if (!versionedEntity) {
+            throw new Error(`Version data not found for entity ${entityId} version ${version}`);
+        }
+        // Restore entity in storage
+        await this.brain.saveNounMetadata(entityId, versionedEntity);
+        return targetVersion;
+    }
+    /**
+     * Compare two versions of an entity
+     *
+     * @param entityId Entity ID
+     * @param fromVersion Version number or tag (older)
+     * @param toVersion Version number or tag (newer)
+     * @returns Diff between versions
+     */
+    async compare(entityId, fromVersion, toVersion) {
+        await this.initialize();
+        // Get versions
+        const fromVer = typeof fromVersion === 'number'
+            ? await this.getVersion(entityId, fromVersion)
+            : await this.getVersionByTag(entityId, fromVersion);
+        const toVer = typeof toVersion === 'number'
+            ? await this.getVersion(entityId, toVersion)
+            : await this.getVersionByTag(entityId, toVersion);
+        if (!fromVer) {
+            throw new Error(`Version ${fromVersion} not found for entity ${entityId}`);
+        }
+        if (!toVer) {
+            throw new Error(`Version ${toVersion} not found for entity ${entityId}`);
+        }
+        // Load entity data
+        const fromEntity = await this.versionStorage.loadVersion(fromVer);
+        const toEntity = await this.versionStorage.loadVersion(toVer);
+        if (!fromEntity || !toEntity) {
+            throw new Error('Failed to load version data for comparison');
+        }
+        // Compare versions
+        return compareEntityVersions(fromEntity, toEntity, {
+            fromVersion: fromVer.version,
+            toVersion: toVer.version,
+            entityId
+        });
+    }
+    /**
+     * Prune old versions based on retention policy
+     *
+     * @param entityId Entity ID (or '*' for all entities)
+     * @param options Prune options
+     * @returns Number of versions deleted
+     */
+    async prune(entityId, options) {
+        await this.initialize();
+        if (!options.keepRecent && !options.keepAfter) {
+            throw new Error('Must specify either keepRecent or keepAfter in prune options');
+        }
+        const currentBranch = this.brain.currentBranch;
+        // Get all versions
+        const versions = await this.versionIndex.getVersions({
+            entityId,
+            branch: currentBranch
+        });
+        // Determine which versions to keep
+        const toKeep = new Set();
+        const toDelete = [];
+        // Keep recent versions
+        if (options.keepRecent) {
+            const recentVersions = versions.slice(0, options.keepRecent);
+            recentVersions.forEach((v) => toKeep.add(v.version));
+        }
+        // Keep versions after timestamp
+        if (options.keepAfter) {
+            versions
+                .filter((v) => v.timestamp >= options.keepAfter)
+                .forEach((v) => toKeep.add(v.version));
+        }
+        // Keep tagged versions
+        if (options.keepTagged !== false) {
+            versions
+                .filter((v) => v.tag !== undefined)
+                .forEach((v) => toKeep.add(v.version));
+        }
+        // Build delete list
+        for (const version of versions) {
+            if (!toKeep.has(version.version)) {
+                toDelete.push(version);
+            }
+        }
+        // Dry run - just return counts
+        if (options.dryRun) {
+            return {
+                deleted: toDelete.length,
+                kept: toKeep.size
+            };
+        }
+        // Delete versions
+        for (const version of toDelete) {
+            await this.versionStorage.deleteVersion(version);
+            await this.versionIndex.removeVersion(entityId, version.version, currentBranch);
+        }
+        return {
+            deleted: toDelete.length,
+            kept: toKeep.size
+        };
+    }
+    /**
+     * Get version count for an entity
+     *
+     * @param entityId Entity ID
+     * @returns Number of versions
+     */
+    async getVersionCount(entityId) {
+        await this.initialize();
+        const currentBranch = this.brain.currentBranch;
+        return this.versionIndex.getVersionCount(entityId, currentBranch);
+    }
+    /**
+     * Check if entity has versions
+     *
+     * @param entityId Entity ID
+     * @returns True if entity has versions
+     */
+    async hasVersions(entityId) {
+        const count = await this.getVersionCount(entityId);
+        return count > 0;
+    }
+    /**
+     * Get latest version of an entity
+     *
+     * @param entityId Entity ID
+     * @returns Latest version metadata or null
+     */
+    async getLatest(entityId) {
+        await this.initialize();
+        const versions = await this.list(entityId, { limit: 1 });
+        return versions[0] || null;
+    }
+    /**
+     * Clear all versions for an entity
+     *
+     * @param entityId Entity ID
+     * @returns Number of versions deleted
+     */
+    async clear(entityId) {
+        await this.initialize();
+        const result = await this.prune(entityId, {
+            keepRecent: 0,
+            keepTagged: false
+        });
+        return result.deleted;
+    }
+}
+//# sourceMappingURL=VersionManager.js.map

package/dist/versioning/VersionStorage.d.ts

@@ -0,0 +1,101 @@
+/**
+ * VersionStorage - Hybrid Storage for Entity Versions (v5.3.0)
+ *
+ * Implements content-addressable storage for entity versions:
+ * - SHA-256 content hashing for deduplication
+ * - Stores versions in .brainy/versions/ directory
+ * - Integrates with COW commit system
+ * - Space-efficient: Only stores unique content
+ *
+ * Storage structure:
+ * .brainy/versions/
+ *   ├── entities/
+ *   │   └── {entityId}/
+ *   │       └── {contentHash}.json  # Entity version data
+ *   └── index/
+ *       └── {entityId}.json         # Version index (managed by VersionIndex)
+ *
+ * NO MOCKS - Production implementation
+ */
+import type { NounMetadata } from '../coreTypes.js';
+import type { EntityVersion } from './VersionManager.js';
+/**
+ * VersionStorage - Content-addressable version storage
+ */
+export declare class VersionStorage {
+    private brain;
+    private initialized;
+    constructor(brain: any);
+    /**
+     * Initialize version storage directories
+     */
+    initialize(): Promise<void>;
+    /**
+     * Calculate SHA-256 hash of entity content
+     *
+     * Used for content-addressable storage and deduplication
+     *
+     * @param entity Entity to hash
+     * @returns SHA-256 hash (hex string)
+     */
+    hashEntity(entity: NounMetadata): string;
+    /**
+     * Convert entity to stable JSON (sorted keys for consistent hashing)
+     */
+    private toStableJson;
+    /**
+     * Save entity version to content-addressable storage
+     *
+     * @param version Version metadata
+     * @param entity Entity data
+     */
+    saveVersion(version: EntityVersion, entity: NounMetadata): Promise<void>;
+    /**
+     * Load entity version from storage
+     *
+     * @param version Version metadata
+     * @returns Entity data or null if not found
+     */
+    loadVersion(version: EntityVersion): Promise<NounMetadata | null>;
+    /**
+     * Delete entity version from storage
+     *
+     * @param version Version to delete
+     */
+    deleteVersion(version: EntityVersion): Promise<void>;
+    /**
+     * Get version storage path
+     *
+     * @param entityId Entity ID
+     * @param contentHash Content hash
+     * @returns Storage path
+     */
+    private getVersionPath;
+    /**
+     * Check if content exists in storage
+     *
+     * @param path Storage path
+     * @returns True if exists
+     */
+    private contentExists;
+    /**
+     * Write version data to storage
+     *
+     * @param path Storage path
+     * @param entity Entity data
+     */
+    private writeVersionData;
+    /**
+     * Read version data from storage
+     *
+     * @param path Storage path
+     * @returns Entity data
+     */
+    private readVersionData;
+    /**
+     * Delete version data from storage
+     *
+     * @param path Storage path
+     */
+    private deleteVersionData;
+}

package/dist/versioning/VersionStorage.js

@@ -0,0 +1,222 @@
+/**
+ * VersionStorage - Hybrid Storage for Entity Versions (v5.3.0)
+ *
+ * Implements content-addressable storage for entity versions:
+ * - SHA-256 content hashing for deduplication
+ * - Stores versions in .brainy/versions/ directory
+ * - Integrates with COW commit system
+ * - Space-efficient: Only stores unique content
+ *
+ * Storage structure:
+ * .brainy/versions/
+ *   ├── entities/
+ *   │   └── {entityId}/
+ *   │       └── {contentHash}.json  # Entity version data
+ *   └── index/
+ *       └── {entityId}.json         # Version index (managed by VersionIndex)
+ *
+ * NO MOCKS - Production implementation
+ */
+import { createHash } from 'crypto';
+/**
+ * VersionStorage - Content-addressable version storage
+ */
+export class VersionStorage {
+    constructor(brain) {
+        this.initialized = false;
+        this.brain = brain;
+    }
+    /**
+     * Initialize version storage directories
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        // Version storage uses the same storage adapter as the main database
+        // Directories are created automatically by the storage adapter
+        this.initialized = true;
+    }
+    /**
+     * Calculate SHA-256 hash of entity content
+     *
+     * Used for content-addressable storage and deduplication
+     *
+     * @param entity Entity to hash
+     * @returns SHA-256 hash (hex string)
+     */
+    hashEntity(entity) {
+        // Create stable JSON representation (sorted keys)
+        const stableJson = this.toStableJson(entity);
+        return createHash('sha256').update(stableJson).digest('hex');
+    }
+    /**
+     * Convert entity to stable JSON (sorted keys for consistent hashing)
+     */
+    toStableJson(obj) {
+        if (obj === null)
+            return 'null';
+        if (obj === undefined)
+            return 'undefined';
+        if (typeof obj !== 'object')
+            return JSON.stringify(obj);
+        if (Array.isArray(obj)) {
+            const items = obj.map((item) => this.toStableJson(item));
+            return `[${items.join(',')}]`;
+        }
+        // Sort object keys for stable hashing
+        const sortedKeys = Object.keys(obj).sort();
+        const pairs = sortedKeys.map((key) => {
+            const value = this.toStableJson(obj[key]);
+            return `"${key}":${value}`;
+        });
+        return `{${pairs.join(',')}}`;
+    }
+    /**
+     * Save entity version to content-addressable storage
+     *
+     * @param version Version metadata
+     * @param entity Entity data
+     */
+    async saveVersion(version, entity) {
+        await this.initialize();
+        // Content-addressable path: .brainy/versions/entities/{entityId}/{contentHash}.json
+        const versionPath = this.getVersionPath(version.entityId, version.contentHash);
+        // Check if content already exists (deduplication)
+        const exists = await this.contentExists(versionPath);
+        if (exists) {
+            // Content already stored - no need to write again
+            return;
+        }
+        // Store entity data
+        await this.writeVersionData(versionPath, entity);
+    }
+    /**
+     * Load entity version from storage
+     *
+     * @param version Version metadata
+     * @returns Entity data or null if not found
+     */
+    async loadVersion(version) {
+        await this.initialize();
+        const versionPath = this.getVersionPath(version.entityId, version.contentHash);
+        try {
+            return await this.readVersionData(versionPath);
+        }
+        catch (error) {
+            console.error(`Failed to load version ${version.version}:`, error);
+            return null;
+        }
+    }
+    /**
+     * Delete entity version from storage
+     *
+     * @param version Version to delete
+     */
+    async deleteVersion(version) {
+        await this.initialize();
+        const versionPath = this.getVersionPath(version.entityId, version.contentHash);
+        await this.deleteVersionData(versionPath);
+    }
+    /**
+     * Get version storage path
+     *
+     * @param entityId Entity ID
+     * @param contentHash Content hash
+     * @returns Storage path
+     */
+    getVersionPath(entityId, contentHash) {
+        return `versions/entities/${entityId}/${contentHash}.json`;
+    }
+    /**
+     * Check if content exists in storage
+     *
+     * @param path Storage path
+     * @returns True if exists
+     */
+    async contentExists(path) {
+        try {
+            // Use storage adapter's exists check if available
+            const adapter = this.brain.storageAdapter;
+            if (adapter && typeof adapter.exists === 'function') {
+                return await adapter.exists(path);
+            }
+            // Fallback: Try to read and catch error
+            await this.readVersionData(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Write version data to storage
+     *
+     * @param path Storage path
+     * @param entity Entity data
+     */
+    async writeVersionData(path, entity) {
+        const adapter = this.brain.storageAdapter;
+        if (!adapter) {
+            throw new Error('Storage adapter not available');
+        }
+        // Serialize entity data
+        const data = JSON.stringify(entity, null, 2);
+        // Write to storage using adapter
+        if (typeof adapter.writeFile === 'function') {
+            await adapter.writeFile(path, data);
+        }
+        else if (typeof adapter.set === 'function') {
+            await adapter.set(path, data);
+        }
+        else {
+            throw new Error('Storage adapter does not support write operations');
+        }
+    }
+    /**
+     * Read version data from storage
+     *
+     * @param path Storage path
+     * @returns Entity data
+     */
+    async readVersionData(path) {
+        const adapter = this.brain.storageAdapter;
+        if (!adapter) {
+            throw new Error('Storage adapter not available');
+        }
+        // Read from storage using adapter
+        let data;
+        if (typeof adapter.readFile === 'function') {
+            data = await adapter.readFile(path);
+        }
+        else if (typeof adapter.get === 'function') {
+            data = await adapter.get(path);
+        }
+        else {
+            throw new Error('Storage adapter does not support read operations');
+        }
+        // Parse entity data
+        return JSON.parse(data);
+    }
+    /**
+     * Delete version data from storage
+     *
+     * @param path Storage path
+     */
+    async deleteVersionData(path) {
+        const adapter = this.brain.storageAdapter;
+        if (!adapter) {
+            throw new Error('Storage adapter not available');
+        }
+        // Delete from storage using adapter
+        if (typeof adapter.deleteFile === 'function') {
+            await adapter.deleteFile(path);
+        }
+        else if (typeof adapter.delete === 'function') {
+            await adapter.delete(path);
+        }
+        else {
+            throw new Error('Storage adapter does not support delete operations');
+        }
+    }
+}
+//# sourceMappingURL=VersionStorage.js.map