@soulcraft/brainy 5.3.6 → 5.5.0

package/dist/storage/baseStorage.d.ts

@@ -5,6 +5,7 @@
 import { GraphAdjacencyIndex } from '../graph/graphAdjacencyIndex.js';
 import { GraphVerb, HNSWNoun, HNSWVerb, NounMetadata, VerbMetadata, HNSWNounWithMetadata, HNSWVerbWithMetadata, StatisticsData } from '../coreTypes.js';
 import { BaseStorageAdapter } from './adapters/baseStorageAdapter.js';
+import { NounType, VerbType } from '../types/graphTypes.js';
 import { RefManager } from './cow/RefManager.js';
 import { BlobStorage } from './cow/BlobStorage.js';
 import { CommitLog } from './cow/CommitLog.js';
@@ -56,6 +57,10 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     commitLog?: CommitLog;
     currentBranch: string;
     protected cowEnabled: boolean;
+    protected nounCountsByType: Uint32Array<ArrayBuffer>;
+    protected verbCountsByType: Uint32Array<ArrayBuffer>;
+    protected nounTypeCache: Map<string, NounType>;
+    protected verbTypeCache: Map<string, VerbType>;
     /**
      * Analyze a storage key to determine its routing and path
      * @param id - The key to analyze (UUID or system key)
@@ -65,10 +70,12 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      */
     private analyzeKey;
     /**
-     * Initialize the storage adapter
-     * This method should be implemented by each specific adapter
+     * Initialize the storage adapter (v5.4.0)
+     * Loads type statistics for built-in type-aware indexing
+     *
+     * IMPORTANT: If your adapter overrides init(), call await super.init() first!
      */
-    abstract init(): Promise<void>;
+    init(): Promise<void>;
     /**
      * Ensure the storage adapter is initialized
      */
@@ -213,6 +220,27 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
         hasMore: boolean;
         nextCursor?: string;
     }>;
