@soulcraft/brainy 5.11.1 → 6.0.0

package/dist/brainy.js

@@ -541,6 +541,59 @@ export class Brainy {
             }
         });
     }
+    /**
+     * Batch get multiple entities by IDs (v5.12.0 - Cloud Storage Optimization)
+     *
+     * **Performance**: Eliminates N+1 query pattern
+     * - Current: N × get() = N × 300ms cloud latency = 3-6 seconds for 10-20 entities
+     * - Batched: 1 × batchGet() = 1 × 300ms cloud latency = 0.3 seconds ✨
+     *
+     * **Use cases:**
+     * - VFS tree traversal (get all children at once)
+     * - Relationship traversal (get all targets at once)
+     * - Import operations (batch existence checks)
+     * - Admin tools (fetch multiple entities for listing)
+     *
+     * @param ids Array of entity IDs to fetch
+     * @param options Get options (includeVectors defaults to false for speed)
+     * @returns Map of id → entity (only successfully fetched entities included)
+     *
+     * @example
+     * ```typescript
+     * // VFS getChildren optimization
+     * const childIds = relations.map(r => r.to)
+     * const childrenMap = await brain.batchGet(childIds)
+     * const children = childIds.map(id => childrenMap.get(id)).filter(Boolean)
+     * ```
+     *
+     * @since v5.12.0
+     */
+    async batchGet(ids, options) {
+        await this.ensureInitialized();
+        const results = new Map();
+        if (ids.length === 0)
+            return results;
+        const includeVectors = options?.includeVectors ?? false;
+        if (includeVectors) {
+            // FULL PATH: Load vectors + metadata (currently not batched, fall back to individual)
+            // TODO v5.13.0: Add getNounBatch() for batched vector loading
+            for (const id of ids) {
+                const entity = await this.get(id, { includeVectors: true });
+                if (entity) {
+                    results.set(id, entity);
+                }
+            }
+        }
+        else {
+            // FAST PATH: Metadata-only batch (default) - OPTIMIZED
+            const metadataMap = await this.storage.getNounMetadataBatch(ids);
+            for (const [id, metadata] of metadataMap.entries()) {
+                const entity = await this.convertMetadataToEntity(id, metadata);
+                results.set(id, entity);
+            }
+        }
+        return results;
+    }
     /**
      * Create a flattened Result object from entity
      * Flattens commonly-used entity fields to top level for convenience
@@ -2389,368 +2442,6 @@ export class Brainy {
         console.log(`[asOf] Snapshot ready (lazy-loading, cache size: ${options?.cacheSize || 10000})`);
         return snapshotBrain;
     }
-    /**
-     * Merge a source branch into target branch
-     * @param sourceBranch - Branch to merge from
-     * @param targetBranch - Branch to merge into
-     * @param options - Merge options (strategy, author, onConflict)
-     * @returns Merge result with statistics
-     *
-     * @example
-     * ```typescript
-     * const result = await brain.merge('experiment', 'main', {
-     *   strategy: 'last-write-wins',
-     *   author: 'dev@example.com'
-     * })
-     * console.log(result) // { added: 5, modified: 3, deleted: 1, conflicts: 0 }
-     * ```
-     */
-    async merge(sourceBranch, targetBranch, options) {
-        await this.ensureInitialized();
-        return this.augmentationRegistry.execute('merge', { sourceBranch, targetBranch, options }, async () => {
-            if (!('refManager' in this.storage) || !('blobStorage' in this.storage)) {
-                throw new Error('Merge requires COW-enabled storage (v5.0.0+)');
-            }
-            const strategy = options?.strategy || 'last-write-wins';
-            let added = 0;
-            let modified = 0;
-            let deleted = 0;
-            let conflicts = 0;
-            // Verify both branches exist
-            const branches = await this.listBranches();
-            if (!branches.includes(sourceBranch)) {
-                throw new Error(`Source branch '${sourceBranch}' does not exist`);
-            }
-            if (!branches.includes(targetBranch)) {
-                throw new Error(`Target branch '${targetBranch}' does not exist`);
-            }
-            // 1. Create temporary fork of source branch to read from
-            const sourceFork = await this.fork(`${sourceBranch}-merge-temp-${Date.now()}`);
-            await sourceFork.checkout(sourceBranch);
-            // 2. Save current branch and checkout target
-            const currentBranch = await this.getCurrentBranch();
-            if (currentBranch !== targetBranch) {
-                await this.checkout(targetBranch);
-            }
-            try {
-                // 3. Get all entities from source and target
-                const sourceResults = await sourceFork.find({});
-                const targetResults = await this.find({});
-                // Create maps for faster lookup
-                const targetMap = new Map(targetResults.map(r => [r.entity.id, r.entity]));
-                // 4. Merge entities
-                for (const sourceResult of sourceResults) {
-                    const sourceEntity = sourceResult.entity;
-                    const targetEntity = targetMap.get(sourceEntity.id);
-                    if (!targetEntity) {
-                        // NEW entity in source - ADD to target
-                        await this.add({
-                            id: sourceEntity.id,
-                            type: sourceEntity.type,
-                            data: sourceEntity.data,
-                            vector: sourceEntity.vector
-                        });
-                        added++;
-                    }
-                    else {
-                        // Entity exists in both branches - check for conflicts
-                        const sourceTime = sourceEntity.updatedAt || sourceEntity.createdAt || 0;
-                        const targetTime = targetEntity.updatedAt || targetEntity.createdAt || 0;
-                        // If timestamps are identical, no change needed
-                        if (sourceTime === targetTime) {
-                            continue;
-                        }
-                        // Apply merge strategy
-                        if (strategy === 'last-write-wins') {
-                            if (sourceTime > targetTime) {
-                                // Source is newer, update target
-                                await this.update({ id: sourceEntity.id, data: sourceEntity.data });
-                                modified++;
-                            }
-                            // else target is newer, keep target
-                        }
-                        else if (strategy === 'first-write-wins') {
-                            if (sourceTime < targetTime) {
-                                // Source is older, update target
-                                await this.update({ id: sourceEntity.id, data: sourceEntity.data });
-                                modified++;
-                            }
-                        }
-                        else if (strategy === 'custom' && options?.onConflict) {
-                            // Custom conflict resolution
-                            const resolved = await options.onConflict(targetEntity, sourceEntity);
-                            await this.update({ id: sourceEntity.id, data: resolved.data });
-                            modified++;
-                            conflicts++;
-                        }
-                        else {
-                            // Conflict detected but no resolution strategy
-                            conflicts++;
-                        }
-                    }
-                }
-                // 5. Merge relationships (verbs)
-                const sourceVerbsResult = await sourceFork.storage.getVerbs({});
-                const targetVerbsResult = await this.storage.getVerbs({});
-                const sourceVerbs = sourceVerbsResult.items || [];
-                const targetVerbs = targetVerbsResult.items || [];
-                // Create set of existing target relationships for deduplication
-                const targetRelSet = new Set(targetVerbs.map((v) => `${v.sourceId}-${v.verb}-${v.targetId}`));
-                // Add relationships that don't exist in target
-                for (const sourceVerb of sourceVerbs) {
-                    const key = `${sourceVerb.sourceId}-${sourceVerb.verb}-${sourceVerb.targetId}`;
-                    if (!targetRelSet.has(key)) {
-                        // Only add if both entities exist in target
-                        const hasSource = targetMap.has(sourceVerb.sourceId);
-                        const hasTarget = targetMap.has(sourceVerb.targetId);
-                        if (hasSource && hasTarget) {
-                            await this.relate({
-                                from: sourceVerb.sourceId,
-                                to: sourceVerb.targetId,
-                                type: sourceVerb.verb,
-                                weight: sourceVerb.weight,
-                                metadata: sourceVerb.metadata
-                            });
-                        }
-                    }
-                }
-                // 6. Create merge commit
-                if ('commitLog' in this.storage) {
-                    await this.commit({
-                        message: `Merge ${sourceBranch} into ${targetBranch}`,
-                        author: options?.author || 'system',
-                        metadata: {
-                            mergeType: 'branch',
-                            source: sourceBranch,
-                            target: targetBranch,
-                            strategy,
-                            stats: { added, modified, deleted, conflicts }
-                        }
-                    });
-                }
-            }
-            finally {
-                // 7. Clean up temporary fork (just delete the temp branch)
-                try {
-                    const tempBranchName = `${sourceBranch}-merge-temp-${Date.now()}`;
-                    const branches = await this.listBranches();
-                    if (branches.includes(tempBranchName)) {
-                        await this.deleteBranch(tempBranchName);
-                    }
-                }
-                catch (err) {
-                    // Ignore cleanup errors
-                }
-                // Restore original branch if needed
-                if (currentBranch !== targetBranch) {
-                    await this.checkout(currentBranch);
-                }
-            }
-            return { added, modified, deleted, conflicts };
-        });
-    }
-    /**
-     * Compare differences between two branches (like git diff)
-     * @param sourceBranch - Branch to compare from (defaults to current branch)
-     * @param targetBranch - Branch to compare to (defaults to 'main')
-     * @returns Diff result showing added, modified, and deleted entities/relationships
-     *
-     * @example
-     * ```typescript
-     * // Compare current branch with main
-     * const diff = await brain.diff()
-     *
-     * // Compare two specific branches
-     * const diff = await brain.diff('experiment', 'main')
-     * console.log(diff)
-     * // {
-     * //   entities: { added: 5, modified: 3, deleted: 1 },
-     * //   relationships: { added: 10, modified: 2, deleted: 0 }
-     * // }
-     * ```
-     */
-    async diff(sourceBranch, targetBranch) {
-        await this.ensureInitialized();
-        return this.augmentationRegistry.execute('diff', { sourceBranch, targetBranch }, async () => {
-            // Default branches
-            const source = sourceBranch || (await this.getCurrentBranch());
-            const target = targetBranch || 'main';
-            const currentBranch = await this.getCurrentBranch();
-            // If source is current branch, use this instance directly (no fork needed)
-            let sourceFork;
-            let sourceForkCreated = false;
-            if (source === currentBranch) {
-                sourceFork = this;
-            }
-            else {
-                sourceFork = await this.fork(`temp-diff-source-${Date.now()}`);
-                sourceForkCreated = true;
-                try {
-                    await sourceFork.checkout(source);
-                }
-                catch (err) {
-                    // If checkout fails, branch may not exist - just use current state
-                }
-            }
-            // If target is current branch, use this instance directly (no fork needed)
-            let targetFork;
-            let targetForkCreated = false;
-            if (target === currentBranch) {
-                targetFork = this;
-            }
-            else {
-                targetFork = await this.fork(`temp-diff-target-${Date.now()}`);
-                targetForkCreated = true;
-                try {
-                    await targetFork.checkout(target);
-                }
-                catch (err) {
-                    // If checkout fails, branch may not exist - just use current state
-                }
-            }
-            try {
-                // Get all entities from both branches
-                const sourceResults = await sourceFork.find({});
-                const targetResults = await targetFork.find({});
-                // Create maps for lookup
-                const sourceMap = new Map(sourceResults.map(r => [r.entity.id, r.entity]));
-                const targetMap = new Map(targetResults.map(r => [r.entity.id, r.entity]));
-                // Track differences
-                const entitiesAdded = [];
-                const entitiesModified = [];
-                const entitiesDeleted = [];
-                // Find added and modified entities
-                for (const [id, sourceEntity] of sourceMap.entries()) {
-                    const targetEntity = targetMap.get(id);
-                    if (!targetEntity) {
-                        // Entity exists in source but not target = ADDED
-                        entitiesAdded.push({
-                            id: sourceEntity.id,
-                            type: sourceEntity.type,
-                            data: sourceEntity.data
-                        });
-                    }
-                    else {
-                        // Entity exists in both - check for modifications
-                        const changes = [];
-                        if (sourceEntity.data !== targetEntity.data) {
-                            changes.push('data');
-                        }
-                        if ((sourceEntity.updatedAt || 0) !== (targetEntity.updatedAt || 0)) {
-                            changes.push('updatedAt');
-                        }
-                        if (changes.length > 0) {
-                            entitiesModified.push({
-                                id: sourceEntity.id,
-                                type: sourceEntity.type,
-                                changes
-                            });
-                        }
-                    }
-                }
-                // Find deleted entities (in target but not in source)
-                for (const [id, targetEntity] of targetMap.entries()) {
-                    if (!sourceMap.has(id)) {
-                        entitiesDeleted.push({
-                            id: targetEntity.id,
-                            type: targetEntity.type
-                        });
-                    }
-                }
-                // Compare relationships
-                const sourceVerbsResult = await sourceFork.storage.getVerbs({});
-                const targetVerbsResult = await targetFork.storage.getVerbs({});
-                const sourceVerbs = sourceVerbsResult.items || [];
-                const targetVerbs = targetVerbsResult.items || [];
-                const sourceRelMap = new Map(sourceVerbs.map((v) => [`${v.sourceId}-${v.verb}-${v.targetId}`, v]));
-                const targetRelMap = new Map(targetVerbs.map((v) => [`${v.sourceId}-${v.verb}-${v.targetId}`, v]));
-                const relationshipsAdded = [];
-                const relationshipsModified = [];
-                const relationshipsDeleted = [];
-                // Find added and modified relationships
-                for (const [key, sourceVerb] of sourceRelMap.entries()) {
-                    const targetVerb = targetRelMap.get(key);
-                    if (!targetVerb) {
-                        // Relationship exists in source but not target = ADDED
-                        relationshipsAdded.push({
-                            from: sourceVerb.sourceId,
-                            to: sourceVerb.targetId,
-                            type: sourceVerb.verb
-                        });
-                    }
-                    else {
-                        // Relationship exists in both - check for modifications
-                        const changes = [];
-                        if ((sourceVerb.weight || 0) !== (targetVerb.weight || 0)) {
-                            changes.push('weight');
-                        }
-                        if (JSON.stringify(sourceVerb.metadata) !== JSON.stringify(targetVerb.metadata)) {
-                            changes.push('metadata');
-                        }
-                        if (changes.length > 0) {
-                            relationshipsModified.push({
-                                from: sourceVerb.sourceId,
-                                to: sourceVerb.targetId,
-                                type: sourceVerb.verb,
-                                changes
-                            });
-                        }
-                    }
-                }
-                // Find deleted relationships
-                for (const [key, targetVerb] of targetRelMap.entries()) {
-                    if (!sourceRelMap.has(key)) {
-                        relationshipsDeleted.push({
-                            from: targetVerb.sourceId,
-                            to: targetVerb.targetId,
-                            type: targetVerb.verb
-                        });
-                    }
-                }
-                return {
-                    entities: {
-                        added: entitiesAdded,
-                        modified: entitiesModified,
-                        deleted: entitiesDeleted
-                    },
-                    relationships: {
-                        added: relationshipsAdded,
-                        modified: relationshipsModified,
-                        deleted: relationshipsDeleted
-                    },
-                    summary: {
-                        entitiesAdded: entitiesAdded.length,
-                        entitiesModified: entitiesModified.length,
-                        entitiesDeleted: entitiesDeleted.length,
-                        relationshipsAdded: relationshipsAdded.length,
-                        relationshipsModified: relationshipsModified.length,
-                        relationshipsDeleted: relationshipsDeleted.length
-                    }
-                };
-            }
-            finally {
-                // Clean up temporary forks (only if we created them)
-                try {
-                    const branches = await this.listBranches();
-                    if (sourceForkCreated && sourceFork !== this) {
-                        const sourceBranchName = await sourceFork.getCurrentBranch();
-                        if (branches.includes(sourceBranchName)) {
-                            await this.deleteBranch(sourceBranchName);
-                        }
-                    }
-                    if (targetForkCreated && targetFork !== this) {
-                        const targetBranchName = await targetFork.getCurrentBranch();
-                        if (branches.includes(targetBranchName)) {
-                            await this.deleteBranch(targetBranchName);
-                        }
-                    }
-                }
-                catch (err) {
-                    // Ignore cleanup errors
-                }
-            }
-        });
-    }
     /**
      * Delete a branch/fork
      * @param branch - Branch name to delete
@@ -3327,14 +3018,6 @@ export class Brainy {
         await this.ensureInitialized();
         return this.metadataIndex.getFieldsForType(nounType);
     }
-    /**
-     * Get comprehensive type-field affinity statistics
-     * Useful for understanding data patterns and NLP optimization
-     */
-    async getTypeFieldAffinityStats() {
-        await this.ensureInitialized();
-        return this.metadataIndex.getTypeFieldAffinityStats();
-    }
     /**
      * Create a streaming pipeline
      */

