@soulcraft/brainy 4.11.2 → 5.1.0

package/dist/storage/cow/RefManager.js

@@ -0,0 +1,409 @@
+/**
+ * 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
+ */
+/**
+ * RefManager: Manages branches, tags, and HEAD pointer
+ *
+ * Pure implementation for v5.0.0 - no backward compatibility
+ */
+export class RefManager {
+    constructor(adapter) {
+        this.adapter = adapter;
+        this.cache = new Map();
+        this.cacheValid = false;
+    }
+    /**
+     * Get reference by name
+     *
+     * @param name - Reference name (e.g., 'main', 'refs/heads/main')
+     * @returns Reference object or undefined
+     */
+    async getRef(name) {
+        const fullName = this.normalizeRefName(name);
+        // Check cache
+        if (this.cacheValid && this.cache.has(fullName)) {
+            return this.cache.get(fullName);
+        }
+        // Read from storage
+        const data = await this.adapter.get(`ref:${fullName}`);
+        if (!data) {
+            return undefined;
+        }
+        const ref = JSON.parse(data.toString());
+        // Update cache
+        this.cache.set(fullName, ref);
+        return ref;
+    }
+    /**
+     * Set reference to point to commit
+     *
+     * @param name - Reference name
+     * @param commitHash - Commit hash to point to
+     * @param options - Update options
+     */
+    async setRef(name, commitHash, options = {}) {
+        const fullName = this.normalizeRefName(name);
+        // Validate commit hash format
+        if (!/^[a-f0-9]{64}$/.test(commitHash)) {
+            throw new Error(`Invalid commit hash: ${commitHash}`);
+        }
+        // Check if ref exists
+        const existing = await this.getRef(fullName);
+        // Handle createOnly
+        if (options.createOnly && existing) {
+            throw new Error(`Ref already exists: ${fullName}`);
+        }
+        // Handle updateOnly
+        if (options.updateOnly && !existing) {
+            throw new Error(`Ref does not exist: ${fullName}`);
+        }
+        // Handle CAS (Compare-And-Swap)
+        if (options.expectedOldValue !== undefined) {
+            if (!existing || existing.commitHash !== options.expectedOldValue) {
+                throw new Error(`Ref update failed: expected ${options.expectedOldValue}, ` +
+                    `got ${existing?.commitHash ?? 'none'}`);
+            }
+        }
+        // Check for fast-forward (if not force)
+        if (!options.force && existing) {
+            // TODO: Verify this is a fast-forward update
+            // For now, allow all updates
+        }
+        // Create/update ref
+        const ref = {
+            name: fullName,
+            commitHash,
+            type: this.getRefType(fullName),
+            createdAt: existing?.createdAt ?? Date.now(),
+            updatedAt: Date.now(),
+            metadata: existing?.metadata
+        };
+        // Write to storage
+        await this.adapter.put(`ref:${fullName}`, Buffer.from(JSON.stringify(ref)));
+        // Update cache
+        this.cache.set(fullName, ref);
+        this.cacheValid = false; // Invalidate for listRefs
+    }
+    /**
+     * Delete reference
+     *
+     * @param name - Reference name
+     */
+    async deleteRef(name) {
+        const fullName = this.normalizeRefName(name);
+        // Don't allow deleting HEAD
+        if (fullName === 'HEAD') {
+            throw new Error('Cannot delete HEAD');
+        }
+        // Don't allow deleting main if it's the only branch
+        if (fullName === 'refs/heads/main') {
+            const branches = await this.listRefs('branch');
+            if (branches.length === 1) {
+                throw new Error('Cannot delete last branch');
+            }
+        }
+        // Delete from storage
+        await this.adapter.delete(`ref:${fullName}`);
+        // Update cache
+        this.cache.delete(fullName);
+        this.cacheValid = false;
+    }
+    /**
+     * List all references
+     *
+     * @param type - Filter by type (optional)
+     * @returns Array of references
+     */
+    async listRefs(type) {
+        // Get all ref keys
+        const keys = await this.adapter.list('ref:');
+        const refs = [];
+        for (const key of keys) {
+            const refName = key.replace(/^ref:/, '');
+            // Skip HEAD in listings (it's special)
+            if (refName === 'HEAD') {
+                continue;
+            }
+            const ref = await this.getRef(refName);
+            if (ref) {
+                // Filter by type if requested
+                if (!type || ref.type === type) {
+                    refs.push(ref);
+                }
+            }
+        }
+        // Mark cache as valid
+        this.cacheValid = true;
+        return refs.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /**
+     * Copy reference (create branch from existing ref)
+     *
+     * @param sourceName - Source reference name
+     * @param targetName - Target reference name
+     * @param options - Update options
+     */
+    async copyRef(sourceName, targetName, options = {}) {
+        const sourceRef = await this.getRef(sourceName);
+        if (!sourceRef) {
+            throw new Error(`Source ref not found: ${sourceName}`);
+        }
+        // Set target ref to same commit as source
+        await this.setRef(targetName, sourceRef.commitHash, options);
+    }
+    /**
+     * Get current HEAD (current branch)
+     *
+     * @returns HEAD reference or undefined
+     */
+    async getHead() {
+        const data = await this.adapter.get('ref:HEAD');
+        if (!data) {
+            return undefined;
+        }
+        const head = JSON.parse(data.toString());
+        // Resolve symbolic ref
+        return this.getRef(head.ref);
+    }
+    /**
+     * Set HEAD to point to branch
+     *
+     * @param branchName - Branch name (e.g., 'main', 'refs/heads/experiment')
+     */
+    async setHead(branchName) {
+        const fullName = this.normalizeRefName(branchName);
+        // Verify branch exists
+        const branch = await this.getRef(fullName);
+        if (!branch) {
+            throw new Error(`Branch not found: ${fullName}`);
+        }
+        if (branch.type !== 'branch') {
+            throw new Error(`Cannot set HEAD to non-branch ref: ${fullName}`);
+        }
+        // Set HEAD (symbolic ref)
+        const head = { ref: fullName };
+        await this.adapter.put('ref:HEAD', Buffer.from(JSON.stringify(head)));
+    }
+    /**
+     * Get current commit hash (resolves HEAD)
+     *
+     * @returns Current commit hash or undefined
+     */
+    async getCurrentCommit() {
+        const head = await this.getHead();
+        return head?.commitHash;
+    }
+    /**
+     * Create branch
+     *
+     * @param name - Branch name (e.g., 'experiment')
+     * @param commitHash - Commit hash to point to
+     * @param options - Create options
+     */
+    async createBranch(name, commitHash, options) {
+        const fullName = this.normalizeRefName(name, 'branch');
+        await this.setRef(fullName, commitHash, { createOnly: true });
+        // Update metadata if provided
+        if (options?.description || options?.author) {
+            const ref = await this.getRef(fullName);
+            if (ref) {
+                ref.metadata = {
+                    ...ref.metadata,
+                    description: options.description,
+                    author: options.author
+                };
+                await this.adapter.put(`ref:${fullName}`, Buffer.from(JSON.stringify(ref)));
+            }
+        }
+    }
+    /**
+     * Delete branch
+     *
+     * @param name - Branch name
+     */
+    async deleteBranch(name) {
+        const fullName = this.normalizeRefName(name, 'branch');
+        await this.deleteRef(fullName);
+    }
+    /**
+     * List all branches
+     *
+     * @returns Array of branch references
+     */
+    async listBranches() {
+        return this.listRefs('branch');
+    }
+    /**
+     * Create tag
+     *
+     * @param name - Tag name (e.g., 'v1.0.0')
+     * @param commitHash - Commit hash to point to
+     * @param options - Create options
+     */
+    async createTag(name, commitHash, options) {
+        const fullName = this.normalizeRefName(name, 'tag');
+        await this.setRef(fullName, commitHash, { createOnly: true });
+        // Update metadata if provided
+        if (options?.description || options?.author) {
+            const ref = await this.getRef(fullName);
+            if (ref) {
+                ref.metadata = {
+                    ...ref.metadata,
+                    description: options.description,
+                    author: options.author
+                };
+                await this.adapter.put(`ref:${fullName}`, Buffer.from(JSON.stringify(ref)));
+            }
+        }
+    }
+    /**
+     * Delete tag
+     *
+     * @param name - Tag name
+     */
+    async deleteTag(name) {
+        const fullName = this.normalizeRefName(name, 'tag');
+        await this.deleteRef(fullName);
+    }
+    /**
+     * List all tags
+     *
+     * @returns Array of tag references
+     */
+    async listTags() {
+        return this.listRefs('tag');
+    }
+    /**
+     * Check if reference exists
+     *
+     * @param name - Reference name
+     * @returns True if reference exists
+     */
+    async hasRef(name) {
+        const ref = await this.getRef(name);
+        return ref !== undefined;
+    }
+    /**
+     * Update reference to new commit (with validation)
+     *
+     * @param name - Reference name
+     * @param newCommitHash - New commit hash
+     * @param oldCommitHash - Expected old commit hash (for safety)
+     */
+    async updateRef(name, newCommitHash, oldCommitHash) {
+        const options = {};
+        if (oldCommitHash) {
+            options.expectedOldValue = oldCommitHash;
+        }
+        await this.setRef(name, newCommitHash, options);
+    }
+    /**
+     * Get commit hash for reference
+     *
+     * @param name - Reference name
+     * @returns Commit hash or undefined
+     */
+    async resolveRef(name) {
+        const ref = await this.getRef(name);
+        return ref?.commitHash;
+    }
+    /**
+     * Find references pointing to commit
+     *
+     * @param commitHash - Commit hash
+     * @returns Array of references pointing to this commit
+     */
+    async findRefsPointingTo(commitHash) {
+        const allRefs = await this.listRefs();
+        return allRefs.filter(ref => ref.commitHash === commitHash);
+    }
+    /**
+     * Clear cache (useful for testing)
+     */
+    clearCache() {
+        this.cache.clear();
+        this.cacheValid = false;
+    }
+    // ========== PRIVATE METHODS ==========
+    /**
+     * 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
+     */
+    normalizeRefName(name, type) {
+        // Already full format
+        if (name.startsWith('refs/')) {
+            return name;
+        }
+        // HEAD is special
+        if (name === 'HEAD') {
+            return 'HEAD';
+        }
+        // Infer type from name if not provided
+        if (!type) {
+            // Tags usually start with 'v' or contain dots
+            if (name.startsWith('v') && /\d/.test(name)) {
+                type = 'tag';
+            }
+            else {
+                type = 'branch'; // Default to branch
+            }
+        }
+        // Add prefix
+        switch (type) {
+            case 'branch':
+                return `refs/heads/${name}`;
+            case 'tag':
+                return `refs/tags/${name}`;
+            case 'remote':
+                return `refs/remotes/${name}`;
+            default:
+                return name;
+        }
+    }
+    /**
+     * Get reference type from full name
+     *
+     * @param fullName - Full reference name
+     * @returns Reference type
+     */
+    getRefType(fullName) {
+        if (fullName.startsWith('refs/heads/')) {
+            return 'branch';
+        }
+        else if (fullName.startsWith('refs/tags/')) {
+            return 'tag';
+        }
+        else if (fullName.startsWith('refs/remotes/')) {
+            return 'remote';
+        }
+        else {
+            return 'branch'; // Default
+        }
+    }
+}
+//# sourceMappingURL=RefManager.js.map

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

@@ -0,0 +1,177 @@
+/**
+ * TreeObject: Directory structure for COW (Copy-on-Write)
+ *
+ * Similar to Git trees, represents the structure of a Brainy instance at a point in time.
+ * Trees contain entries mapping names to blob hashes.
+ *
+ * Structure:
+ * - entities/ → tree hash (entity blobs)
+ * - indexes/nouns → blob hash (HNSW noun index)
+ * - indexes/metadata → blob hash (metadata index)
+ * - indexes/graph → blob hash (graph adjacency index)
+ * - indexes/deleted → blob hash (deleted items index)
+ *
+ * @module storage/cow/TreeObject
+ */
+import { BlobStorage } from './BlobStorage.js';
+/**
+ * Tree entry: name → blob hash mapping
+ */
+export interface TreeEntry {
+    name: string;
+    hash: string;
+    type: 'blob' | 'tree';
+    size: number;
+}
+/**
+ * Tree object structure
+ */
+export interface TreeObject {
+    entries: TreeEntry[];
+    createdAt: number;
+}
+/**
+ * TreeBuilder: Fluent API for building tree objects
+ *
+ * Example:
+ * ```typescript
+ * const tree = await TreeBuilder.create(blobStorage)
+ *   .addBlob('entities/abc123', entityHash, size)
+ *   .addBlob('indexes/nouns', nounsHash, size)
+ *   .build()
+ * ```
+ */
+export declare class TreeBuilder {
+    private entries;
+    private blobStorage;
+    constructor(blobStorage: BlobStorage);
+    static create(blobStorage: BlobStorage): TreeBuilder;
+    /**
+     * Add a blob entry to the tree
+     *
+     * @param name - Entry name (e.g., 'entities/abc123')
+     * @param hash - Blob hash
+     * @param size - Original blob size
+     */
+    addBlob(name: string, hash: string, size: number): this;
+    /**
+     * Add a subtree entry to the tree
+     *
+     * @param name - Subtree name (e.g., 'entities/')
+     * @param treeHash - Tree hash
+     * @param size - Total size of subtree
+     */
+    addTree(name: string, treeHash: string, size: number): this;
+    /**
+     * Build and persist the tree object
+     *
+     * @returns Tree hash
+     */
+    build(): Promise<string>;
+}
+/**
+ * TreeObject: Represents directory structure in COW storage
+ */
+export declare class TreeObject {
+    /**
+     * Serialize tree object to Buffer
+     *
+     * Format: JSON (simple, debuggable)
+     * Future: Could use protobuf for efficiency
+     *
+     * @param tree - Tree object
+     * @returns Serialized tree
+     */
+    static serialize(tree: TreeObject): Buffer;
+    /**
+     * Deserialize tree object from Buffer
+     *
+     * @param data - Serialized tree
+     * @returns Tree object
+     */
+    static deserialize(data: Buffer): TreeObject;
+    /**
+     * Compute hash of tree object
+     *
+     * @param tree - Tree object
+     * @returns SHA-256 hash
+     */
+    static hash(tree: TreeObject): string;
+    /**
+     * Write tree object to blob storage
+     *
+     * @param blobStorage - Blob storage instance
+     * @param tree - Tree object
+     * @returns Tree hash
+     */
+    static write(blobStorage: BlobStorage, tree: TreeObject): Promise<string>;
+    /**
+     * Read tree object from blob storage
+     *
+     * @param blobStorage - Blob storage instance
+     * @param hash - Tree hash
+     * @returns Tree object
+     */
+    static read(blobStorage: BlobStorage, hash: string): Promise<TreeObject>;
+    /**
+     * Get specific entry from tree
+     *
+     * @param tree - Tree object
+     * @param name - Entry name
+     * @returns Tree entry or undefined
+     */
+    static getEntry(tree: TreeObject, name: string): TreeEntry | undefined;
+    /**
+     * Get all blob entries from tree (non-recursive)
+     *
+     * @param tree - Tree object
+     * @returns Array of blob entries
+     */
+    static getBlobs(tree: TreeObject): TreeEntry[];
+    /**
+     * Get all subtree entries from tree (non-recursive)
+     *
+     * @param tree - Tree object
+     * @returns Array of tree entries
+     */
+    static getSubtrees(tree: TreeObject): TreeEntry[];
+    /**
+     * Walk tree recursively, yielding all blob entries
+     *
+     * @param blobStorage - Blob storage instance
+     * @param tree - Tree object
+     */
+    static walk(blobStorage: BlobStorage, tree: TreeObject): AsyncIterableIterator<TreeEntry>;
+    /**
+     * Compute total size of tree (recursive)
+     *
+     * @param blobStorage - Blob storage instance
+     * @param tree - Tree object
+     * @returns Total size in bytes
+     */
+    static getTotalSize(blobStorage: BlobStorage, tree: TreeObject): Promise<number>;
+    /**
+     * Create a new tree by updating a single entry
+     * (Copy-on-write: creates new tree, doesn't modify original)
+     *
+     * @param blobStorage - Blob storage instance
+     * @param tree - Original tree
+     * @param name - Entry name to update
+     * @param hash - New blob/tree hash
+     * @param size - New size
+     * @returns New tree hash
+     */
+    static updateEntry(blobStorage: BlobStorage, tree: TreeObject, name: string, hash: string, size: number): Promise<string>;
+    /**
+     * Diff two trees, return changed/added/deleted entries
+     *
+     * @param tree1 - First tree (base)
+     * @param tree2 - Second tree (comparison)
+     * @returns Diff result
+     */
+    static diff(tree1: TreeObject, tree2: TreeObject): {
+        added: TreeEntry[];
+        modified: TreeEntry[];
+        deleted: TreeEntry[];
+    };
+}