+    /**
+     * 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.
+     */
+    getNounsWithPagination(options: {
+        limit: number;
+        offset: number;
+        cursor?: string;
+        filter?: {
+            nounType?: string | string[];
+            service?: string | string[];
+            metadata?: Record<string, any>;
+        };
+    }): Promise<{
+        items: HNSWNounWithMetadata[];
+        totalCount: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
     /**
      * Get verbs with pagination and filtering
      * @param options Pagination and filtering options
@@ -319,12 +347,12 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     protected saveNounMetadata_internal(id: string, metadata: NounMetadata): Promise<void>;
     /**
      * Get noun metadata from storage (v4.0.0: now typed)
-     * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
+     * v5.4.0: Uses type-first paths (must match saveNounMetadata_internal)
      */
     getNounMetadata(id: string): Promise<NounMetadata | null>;
     /**
      * Delete noun metadata from storage
-     * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
+     * v5.4.0: Uses type-first paths (must match saveNounMetadata_internal)
      */
     deleteNounMetadata(id: string): Promise<void>;
     /**
@@ -334,7 +362,7 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     saveVerbMetadata(id: string, metadata: VerbMetadata): Promise<void>;
     /**
      * Internal method for saving verb metadata (v4.0.0: now typed)
-     * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
+     * v5.4.0: Uses type-first paths (must match getVerbMetadata)
      *
      * CRITICAL (v4.1.2): Count synchronization happens here
      * This ensures verb counts are updated AFTER metadata exists, fixing the race condition
@@ -347,64 +375,76 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     protected saveVerbMetadata_internal(id: string, metadata: VerbMetadata): Promise<void>;
     /**
      * Get verb metadata from storage (v4.0.0: now typed)
-     * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
+     * v5.4.0: Uses type-first paths (must match saveVerbMetadata_internal)
      */
     getVerbMetadata(id: string): Promise<VerbMetadata | null>;
     /**
      * Delete verb metadata from storage
-     * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
+     * v5.4.0: Uses type-first paths (must match saveVerbMetadata_internal)
      */
     deleteVerbMetadata(id: string): Promise<void>;
     /**
-     * Save a noun to storage
-     * This method should be implemented by each specific adapter
+     * Load type statistics from storage
+     * Rebuilds type counts if needed (called during init)
      */
-    protected abstract saveNoun_internal(noun: HNSWNoun): Promise<void>;
+    protected loadTypeStatistics(): Promise<void>;
     /**
-     * Get a noun from storage
-     * This method should be implemented by each specific adapter
+     * Save type statistics to storage
+     * Periodically called when counts are updated
      */
-    protected abstract getNoun_internal(id: string): Promise<HNSWNoun | null>;
+    protected saveTypeStatistics(): Promise<void>;
     /**
-     * Get nouns by noun type
-     * This method should be implemented by each specific adapter
+     * Get noun type from cache or metadata
+     * Relies on nounTypeCache populated during metadata saves
      */
-    protected abstract getNounsByNounType_internal(nounType: string): Promise<HNSWNoun[]>;
+    protected getNounType(noun: HNSWNoun): NounType;
     /**
-     * Delete a noun from storage
-     * This method should be implemented by each specific adapter
+     * Get verb type from verb object
+     * Verb type is a required field in HNSWVerb
      */
-    protected abstract deleteNoun_internal(id: string): Promise<void>;
+    protected getVerbType(verb: HNSWVerb | GraphVerb): VerbType;
     /**
-     * Save a verb to storage
-     * This method should be implemented by each specific adapter
+     * Save a noun to storage (type-first path)
      */
-    protected abstract saveVerb_internal(verb: HNSWVerb): Promise<void>;
+    protected saveNoun_internal(noun: HNSWNoun): Promise<void>;
     /**
-     * Get a verb from storage
-     * This method should be implemented by each specific adapter
+     * Get a noun from storage (type-first path)
      */
-    protected abstract getVerb_internal(id: string): Promise<HNSWVerb | null>;
+    protected getNoun_internal(id: string): Promise<HNSWNoun | null>;
     /**
-     * Get verbs by source
-     * This method should be implemented by each specific adapter
+     * Get nouns by noun type (O(1) with type-first paths!)
      */
-    protected abstract getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
+    protected getNounsByNounType_internal(nounType: string): Promise<HNSWNoun[]>;
     /**
-     * Get verbs by target
-     * This method should be implemented by each specific adapter
+     * Delete a noun from storage (type-first path)
      */
-    protected abstract getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
+    protected deleteNoun_internal(id: string): Promise<void>;
     /**
-     * Get verbs by type
-     * This method should be implemented by each specific adapter
+     * Save a verb to storage (type-first path)
      */
-    protected abstract getVerbsByType_internal(type: string): Promise<HNSWVerbWithMetadata[]>;
+    protected saveVerb_internal(verb: HNSWVerb): Promise<void>;
     /**
-     * Delete a verb from storage
-     * This method should be implemented by each specific adapter
+     * Get a verb from storage (type-first path)
+     */
+    protected getVerb_internal(id: string): Promise<HNSWVerb | null>;
+    /**
+     * Get verbs by source (COW-aware implementation)
+     * v5.4.0: Fixed to directly list verb files instead of directories
+     */
+    protected getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
+    /**
+     * Get verbs by target (COW-aware implementation)
+     * v5.4.0: Fixed to directly list verb files instead of directories
+     */
+    protected getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
+    /**
+     * Get verbs by type (O(1) with type-first paths!)
+     */
+    protected getVerbsByType_internal(verbType: string): Promise<HNSWVerbWithMetadata[]>;
+    /**
+     * Delete a verb from storage (type-first path)
      */
-    protected abstract deleteVerb_internal(id: string): Promise<void>;
+    protected deleteVerb_internal(id: string): Promise<void>;
     /**
      * Helper method to convert a Map to a plain object for serialization
      */