@soulcraft/brainy 4.11.2 → 5.0.0

package/dist/storage/cow/CommitObject.js

@@ -0,0 +1,431 @@
+/**
+ * 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';
+/**
+ * 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 class CommitBuilder {
+    constructor(blobStorage) {
+        this._message = 'Auto-commit';
+        this._author = 'system';
+        this._timestamp = Date.now();
+        this._metadata = {};
+        this.blobStorage = blobStorage;
+    }
+    static create(blobStorage) {
+        return new CommitBuilder(blobStorage);
+    }
+    /**
+     * Set tree hash
+     */
+    tree(hash) {
+        this._tree = hash;
+        return this;
+    }
+    /**
+     * Set parent commit hash (null for initial commit)
+     */
+    parent(hash) {
+        this._parent = hash;
+        return this;
+    }
+    /**
+     * Set commit message
+     */
+    message(message) {
+        this._message = message;
+        return this;
+    }
+    /**
+     * Set commit author
+     */
+    author(author) {
+        this._author = author;
+        return this;
+    }
+    /**
+     * Set commit timestamp (defaults to now)
+     */
+    timestamp(timestamp) {
+        this._timestamp = typeof timestamp === 'number' ? timestamp : timestamp.getTime();
+        return this;
+    }
+    /**
+     * Add tag to commit
+     */
+    tag(tag) {
+        if (!this._metadata.tags) {
+            this._metadata.tags = [];
+        }
+        this._metadata.tags.push(tag);
+        return this;
+    }
+    /**
+     * Set branch name
+     */
+    branch(branch) {
+        this._metadata.branch = branch;
+        return this;
+    }
+    /**
+     * Set operation type
+     */
+    operation(operation) {
+        this._metadata.operation = operation;
+        return this;
+    }
+    /**
+     * Set entity count
+     */
+    entityCount(count) {
+        this._metadata.entityCount = count;
+        return this;
+    }
+    /**
+     * Set relationship count
+     */
+    relationshipCount(count) {
+        this._metadata.relationshipCount = count;
+        return this;
+    }
+    /**
+     * Set custom metadata
+     */
+    meta(key, value) {
+        this._metadata[key] = value;
+        return this;
+    }
+    /**
+     * Build and persist the commit object
+     *
+     * @returns Commit hash
+     */
+    async build() {
+        if (!this._tree) {
+            throw new Error('CommitBuilder: tree hash is required');
+        }
+        const commit = {
+            tree: this._tree,
+            parent: this._parent ?? null,
+            message: this._message,
+            author: this._author,
+            timestamp: this._timestamp,
+            metadata: Object.keys(this._metadata).length > 0 ? this._metadata : undefined
+        };
+        return CommitObject.write(this.blobStorage, commit);
+    }
+}
+/**
+ * CommitObject: Represents a point-in-time snapshot in COW storage
+ */
+export 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) {
+        return Buffer.from(JSON.stringify(commit, null, 0)); // Compact JSON
+    }
+    /**
+     * Deserialize commit object from Buffer
+     *
+     * @param data - Serialized commit
+     * @returns Commit object
+     */
+    static deserialize(data) {
+        const commit = JSON.parse(data.toString());
+        // Validate structure
+        if (typeof commit.tree !== 'string' || commit.tree.length !== 64) {
+            throw new Error('Invalid commit object: tree must be 64-char SHA-256');
+        }
+        if (commit.parent !== null && (typeof commit.parent !== 'string' || commit.parent.length !== 64)) {
+            throw new Error('Invalid commit object: parent must be 64-char SHA-256 or null');
+        }
+        if (typeof commit.message !== 'string') {
+            throw new Error('Invalid commit object: message must be string');
+        }
+        if (typeof commit.author !== 'string') {
+            throw new Error('Invalid commit object: author must be string');
+        }
+        if (typeof commit.timestamp !== 'number') {
+            throw new Error('Invalid commit object: timestamp must be number');
+        }
+        if (commit.metadata !== undefined && typeof commit.metadata !== 'object') {
+            throw new Error('Invalid commit object: metadata must be object');
+        }
+        return commit;
+    }
+    /**
+     * Compute hash of commit object
+     *
+     * @param commit - Commit object
+     * @returns SHA-256 hash
+     */
+    static hash(commit) {
+        const data = CommitObject.serialize(commit);
+        return BlobStorage.hash(data);
+    }
+    /**
+     * Write commit object to blob storage
+     *
+     * @param blobStorage - Blob storage instance
+     * @param commit - Commit object
+     * @returns Commit hash
+     */
+    static async write(blobStorage, commit) {
+        const data = CommitObject.serialize(commit);
+        return blobStorage.write(data, { type: 'commit', compression: 'auto' });
+    }
+    /**
+     * Read commit object from blob storage
+     *
+     * @param blobStorage - Blob storage instance
+     * @param hash - Commit hash
+     * @returns Commit object
+     */
+    static async read(blobStorage, hash) {
+        const data = await blobStorage.read(hash);
+        return CommitObject.deserialize(data);
+    }
+    /**
+     * Check if commit is initial commit (has no parent)
+     *
+     * @param commit - Commit object
+     * @returns True if initial commit
+     */
+    static isInitial(commit) {
+        return commit.parent === null;
+    }
+    /**
+     * 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) {
+        // For now, we only support single-parent commits
+        // Future: extend to support multiple parents
+        return commit.metadata?.merge !== undefined;
+    }
+    /**
+     * 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, tag) {
+        return commit.metadata?.tags?.includes(tag) ?? false;
+    }
+    /**
+     * Get all tags from commit
+     *
+     * @param commit - Commit object
+     * @returns Array of tags
+     */
+    static getTags(commit) {
+        return commit.metadata?.tags ?? [];
+    }
+    /**
+     * 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 async *walk(blobStorage, startHash, options) {
+        let currentHash = startHash;
+        let depth = 0;
+        while (currentHash) {
+            // Check max depth
+            if (options?.maxDepth && depth >= options.maxDepth) {
+                break;
+            }
+            // Read commit
+            const commit = await CommitObject.read(blobStorage, currentHash);
+            // Check filter
+            if (options?.filter && !options.filter(commit)) {
+                currentHash = commit.parent;
+                depth++;
+                continue;
+            }
+            // Yield commit
+            yield commit;
+            // Check stop conditions
+            if (options?.until && commit.timestamp < options.until) {
+                break;
+            }
+            if (options?.stopAt && currentHash === options.stopAt) {
+                break;
+            }
+            // Move to parent
+            currentHash = commit.parent;
+            depth++;
+        }
+    }
+    /**
+     * 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 async findAtTime(blobStorage, startHash, timestamp) {
+        for await (const commit of CommitObject.walk(blobStorage, startHash)) {
+            if (commit.timestamp <= timestamp) {
+                return commit;
+            }
+        }
+        return 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 async getHistory(blobStorage, startHash, options) {
+        const commits = [];
+        for await (const commit of CommitObject.walk(blobStorage, startHash, options)) {
+            commits.push(commit);
+        }
+        return commits;
+    }
+    /**
+     * 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 async findCommonAncestor(blobStorage, hash1, hash2) {
+        // Build set of all ancestors of commit1
+        const ancestors1 = new Set();
+        for await (const commit of CommitObject.walk(blobStorage, hash1)) {
+            ancestors1.add(CommitObject.hash(commit));
+        }
+        // Walk commit2 history, find first commit in ancestors1
+        for await (const commit of CommitObject.walk(blobStorage, hash2)) {
+            const commitHash = CommitObject.hash(commit);
+            if (ancestors1.has(commitHash)) {
+                return commit;
+            }
+        }
+        return 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 async countBetween(blobStorage, fromHash, toHash) {
+        let count = 0;
+        for await (const commit of CommitObject.walk(blobStorage, fromHash, {
+            stopAt: toHash
+        })) {
+            count++;
+        }
+        return count;
+    }
+    /**
+     * 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 async getInTimeRange(blobStorage, startHash, startTime, endTime) {
+        const commits = [];
+        for await (const commit of CommitObject.walk(blobStorage, startHash, {
+            until: startTime
+        })) {
+            if (commit.timestamp >= startTime && commit.timestamp <= endTime) {
+                commits.push(commit);
+            }
+        }
+        return commits;
+    }
+    /**
+     * 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 async getByAuthor(blobStorage, startHash, author, options) {
+        const commits = [];
+        for await (const commit of CommitObject.walk(blobStorage, startHash, {
+            ...options,
+            filter: c => c.author === author
+        })) {
+            commits.push(commit);
+        }
+        return commits;
+    }
+    /**
+     * 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 async getByOperation(blobStorage, startHash, operation, options) {
+        const commits = [];
+        for await (const commit of CommitObject.walk(blobStorage, startHash, {
+            ...options,
+            filter: c => c.metadata?.operation === operation
+        })) {
+            commits.push(commit);
+        }
+        return commits;
+    }
+}
+//# sourceMappingURL=CommitObject.js.map

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

@@ -0,0 +1,213 @@
+/**
+ * RefManager: Branch and reference management for COW (Copy-on-Write)
+ *
+ * Similar to Git refs, manages symbolic names (branches, tags) that point to commits.
+ *
+ * Structure:
+ * - refs/heads/main → commit hash (main branch)
+ * - refs/heads/experiment → commit hash (experiment branch)
+ * - refs/tags/v1.0.0 → commit hash (version tag)
+ * - HEAD → ref name (current branch)
+ *
+ * Features:
+ * - Branch management (create, delete, list)
+ * - Tag management
+ * - HEAD pointer (current branch)
+ * - Fast-forward and force updates
+ * - Atomic operations
+ *
+ * @module storage/cow/RefManager
+ */
+import type { COWStorageAdapter } from './BlobStorage.js';
+/**
+ * Reference type
+ */
+export type RefType = 'branch' | 'tag' | 'remote';
+/**
+ * Reference object
+ */
+export interface Ref {
+    name: string;
+    commitHash: string;
+    type: RefType;
+    createdAt: number;
+    updatedAt: number;
+    metadata?: {
+        description?: string;
+        author?: string;
+        [key: string]: any;
+    };
+}
+/**
+ * Ref update options
+ */
+export interface RefUpdateOptions {
+    force?: boolean;
+    createOnly?: boolean;
+    updateOnly?: boolean;
+    expectedOldValue?: string;
+}
+/**
+ * RefManager: Manages branches, tags, and HEAD pointer
+ *
+ * Pure implementation for v5.0.0 - no backward compatibility
+ */
+export declare class RefManager {
+    private adapter;
+    private cache;
+    private cacheValid;
+    constructor(adapter: COWStorageAdapter);
+    /**
+     * Get reference by name
+     *
+     * @param name - Reference name (e.g., 'main', 'refs/heads/main')
+     * @returns Reference object or undefined
+     */
+    getRef(name: string): Promise<Ref | undefined>;
+    /**
+     * Set reference to point to commit
+     *
+     * @param name - Reference name
+     * @param commitHash - Commit hash to point to
+     * @param options - Update options
+     */
+    setRef(name: string, commitHash: string, options?: RefUpdateOptions): Promise<void>;
+    /**
+     * Delete reference
+     *
+     * @param name - Reference name
+     */
+    deleteRef(name: string): Promise<void>;
+    /**
+     * List all references
+     *
+     * @param type - Filter by type (optional)
+     * @returns Array of references
+     */
+    listRefs(type?: RefType): Promise<Ref[]>;
+    /**
+     * Copy reference (create branch from existing ref)
+     *
+     * @param sourceName - Source reference name
+     * @param targetName - Target reference name
+     * @param options - Update options
+     */
+    copyRef(sourceName: string, targetName: string, options?: RefUpdateOptions): Promise<void>;
+    /**
+     * Get current HEAD (current branch)
+     *
+     * @returns HEAD reference or undefined
+     */
+    getHead(): Promise<Ref | undefined>;
+    /**
+     * Set HEAD to point to branch
+     *
+     * @param branchName - Branch name (e.g., 'main', 'refs/heads/experiment')
+     */
+    setHead(branchName: string): Promise<void>;
+    /**
+     * Get current commit hash (resolves HEAD)
+     *
+     * @returns Current commit hash or undefined
+     */
+    getCurrentCommit(): Promise<string | undefined>;
+    /**
+     * Create branch
+     *
+     * @param name - Branch name (e.g., 'experiment')
+     * @param commitHash - Commit hash to point to
+     * @param options - Create options
+     */
+    createBranch(name: string, commitHash: string, options?: {
+        description?: string;
+        author?: string;
+    }): Promise<void>;
+    /**
+     * Delete branch
+     *
+     * @param name - Branch name
+     */
+    deleteBranch(name: string): Promise<void>;
+    /**
+     * List all branches
+     *
+     * @returns Array of branch references
+     */
+    listBranches(): Promise<Ref[]>;
+    /**
+     * Create tag
+     *
+     * @param name - Tag name (e.g., 'v1.0.0')
+     * @param commitHash - Commit hash to point to
+     * @param options - Create options
+     */
+    createTag(name: string, commitHash: string, options?: {
+        description?: string;
+        author?: string;
+    }): Promise<void>;
+    /**
+     * Delete tag
+     *
+     * @param name - Tag name
+     */
+    deleteTag(name: string): Promise<void>;
+    /**
+     * List all tags
+     *
+     * @returns Array of tag references
+     */
+    listTags(): Promise<Ref[]>;
+    /**
+     * Check if reference exists
+     *
+     * @param name - Reference name
+     * @returns True if reference exists
+     */
+    hasRef(name: string): Promise<boolean>;
+    /**
+     * Update reference to new commit (with validation)
+     *
+     * @param name - Reference name
+     * @param newCommitHash - New commit hash
+     * @param oldCommitHash - Expected old commit hash (for safety)
+     */
+    updateRef(name: string, newCommitHash: string, oldCommitHash?: string): Promise<void>;
+    /**
+     * Get commit hash for reference
+     *
+     * @param name - Reference name
+     * @returns Commit hash or undefined
+     */
+    resolveRef(name: string): Promise<string | undefined>;
+    /**
+     * Find references pointing to commit
+     *
+     * @param commitHash - Commit hash
+     * @returns Array of references pointing to this commit
+     */
+    findRefsPointingTo(commitHash: string): Promise<Ref[]>;
+    /**
+     * Clear cache (useful for testing)
+     */
+    clearCache(): void;
+    /**
+     * Normalize reference name to full format
+     *
+     * Examples:
+     * - 'main' → 'refs/heads/main'
+     * - 'v1.0.0' (with type='tag') → 'refs/tags/v1.0.0'
+     * - 'refs/heads/experiment' → 'refs/heads/experiment'
+     *
+     * @param name - Reference name
+     * @param type - Reference type hint
+     * @returns Full reference name
+     */
+    private normalizeRefName;
+    /**
+     * Get reference type from full name
+     *
+     * @param fullName - Full reference name
+     * @returns Reference type
+     */
+    private getRefType;
+}