@soulcraft/brainy 4.11.2 → 5.1.0

package/dist/storage/cow/TreeObject.js

@@ -0,0 +1,293 @@
+/**
+ * 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';
+/**
+ * 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 class TreeBuilder {
+    constructor(blobStorage) {
+        this.entries = [];
+        this.blobStorage = blobStorage;
+    }
+    static create(blobStorage) {
+        return new TreeBuilder(blobStorage);
+    }
+    /**
+     * 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, hash, size) {
+        this.entries.push({
+            name,
+            hash,
+            type: 'blob',
+            size
+        });
+        return 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, treeHash, size) {
+        this.entries.push({
+            name,
+            hash: treeHash,
+            type: 'tree',
+            size
+        });
+        return this;
+    }
+    /**
+     * Build and persist the tree object
+     *
+     * @returns Tree hash
+     */
+    async build() {
+        const tree = {
+            entries: this.entries.sort((a, b) => a.name.localeCompare(b.name)),
+            createdAt: Date.now()
+        };
+        return TreeObject.write(this.blobStorage, tree);
+    }
+}
+/**
+ * TreeObject: Represents directory structure in COW storage
+ */
+export 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) {
+        return Buffer.from(JSON.stringify(tree, null, 0)); // Compact JSON
+    }
+    /**
+     * Deserialize tree object from Buffer
+     *
+     * @param data - Serialized tree
+     * @returns Tree object
+     */
+    static deserialize(data) {
+        const tree = JSON.parse(data.toString());
+        // Validate structure
+        if (!tree.entries || !Array.isArray(tree.entries)) {
+            throw new Error('Invalid tree object: missing entries array');
+        }
+        if (typeof tree.createdAt !== 'number') {
+            throw new Error('Invalid tree object: missing or invalid createdAt');
+        }
+        // Validate entries
+        for (const entry of tree.entries) {
+            if (typeof entry.name !== 'string') {
+                throw new Error(`Invalid tree entry: name must be string`);
+            }
+            if (typeof entry.hash !== 'string' || entry.hash.length !== 64) {
+                throw new Error(`Invalid tree entry: hash must be 64-char SHA-256`);
+            }
+            if (entry.type !== 'blob' && entry.type !== 'tree') {
+                throw new Error(`Invalid tree entry: type must be 'blob' or 'tree'`);
+            }
+            if (typeof entry.size !== 'number' || entry.size < 0) {
+                throw new Error(`Invalid tree entry: size must be non-negative number`);
+            }
+        }
+        return tree;
+    }
+    /**
+     * Compute hash of tree object
+     *
+     * @param tree - Tree object
+     * @returns SHA-256 hash
+     */
+    static hash(tree) {
+        const data = TreeObject.serialize(tree);
+        return BlobStorage.hash(data);
+    }
+    /**
+     * Write tree object to blob storage
+     *
+     * @param blobStorage - Blob storage instance
+     * @param tree - Tree object
+     * @returns Tree hash
+     */
+    static async write(blobStorage, tree) {
+        const data = TreeObject.serialize(tree);
+        return blobStorage.write(data, { type: 'tree', compression: 'auto' });
+    }
+    /**
+     * Read tree object from blob storage
+     *
+     * @param blobStorage - Blob storage instance
+     * @param hash - Tree hash
+     * @returns Tree object
+     */
+    static async read(blobStorage, hash) {
+        const data = await blobStorage.read(hash);
+        return TreeObject.deserialize(data);
+    }
+    /**
+     * Get specific entry from tree
+     *
+     * @param tree - Tree object
+     * @param name - Entry name
+     * @returns Tree entry or undefined
+     */
+    static getEntry(tree, name) {
+        return tree.entries.find(e => e.name === name);
+    }
+    /**
+     * Get all blob entries from tree (non-recursive)
+     *
+     * @param tree - Tree object
+     * @returns Array of blob entries
+     */
+    static getBlobs(tree) {
+        return tree.entries.filter(e => e.type === 'blob');
+    }
+    /**
+     * Get all subtree entries from tree (non-recursive)
+     *
+     * @param tree - Tree object
+     * @returns Array of tree entries
+     */
+    static getSubtrees(tree) {
+        return tree.entries.filter(e => e.type === 'tree');
+    }
+    /**
+     * Walk tree recursively, yielding all blob entries
+     *
+     * @param blobStorage - Blob storage instance
+     * @param tree - Tree object
+     */
+    static async *walk(blobStorage, tree) {
+        for (const entry of tree.entries) {
+            if (entry.type === 'blob') {
+                yield entry;
+            }
+            else {
+                // Recurse into subtree
+                const subtree = await TreeObject.read(blobStorage, entry.hash);
+                yield* TreeObject.walk(blobStorage, subtree);
+            }
+        }
+    }
+    /**
+     * Compute total size of tree (recursive)
+     *
+     * @param blobStorage - Blob storage instance
+     * @param tree - Tree object
+     * @returns Total size in bytes
+     */
+    static async getTotalSize(blobStorage, tree) {
+        let totalSize = 0;
+        for await (const entry of TreeObject.walk(blobStorage, tree)) {
+            totalSize += entry.size;
+        }
+        return totalSize;
+    }
+    /**
+     * 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 async updateEntry(blobStorage, tree, name, hash, size) {
+        const builder = TreeBuilder.create(blobStorage);
+        // Copy all entries except the one being updated
+        for (const entry of tree.entries) {
+            if (entry.name === name) {
+                // Replace with new entry
+                if (entry.type === 'blob') {
+                    builder.addBlob(name, hash, size);
+                }
+                else {
+                    builder.addTree(name, hash, size);
+                }
+            }
+            else {
+                // Keep existing entry
+                if (entry.type === 'blob') {
+                    builder.addBlob(entry.name, entry.hash, entry.size);
+                }
+                else {
+                    builder.addTree(entry.name, entry.hash, entry.size);
+                }
+            }
+        }
+        // If entry didn't exist, add it
+        if (!TreeObject.getEntry(tree, name)) {
+            builder.addBlob(name, hash, size);
+        }
+        return builder.build();
+    }
+    /**
+     * Diff two trees, return changed/added/deleted entries
+     *
+     * @param tree1 - First tree (base)
+     * @param tree2 - Second tree (comparison)
+     * @returns Diff result
+     */
+    static diff(tree1, tree2) {
+        const entries1 = new Map(tree1.entries.map(e => [e.name, e]));
+        const entries2 = new Map(tree2.entries.map(e => [e.name, e]));
+        const added = [];
+        const modified = [];
+        const deleted = [];
+        // Find added and modified
+        for (const [name, entry2] of entries2) {
+            const entry1 = entries1.get(name);
+            if (!entry1) {
+                added.push(entry2);
+            }
+            else if (entry1.hash !== entry2.hash) {
+                modified.push(entry2);
+            }
+        }
+        // Find deleted
+        for (const [name, entry1] of entries1) {
+            if (!entries2.has(name)) {
+                deleted.push(entry1);
+            }
+        }
+        return { added, modified, deleted };
+    }
+}
+//# sourceMappingURL=TreeObject.js.map

package/dist/storage/storageFactory.d.ts

@@ -290,6 +290,12 @@ export interface StorageOptions {
          */
         readOnly?: boolean;
     };
+    /**
+     * COW (Copy-on-Write) configuration for instant fork() capability
+     * v5.0.1: COW is now always enabled (automatic, zero-config)
+     */
+    branch?: string;
+    enableCompression?: boolean;
 }
 /**
  * Create a storage adapter based on the environment and configuration