package/dist/cli/commands/cow.d.ts

@@ -13,10 +13,6 @@ interface ForkOptions extends CoreOptions {
     message?: string;
     author?: string;
 }
-interface MergeOptions extends CoreOptions {
-    force?: boolean;
-    strategy?: 'last-write-wins' | 'custom';
-}
 interface MigrateOptions extends CoreOptions {
     from?: string;
     to?: string;
@@ -43,11 +39,7 @@ export declare const cowCommands: {
         force?: boolean;
     }): Promise<void>;
     /**
-     * Merge a fork/branch into current branch
-     */
-    merge(source: string | undefined, target: string | undefined, options: MergeOptions): Promise<void>;
-    /**
-     * Get commit history
+     * View commit history
      */
     history(options: CoreOptions & {
         limit?: string;

package/dist/cli/commands/cow.js

@@ -215,67 +215,7 @@ ${chalk.cyan('Fork Statistics:')}
         }
     },
     /**
-     * Merge a fork/branch into current branch
-     */
-    async merge(source, target, options) {
-        let spinner = null;
-        try {
-            const brain = getBrainy();
-            await brain.init();
-            // Interactive mode if parameters missing
-            if (!source || !target) {
-                const branches = await brain.listBranches();
-                const currentBranch = await brain.getCurrentBranch();
-                const answers = await inquirer.prompt([
-                    {
-                        type: 'list',
-                        name: 'source',
-                        message: 'Merge FROM branch:',
-                        choices: branches.map(b => ({ name: b, value: b })),
-                        when: !source
-                    },
-                    {
-                        type: 'list',
-                        name: 'target',
-                        message: 'Merge INTO branch:',
-                        choices: branches.map(b => ({
-                            name: b === currentBranch ? `${b} (current)` : b,
-                            value: b
-                        })),
-                        default: currentBranch,
-                        when: !target
-                    }
-                ]);
-                source = source || answers.source;
-                target = target || answers.target;
-            }
-            spinner = ora(`Merging ${chalk.cyan(source)} → ${chalk.green(target)}...`).start();
-            const result = await brain.merge(source, target, {
-                strategy: options.strategy || 'last-write-wins'
-            });
-            spinner.succeed(`Merged ${chalk.cyan(source)} → ${chalk.green(target)}`);
-            console.log(`
-${chalk.cyan('Merge Summary:')}
-  ${chalk.green('Added:')} ${result.added} entities
-  ${chalk.yellow('Modified:')} ${result.modified} entities
-  ${chalk.red('Deleted:')} ${result.deleted} entities
-  ${chalk.magenta('Conflicts:')} ${result.conflicts} (resolved)
-      `.trim());
-            if (options.json) {
-                formatOutput(result, options);
-            }
-        }
-        catch (error) {
-            if (spinner)
-                spinner.fail('Merge failed');
-            console.error(chalk.red('Error:'), error.message);
-            if (options.verbose)
-                console.error(error);
-            process.exit(1);
-        }
-    },
-    /**
-     * Get commit history
+     * View commit history
      */
     async history(options) {
         try {

package/dist/cli/commands/data.d.ts

@@ -1,7 +1,7 @@
 /**
  * Data Management Commands
  *
- * Backup, restore, import, export operations
+ * Import, export, and statistics operations
  */
 interface DataOptions {
     verbose?: boolean;
@@ -9,18 +9,6 @@ interface DataOptions {
     pretty?: boolean;
 }
 export declare const dataCommands: {
-    /**
-     * Backup database
-     */
-    backup(file: string, options: DataOptions & {
-        compress?: boolean;
-    }): Promise<void>;
-    /**
-     * Restore from backup
-     */
-    restore(file: string, options: DataOptions & {
-        merge?: boolean;
-    }): Promise<void>;
     /**
      * Get database statistics
      */

package/dist/cli/commands/data.js

@@ -1,11 +1,10 @@
 /**
  * Data Management Commands
  *
- * Backup, restore, import, export operations
+ * Import, export, and statistics operations
  */
 import chalk from 'chalk';
 import ora from 'ora';
-import { readFileSync, writeFileSync } from 'node:fs';
 import { Brainy } from '../../brainy.js';
 let brainyInstance = null;
 const getBrainy = () => {
@@ -20,78 +19,6 @@ const formatOutput = (data, options) => {
     }
 };
 export const dataCommands = {
-    /**
-     * Backup database
-     */
-    async backup(file, options) {
-        const spinner = ora('Creating backup...').start();
-        try {
-            const brain = getBrainy();
-            const dataApi = await brain.data();
-            const backup = await dataApi.backup({
-                compress: options.compress
-            });
-            spinner.text = 'Writing backup file...';
-            // Write backup to file
-            const content = typeof backup === 'string'
-                ? backup
-                : JSON.stringify(backup, null, options.pretty ? 2 : 0);
-            writeFileSync(file, content);
-            spinner.succeed('Backup created');
-            if (!options.json) {
-                console.log(chalk.green(`✓ Backup saved to: ${file}`));
-                if (backup.compressed) {
-                    console.log(chalk.dim(`  Original size: ${formatBytes(backup.originalSize)}`));
-                    console.log(chalk.dim(`  Compressed size: ${formatBytes(backup.compressedSize)}`));
-                    console.log(chalk.dim(`  Compression ratio: ${((backup.compressedSize / backup.originalSize) * 100).toFixed(1)}%`));
-                }
-            }
-            else {
-                formatOutput({ file, backup: true }, options);
-            }
-        }
-        catch (error) {
-            spinner.fail('Backup failed');
-            console.error(chalk.red(error.message));
-            process.exit(1);
-        }
-    },
-    /**
-     * Restore from backup
-     */
-    async restore(file, options) {
-        const spinner = ora('Restoring from backup...').start();
-        try {
-            const brain = getBrainy();
-            const dataApi = await brain.data();
-            // Read backup file
-            const content = readFileSync(file, 'utf-8');
-            const backup = JSON.parse(content);
-            // Restore
-            await dataApi.restore({
-                backup,
-                merge: options.merge || false
-            });
-            spinner.succeed('Restore complete');
-            if (!options.json) {
-                console.log(chalk.green(`✓ Restored from: ${file}`));
-                if (options.merge) {
-                    console.log(chalk.dim('  Mode: Merged with existing data'));
-                }
-                else {
-                    console.log(chalk.dim('  Mode: Replaced all data'));
-                }
-            }
-            else {
-                formatOutput({ file, restored: true }, options);
-            }
-        }
-        catch (error) {
-            spinner.fail('Restore failed');
-            console.error(chalk.red(error.message));
-            process.exit(1);
-        }
-    },
     /**
      * Get database statistics
      */

package/dist/cli/index.js

@@ -454,16 +454,7 @@ program
     storageCommands.costEstimate(options);
 }));
 // ===== Data Management Commands =====
-program
-    .command('backup <file>')
-    .description('Create database backup')
-    .option('--compress', 'Compress backup')
-    .action(dataCommands.backup);
-program
-    .command('restore <file>')
-    .description('Restore from backup')
-    .option('--merge', 'Merge with existing data (default: replace)')
-    .action(dataCommands.restore);
+program;
 program
     .command('data-stats')
     .description('Show detailed database statistics')
@@ -551,12 +542,6 @@ program
     .alias('co')
     .description('Switch to a different branch')
     .action(cowCommands.checkout);
-program
-    .command('merge [source] [target]')
-    .description('Merge a fork/branch into another branch')
-    .option('--strategy <type>', 'Merge strategy (last-write-wins|custom)', 'last-write-wins')
-    .option('-f, --force', 'Force merge on conflicts')
-    .action(cowCommands.merge);
 program
     .command('history')
     .alias('log')