@soulcraft/brainy 5.7.13 → 5.9.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [5.9.0](https://github.com/soulcraftlabs/brainy/compare/v5.8.0...v5.9.0) (2025-11-14)
+
+- fix: resolve VFS tree corruption from blob errors (v5.8.0) (93d2d70)
+
+
+### [5.8.0](https://github.com/soulcraftlabs/brainy/compare/v5.7.13...v5.8.0) (2025-11-14)
+
+- feat: add v5.8.0 features - transactions, pagination, and comprehensive docs (e40fee3)
+- docs: label all performance claims as MEASURED vs PROJECTED (NO FAKE CODE compliance) (52e9617)
+
+
 ### [5.7.13](https://github.com/soulcraftlabs/brainy/compare/v5.7.12...v5.7.13) (2025-11-14)
 
 
@@ -1666,11 +1677,11 @@ After upgrading to v3.50.2:
 
 ### ✨ Features
 
-**Phase 2: Type-Aware HNSW - 87% Memory Reduction @ Billion Scale**
+**Phase 2: Type-Aware HNSW - PROJECTED 87% Memory Reduction @ Billion Scale**
 
 - **feat**: TypeAwareHNSWIndex with separate HNSW graphs per entity type
-  - **87% HNSW memory reduction**: 384GB → 50GB (-334GB) @ 1B scale
-  - **10x faster single-type queries**: search 100M nodes instead of 1B
+  - **PROJECTED 87% HNSW memory reduction**: 384GB → 50GB (-334GB) @ 1B scale (calculated from architectural analysis, not yet benchmarked at billion scale)
+  - **PROJECTED 10x faster single-type queries**: search 100M nodes instead of 1B (not yet benchmarked)
   - **5-8x faster multi-type queries**: search subset of types
   - **~3x faster all-types queries**: 31 smaller graphs vs 1 large graph
   - Lazy initialization - only creates indexes for types with entities
@@ -1688,11 +1699,11 @@ After upgrading to v3.50.2:
   - Maintains O(log n) performance guarantees
   - Zero API changes for existing code
 
-### 📊 Impact @ Billion Scale
+### 📊 Impact @ Billion Scale (PROJECTED)
 
-**Memory Reduction (Phase 2):**
+**Memory Reduction (Phase 2) - PROJECTED:**
 ```
-HNSW memory: 384GB → 50GB (-87% / -334GB)
+HNSW memory: 384GB → 50GB (-87% / -334GB) - PROJECTED from architectural analysis, not benchmarked at 1B scale
 ```
 
 **Query Performance:**
@@ -1758,7 +1769,7 @@ Part of the billion-scale optimization roadmap:
 ### 🎯 Next Steps
 
 **Phase 3** (planned): Type-First Query Optimization
-- Query: 40% latency reduction via type-aware planning
+- Query: PROJECTED 40% latency reduction via type-aware planning (not yet benchmarked)
 - Index: Smart query routing based on type cardinality
 - Estimated: 2 weeks implementation
 

package/README.md

@@ -631,16 +631,20 @@ This comprehensive guide includes:
    - Your primary resource for building with Brainy
    - Every method documented with working examples
 
-2. **[Natural Language Queries](docs/guides/natural-language.md)**
+2. **[Filter & Query Syntax Guide](docs/FIND_SYSTEM.md)**
+   - Complete reference for operators, compound filters, and optimization tips
+
+3. **[Natural Language Queries](docs/guides/natural-language.md)**
    - Master the `find()` method and Triple Intelligence queries
 
-3. **[v4.0.0 Migration Guide](docs/MIGRATION-V3-TO-V4.md)**
+4. **[v4.0.0 Migration Guide](docs/MIGRATION-V3-TO-V4.md)**
    - Upgrading from v3 (100% backward compatible)
 
 ### 🧠 Core Concepts & Architecture
 
 - **[Triple Intelligence Architecture](docs/architecture/triple-intelligence.md)** — How vector + graph + document work together
 - **[Noun-Verb Taxonomy](docs/architecture/noun-verb-taxonomy.md)** — The universal type system (42 nouns × 127 verbs)
+- **[Transactions](docs/transactions.md)** — Atomic operations with automatic rollback
 - **[Architecture Overview](docs/architecture/overview.md)** — System design and components
 - **[Data Storage Architecture](docs/architecture/data-storage-architecture.md)** — Type-aware indexing and HNSW
 

package/dist/augmentations/intelligentImport/handlers/imageHandler.d.ts

@@ -1,13 +1,13 @@
 /**
- * Image Import Handler (v5.2.0)
+ * Image Import Handler (v5.8.0 - Pure JavaScript)
  *
  * Handles image files with:
- * - EXIF metadata extraction (camera, GPS, timestamps)
- * - Thumbnail generation (multiple sizes)
- * - Image metadata (dimensions, format, color space)
- * - Support for JPEG, PNG, WebP, GIF, TIFF, AVIF, etc.
+ * - EXIF metadata extraction (camera, GPS, timestamps) via exifr
+ * - Image metadata (dimensions, format) via probe-image-size
+ * - Support for JPEG, PNG, WebP, GIF, TIFF, BMP, SVG
  *
- * NO MOCKS - Production implementation using sharp and exifr
+ * NO NATIVE DEPENDENCIES - Pure JavaScript implementation
+ * Replaces Sharp (v5.7.x) with lightweight pure-JS alternatives
  */
 import { BaseFormatHandler } from './base.js';
 import type { FormatHandlerOptions, ProcessedData } from '../types.js';
@@ -17,18 +17,12 @@ export interface ImageMetadata {
     height: number;
     /** Image format (jpeg, png, webp, etc.) */
     format: string;
-    /** Color space */
-    space: string;
-    /** Number of channels */
-    channels: number;
-    /** Bit depth */
-    depth: string;
     /** File size in bytes */
     size: number;
-    /** Whether image has alpha channel */
-    hasAlpha: boolean;
     /** Orientation (EXIF) */
     orientation?: number;
+    /** MIME type */
+    mimeType?: string;
 }
 export interface EXIFData {
     /** Camera make (e.g., "Canon", "Nikon") */
@@ -74,6 +68,8 @@ export interface ImageHandlerOptions extends FormatHandlerOptions {
  * Processes image files and extracts rich metadata including EXIF data.
  * Enables developers to import images into the knowledge graph with
  * full metadata extraction.
+ *
+ * v5.8.0: Pure JavaScript implementation (no native dependencies)
  */
 export declare class ImageHandler extends BaseFormatHandler {
     readonly format = "image";
@@ -89,11 +85,11 @@ export declare class ImageHandler extends BaseFormatHandler {
      */
     process(data: Buffer | string, options?: ImageHandlerOptions): Promise<ProcessedData>;
     /**
-     * Extract image metadata using sharp
+     * Extract image metadata using probe-image-size (pure JS)
      */
     private extractMetadata;
     /**
-     * Extract EXIF data using exifr
+     * Extract EXIF data using exifr (pure JS)
      */
     private extractEXIF;
     /**

package/dist/augmentations/intelligentImport/handlers/imageHandler.js

@@ -1,23 +1,26 @@
 /**
- * Image Import Handler (v5.2.0)
+ * Image Import Handler (v5.8.0 - Pure JavaScript)
  *
  * Handles image files with:
- * - EXIF metadata extraction (camera, GPS, timestamps)
- * - Thumbnail generation (multiple sizes)
- * - Image metadata (dimensions, format, color space)
- * - Support for JPEG, PNG, WebP, GIF, TIFF, AVIF, etc.
+ * - EXIF metadata extraction (camera, GPS, timestamps) via exifr
+ * - Image metadata (dimensions, format) via probe-image-size
+ * - Support for JPEG, PNG, WebP, GIF, TIFF, BMP, SVG
  *
- * NO MOCKS - Production implementation using sharp and exifr
+ * NO NATIVE DEPENDENCIES - Pure JavaScript implementation
+ * Replaces Sharp (v5.7.x) with lightweight pure-JS alternatives
  */
 import { BaseFormatHandler } from './base.js';
-import sharp from 'sharp';
 import exifr from 'exifr';
+import probeImageSize from 'probe-image-size';
+import { Readable } from 'stream';
 /**
  * ImageImportHandler
  *
  * Processes image files and extracts rich metadata including EXIF data.
  * Enables developers to import images into the knowledge graph with
  * full metadata extraction.
+ *
+ * v5.8.0: Pure JavaScript implementation (no native dependencies)
  */
 export class ImageHandler extends BaseFormatHandler {
     constructor() {
@@ -93,25 +96,36 @@ export class ImageHandler extends BaseFormatHandler {
         }
     }
     /**
-     * Extract image metadata using sharp
+     * Extract image metadata using probe-image-size (pure JS)
      */
     async extractMetadata(buffer) {
-        const image = sharp(buffer);
-        const metadata = await image.metadata();
-        return {
-            width: metadata.width || 0,
-            height: metadata.height || 0,
-            format: metadata.format || 'unknown',
-            space: metadata.space || 'unknown',
-            channels: metadata.channels || 0,
-            depth: metadata.depth || 'unknown',
-            size: buffer.length,
-            hasAlpha: metadata.hasAlpha || false,
-            orientation: metadata.orientation
-        };
+        try {
+            // Convert Buffer to Stream for probe-image-size
+            const stream = Readable.from(buffer);
+            const result = await probeImageSize(stream);
+            return {
+                width: result.width,
+                height: result.height,
+                format: result.type, // 'jpeg', 'png', 'webp', etc.
+                size: buffer.length,
+                mimeType: result.mime,
+                orientation: result.orientation
+            };
+        }
+        catch (error) {
+            // Fallback: Try to detect format from magic bytes
+            const detectedFormat = this.detectImageFormat(buffer);
+            return {
+                width: 0,
+                height: 0,
+                format: detectedFormat || 'unknown',
+                size: buffer.length,
+                mimeType: detectedFormat ? `image/${detectedFormat}` : undefined
+            };
+        }
     }
     /**
-     * Extract EXIF data using exifr
+     * Extract EXIF data using exifr (pure JS)
      */
     async extractEXIF(buffer) {
         try {
@@ -199,6 +213,10 @@ export class ImageHandler extends BaseFormatHandler {
             (buffer[0] === 0x4d && buffer[1] === 0x4d && buffer[2] === 0x00 && buffer[3] === 0x2a)) {
             return 'tiff';
         }
+        // BMP: 42 4D
+        if (buffer[0] === 0x42 && buffer[1] === 0x4d) {
+            return 'bmp';
+        }
         return null;
     }
     /**

package/dist/brainy.d.ts

@@ -27,6 +27,7 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     private storage;
     private metadataIndex;
     private graphIndex;
+    private transactionManager;
     private embedder;
     private distance;
     private augmentationRegistry;

package/dist/brainy.js

@@ -6,6 +6,7 @@
  */
 import { v4 as uuidv4 } from './universal/uuid.js';
 import { HNSWIndex } from './hnsw/hnswIndex.js';
+import { HNSWIndexOptimized } from './hnsw/hnswIndexOptimized.js';
 import { TypeAwareHNSWIndex } from './hnsw/typeAwareHNSWIndex.js';
 import { createStorage } from './storage/storageFactory.js';
 import { defaultEmbeddingFunction, cosineDistance } from './utils/index.js';
@@ -23,6 +24,8 @@ import { CommitBuilder } from './storage/cow/CommitObject.js';
 import { NULL_HASH } from './storage/cow/constants.js';
 import { createPipeline } from './streaming/pipeline.js';
 import { configureLogger, LogLevel } from './utils/logger.js';
+import { TransactionManager } from './transaction/TransactionManager.js';
+import { SaveNounMetadataOperation, SaveNounOperation, AddToTypeAwareHNSWOperation, AddToHNSWOperation, AddToMetadataIndexOperation, SaveVerbMetadataOperation, SaveVerbOperation, AddToGraphIndexOperation, RemoveFromHNSWOperation, RemoveFromTypeAwareHNSWOperation, RemoveFromMetadataIndexOperation, RemoveFromGraphIndexOperation, UpdateNounMetadataOperation, DeleteNounMetadataOperation, DeleteVerbMetadataOperation } from './transaction/operations/index.js';
 import { DistributedCoordinator, ShardManager, CacheSync, ReadWriteSeparation } from './distributed/index.js';
 import { NounType } from './types/graphTypes.js';
 /**
@@ -46,6 +49,7 @@ export class Brainy {
         this.distance = cosineDistance;
         this.embedder = this.setupEmbedder();
         this.augmentationRegistry = this.setupAugmentations();
+        this.transactionManager = new TransactionManager();
         // Setup distributed components if enabled
         if (this.config.distributed?.enabled) {
             this.setupDistributedComponents();
@@ -327,24 +331,6 @@ export class Brainy {
                 ...(params.weight !== undefined && { weight: params.weight }),
                 ...(params.createdBy && { createdBy: params.createdBy })
             };
-            // v5.0.1: Save metadata FIRST so TypeAwareStorage can cache the type
-            // This prevents the race condition where saveNoun() defaults to 'thing'
-            await this.storage.saveNounMetadata(id, storageMetadata);
-            // Then save vector
-            await this.storage.saveNoun({
-                id,
-                vector,
-                connections: new Map(),
-                level: 0
-            });
-            // v5.4.0: Add to HNSW index AFTER entity is saved (fixes race condition)
-            // CRITICAL: Entity must exist in storage before HNSW tries to persist
-            if (this.index instanceof TypeAwareHNSWIndex) {
-                await this.index.addItem({ id, vector }, params.type);
-            }
-            else {
-                await this.index.addItem({ id, vector });
-            }
             // v4.8.0: Build entity structure for indexing (NEW - with top-level fields)
             const entityForIndexing = {
                 id,
@@ -362,8 +348,28 @@ export class Brainy {
                 // Only custom fields in metadata
                 metadata: params.metadata || {}
             };
-            // Pass full entity structure to metadata index
-            await this.metadataIndex.addToIndex(id, entityForIndexing);
+            // v5.8.0: Execute atomically with transaction system
+            // All operations succeed or all rollback - prevents partial failures
+            await this.transactionManager.executeTransaction(async (tx) => {
+                // Operation 1: Save metadata FIRST (v5.0.1 - TypeAwareStorage caching)
+                tx.addOperation(new SaveNounMetadataOperation(this.storage, id, storageMetadata));
+                // Operation 2: Save vector data
+                tx.addOperation(new SaveNounOperation(this.storage, {
+                    id,
+                    vector,
+                    connections: new Map(),
+                    level: 0
+                }));
+                // Operation 3: Add to HNSW index (v5.4.0 - after entity saved)
+                if (this.index instanceof TypeAwareHNSWIndex) {
+                    tx.addOperation(new AddToTypeAwareHNSWOperation(this.index, id, vector, params.type));
+                }
+                else {
+                    tx.addOperation(new AddToHNSWOperation(this.index, id, vector));
+                }
+                // Operation 4: Add to metadata index
+                tx.addOperation(new AddToMetadataIndexOperation(this.metadataIndex, id, entityForIndexing));
+            });
             return id;
         });
     }
@@ -557,32 +563,6 @@ export class Brainy {
                 ...(params.confidence === undefined && existing.confidence !== undefined && { confidence: existing.confidence }),
                 ...(params.weight === undefined && existing.weight !== undefined && { weight: existing.weight })
             };
-            // v4.0.0: Save metadata FIRST (v5.1.0 fix: updates type cache for TypeAwareStorage)
-            // v5.1.0: saveNounMetadata must be called before saveNoun so that the type cache
-            // is updated before determining the shard path. Otherwise type changes cause
-            // entities to be saved in the wrong shard and become unfindable.
-            await this.storage.saveNounMetadata(params.id, updatedMetadata);
-            // Then save vector (will use updated type cache)
-            await this.storage.saveNoun({
-                id: params.id,
-                vector,
-                connections: new Map(),
-                level: 0
-            });
-            // v5.4.0: Update HNSW index AFTER entity is saved (fixes race condition)
-            // CRITICAL: Entity must be fully updated in storage before HNSW tries to persist
-            if (needsReindexing) {
-                // Update in index (remove and re-add since no update method)
-                // Phase 2: pass type for TypeAwareHNSWIndex
-                if (this.index instanceof TypeAwareHNSWIndex) {
-                    await this.index.removeItem(params.id, existing.type);
-                    await this.index.addItem({ id: params.id, vector }, newType); // v5.1.0: use new type
-                }
-                else {
-                    await this.index.removeItem(params.id);
-                    await this.index.addItem({ id: params.id, vector });
-                }
-            }
             // v4.8.0: Build entity structure for metadata index (with top-level fields)
             const entityForIndexing = {
                 id: params.id,
@@ -600,9 +580,32 @@ export class Brainy {
                 // Only custom fields in metadata
                 metadata: newMetadata
             };
-            // Update metadata index - remove old entry and add new one with v4.8.0 structure
-            await this.metadataIndex.removeFromIndex(params.id, existing.metadata);
-            await this.metadataIndex.addToIndex(params.id, entityForIndexing);
+            // v5.8.0: Execute atomically with transaction system
+            await this.transactionManager.executeTransaction(async (tx) => {
+                // Operation 1: Update metadata FIRST (v5.1.0 - updates type cache)
+                tx.addOperation(new UpdateNounMetadataOperation(this.storage, params.id, updatedMetadata));
+                // Operation 2: Update vector data (will use updated type cache)
+                tx.addOperation(new SaveNounOperation(this.storage, {
+                    id: params.id,
+                    vector,
+                    connections: new Map(),
+                    level: 0
+                }));
+                // Operation 3-4: Update HNSW index (remove and re-add if reindexing needed)
+                if (needsReindexing) {
+                    if (this.index instanceof TypeAwareHNSWIndex) {
+                        tx.addOperation(new RemoveFromTypeAwareHNSWOperation(this.index, params.id, existing.vector, existing.type));
+                        tx.addOperation(new AddToTypeAwareHNSWOperation(this.index, params.id, vector, newType));
+                    }
+                    else {
+                        tx.addOperation(new RemoveFromHNSWOperation(this.index, params.id, existing.vector));
+                        tx.addOperation(new AddToHNSWOperation(this.index, params.id, vector));
+                    }
+                }
+                // Operation 5-6: Update metadata index (remove old, add new)
+                tx.addOperation(new RemoveFromMetadataIndexOperation(this.metadataIndex, params.id, existing.metadata));
+                tx.addOperation(new AddToMetadataIndexOperation(this.metadataIndex, params.id, entityForIndexing));
+            });
         });
     }
     /**
@@ -615,47 +618,37 @@ export class Brainy {
         }
         await this.ensureInitialized();
         return this.augmentationRegistry.execute('delete', { id }, async () => {
-            // Remove from vector index (Phase 2: get type for TypeAwareHNSWIndex)
-            if (this.index instanceof TypeAwareHNSWIndex) {
-                // Get entity metadata to determine type
-                const metadata = await this.storage.getNounMetadata(id);
-                if (metadata && metadata.noun) {
-                    await this.index.removeItem(id, metadata.noun);
-                }
-            }
-            else {
-                await this.index.removeItem(id);
-            }
-            // Remove from metadata index
-            await this.metadataIndex.removeFromIndex(id);
-            // Delete from storage
-            await this.storage.deleteNoun(id);
-            // Delete metadata (if it exists as separate)
-            try {
-                await this.storage.saveMetadata(id, null); // Clear metadata
-            }
-            catch {
-                // Ignore if not supported
-            }
-            // Delete related verbs
+            // Get entity metadata and related verbs before deletion
+            const metadata = await this.storage.getNounMetadata(id);
+            const noun = await this.storage.getNoun(id);
             const verbs = await this.storage.getVerbsBySource(id);
             const targetVerbs = await this.storage.getVerbsByTarget(id);
             const allVerbs = [...verbs, ...targetVerbs];
-            for (const verb of allVerbs) {
-                // Remove from graph index first
-                await this.graphIndex.removeVerb(verb.id);
-                // Then delete from storage
-                await this.storage.deleteVerb(verb.id);
-                // Delete verb metadata if exists
-                try {
-                    if (typeof this.storage.deleteVerbMetadata === 'function') {
-                        await this.storage.deleteVerbMetadata(verb.id);
+            // v5.8.0: Execute atomically with transaction system
+            await this.transactionManager.executeTransaction(async (tx) => {
+                // Operation 1: Remove from vector index
+                if (noun && metadata) {
+                    if (this.index instanceof TypeAwareHNSWIndex && metadata.noun) {
+                        tx.addOperation(new RemoveFromTypeAwareHNSWOperation(this.index, id, noun.vector, metadata.noun));
+                    }
+                    else if (this.index instanceof HNSWIndex || this.index instanceof HNSWIndexOptimized) {
+                        tx.addOperation(new RemoveFromHNSWOperation(this.index, id, noun.vector));
                     }
                 }
-                catch {
-                    // Ignore if not supported
+                // Operation 2: Remove from metadata index
+                if (metadata) {
+                    tx.addOperation(new RemoveFromMetadataIndexOperation(this.metadataIndex, id, metadata));
                 }
-            }
+                // Operation 3: Delete noun metadata
+                tx.addOperation(new DeleteNounMetadataOperation(this.storage, id));
+                // Operations 4+: Delete all related verbs atomically
+                for (const verb of allVerbs) {
+                    // Remove from graph index
+                    tx.addOperation(new RemoveFromGraphIndexOperation(this.graphIndex, verb));
+                    // Delete verb metadata
+                    tx.addOperation(new DeleteVerbMetadataOperation(this.storage, verb.id));
+                }
+            });
         });
     }
     // ============= RELATIONSHIP OPERATIONS =============
@@ -780,14 +773,18 @@ export class Brainy {
         // CRITICAL FIX (v3.43.2): Check for duplicate relationships
         // This prevents infinite loops where same relationship is created repeatedly
         // Bug #1 showed incrementing verb counts (7→8→9...) indicating duplicates
-        const existingVerbs = await this.storage.getVerbsBySource(params.from);
-        const duplicate = existingVerbs.find(v => v.targetId === params.to &&
-            v.verb === params.type);
-        if (duplicate) {
-            // Relationship already exists - return existing ID instead of creating duplicate
-            console.log(`[DEBUG] Skipping duplicate relationship: ${params.from} → ${params.to} (${params.type})`);
-            return duplicate.id;
+        // v5.8.0 OPTIMIZATION: Use GraphAdjacencyIndex for O(log n) lookup instead of O(n) storage scan
+        const verbIds = await this.graphIndex.getVerbIdsBySource(params.from);
+        // Check each verb ID for matching relationship (only load verbs we need to check)
+        for (const verbId of verbIds) {
+            const verb = await this.graphIndex.getVerbCached(verbId);
+            if (verb && verb.targetId === params.to && verb.verb === params.type) {
+                // Relationship already exists - return existing ID instead of creating duplicate
+                console.log(`[DEBUG] Skipping duplicate relationship: ${params.from} → ${params.to} (${params.type})`);
+                return verb.id;
+            }
         }
+        // No duplicate found - proceed with creation
         // Generate ID
         const id = uuidv4();
         // Compute relationship vector (average of entities)
@@ -815,40 +812,47 @@ export class Brainy {
                 metadata: params.metadata,
                 createdAt: Date.now()
             };
-            await this.storage.saveVerb({
-                id,
-                vector: relationVector,
-                connections: new Map(),
-                verb: params.type,
-                sourceId: params.from,
-                targetId: params.to
-            });
-            await this.storage.saveVerbMetadata(id, verbMetadata);
-            // Add to graph index for O(1) lookups
-            await this.graphIndex.addVerb(verb);
-            // Create bidirectional if requested
-            if (params.bidirectional) {
-                const reverseId = uuidv4();
-                const reverseVerb = {
-                    ...verb,
-                    id: reverseId,
-                    sourceId: params.to,
-                    targetId: params.from,
-                    source: toEntity.type,
-                    target: fromEntity.type
-                };
-                await this.storage.saveVerb({
-                    id: reverseId,
+            // v5.8.0: Execute atomically with transaction system
+            await this.transactionManager.executeTransaction(async (tx) => {
+                // Operation 1: Save verb vector data
+                tx.addOperation(new SaveVerbOperation(this.storage, {
+                    id,
                     vector: relationVector,
                     connections: new Map(),
                     verb: params.type,
-                    sourceId: params.to,
-                    targetId: params.from
-                });
-                await this.storage.saveVerbMetadata(reverseId, verbMetadata);
-                // Add reverse relationship to graph index too
-                await this.graphIndex.addVerb(reverseVerb);
-            }
+                    sourceId: params.from,
+                    targetId: params.to
+                }));
+                // Operation 2: Save verb metadata
+                tx.addOperation(new SaveVerbMetadataOperation(this.storage, id, verbMetadata));
+                // Operation 3: Add to graph index for O(1) lookups
+                tx.addOperation(new AddToGraphIndexOperation(this.graphIndex, verb));
+                // Create bidirectional if requested
+                if (params.bidirectional) {
+                    const reverseId = uuidv4();
+                    const reverseVerb = {
+                        ...verb,
+                        id: reverseId,
+                        sourceId: params.to,
+                        targetId: params.from,
+                        source: toEntity.type,
+                        target: fromEntity.type
+                    };
+                    // Operation 4: Save reverse verb vector data
+                    tx.addOperation(new SaveVerbOperation(this.storage, {
+                        id: reverseId,
+                        vector: relationVector,
+                        connections: new Map(),
+                        verb: params.type,
+                        sourceId: params.to,
+                        targetId: params.from
+                    }));
+                    // Operation 5: Save reverse verb metadata
+                    tx.addOperation(new SaveVerbMetadataOperation(this.storage, reverseId, verbMetadata));
+                    // Operation 6: Add reverse relationship to graph index
+                    tx.addOperation(new AddToGraphIndexOperation(this.graphIndex, reverseVerb));
+                }
+            });
             return id;
         });
     }
@@ -858,10 +862,17 @@ export class Brainy {
     async unrelate(id) {
         await this.ensureInitialized();
         return this.augmentationRegistry.execute('unrelate', { id }, async () => {
-            // Remove from graph index
-            await this.graphIndex.removeVerb(id);
-            // Remove from storage
-            await this.storage.deleteVerb(id);
+            // Get verb data before deletion for rollback
+            const verb = await this.storage.getVerb(id);
+            // v5.8.0: Execute atomically with transaction system
+            await this.transactionManager.executeTransaction(async (tx) => {
+                // Operation 1: Remove from graph index
+                if (verb) {
+                    tx.addOperation(new RemoveFromGraphIndexOperation(this.graphIndex, verb));
+                }
+                // Operation 2: Delete verb metadata (which also deletes vector)
+                tx.addOperation(new DeleteVerbMetadataOperation(this.storage, id));
+            });
         });
     }
     /**