@soulcraft/brainy 4.11.1 → 5.0.0

package/dist/storage/cow/CommitLog.js

@@ -0,0 +1,363 @@
+/**
+ * CommitLog: Commit history traversal and querying for COW (Copy-on-Write)
+ *
+ * Provides efficient commit history operations:
+ * - Walk commit graph (DAG traversal)
+ * - Find commits by time, author, operation
+ * - Time-travel queries (asOf)
+ * - Commit statistics and analytics
+ *
+ * Optimizations:
+ * - Commit index for fast timestamp lookups
+ * - Parent cache for efficient traversal
+ * - Lazy loading (only read commits when needed)
+ *
+ * @module storage/cow/CommitLog
+ */
+import { CommitObject } from './CommitObject.js';
+/**
+ * CommitLog: Efficient commit history traversal and querying
+ *
+ * Pure v5.0.0 implementation - modern, clean, fast
+ */
+export class CommitLog {
+    constructor(blobStorage, refManager) {
+        this.blobStorage = blobStorage;
+        this.refManager = refManager;
+        this.index = new Map();
+        this.indexValid = false;
+    }
+    /**
+     * Walk commit history from a starting point
+     *
+     * Yields commits in reverse chronological order (newest first)
+     *
+     * @param startRef - Starting ref/commit (e.g., 'main', commit hash)
+     * @param options - Walk options
+     */
+    async *walk(startRef = 'main', options) {
+        // Resolve ref to commit hash
+        let startHash;
+        if (/^[a-f0-9]{64}$/.test(startRef)) {
+            // Already a commit hash
+            startHash = startRef;
+        }
+        else {
+            // Resolve ref
+            const commitHash = await this.refManager.resolveRef(startRef);
+            if (!commitHash) {
+                throw new Error(`Ref not found: ${startRef}`);
+            }
+            startHash = commitHash;
+        }
+        // Walk using CommitObject (delegates to it)
+        yield* CommitObject.walk(this.blobStorage, startHash, options);
+    }
+    /**
+     * Find commit at or before a specific timestamp
+     *
+     * Uses index for fast O(log n) lookup
+     *
+     * @param ref - Starting ref (e.g., 'main')
+     * @param timestamp - Target timestamp
+     * @returns Commit at or before timestamp, or null
+     */
+    async findAtTime(ref, timestamp) {
+        // Build index if needed
+        await this.buildIndex(ref);
+        // Binary search in index
+        const entries = Array.from(this.index.values()).sort((a, b) => b.timestamp - a.timestamp // Newest first
+        );
+        let left = 0;
+        let right = entries.length - 1;
+        let result = null;
+        while (left <= right) {
+            const mid = Math.floor((left + right) / 2);
+            const entry = entries[mid];
+            if (entry.timestamp <= timestamp) {
+                result = entry;
+                right = mid - 1; // Look for newer commit
+            }
+            else {
+                left = mid + 1; // Look for older commit
+            }
+        }
+        if (!result) {
+            return null;
+        }
+        // Read full commit
+        return CommitObject.read(this.blobStorage, result.hash);
+    }
+    /**
+     * Get commit by hash
+     *
+     * @param hash - Commit hash
+     * @returns Commit object
+     */
+    async getCommit(hash) {
+        return CommitObject.read(this.blobStorage, hash);
+    }
+    /**
+     * Get commits in time range
+     *
+     * @param ref - Starting ref
+     * @param startTime - Start of time range
+     * @param endTime - End of time range
+     * @returns Array of commits in range (newest first)
+     */
+    async getInTimeRange(ref, startTime, endTime) {
+        const commits = [];
+        for await (const commit of this.walk(ref, { until: startTime })) {
+            if (commit.timestamp >= startTime && commit.timestamp <= endTime) {
+                commits.push(commit);
+            }
+        }
+        return commits;
+    }
+    /**
+     * Get commits by author
+     *
+     * @param ref - Starting ref
+     * @param author - Author name
+     * @param options - Additional options
+     * @returns Array of commits by author
+     */
+    async getByAuthor(ref, author, options) {
+        const commits = [];
+        let count = 0;
+        for await (const commit of this.walk(ref, { until: options?.since })) {
+            if (commit.author === author) {
+                commits.push(commit);
+                count++;
+                if (options?.maxCount && count >= options.maxCount) {
+                    break;
+                }
+            }
+        }
+        return commits;
+    }
+    /**
+     * Get commits by operation type
+     *
+     * @param ref - Starting ref
+     * @param operation - Operation type (e.g., 'add', 'update', 'delete')
+     * @param options - Additional options
+     * @returns Array of commits by operation
+     */
+    async getByOperation(ref, operation, options) {
+        const commits = [];
+        let count = 0;
+        for await (const commit of this.walk(ref, { until: options?.since })) {
+            if (commit.metadata?.operation === operation) {
+                commits.push(commit);
+                count++;
+                if (options?.maxCount && count >= options.maxCount) {
+                    break;
+                }
+            }
+        }
+        return commits;
+    }
+    /**
+     * Get commit history as array
+     *
+     * @param ref - Starting ref
+     * @param options - Walk options
+     * @returns Array of commits (newest first)
+     */
+    async getHistory(ref, options) {
+        const commits = [];
+        let count = 0;
+        for await (const commit of this.walk(ref, {
+            maxDepth: options?.maxCount,
+            until: options?.until
+        })) {
+            if (options?.since && commit.timestamp < options.since) {
+                continue;
+            }
+            commits.push(commit);
+            count++;
+            if (options?.maxCount && count >= options.maxCount) {
+                break;
+            }
+        }
+        return commits;
+    }
+    /**
+     * Count commits between two commits
+     *
+     * @param fromRef - Starting ref/commit
+     * @param toRef - Ending ref/commit (optional, defaults to fromRef's parent)
+     * @returns Number of commits between
+     */
+    async countBetween(fromRef, toRef) {
+        const fromHash = await this.resolveToHash(fromRef);
+        const toHash = toRef ? await this.resolveToHash(toRef) : null;
+        return CommitObject.countBetween(this.blobStorage, fromHash, toHash);
+    }
+    /**
+     * Find common ancestor of two commits (merge base)
+     *
+     * @param ref1 - First ref/commit
+     * @param ref2 - Second ref/commit
+     * @returns Common ancestor commit or null
+     */
+    async findCommonAncestor(ref1, ref2) {
+        const hash1 = await this.resolveToHash(ref1);
+        const hash2 = await this.resolveToHash(ref2);
+        return CommitObject.findCommonAncestor(this.blobStorage, hash1, hash2);
+    }
+    /**
+     * Get commit log statistics
+     *
+     * @param ref - Starting ref
+     * @param options - Options
+     * @returns Commit log statistics
+     */
+    async getStats(ref = 'main', options) {
+        const authors = new Set();
+        const operations = new Set();
+        const timestamps = [];
+        let totalCommits = 0;
+        for await (const commit of this.walk(ref, options)) {
+            totalCommits++;
+            authors.add(commit.author);
+            timestamps.push(commit.timestamp);
+            if (commit.metadata?.operation) {
+                operations.add(commit.metadata.operation);
+            }
+        }
+        // Calculate average interval
+        let avgInterval = 0;
+        if (timestamps.length > 1) {
+            const intervals = [];
+            for (let i = 0; i < timestamps.length - 1; i++) {
+                intervals.push(timestamps[i] - timestamps[i + 1]);
+            }
+            avgInterval = intervals.reduce((a, b) => a + b, 0) / intervals.length;
+        }
+        return {
+            totalCommits,
+            oldestCommit: timestamps[timestamps.length - 1] ?? 0,
+            newestCommit: timestamps[0] ?? 0,
+            authors,
+            operations,
+            avgCommitInterval: avgInterval
+        };
+    }
+    /**
+     * Check if commit is ancestor of another commit
+     *
+     * @param ancestorRef - Potential ancestor ref/commit
+     * @param descendantRef - Descendant ref/commit
+     * @returns True if ancestor is in descendant's history
+     */
+    async isAncestor(ancestorRef, descendantRef) {
+        const ancestorHash = await this.resolveToHash(ancestorRef);
+        const descendantHash = await this.resolveToHash(descendantRef);
+        // Walk from descendant, check if we encounter ancestor
+        for await (const commit of this.walk(descendantHash)) {
+            const commitHash = CommitObject.hash(commit);
+            if (commitHash === ancestorHash) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Get recent commits (last N)
+     *
+     * @param ref - Starting ref
+     * @param count - Number of commits to retrieve
+     * @returns Array of recent commits
+     */
+    async getRecent(ref, count = 10) {
+        return this.getHistory(ref, { maxCount: count });
+    }
+    /**
+     * Find commits with tag
+     *
+     * @param ref - Starting ref
+     * @param tag - Tag to search for
+     * @returns Array of commits with tag
+     */
+    async findWithTag(ref, tag) {
+        const commits = [];
+        for await (const commit of this.walk(ref)) {
+            if (CommitObject.hasTag(commit, tag)) {
+                commits.push(commit);
+            }
+        }
+        return commits;
+    }
+    /**
+     * Get first (oldest) commit
+     *
+     * @param ref - Starting ref
+     * @returns Oldest commit
+     */
+    async getFirstCommit(ref) {
+        let oldest = null;
+        for await (const commit of this.walk(ref)) {
+            oldest = commit;
+        }
+        return oldest;
+    }
+    /**
+     * Get latest commit
+     *
+     * @param ref - Starting ref
+     * @returns Latest commit
+     */
+    async getLatestCommit(ref) {
+        for await (const commit of this.walk(ref, { maxDepth: 1 })) {
+            return commit;
+        }
+        return null;
+    }
+    /**
+     * Clear index (useful for testing, after new commits)
+     */
+    clearIndex() {
+        this.index.clear();
+        this.indexValid = false;
+    }
+    // ========== PRIVATE METHODS ==========
+    /**
+     * Build commit index for fast lookups
+     *
+     * @param ref - Starting ref
+     */
+    async buildIndex(ref) {
+        if (this.indexValid) {
+            return; // Already built
+        }
+        this.index.clear();
+        for await (const commit of this.walk(ref)) {
+            const hash = CommitObject.hash(commit);
+            this.index.set(hash, {
+                hash,
+                timestamp: commit.timestamp,
+                parentHash: commit.parent
+            });
+        }
+        this.indexValid = true;
+    }
+    /**
+     * Resolve ref or hash to commit hash
+     *
+     * @param refOrHash - Ref name or commit hash
+     * @returns Commit hash
+     */
+    async resolveToHash(refOrHash) {
+        if (/^[a-f0-9]{64}$/.test(refOrHash)) {
+            return refOrHash; // Already a hash
+        }
+        const hash = await this.refManager.resolveRef(refOrHash);
+        if (!hash) {
+            throw new Error(`Ref not found: ${refOrHash}`);
+        }
+        return hash;
+    }
+}
+//# sourceMappingURL=CommitLog.js.map

package/dist/storage/cow/CommitObject.d.ts

@@ -0,0 +1,276 @@
+/**
+ * CommitObject: Snapshot metadata for COW (Copy-on-Write)
+ *
+ * Similar to Git commits, represents a point-in-time snapshot of a Brainy instance.
+ * Commits reference tree objects and parent commits, forming a directed acyclic graph (DAG).
+ *
+ * Structure:
+ * - tree: hash of root tree object (contains all data)
+ * - parent: hash of parent commit (null for initial commit)
+ * - message: human-readable commit message
+ * - author: who/what created this commit
+ * - timestamp: when this commit was created
+ * - metadata: additional commit metadata (tags, etc.)
+ *
+ * @module storage/cow/CommitObject
+ */
+import { BlobStorage } from './BlobStorage.js';
+/**
+ * Commit object structure
+ */
+export interface CommitObject {
+    tree: string;
+    parent: string | null;
+    message: string;
+    author: string;
+    timestamp: number;
+    metadata?: {
+        tags?: string[];
+        branch?: string;
+        operation?: string;
+        entityCount?: number;
+        relationshipCount?: number;
+        [key: string]: any;
+    };
+}
+/**
+ * CommitBuilder: Fluent API for building commit objects
+ *
+ * Example:
+ * ```typescript
+ * const commit = await CommitBuilder.create(blobStorage)
+ *   .tree(treeHash)
+ *   .parent(parentHash)
+ *   .message('Add user entities')
+ *   .author('system')
+ *   .tag('v1.0.0')
+ *   .build()
+ * ```
+ */
+export declare class CommitBuilder {
+    private _tree?;
+    private _parent?;
+    private _message;
+    private _author;
+    private _timestamp;
+    private _metadata;
+    private blobStorage;
+    constructor(blobStorage: BlobStorage);
+    static create(blobStorage: BlobStorage): CommitBuilder;
+    /**
+     * Set tree hash
+     */
+    tree(hash: string): this;
+    /**
+     * Set parent commit hash (null for initial commit)
+     */
+    parent(hash: string | null): this;
+    /**
+     * Set commit message
+     */
+    message(message: string): this;
+    /**
+     * Set commit author
+     */
+    author(author: string): this;
+    /**
+     * Set commit timestamp (defaults to now)
+     */
+    timestamp(timestamp: number | Date): this;
+    /**
+     * Add tag to commit
+     */
+    tag(tag: string): this;
+    /**
+     * Set branch name
+     */
+    branch(branch: string): this;
+    /**
+     * Set operation type
+     */
+    operation(operation: string): this;
+    /**
+     * Set entity count
+     */
+    entityCount(count: number): this;
+    /**
+     * Set relationship count
+     */
+    relationshipCount(count: number): this;
+    /**
+     * Set custom metadata
+     */
+    meta(key: string, value: any): this;
+    /**
+     * Build and persist the commit object
+     *
+     * @returns Commit hash
+     */
+    build(): Promise<string>;
+}
+/**
+ * CommitObject: Represents a point-in-time snapshot in COW storage
+ */
+export declare class CommitObject {
+    /**
+     * Serialize commit object to Buffer
+     *
+     * Format: JSON (simple, debuggable)
+     * Future: Could use protobuf for efficiency
+     *
+     * @param commit - Commit object
+     * @returns Serialized commit
+     */
+    static serialize(commit: CommitObject): Buffer;
+    /**
+     * Deserialize commit object from Buffer
+     *
+     * @param data - Serialized commit
+     * @returns Commit object
+     */
+    static deserialize(data: Buffer): CommitObject;
+    /**
+     * Compute hash of commit object
+     *
+     * @param commit - Commit object
+     * @returns SHA-256 hash
+     */
+    static hash(commit: CommitObject): string;
+    /**
+     * Write commit object to blob storage
+     *
+     * @param blobStorage - Blob storage instance
+     * @param commit - Commit object
+     * @returns Commit hash
+     */
+    static write(blobStorage: BlobStorage, commit: CommitObject): Promise<string>;
+    /**
+     * Read commit object from blob storage
+     *
+     * @param blobStorage - Blob storage instance
+     * @param hash - Commit hash
+     * @returns Commit object
+     */
+    static read(blobStorage: BlobStorage, hash: string): Promise<CommitObject>;
+    /**
+     * Check if commit is initial commit (has no parent)
+     *
+     * @param commit - Commit object
+     * @returns True if initial commit
+     */
+    static isInitial(commit: CommitObject): boolean;
+    /**
+     * Check if commit is merge commit (has multiple parents)
+     * (Future enhancement: support merge commits with multiple parents)
+     *
+     * @param commit - Commit object
+     * @returns True if merge commit
+     */
+    static isMerge(commit: CommitObject): boolean;
+    /**
+     * Check if commit has a specific tag
+     *
+     * @param commit - Commit object
+     * @param tag - Tag to check
+     * @returns True if commit has tag
+     */
+    static hasTag(commit: CommitObject, tag: string): boolean;
+    /**
+     * Get all tags from commit
+     *
+     * @param commit - Commit object
+     * @returns Array of tags
+     */
+    static getTags(commit: CommitObject): string[];
+    /**
+     * Walk commit history (traverse DAG)
+     *
+     * Yields commits in reverse chronological order (newest first)
+     *
+     * @param blobStorage - Blob storage instance
+     * @param startHash - Starting commit hash
+     * @param options - Walk options
+     */
+    static walk(blobStorage: BlobStorage, startHash: string, options?: {
+        maxDepth?: number;
+        until?: number;
+        stopAt?: string;
+        filter?: (commit: CommitObject) => boolean;
+    }): AsyncIterableIterator<CommitObject>;
+    /**
+     * Find commit at or before a specific timestamp
+     *
+     * @param blobStorage - Blob storage instance
+     * @param startHash - Starting commit hash (e.g., 'main' ref)
+     * @param timestamp - Target timestamp
+     * @returns Commit at or before timestamp, or null if not found
+     */
+    static findAtTime(blobStorage: BlobStorage, startHash: string, timestamp: number): Promise<CommitObject | null>;
+    /**
+     * Get commit history as array (newest first)
+     *
+     * @param blobStorage - Blob storage instance
+     * @param startHash - Starting commit hash
+     * @param options - Walk options
+     * @returns Array of commits
+     */
+    static getHistory(blobStorage: BlobStorage, startHash: string, options?: {
+        maxDepth?: number;
+        until?: number;
+        stopAt?: string;
+    }): Promise<CommitObject[]>;
+    /**
+     * Find common ancestor of two commits (merge base)
+     *
+     * Useful for diff/merge operations
+     *
+     * @param blobStorage - Blob storage instance
+     * @param hash1 - First commit hash
+     * @param hash2 - Second commit hash
+     * @returns Common ancestor commit, or null if not found
+     */
+    static findCommonAncestor(blobStorage: BlobStorage, hash1: string, hash2: string): Promise<CommitObject | null>;
+    /**
+     * Count commits between two commits
+     *
+     * @param blobStorage - Blob storage instance
+     * @param fromHash - Starting commit hash
+     * @param toHash - Ending commit hash
+     * @returns Number of commits between (inclusive)
+     */
+    static countBetween(blobStorage: BlobStorage, fromHash: string, toHash: string): Promise<number>;
+    /**
+     * Get commits in time range
+     *
+     * @param blobStorage - Blob storage instance
+     * @param startHash - Starting commit hash
+     * @param startTime - Start of time range
+     * @param endTime - End of time range
+     * @returns Array of commits in range
+     */
+    static getInTimeRange(blobStorage: BlobStorage, startHash: string, startTime: number, endTime: number): Promise<CommitObject[]>;
+    /**
+     * Get commits by author
+     *
+     * @param blobStorage - Blob storage instance
+     * @param startHash - Starting commit hash
+     * @param author - Author name
+     * @param options - Walk options
+     * @returns Array of commits by author
+     */
+    static getByAuthor(blobStorage: BlobStorage, startHash: string, author: string, options?: {
+        maxDepth?: number;
+    }): Promise<CommitObject[]>;
+    /**
+     * Get commits by operation type
+     *
+     * @param blobStorage - Blob storage instance
+     * @param startHash - Starting commit hash
+     * @param operation - Operation type (e.g., 'add', 'update', 'delete')
+     * @param options - Walk options
+     * @returns Array of commits by operation
+     */
+    static getByOperation(blobStorage: BlobStorage, startHash: string, operation: string, options?: {
+        maxDepth?: number;
+    }): Promise<CommitObject[]>;
+}