@soulcraft/brainy 5.4.0 → 5.6.0

package/dist/neural/entityExtractor.js

@@ -234,11 +234,11 @@ export class NeuralEntityExtractor {
         }
         // Hashtag
         if (text.startsWith('#')) {
-            return { type: NounType.Topic, confidence: 0.8 };
+            return { type: NounType.Concept, confidence: 0.8 };
         }
         // Mention
         if (text.startsWith('@')) {
-            return { type: NounType.User, confidence: 0.8 };
+            return { type: NounType.Person, confidence: 0.8 };
         }
         // Capitalized words (likely proper nouns)
         if (/^[A-Z]/.test(text)) {

package/dist/neural/relationshipConfidence.js

@@ -106,7 +106,7 @@ export class RelationshipConfidenceScorer {
             [VerbType.Contains]: ['contains', 'includes', 'has', 'holds'],
             [VerbType.Requires]: ['requires', 'needs', 'depends on', 'relies on'],
             [VerbType.Uses]: ['uses', 'utilizes', 'employs', 'applies'],
-            [VerbType.Supervises]: ['manages', 'oversees', 'supervises', 'controls'],
+            [VerbType.ReportsTo]: ['manages', 'oversees', 'supervises', 'controls'],
             [VerbType.Causes]: ['influences', 'affects', 'impacts', 'shapes', 'causes'],
             [VerbType.DependsOn]: ['depends on', 'relies on', 'based on'],
             [VerbType.Modifies]: ['modifies', 'changes', 'alters', 'updates'],

package/dist/neural/signals/VerbContextSignal.js

@@ -105,7 +105,7 @@ export class VerbContextSignal {
             {
                 subjectType: NounType.Document,
                 objectType: NounType.Person,
-                verbType: VerbType.CreatedBy,
+                verbType: VerbType.Creates,
                 confidence: 0.80,
                 description: 'Document created by Person'
             },
@@ -173,7 +173,7 @@ export class VerbContextSignal {
             {
                 subjectType: NounType.Product,
                 objectType: NounType.Organization,
-                verbType: VerbType.CreatedBy,
+                verbType: VerbType.Creates,
                 confidence: 0.75,
                 description: 'Product created by Organization'
             },
@@ -188,7 +188,7 @@ export class VerbContextSignal {
             {
                 subjectType: NounType.Product,
                 objectType: NounType.Person,
-                verbType: VerbType.CreatedBy,
+                verbType: VerbType.Creates,
                 confidence: 0.75,
                 description: 'Product created by Person'
             },
@@ -196,7 +196,7 @@ export class VerbContextSignal {
             {
                 subjectType: NounType.Event,
                 objectType: NounType.Person,
-                verbType: VerbType.CreatedBy,
+                verbType: VerbType.Creates,
                 confidence: 0.70,
                 description: 'Event created by Person'
             },
@@ -220,7 +220,7 @@ export class VerbContextSignal {
             {
                 subjectType: NounType.Project,
                 objectType: NounType.Organization,
-                verbType: VerbType.BelongsTo,
+                verbType: VerbType.Owns,
                 confidence: 0.75,
                 description: 'Project belongs to Organization'
             },
@@ -228,7 +228,7 @@ export class VerbContextSignal {
             {
                 subjectType: NounType.Project,
                 objectType: NounType.Person,
-                verbType: VerbType.CreatedBy,
+                verbType: VerbType.Creates,
                 confidence: 0.70,
                 description: 'Project created by Person'
             },

package/dist/neural/signals/VerbExactMatchSignal.js

@@ -190,14 +190,14 @@ export class VerbExactMatchSignal {
         // Common relationship phrases with their VerbTypes
         const phrases = [
             // Creation relationships
-            { pattern: /created?\s+by/i, type: VerbType.CreatedBy, confidence: 0.95 },
-            { pattern: /authored?\s+by/i, type: VerbType.CreatedBy, confidence: 0.95 },
-            { pattern: /written\s+by/i, type: VerbType.CreatedBy, confidence: 0.95 },
-            { pattern: /developed\s+by/i, type: VerbType.CreatedBy, confidence: 0.90 },
+            { pattern: /created?\s+by/i, type: VerbType.Creates, confidence: 0.95 },
+            { pattern: /authored?\s+by/i, type: VerbType.Creates, confidence: 0.95 },
+            { pattern: /written\s+by/i, type: VerbType.Creates, confidence: 0.95 },
+            { pattern: /developed\s+by/i, type: VerbType.Creates, confidence: 0.90 },
             { pattern: /built\s+by/i, type: VerbType.Creates, confidence: 0.85 },
             // Ownership relationships
             { pattern: /owned\s+by/i, type: VerbType.Owns, confidence: 0.95 },
-            { pattern: /belongs\s+to/i, type: VerbType.BelongsTo, confidence: 0.95 },
+            { pattern: /belongs\s+to/i, type: VerbType.Owns, confidence: 0.95 },
             { pattern: /attributed\s+to/i, type: VerbType.AttributedTo, confidence: 0.95 },
             // Part/Whole relationships
             { pattern: /part\s+of/i, type: VerbType.PartOf, confidence: 0.95 },
@@ -213,17 +213,17 @@ export class VerbExactMatchSignal {
             { pattern: /employed\s+by/i, type: VerbType.WorksWith, confidence: 0.90 },
             // Reporting relationships
             { pattern: /reports?\s+to/i, type: VerbType.ReportsTo, confidence: 0.95 },
-            { pattern: /manages/i, type: VerbType.Supervises, confidence: 0.85 },
-            { pattern: /supervises/i, type: VerbType.Supervises, confidence: 0.95 },
+            { pattern: /manages/i, type: VerbType.ReportsTo, confidence: 0.85 },
+            { pattern: /supervises/i, type: VerbType.ReportsTo, confidence: 0.95 },
             // Reference relationships
             { pattern: /references/i, type: VerbType.References, confidence: 0.90 },
             { pattern: /cites/i, type: VerbType.References, confidence: 0.90 },
             { pattern: /mentions/i, type: VerbType.References, confidence: 0.85 },
             // Temporal relationships
             { pattern: /precedes/i, type: VerbType.Precedes, confidence: 0.90 },
-            { pattern: /follows/i, type: VerbType.Succeeds, confidence: 0.90 },
+            { pattern: /follows/i, type: VerbType.Precedes, confidence: 0.90 },
             { pattern: /before/i, type: VerbType.Precedes, confidence: 0.75 },
-            { pattern: /after/i, type: VerbType.Succeeds, confidence: 0.75 },
+            { pattern: /after/i, type: VerbType.Precedes, confidence: 0.75 },
             // Causal relationships
             { pattern: /causes/i, type: VerbType.Causes, confidence: 0.90 },
             { pattern: /requires/i, type: VerbType.Requires, confidence: 0.90 },

package/dist/neural/signals/VerbPatternSignal.js

@@ -53,7 +53,7 @@ export class VerbPatternSignal {
             // ========== Creation & Authorship ==========
             {
                 regex: /\b(?:created?|made|built|developed|designed|wrote|authored|composed)\s+(?:by|from)\b/i,
-                type: VerbType.CreatedBy,
+                type: VerbType.Creates,
                 confidence: 0.90,
                 description: 'Creation with agent (passive)'
             },
@@ -84,7 +84,7 @@ export class VerbPatternSignal {
             },
             {
                 regex: /\bbelongs?\s+to\b/i,
-                type: VerbType.BelongsTo,
+                type: VerbType.Owns,
                 confidence: 0.95,
                 description: 'Belonging relationship'
             },
@@ -141,7 +141,7 @@ export class VerbPatternSignal {
             },
             {
                 regex: /\b(?:manages?|supervises?|oversees?)\b/i,
-                type: VerbType.Supervises,
+                type: VerbType.ReportsTo,
                 confidence: 0.85,
                 description: 'Management relationship'
             },
@@ -198,7 +198,7 @@ export class VerbPatternSignal {
             },
             {
                 regex: /\b(?:succeeds?|follows?|comes?\s+after|happens?\s+after)\b/i,
-                type: VerbType.Succeeds,
+                type: VerbType.Precedes,
                 confidence: 0.85,
                 description: 'Temporal succession'
             },
@@ -210,7 +210,7 @@ export class VerbPatternSignal {
             },
             {
                 regex: /\bafter\b/i,
-                type: VerbType.Succeeds,
+                type: VerbType.Precedes,
                 confidence: 0.70,
                 description: 'After (temporal)'
             },

package/dist/query/typeAwareQueryPlanner.d.ts

@@ -6,14 +6,14 @@
  * TypeAwareHNSWIndex graphs.
  *
  * Performance Impact:
- * - Single-type queries: 31x speedup (search 1/31 graphs)
- * - Multi-type queries: 6-15x speedup (search 2-5/31 graphs)
+ * - Single-type queries: 42x speedup (search 1/42 graphs)
+ * - Multi-type queries: 8-21x speedup (search 2-5/42 graphs)
  * - Overall: 40% latency reduction @ 1B scale
  *
  * Examples:
- * - "Find engineers" → single-type → [Person] → 31x speedup
- * - "People at Tesla" → multi-type → [Person, Organization] → 15.5x speedup
- * - "Everything about AI" → all-types → [all 31 types] → no speedup
+ * - "Find engineers" → single-type → [Person] → 42x speedup
+ * - "People at Tesla" → multi-type → [Person, Organization] → 21x speedup
+ * - "Everything about AI" → all-types → [all 42 types] → no speedup
  */
 import { NounType } from '../types/graphTypes.js';
 import { type TypeInference } from './semanticTypeInference.js';
@@ -38,11 +38,11 @@ export interface TypeAwareQueryPlan {
      */
     routing: QueryRoutingStrategy;
     /**
-     * Target types to search (1-31 types)
+     * Target types to search (1-42 types)
      */
     targetTypes: NounType[];
     /**
-     * Estimated speedup factor (1.0 = no speedup, 31.0 = 31x faster)
+     * Estimated speedup factor (1.0 = no speedup, 42.0 = 42x faster)
      */
     estimatedSpeedup: number;
     /**

package/dist/query/typeAwareQueryPlanner.js

@@ -6,14 +6,14 @@
  * TypeAwareHNSWIndex graphs.
  *
  * Performance Impact:
- * - Single-type queries: 31x speedup (search 1/31 graphs)
- * - Multi-type queries: 6-15x speedup (search 2-5/31 graphs)
+ * - Single-type queries: 42x speedup (search 1/42 graphs)
+ * - Multi-type queries: 8-21x speedup (search 2-5/42 graphs)
  * - Overall: 40% latency reduction @ 1B scale
  *
  * Examples:
- * - "Find engineers" → single-type → [Person] → 31x speedup
- * - "People at Tesla" → multi-type → [Person, Organization] → 15.5x speedup
- * - "Everything about AI" → all-types → [all 31 types] → no speedup
+ * - "Find engineers" → single-type → [Person] → 42x speedup
+ * - "People at Tesla" → multi-type → [Person, Organization] → 21x speedup
+ * - "Everything about AI" → all-types → [all 42 types] → no speedup
  */
 import { NounType, NOUN_TYPE_COUNT } from '../types/graphTypes.js';
 import { inferNouns } from './semanticTypeInference.js';
@@ -145,18 +145,17 @@ export class TypeAwareQueryPlanner {
             NounType.Media,
             NounType.File,
             NounType.Message,
-            NounType.Content,
             NounType.Collection,
             NounType.Dataset,
             NounType.Product,
             NounType.Service,
-            NounType.User,
+            NounType.Person,
             NounType.Task,
             NounType.Project,
             NounType.Process,
             NounType.State,
             NounType.Role,
-            NounType.Topic,
+            NounType.Concept,
             NounType.Language,
             NounType.Currency,
             NounType.Measurement,
@@ -208,13 +207,13 @@ export class TypeAwareQueryPlanner {
         const allPct = ((this.stats.allTypesQueries / total) * 100).toFixed(1);
         const avgConf = (this.stats.avgConfidence * 100).toFixed(1);
         // Calculate weighted average speedup
-        const avgSpeedup = ((this.stats.singleTypeQueries * 31.0 +
+        const avgSpeedup = ((this.stats.singleTypeQueries * 42.0 +
             this.stats.multiTypeQueries * 10.0 +
             this.stats.allTypesQueries * 1.0) /
             total).toFixed(1);
         return `
 Query Statistics (${total} total):
-- Single-type: ${this.stats.singleTypeQueries} (${singlePct}%) - 31x speedup
+- Single-type: ${this.stats.singleTypeQueries} (${singlePct}%) - 42x speedup
 - Multi-type:  ${this.stats.multiTypeQueries} (${multiPct}%) - ~10x speedup
 - All-types:   ${this.stats.allTypesQueries} (${allPct}%) - 1x speedup
 - Avg confidence: ${avgConf}%

package/dist/storage/baseStorage.d.ts

@@ -61,6 +61,7 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     protected verbCountsByType: Uint32Array<ArrayBuffer>;
     protected nounTypeCache: Map<string, NounType>;
     protected verbTypeCache: Map<string, VerbType>;
+    private typeCountsRebuilt;
     /**
      * Analyze a storage key to determine its routing and path
      * @param id - The key to analyze (UUID or system key)
@@ -224,7 +225,15 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * Get nouns with pagination (v5.4.0: Type-first implementation)
      *
      * CRITICAL: This method is required for brain.find() to work!
-     * Iterates through all noun types to find entities.
+     * Iterates through noun types with billion-scale optimizations.
+     *
+     * ARCHITECTURE: Reads storage directly (not indexes) to avoid circular dependencies.
+     * Storage → Indexes (one direction only). GraphAdjacencyIndex built FROM storage.
+     *
+     * OPTIMIZATIONS (v5.5.0):
+     * - Skip empty types using nounCountsByType[] tracking (O(1) check)
+     * - Early termination when offset + limit entities collected
+     * - Memory efficient: Never loads full dataset
      */
     getNounsWithPagination(options: {
         limit: number;
@@ -241,6 +250,38 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
         hasMore: boolean;
         nextCursor?: string;
     }>;
+    /**
+     * Get verbs with pagination (v5.5.0: Type-first implementation with billion-scale optimizations)
+     *
+     * CRITICAL: This method is required for brain.getRelations() to work!
+     * Iterates through verb types with the same optimizations as nouns.
+     *
+     * ARCHITECTURE: Reads storage directly (not indexes) to avoid circular dependencies.
+     * Storage → Indexes (one direction only). GraphAdjacencyIndex built FROM storage.
+     *
+     * OPTIMIZATIONS (v5.5.0):
+     * - Skip empty types using verbCountsByType[] tracking (O(1) check)
+     * - Early termination when offset + limit verbs collected
+     * - Memory efficient: Never loads full dataset
+     * - Inline filtering for sourceId, targetId, verbType
+     */
+    getVerbsWithPagination(options: {
+        limit: number;
+        offset: number;
+        cursor?: string;
+        filter?: {
+            verbType?: string | string[];
+            sourceId?: string | string[];
+            targetId?: string | string[];
+            service?: string | string[];
+            metadata?: Record<string, any>;
+        };
+    }): Promise<{
+        items: HNSWVerbWithMetadata[];
+        totalCount: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
     /**
      * Get verbs with pagination and filtering
      * @param options Pagination and filtering options
@@ -393,6 +434,12 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * Periodically called when counts are updated
      */
     protected saveTypeStatistics(): Promise<void>;
+    /**
+     * Rebuild type counts from actual storage (v5.5.0)
+     * Called when statistics are missing or inconsistent
+     * Ensures verbCountsByType is always accurate for reliable pagination
+     */
+    protected rebuildTypeCounts(): Promise<void>;
     /**
      * Get noun type from cache or metadata
      * Relies on nounTypeCache populated during metadata saves

package/dist/storage/baseStorage.js

@@ -77,12 +77,14 @@ export class BaseStorage extends BaseStorageAdapter {
         this.cowEnabled = false;
         // Type-first indexing support (v5.4.0)
         // Built into all storage adapters for billion-scale efficiency
-        this.nounCountsByType = new Uint32Array(NOUN_TYPE_COUNT); // 124 bytes
-        this.verbCountsByType = new Uint32Array(VERB_TYPE_COUNT); // 160 bytes
-        // Total: 284 bytes (99.76% reduction vs Map-based tracking)
+        this.nounCountsByType = new Uint32Array(NOUN_TYPE_COUNT); // 168 bytes (Stage 3: 42 types)
+        this.verbCountsByType = new Uint32Array(VERB_TYPE_COUNT); // 508 bytes (Stage 3: 127 types)
+        // Total: 676 bytes (99.2% reduction vs Map-based tracking)
         // Type cache for O(1) lookups after first access
         this.nounTypeCache = new Map();
         this.verbTypeCache = new Map();
+        // v5.5.0: Track if type counts have been rebuilt (prevent repeated rebuilds)
+        this.typeCountsRebuilt = false;
     }
     /**
      * Analyze a storage key to determine its routing and path
@@ -825,14 +827,30 @@ export class BaseStorage extends BaseStorageAdapter {
      * Get nouns with pagination (v5.4.0: Type-first implementation)
      *
      * CRITICAL: This method is required for brain.find() to work!
-     * Iterates through all noun types to find entities.
+     * Iterates through noun types with billion-scale optimizations.
+     *
+     * ARCHITECTURE: Reads storage directly (not indexes) to avoid circular dependencies.
+     * Storage → Indexes (one direction only). GraphAdjacencyIndex built FROM storage.
+     *
+     * OPTIMIZATIONS (v5.5.0):
+     * - Skip empty types using nounCountsByType[] tracking (O(1) check)
+     * - Early termination when offset + limit entities collected
+     * - Memory efficient: Never loads full dataset
      */
     async getNounsWithPagination(options) {
         await this.ensureInitialized();
-        const { limit, offset, filter } = options;
-        const allNouns = [];
-        // v5.4.0: Iterate through all noun types (type-first architecture)
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
+        const { limit, offset = 0, filter } = options;
+        const collectedNouns = [];
+        const targetCount = offset + limit; // Early termination target
+        // v5.5.0 BUG FIX: Only use optimization if counts are reliable
+        const totalNounCountFromArray = this.nounCountsByType.reduce((sum, c) => sum + c, 0);
+        const useOptimization = totalNounCountFromArray > 0;
+        // v5.5.0: Iterate through noun types with billion-scale optimizations
+        for (let i = 0; i < NOUN_TYPE_COUNT && collectedNouns.length < targetCount; i++) {
+            // OPTIMIZATION 1: Skip empty types (only if counts are reliable)
+            if (useOptimization && this.nounCountsByType[i] === 0) {
+                continue;
+            }
             const type = TypeUtils.getNounFromIndex(i);
             // If filtering by type, skip other types
             if (filter?.nounType) {
@@ -846,6 +864,10 @@ export class BaseStorage extends BaseStorageAdapter {
                 // List all noun files for this type
                 const nounFiles = await this.listObjectsInBranch(typeDir);
                 for (const nounPath of nounFiles) {
+                    // OPTIMIZATION 2: Early termination (stop when we have enough)
+                    if (collectedNouns.length >= targetCount) {
+                        break;
+                    }
                     // Skip if not a .json file
                     if (!nounPath.endsWith('.json'))
                         continue;
@@ -864,7 +886,7 @@ export class BaseStorage extends BaseStorageAdapter {
                                     }
                                 }
                                 // Combine noun + metadata (v5.4.0: Extract standard fields to top-level)
-                                allNouns.push({
+                                collectedNouns.push({
                                     ...noun,
                                     type: metadata.noun || type, // Required: Extract type from metadata
                                     confidence: metadata.confidence,
@@ -892,19 +914,104 @@ export class BaseStorage extends BaseStorageAdapter {
                 // Skip types that have no data
             }
         }
-        // Apply pagination
-        const totalCount = allNouns.length;
-        const paginatedNouns = allNouns.slice(offset, offset + limit);
-        const hasMore = offset + limit < totalCount;
+        // Apply pagination (v5.5.0: Efficient slicing after early termination)
+        const paginatedNouns = collectedNouns.slice(offset, offset + limit);
+        const hasMore = collectedNouns.length >= targetCount;
         return {
             items: paginatedNouns,
-            totalCount,
+            totalCount: collectedNouns.length, // Accurate count of collected results
             hasMore,
             nextCursor: hasMore && paginatedNouns.length > 0
                 ? paginatedNouns[paginatedNouns.length - 1].id
                 : undefined
         };
     }
+    /**
+     * Get verbs with pagination (v5.5.0: Type-first implementation with billion-scale optimizations)
+     *
+     * CRITICAL: This method is required for brain.getRelations() to work!
+     * Iterates through verb types with the same optimizations as nouns.
+     *
+     * ARCHITECTURE: Reads storage directly (not indexes) to avoid circular dependencies.
+     * Storage → Indexes (one direction only). GraphAdjacencyIndex built FROM storage.
+     *
+     * OPTIMIZATIONS (v5.5.0):
+     * - Skip empty types using verbCountsByType[] tracking (O(1) check)
+     * - Early termination when offset + limit verbs collected
+     * - Memory efficient: Never loads full dataset
+     * - Inline filtering for sourceId, targetId, verbType
+     */
+    async getVerbsWithPagination(options) {
+        await this.ensureInitialized();
+        const { limit, offset = 0, filter } = options;
+        const collectedVerbs = [];
+        const targetCount = offset + limit; // Early termination target
+        // v5.5.0 BUG FIX: Only use optimization if counts are reliable
+        const totalVerbCountFromArray = this.verbCountsByType.reduce((sum, c) => sum + c, 0);
+        const useOptimization = totalVerbCountFromArray > 0;
+        // v5.5.0: Iterate through verb types with billion-scale optimizations
+        for (let i = 0; i < VERB_TYPE_COUNT && collectedVerbs.length < targetCount; i++) {
+            // OPTIMIZATION 1: Skip empty types (only if counts are reliable)
+            if (useOptimization && this.verbCountsByType[i] === 0) {
+                continue;
+            }
+            const type = TypeUtils.getVerbFromIndex(i);
+            // If filtering by verbType, skip other types
+            if (filter?.verbType) {
+                const filterTypes = Array.isArray(filter.verbType) ? filter.verbType : [filter.verbType];
+                if (!filterTypes.includes(type)) {
+                    continue;
+                }
+            }
+            try {
+                const verbsOfType = await this.getVerbsByType_internal(type);
+                // Apply filtering inline (memory efficient)
+                for (const verb of verbsOfType) {
+                    // OPTIMIZATION 2: Early termination (stop when we have enough)
+                    if (collectedVerbs.length >= targetCount) {
+                        break;
+                    }
+                    // Apply filters if specified
+                    if (filter) {
+                        // Filter by sourceId
+                        if (filter.sourceId) {
+                            const sourceIds = Array.isArray(filter.sourceId)
+                                ? filter.sourceId
+                                : [filter.sourceId];
+                            if (!sourceIds.includes(verb.sourceId)) {
+                                continue;
+                            }
+                        }
+                        // Filter by targetId
+                        if (filter.targetId) {
+                            const targetIds = Array.isArray(filter.targetId)
+                                ? filter.targetId
+                                : [filter.targetId];
+                            if (!targetIds.includes(verb.targetId)) {
+                                continue;
+                            }
+                        }
+                    }
+                    // Verb passed all filters - add to collection
+                    collectedVerbs.push(verb);
+                }
+            }
+            catch (error) {
+                // Skip types that have no data (directory may not exist)
+            }
+        }
+        // Apply pagination (v5.5.0: Efficient slicing after early termination)
+        const paginatedVerbs = collectedVerbs.slice(offset, offset + limit);
+        const hasMore = collectedVerbs.length >= targetCount;
+        return {
+            items: paginatedVerbs,
+            totalCount: collectedVerbs.length, // Accurate count of collected results
+            hasMore,
+            nextCursor: hasMore && paginatedVerbs.length > 0
+                ? paginatedVerbs[paginatedVerbs.length - 1].id
+                : undefined
+        };
+    }
     /**
      * Get verbs with pagination and filtering
      * @param options Pagination and filtering options
@@ -1080,12 +1187,84 @@ export class BaseStorage extends BaseStorageAdapter {
                     nextCursor: result.nextCursor
                 };
             }
-            // Storage adapter does not support pagination
-            console.error('Storage adapter does not support pagination. The deprecated getAllVerbs_internal() method has been removed. Please implement getVerbsWithPagination() in your storage adapter.');
+            // UNIVERSAL FALLBACK: Iterate through verb types with early termination (billion-scale safe)
+            // This approach works for ALL storage adapters without requiring adapter-specific pagination
+            console.warn('Using universal type-iteration strategy for getVerbs(). ' +
+                'This works for all adapters but may be slower than native pagination. ' +
+                'For optimal performance at scale, storage adapters can implement getVerbsWithPagination().');
+            const collectedVerbs = [];
+            let totalScanned = 0;
+            const targetCount = offset + limit; // We need this many verbs total (including offset)
+            // v5.5.0 BUG FIX: Check if optimization should be used
+            // Only use type-skipping optimization if counts are non-zero (reliable)
+            const totalVerbCountFromArray = this.verbCountsByType.reduce((sum, c) => sum + c, 0);
+            const useOptimization = totalVerbCountFromArray > 0;
+            // Iterate through all 127 verb types (Stage 3 CANONICAL) with early termination
+            // OPTIMIZATION: Skip types with zero count (only if counts are reliable)
+            for (let i = 0; i < VERB_TYPE_COUNT && collectedVerbs.length < targetCount; i++) {
+                // Skip empty types for performance (but only if optimization is enabled)
+                if (useOptimization && this.verbCountsByType[i] === 0) {
+                    continue;
+                }
+                const type = TypeUtils.getVerbFromIndex(i);
+                try {
+                    const verbsOfType = await this.getVerbsByType_internal(type);
+                    // Apply filtering inline (memory efficient)
+                    for (const verb of verbsOfType) {
+                        // Apply filters if specified
+                        if (options?.filter) {
+                            // Filter by sourceId
+                            if (options.filter.sourceId) {
+                                const sourceIds = Array.isArray(options.filter.sourceId)
+                                    ? options.filter.sourceId
+                                    : [options.filter.sourceId];
+                                if (!sourceIds.includes(verb.sourceId)) {
+                                    continue;
+                                }
+                            }
+                            // Filter by targetId
+                            if (options.filter.targetId) {
+                                const targetIds = Array.isArray(options.filter.targetId)
+                                    ? options.filter.targetId
+                                    : [options.filter.targetId];
+                                if (!targetIds.includes(verb.targetId)) {
+                                    continue;
+                                }
+                            }
+                            // Filter by verbType
+                            if (options.filter.verbType) {
+                                const verbTypes = Array.isArray(options.filter.verbType)
+                                    ? options.filter.verbType
+                                    : [options.filter.verbType];
+                                if (!verbTypes.includes(verb.verb)) {
+                                    continue;
+                                }
+                            }
+                        }
+                        // Verb passed filters - add to collection
+                        collectedVerbs.push(verb);
+                        // Early termination: stop when we have enough for offset + limit
+                        if (collectedVerbs.length >= targetCount) {
+                            break;
+                        }
+                    }
+                    totalScanned += verbsOfType.length;
+                }
+                catch (error) {
+                    // Ignore errors for types with no verbs (directory may not exist)
+                    // This is expected for types that haven't been used yet
+                }
+            }
+            // Apply pagination (slice for offset)
+            const paginatedVerbs = collectedVerbs.slice(offset, offset + limit);
+            const hasMore = collectedVerbs.length >= targetCount;
             return {
-                items: [],
-                totalCount: 0,
-                hasMore: false
+                items: paginatedVerbs,
+                totalCount: collectedVerbs.length, // Accurate count of filtered results
+                hasMore,
+                nextCursor: hasMore && paginatedVerbs.length > 0
+                    ? paginatedVerbs[paginatedVerbs.length - 1].id
+                    : undefined
             };
         }
         catch (error) {
@@ -1402,6 +1581,45 @@ export class BaseStorage extends BaseStorageAdapter {
         };
         await this.writeObjectToPath(`${SYSTEM_DIR}/type-statistics.json`, stats);
     }
+    /**
+     * Rebuild type counts from actual storage (v5.5.0)
+     * Called when statistics are missing or inconsistent
+     * Ensures verbCountsByType is always accurate for reliable pagination
+     */
+    async rebuildTypeCounts() {
+        console.log('[BaseStorage] Rebuilding type counts from storage...');
+        // Rebuild verb counts by checking each type directory
+        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
+            const type = TypeUtils.getVerbFromIndex(i);
+            const prefix = `entities/verbs/${type}/vectors/`;
+            try {
+                const paths = await this.listObjectsInBranch(prefix);
+                this.verbCountsByType[i] = paths.length;
+            }
+            catch (error) {
+                // Type directory doesn't exist - count is 0
+                this.verbCountsByType[i] = 0;
+            }
+        }
+        // Rebuild noun counts similarly
+        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
+            const type = TypeUtils.getNounFromIndex(i);
+            const prefix = `entities/nouns/${type}/vectors/`;
+            try {
+                const paths = await this.listObjectsInBranch(prefix);
+                this.nounCountsByType[i] = paths.length;
+            }
+            catch (error) {
+                // Type directory doesn't exist - count is 0
+                this.nounCountsByType[i] = 0;
+            }
+        }
+        // Save rebuilt counts to storage
+        await this.saveTypeStatistics();
+        const totalVerbs = this.verbCountsByType.reduce((sum, count) => sum + count, 0);
+        const totalNouns = this.nounCountsByType.reduce((sum, count) => sum + count, 0);
+        console.log(`[BaseStorage] Rebuilt counts: ${totalNouns} nouns, ${totalVerbs} verbs`);
+    }
     /**
      * Get noun type from cache or metadata
      * Relies on nounTypeCache populated during metadata saves