@soulcraft/brainy 5.2.1 → 5.3.0

package/dist/versioning/VersionIndex.js

@@ -0,0 +1,275 @@
+/**
+ * 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
+ */
+/**
+ * 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 class VersionIndex {
+    constructor(brain) {
+        this.initialized = false;
+        this.brain = brain;
+    }
+    /**
+     * Initialize version index
+     *
+     * No special setup needed - we use existing entity storage and indexes!
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+    }
+    /**
+     * 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
+     */
+    async addVersion(version) {
+        await this.initialize();
+        // Generate unique ID for version entity
+        const versionEntityId = this.getVersionEntityId(version.entityId, version.version, version.branch);
+        // Store as special entity with type='state' (version is a snapshot/state)
+        // This automatically gets indexed by MetadataIndexManager!
+        await this.brain.saveNounMetadata(versionEntityId, {
+            id: versionEntityId,
+            type: 'state', // Use standard 'state' type (version = snapshot state)
+            name: `Version ${version.version} of ${version.entityId}`,
+            metadata: {
+                // Flag to identify as version metadata
+                _isVersion: true,
+                // These fields are automatically indexed by MetadataIndexManager
+                versionEntityId: version.entityId, // Entity being versioned
+                versionBranch: version.branch, // Branch
+                versionNumber: version.version, // Version number
+                versionTag: version.tag, // Optional tag
+                versionTimestamp: version.timestamp, // Timestamp (indexed with bucketing)
+                versionCommitHash: version.commitHash, // Commit hash
+                versionContentHash: version.contentHash, // Content hash
+                versionAuthor: version.author, // Author
+                versionDescription: version.description, // Description
+                versionMetadata: version.metadata // Additional metadata
+            }
+        });
+    }
+    /**
+     * Get versions for an entity
+     *
+     * Uses existing MetadataIndexManager to query efficiently!
+     *
+     * @param query Version query
+     * @returns List of versions (newest first)
+     */
+    async getVersions(query) {
+        await this.initialize();
+        // Build metadata filter using existing query system
+        const filters = {
+            type: 'state',
+            _isVersion: true,
+            versionEntityId: query.entityId,
+            versionBranch: query.branch
+        };
+        // Add optional filters
+        if (query.tag) {
+            filters.versionTag = query.tag;
+        }
+        // Query using existing search infrastructure
+        const results = await this.brain.searchByMetadata(filters);
+        // Convert entities back to EntityVersion format
+        const versions = [];
+        for (const entity of results) {
+            const version = this.entityToVersion(entity);
+            if (version) {
+                // Filter by date range if specified
+                if (query.startDate && version.timestamp < query.startDate)
+                    continue;
+                if (query.endDate && version.timestamp > query.endDate)
+                    continue;
+                versions.push(version);
+            }
+        }
+        // Sort by version number (newest first)
+        versions.sort((a, b) => b.version - a.version);
+        // Apply pagination
+        const start = query.offset || 0;
+        const end = query.limit ? start + query.limit : undefined;
+        return versions.slice(start, end);
+    }
+    /**
+     * Get specific version
+     *
+     * @param entityId Entity ID
+     * @param version Version number
+     * @param branch Branch name
+     * @returns Version metadata or null
+     */
+    async getVersion(entityId, version, branch) {
+        await this.initialize();
+        const versionEntityId = this.getVersionEntityId(entityId, version, branch);
+        const entity = await this.brain.getNounMetadata(versionEntityId);
+        if (!entity)
+            return null;
+        return this.entityToVersion(entity);
+    }
+    /**
+     * Get version by tag
+     *
+     * @param entityId Entity ID
+     * @param tag Version tag
+     * @param branch Branch name
+     * @returns Version metadata or null
+     */
+    async getVersionByTag(entityId, tag, branch) {
+        await this.initialize();
+        // Query using existing metadata index
+        const results = await this.brain.searchByMetadata({
+            type: 'state',
+            _isVersion: true,
+            versionEntityId: entityId,
+            versionBranch: branch,
+            versionTag: tag
+        });
+        if (results.length === 0)
+            return null;
+        // Return first match (tags should be unique per entity/branch)
+        return this.entityToVersion(results[0]);
+    }
+    /**
+     * Get version count for entity
+     *
+     * @param entityId Entity ID
+     * @param branch Branch name
+     * @returns Number of versions
+     */
+    async getVersionCount(entityId, branch) {
+        await this.initialize();
+        // Use existing search infrastructure
+        const results = await this.brain.searchByMetadata({
+            type: 'state',
+            _isVersion: true,
+            versionEntityId: entityId,
+            versionBranch: branch
+        });
+        return results.length;
+    }
+    /**
+     * Remove version from index
+     *
+     * @param entityId Entity ID
+     * @param version Version number
+     * @param branch Branch name
+     */
+    async removeVersion(entityId, version, branch) {
+        await this.initialize();
+        const versionEntityId = this.getVersionEntityId(entityId, version, branch);
+        // Delete version entity (automatically removed from indexes)
+        await this.brain.deleteNounMetadata(versionEntityId);
+    }
+    /**
+     * Convert entity to EntityVersion format
+     *
+     * @param entity Entity from storage
+     * @returns EntityVersion or null if invalid
+     */
+    entityToVersion(entity) {
+        if (!entity || !entity.metadata)
+            return null;
+        const m = entity.metadata;
+        if (!m.versionEntityId ||
+            !m.versionBranch ||
+            m.versionNumber === undefined ||
+            !m.versionCommitHash ||
+            !m.versionContentHash ||
+            !m.versionTimestamp) {
+            return null;
+        }
+        return {
+            version: m.versionNumber,
+            entityId: m.versionEntityId,
+            branch: m.versionBranch,
+            commitHash: m.versionCommitHash,
+            timestamp: m.versionTimestamp,
+            contentHash: m.versionContentHash,
+            tag: m.versionTag,
+            description: m.versionDescription,
+            author: m.versionAuthor,
+            metadata: m.versionMetadata
+        };
+    }
+    /**
+     * 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
+     */
+    getVersionEntityId(entityId, version, branch) {
+        return `_version:${entityId}:${version}:${branch}`;
+    }
+    /**
+     * Get all versioned entities (for cleanup/debugging)
+     *
+     * @returns List of entity IDs that have versions
+     */
+    async getVersionedEntities() {
+        await this.initialize();
+        // Query all version entities
+        const results = await this.brain.searchByMetadata({
+            type: 'state',
+            _isVersion: true
+        });
+        // Extract unique entity IDs
+        const entityIds = new Set();
+        for (const entity of results) {
+            const version = this.entityToVersion(entity);
+            if (version) {
+                entityIds.add(version.entityId);
+            }
+        }
+        return Array.from(entityIds);
+    }
+    /**
+     * Clear all versions for an entity
+     *
+     * @param entityId Entity ID
+     * @param branch Branch name
+     * @returns Number of versions deleted
+     */
+    async clearVersions(entityId, branch) {
+        await this.initialize();
+        const versions = await this.getVersions({ entityId, branch });
+        for (const version of versions) {
+            await this.removeVersion(entityId, version.version, branch);
+        }
+        return versions.length;
+    }
+}
+//# sourceMappingURL=VersionIndex.js.map

