@soulcraft/brainy 4.11.2 → 5.1.0

package/dist/brainy.d.ts

@@ -717,6 +717,231 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * Clear all data from the database
      */
     clear(): Promise<void>;
+    /**
+     * Fork the brain (instant clone via Snowflake-style COW)
+     *
+     * Creates a shallow copy in <100ms using copy-on-write (COW) technology.
+     * Fork shares storage and HNSW data structures with parent, copying only
+     * when modified (lazy deep copy).
+     *
+     * **How It Works (v5.0.0)**:
+     * 1. HNSW Index: Shallow copy via `enableCOW()` (~10ms for 1M+ nodes)
+     * 2. Metadata Index: Fast rebuild from shared storage (<100ms)
+     * 3. Graph Index: Fast rebuild from shared storage (<500ms)
+     *
+     * **Performance**:
+     * - Fork time: <100ms @ 10K entities (MEASURED)
+     * - Memory overhead: 10-20% (shared HNSW nodes)
+     * - Storage overhead: 10-20% (shared blobs)
+     *
+     * **Write Isolation**: Changes in fork don't affect parent, and vice versa.
+     *
+     * @param branch - Optional branch name (auto-generated if not provided)
+     * @param options - Optional fork metadata (author, message)
+     * @returns New Brainy instance (forked, fully independent)
+     *
+     * @example
+     * ```typescript
+     * const brain = new Brainy()
+     * await brain.init()
+     *
+     * // Add data to parent
+     * await brain.add({ type: 'user', data: { name: 'Alice' } })
+     *
+     * // Fork instantly (<100ms)
+     * const experiment = await brain.fork('test-migration')
+     *
+     * // Make changes safely in fork
+     * await experiment.add({ type: 'user', data: { name: 'Bob' } })
+     *
+     * // Original untouched
+     * console.log((await brain.find({})).length)       // 1 (Alice)
+     * console.log((await experiment.find({})).length)  // 2 (Alice + Bob)
+     * ```
+     *
+     * @since v5.0.0
+     */
+    fork(branch?: string, options?: {
+        author?: string;
+        message?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Brainy<T>>;
+    /**
+     * List all branches/forks
+     * @returns Array of branch names
+     *
+     * @example
+     * ```typescript
+     * const branches = await brain.listBranches()
+     * console.log(branches) // ['main', 'experiment', 'backup']
+     * ```
+     */
+    listBranches(): Promise<string[]>;
+    /**
+     * Get current branch name
+     * @returns Current branch name
+     *
+     * @example
+     * ```typescript
+     * const current = await brain.getCurrentBranch()
+     * console.log(current) // 'main'
+     * ```
+     */
+    getCurrentBranch(): Promise<string>;
+    /**
+     * Switch to a different branch
+     * @param branch - Branch name to switch to
+     *
+     * @example
+     * ```typescript
+     * await brain.checkout('experiment')
+     * console.log(await brain.getCurrentBranch()) // 'experiment'
+     * ```
+     */
+    checkout(branch: string): Promise<void>;
+    /**
+     * Create a commit with current state
+     * @param options - Commit options (message, author, metadata)
+     * @returns Commit hash
+     *
+     * @example
+     * ```typescript
+     * await brain.add({ noun: 'user', data: { name: 'Alice' } })
+     * const commitHash = await brain.commit({
+     *   message: 'Add Alice user',
+     *   author: 'dev@example.com'
+     * })
+     * ```
+     */
+    commit(options?: {
+        message?: string;
+        author?: string;
+        metadata?: Record<string, any>;
+    }): Promise<string>;
+    /**
+     * 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 }
+     * ```
+     */
+    merge(sourceBranch: string, targetBranch: string, options?: {
+        strategy?: 'last-write-wins' | 'first-write-wins' | 'custom';
+        author?: string;
+        onConflict?: (entityA: any, entityB: any) => Promise<any>;
+    }): Promise<{
+        added: number;
+        modified: number;
+        deleted: number;
+        conflicts: number;
+    }>;
+    /**
+     * 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 }
+     * // }
+     * ```
+     */
+    diff(sourceBranch?: string, targetBranch?: string): Promise<{
+        entities: {
+            added: Array<{
+                id: string;
+                type: string;
+                data?: any;
+            }>;
+            modified: Array<{
+                id: string;
+                type: string;
+                changes: string[];
+            }>;
+            deleted: Array<{
+                id: string;
+                type: string;
+            }>;
+        };
+        relationships: {
+            added: Array<{
+                from: string;
+                to: string;
+                type: string;
+            }>;
+            modified: Array<{
+                from: string;
+                to: string;
+                type: string;
+                changes: string[];
+            }>;
+            deleted: Array<{
+                from: string;
+                to: string;
+                type: string;
+            }>;
+        };
+        summary: {
+            entitiesAdded: number;
+            entitiesModified: number;
+            entitiesDeleted: number;
+            relationshipsAdded: number;
+            relationshipsModified: number;
+            relationshipsDeleted: number;
+        };
+    }>;
+    /**
+     * Delete a branch/fork
+     * @param branch - Branch name to delete
+     *
+     * @example
+     * ```typescript
+     * await brain.deleteBranch('old-experiment')
+     * ```
+     */
+    deleteBranch(branch: string): Promise<void>;
+    /**
+     * Get commit history for current branch
+     * @param options - History options (limit, offset, author)
+     * @returns Array of commits
+     *
+     * @example
+     * ```typescript
+     * const history = await brain.getHistory({ limit: 10 })
+     * history.forEach(commit => {
+     *   console.log(`${commit.hash}: ${commit.message}`)
+     * })
+     * ```
+     */
+    getHistory(options?: {
+        limit?: number;
+        offset?: number;
+        author?: string;
+    }): Promise<Array<{
+        hash: string;
+        message: string;
+        author: string;
+        timestamp: number;
+        metadata?: Record<string, any>;
+    }>>;
     /**
      * Get total count of nouns - O(1) operation
      * @returns Promise that resolves to the total number of nouns
@@ -911,35 +1136,43 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
         }) => void;
     }): Promise<import("./import/ImportCoordinator.js").ImportResult>;
     /**
-     * Virtual File System API - Knowledge Operating System
+     * Virtual File System API - Knowledge Operating System (v5.0.1+)
      *
-     * Returns a cached VFS instance. You must call vfs.init() before use:
+     * Returns a cached VFS instance that is auto-initialized during brain.init().
+     * No separate initialization needed!
      *
      * @example After import
      * ```typescript
      * await brain.import('./data.xlsx', { vfsPath: '/imports/data' })
-     *
-     * const vfs = brain.vfs()
-     * await vfs.init()  // Required! (safe to call multiple times)
-     * const files = await vfs.readdir('/imports/data')
+     * // VFS ready immediately - no init() call needed!
+     * const files = await brain.vfs.readdir('/imports/data')
      * ```
      *
      * @example Direct VFS usage
      * ```typescript
-     * const vfs = brain.vfs()
-     * await vfs.init()  // Always required before first use
-     * await vfs.writeFile('/docs/readme.md', 'Hello World')
-     * const content = await vfs.readFile('/docs/readme.md')
+     * await brain.init()  // VFS auto-initialized here!
+     * await brain.vfs.writeFile('/docs/readme.md', 'Hello World')
+     * const content = await brain.vfs.readFile('/docs/readme.md')
      * ```
      *
-     * **Note:** brain.import() automatically initializes the VFS, so after
-     * an import you can call vfs.init() again (it's idempotent) and immediately
-     * query the imported files.
+     * @example With fork (COW isolation)
+     * ```typescript
+     * await brain.init()
+     * await brain.vfs.writeFile('/config.json', '{"v": 1}')
+     *
+     * const fork = await brain.fork('experiment')
+     * // Fork inherits parent's files
+     * const config = await fork.vfs.readFile('/config.json')
+     * // Fork modifications are isolated
+     * await fork.vfs.writeFile('/test.txt', 'Fork only')
+     * ```
      *
-     * **Pattern:** The VFS instance is cached, so multiple calls to brain.vfs()
+     * **Pattern:** The VFS instance is cached, so multiple calls to brain.vfs
      * return the same instance. This ensures import and user code share state.
+     *
+     * @since v5.0.1 - Auto-initialization during brain.init()
      */
-    vfs(): VirtualFileSystem;
+    get vfs(): VirtualFileSystem;
     /**
      * Data Management API - backup, restore, import, export
      */