@soulcraft/brainy 5.7.12 → 5.8.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 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.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)
+
+
+### 🐛 Bug Fixes
+
+* resolve excludeVFS architectural bug across all query paths (v5.7.13) ([e57e947](https://github.com/soulcraftlabs/brainy/commit/e57e9474986097f37e89a8dbfa868005368d645c))
+
 ### [5.7.12](https://github.com/soulcraftlabs/brainy/compare/v5.7.11...v5.7.12) (2025-11-13)
 
 
@@ -1659,11 +1672,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
@@ -1681,11 +1694,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:**
@@ -1751,7 +1764,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/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));
+            });
         });
     }
     /**
@@ -1164,41 +1175,6 @@ export class Brainy {
                     Object.assign(filter, params.where);
                 if (params.service)
                     filter.service = params.service;
-                // v5.7.12: excludeVFS helper - ONLY exclude VFS infrastructure entities
-                // Bug fix: Previously excluded entities with ANY vfsType field
-                // Now ONLY excludes entities with isVFSEntity: true OR vfsType: 'file'/'directory'
-                // This allows extracted entities (concepts/people/etc) to be included even if they
-                // have vfsPath metadata showing where they were imported from
-                if (params.excludeVFS === true) {
-                    // Build filter: EXCLUDE WHERE (isVFSEntity == true) OR (vfsType IN ['file', 'directory'])
-                    // Implementation: INCLUDE WHERE (isVFSEntity missing/false) AND (vfsType missing/not file or directory)
-                    const existingFilter = { ...filter };
-                    filter = {
-                        allOf: [
-                            existingFilter,
-                            {
-                                // Only include entities WITHOUT isVFSEntity: true
-                                anyOf: [
-                                    { isVFSEntity: { exists: false } },
-                                    { isVFSEntity: { ne: true } }
-                                ]
-                            },
-                            {
-                                // Only include entities WITHOUT vfsType: 'file' or 'directory'
-                                // Since VFS files ALWAYS have vfsType set, we check it's missing OR not file/dir
-                                anyOf: [
-                                    { vfsType: { exists: false } },
-                                    {
-                                        allOf: [
-                                            { vfsType: { ne: 'file' } },
-                                            { vfsType: { ne: 'directory' } }
-                                        ]
-                                    }
-                                ]
-                            }
-                        ]
-                    };
-                }
                 if (params.type) {
                     const types = Array.isArray(params.type) ? params.type : [params.type];
                     if (types.length === 1) {
@@ -1213,6 +1189,19 @@ export class Brainy {
                         };
                     }
                 }
+                // v5.7.13: excludeVFS helper - ONLY exclude VFS infrastructure entities
+                // Applied AFTER type filter to avoid execution order bugs
+                // Excludes entities where:
+                //   - vfsType is 'file' or 'directory' (VFS files/folders)
+                //   - isVFSEntity is true (explicitly marked as VFS)
+                // Includes extracted entities (person/concept/etc) even if they have vfsPath metadata
+                if (params.excludeVFS === true) {
+                    // VFS infrastructure entities ALWAYS have vfsType set
+                    // Extracted entities do NOT have vfsType (undefined)
+                    filter.vfsType = { exists: false };
+                    // Extra safety: exclude entities explicitly marked as VFS
+                    filter.isVFSEntity = { ne: true };
+                }
                 // v4.5.4: Apply sorting if requested, otherwise just filter
                 let filteredIds;
                 if (params.orderBy) {
@@ -1240,10 +1229,12 @@ export class Brainy {
             if (!hasVectorSearchCriteria && !hasFilterCriteria && !hasGraphCriteria) {
                 const limit = params.limit || 20;
                 const offset = params.offset || 0;
-                // v4.7.0: excludeVFS helper
+                // v5.7.13: excludeVFS helper - exclude VFS infrastructure entities
+                // VFS files/folders have vfsType set, extracted entities do NOT
                 let filter = {};
                 if (params.excludeVFS === true) {
                     filter.vfsType = { exists: false };
+                    filter.isVFSEntity = { ne: true };
                 }
                 // Use metadata index if we need to filter
                 if (Object.keys(filter).length > 0) {
@@ -1308,9 +1299,11 @@ export class Brainy {
                     Object.assign(filter, params.where);
                 if (params.service)
                     filter.service = params.service;
-                // v4.7.0: excludeVFS helper for cleaner UX
+                // v5.7.13: excludeVFS helper - exclude VFS infrastructure entities
+                // VFS files/folders have vfsType set, extracted entities do NOT
                 if (params.excludeVFS === true) {
                     filter.vfsType = { exists: false };
+                    filter.isVFSEntity = { ne: true };
                 }
                 if (params.type) {
                     const types = Array.isArray(params.type) ? params.type : [params.type];

package/dist/graph/graphAdjacencyIndex.d.ts

@@ -55,27 +55,96 @@ export declare class GraphAdjacencyIndex {
     private ensureInitialized;
     /**
      * Core API - Neighbor lookup with LSM-tree storage
-     * Now O(log n) with bloom filter optimization (90% of queries skip disk I/O)
+     *
+     * O(log n) with bloom filter optimization (90% of queries skip disk I/O)
+     * v5.8.0: Added pagination support for high-degree nodes
+     *
+     * @param id Entity ID to get neighbors for
+     * @param optionsOrDirection Optional: direction string OR options object
+     * @returns Array of neighbor IDs (paginated if limit/offset specified)
+     *
+     * @example
+     * // Get all neighbors (backward compatible)
+     * const all = await graphIndex.getNeighbors(id)
+     *
+     * @example
+     * // Get outgoing neighbors (backward compatible)
+     * const out = await graphIndex.getNeighbors(id, 'out')
+     *
+     * @example
+     * // Get first 50 outgoing neighbors (new API)
+     * const page1 = await graphIndex.getNeighbors(id, { direction: 'out', limit: 50 })
+     *
+     * @example
+     * // Paginate through neighbors
+     * const page1 = await graphIndex.getNeighbors(id, { limit: 100, offset: 0 })
+     * const page2 = await graphIndex.getNeighbors(id, { limit: 100, offset: 100 })
      */