package/dist/versioning/VersionManager.d.ts

@@ -0,0 +1,195 @@
+/**
+ * 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 { VersionDiff } from './VersionDiff.js';
+export interface EntityVersion {
+    /** Version number (1-indexed, sequential per entity) */
+    version: number;
+    /** Entity ID */
+    entityId: string;
+    /** Branch this version was created on */
+    branch: string;
+    /** Commit hash containing this version */
+    commitHash: string;
+    /** Timestamp of version creation */
+    timestamp: number;
+    /** Optional user-provided tag (e.g., 'v1.0', 'before-refactor') */
+    tag?: string;
+    /** Optional description */
+    description?: string;
+    /** Content hash (SHA-256 of entity data) */
+    contentHash: string;
+    /** Author of this version */
+    author?: string;
+    /** Metadata about the version */
+    metadata?: Record<string, any>;
+}
+export interface VersionQuery {
+    /** Entity ID to query versions for */
+    entityId: string;
+    /** Optional: Filter by branch (default: current branch) */
+    branch?: string;
+    /** Optional: Limit number of versions returned */
+    limit?: number;
+    /** Optional: Skip first N versions */
+    offset?: number;
+    /** Optional: Filter by tag */
+    tag?: string;
+    /** Optional: Filter by date range */
+    startDate?: number;
+    endDate?: number;
+}
+export interface SaveVersionOptions {
+    /** Optional tag for this version (e.g., 'v1.0', 'milestone-1') */
+    tag?: string;
+    /** Optional description */
+    description?: string;
+    /** Optional author name */
+    author?: string;
+    /** Optional custom metadata */
+    metadata?: Record<string, any>;
+    /** Optional: Create commit automatically (default: false) */
+    createCommit?: boolean;
+    /** Optional: Commit message if createCommit is true */
+    commitMessage?: string;
+}
+export interface RestoreOptions {
+    /** Optional: Create version before restoring (for undo) */
+    createSnapshot?: boolean;
+    /** Optional: Tag for snapshot before restore */
+    snapshotTag?: string;
+}
+export interface PruneOptions {
+    /** Keep N most recent versions (required if keepVersions not set) */
+    keepRecent?: number;
+    /** Keep versions newer than timestamp (optional) */
+    keepAfter?: number;
+    /** Keep tagged versions (default: true) */
+    keepTagged?: boolean;
+    /** Dry run - don't actually delete (default: false) */
+    dryRun?: boolean;
+}
+/**
+ * VersionManager - Core versioning engine
+ */
+export declare class VersionManager {
+    private brain;
+    private versionStorage;
+    private versionIndex;
+    private initialized;
+    constructor(brain: any);
+    /**
+     * Initialize versioning system (lazy)
+     */
+    initialize(): Promise<void>;
+    /**
+     * 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
+     */
+    save(entityId: string, options?: SaveVersionOptions): Promise<EntityVersion>;
+    /**
+     * Get all versions of an entity
+     *
+     * @param entityId Entity ID
+     * @param query Optional query filters
+     * @returns List of versions (newest first)
+     */
+    list(entityId: string, query?: Partial<VersionQuery>): Promise<EntityVersion[]>;
+    /**
+     * Get a specific version of an entity
+     *
+     * @param entityId Entity ID
+     * @param version Version number (1-indexed)
+     * @returns Version metadata
+     */
+    getVersion(entityId: string, version: number): Promise<EntityVersion | null>;
+    /**
+     * Get version by tag
+     *
+     * @param entityId Entity ID
+     * @param tag Version tag
+     * @returns Version metadata
+     */
+    getVersionByTag(entityId: string, tag: string): Promise<EntityVersion | null>;
+    /**
+     * 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
+     */
+    restore(entityId: string, version: number | string, options?: RestoreOptions): Promise<EntityVersion>;
+    /**
+     * 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
+     */
+    compare(entityId: string, fromVersion: number | string, toVersion: number | string): Promise<VersionDiff>;
+    /**
+     * Prune old versions based on retention policy
+     *
+     * @param entityId Entity ID (or '*' for all entities)
+     * @param options Prune options
+     * @returns Number of versions deleted
+     */
+    prune(entityId: string, options: PruneOptions): Promise<{
+        deleted: number;
+        kept: number;
+    }>;
+    /**
+     * Get version count for an entity
+     *
+     * @param entityId Entity ID
+     * @returns Number of versions
+     */
+    getVersionCount(entityId: string): Promise<number>;
+    /**
+     * Check if entity has versions
+     *
+     * @param entityId Entity ID
+     * @returns True if entity has versions
+     */
+    hasVersions(entityId: string): Promise<boolean>;
+    /**
+     * Get latest version of an entity
+     *
+     * @param entityId Entity ID
+     * @returns Latest version metadata or null
+     */
+    getLatest(entityId: string): Promise<EntityVersion | null>;
+    /**
+     * Clear all versions for an entity
+     *
+     * @param entityId Entity ID
+     * @returns Number of versions deleted
+     */
+    clear(entityId: string): Promise<number>;
+}