-    getNeighbors(id: string, direction?: 'in' | 'out' | 'both'): Promise<string[]>;
+    getNeighbors(id: string, optionsOrDirection?: {
+        direction?: 'in' | 'out' | 'both';
+        limit?: number;
+        offset?: number;
+    } | 'in' | 'out' | 'both'): Promise<string[]>;
     /**
      * Get verb IDs by source - Billion-scale optimization for getVerbsBySource
+     *
      * O(log n) LSM-tree lookup with bloom filter optimization
      * v5.7.1: Filters out deleted verb IDs (tombstone deletion workaround)
+     * v5.8.0: Added pagination support for entities with many relationships
      *
      * @param sourceId Source entity ID
-     * @returns Array of verb IDs originating from this source (excluding deleted)
+     * @param options Optional configuration
+     * @param options.limit Maximum number of verb IDs to return (default: all)
+     * @param options.offset Number of verb IDs to skip (default: 0)
+     * @returns Array of verb IDs originating from this source (excluding deleted, paginated if requested)
+     *
+     * @example
+     * // Get all verb IDs (backward compatible)
+     * const all = await graphIndex.getVerbIdsBySource(sourceId)
+     *
+     * @example
+     * // Get first 50 verb IDs
+     * const page1 = await graphIndex.getVerbIdsBySource(sourceId, { limit: 50 })
+     *
+     * @example
+     * // Paginate through verb IDs
+     * const page1 = await graphIndex.getVerbIdsBySource(sourceId, { limit: 100, offset: 0 })
+     * const page2 = await graphIndex.getVerbIdsBySource(sourceId, { limit: 100, offset: 100 })
      */
-    getVerbIdsBySource(sourceId: string): Promise<string[]>;
+    getVerbIdsBySource(sourceId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<string[]>;
     /**
      * Get verb IDs by target - Billion-scale optimization for getVerbsByTarget
+     *
      * O(log n) LSM-tree lookup with bloom filter optimization
      * v5.7.1: Filters out deleted verb IDs (tombstone deletion workaround)
+     * v5.8.0: Added pagination support for popular target entities
      *
      * @param targetId Target entity ID
-     * @returns Array of verb IDs pointing to this target (excluding deleted)
-     */
-    getVerbIdsByTarget(targetId: string): Promise<string[]>;
+     * @param options Optional configuration
+     * @param options.limit Maximum number of verb IDs to return (default: all)
+     * @param options.offset Number of verb IDs to skip (default: 0)
+     * @returns Array of verb IDs pointing to this target (excluding deleted, paginated if requested)
+     *
+     * @example
+     * // Get all verb IDs (backward compatible)
+     * const all = await graphIndex.getVerbIdsByTarget(targetId)
+     *
+     * @example
+     * // Get first 50 verb IDs
+     * const page1 = await graphIndex.getVerbIdsByTarget(targetId, { limit: 50 })
+     *
+     * @example
+     * // Paginate through verb IDs
+     * const page1 = await graphIndex.getVerbIdsByTarget(targetId, { limit: 100, offset: 0 })
+     * const page2 = await graphIndex.getVerbIdsByTarget(targetId, { limit: 100, offset: 100 })
+     */
+    getVerbIdsByTarget(targetId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<string[]>;
     /**
      * Get verb from cache or storage - Billion-scale memory optimization
      * Uses UnifiedCache with LRU eviction instead of storing all verbs in memory