@soulcraft/brainy 5.3.6 → 5.4.0

package/dist/storage/adapters/gcsStorage.d.ts

@@ -8,7 +8,7 @@
  * 3. Service Account Credentials Object
  * 4. HMAC Keys (fallback for backward compatibility)
  */
-import { HNSWNoun, HNSWVerb, HNSWNounWithMetadata, HNSWVerbWithMetadata, StatisticsData } from '../../coreTypes.js';
+import { HNSWNoun, HNSWVerb, StatisticsData } from '../../coreTypes.js';
 import { BaseStorage, StorageBatchConfig } from '../baseStorage.js';
 type HNSWNode = HNSWNoun;
 type Edge = HNSWVerb;
@@ -21,6 +21,12 @@ type Edge = HNSWVerb;
  * 2. Service Account Key File (if keyFilename provided)
  * 3. Service Account Credentials Object (if credentials provided)
  * 4. HMAC Keys (if accessKeyId/secretAccessKey provided)
+ *
+ * v5.4.0: Type-aware storage now built into BaseStorage
+ * - Removed 10 *_internal method overrides (now inherit from BaseStorage's type-first implementation)
+ * - Removed 2 pagination method overrides (getNounsWithPagination, getVerbsWithPagination)
+ * - Updated HNSW methods to use BaseStorage's getNoun/saveNoun (type-first paths)
+ * - All operations now use type-first paths: entities/nouns/{type}/vectors/{shard}/{id}.json
  */
 export declare class GcsStorage extends BaseStorage {
     private storage;
@@ -55,6 +61,7 @@ export declare class GcsStorage extends BaseStorage {
     private nounCacheManager;
     private verbCacheManager;
     private logger;
+    private hnswLocks;
     private skipInitialScan;
     private skipCountsFile;
     /**
@@ -153,10 +160,6 @@ export declare class GcsStorage extends BaseStorage {
      * Flush verb buffer to GCS
      */
     private flushVerbBuffer;
-    /**
-     * Save a noun to storage (internal implementation)
-     */
-    protected saveNoun_internal(noun: HNSWNoun): Promise<void>;
     /**
      * Save a node to storage
      */
@@ -165,20 +168,10 @@ export declare class GcsStorage extends BaseStorage {
      * Save a node directly to GCS (bypass buffer)
      */
     private saveNodeDirect;
-    /**
-     * Get a noun from storage (internal implementation)
-     * v4.0.0: Returns ONLY vector data (no metadata field)
-     * Base class combines with metadata via getNoun() -> HNSWNounWithMetadata
-     */
-    protected getNoun_internal(id: string): Promise<HNSWNoun | null>;
     /**
      * Get a node from storage
      */
     protected getNode(id: string): Promise<HNSWNode | null>;
-    /**
-     * Delete a noun from storage (internal implementation)
-     */
-    protected deleteNoun_internal(id: string): Promise<void>;
     /**
      * Write an object to a specific path in GCS
      * Primitive operation required by base class
@@ -203,10 +196,6 @@ export declare class GcsStorage extends BaseStorage {
      * @protected
      */
     protected listObjectsUnderPath(prefix: string): Promise<string[]>;
-    /**
-     * Save a verb to storage (internal implementation)
-     */
-    protected saveVerb_internal(verb: HNSWVerb): Promise<void>;
     /**
      * Save an edge to storage
      */
@@ -215,123 +204,10 @@ export declare class GcsStorage extends BaseStorage {
      * Save an edge directly to GCS (bypass buffer)
      */
     private saveEdgeDirect;
-    /**
-     * Get a verb from storage (internal implementation)
-     * v4.0.0: Returns ONLY vector + core relational fields (no metadata field)
-     * Base class combines with metadata via getVerb() -> HNSWVerbWithMetadata
-     */
-    protected getVerb_internal(id: string): Promise<HNSWVerb | null>;
     /**
      * Get an edge from storage
      */
     protected getEdge(id: string): Promise<Edge | null>;
-    /**
-     * Delete a verb from storage (internal implementation)
-     */
-    protected deleteVerb_internal(id: string): Promise<void>;
-    /**
-     * Get nouns with pagination
-     * v4.0.0: Returns HNSWNounWithMetadata[] (includes metadata field)
-     * Iterates through all UUID-based shards (00-ff) for consistent pagination
-     */
-    getNounsWithPagination(options?: {
-        limit?: number;
-        cursor?: string;
-        filter?: {
-            nounType?: string | string[];
-            service?: string | string[];
-            metadata?: Record<string, any>;
-        };
-    }): Promise<{
-        items: HNSWNounWithMetadata[];
-        totalCount?: number;
-        hasMore: boolean;
-        nextCursor?: string;
-    }>;
-    /**
-     * Get nodes with pagination (internal implementation)
-     * Iterates through UUID-based shards for consistent pagination
-     */
-    private getNodesWithPagination;
-    /**
-     * Get nouns by noun type (internal implementation)
-     */
-    protected getNounsByNounType_internal(nounType: string): Promise<HNSWNoun[]>;
-    /**
-     * Get verbs by source ID (internal implementation)
-     */
-    protected getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
-    /**
-     * Get verbs by target ID (internal implementation)
-     */
-    protected getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
-    /**
-     * Get verbs by type (internal implementation)
-     */
-    protected getVerbsByType_internal(type: string): Promise<HNSWVerbWithMetadata[]>;
-    /**
-     * Get verbs with pagination
-     * v4.0.0: Returns HNSWVerbWithMetadata[] (includes metadata field)
-     */
-    getVerbsWithPagination(options?: {
-        limit?: 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 nouns with filtering and pagination (public API)
-     */
-    getNouns(options?: {
-        pagination?: {
-            offset?: number;
-            limit?: number;
-            cursor?: string;
-        };
-        filter?: {
-            nounType?: string | string[];
-            service?: string | string[];
-            metadata?: Record<string, any>;
-        };
-    }): Promise<{
-        items: any[];
-        totalCount?: number;
-        hasMore: boolean;
-        nextCursor?: string;
-    }>;
-    /**
-     * Get verbs with filtering and pagination (public API)
-     * v4.0.0: Returns HNSWVerbWithMetadata[] (includes metadata field)
-     */
-    getVerbs(options?: {
-        pagination?: {
-            offset?: number;
-            limit?: 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;
-    }>;
     /**
      * Batch fetch metadata for multiple noun IDs (efficient for large queries)
      * Uses smaller batches to prevent GCS socket exhaustion
@@ -375,11 +251,14 @@ export declare class GcsStorage extends BaseStorage {
     protected persistCounts(): Promise<void>;
     /**
      * Get a noun's vector for HNSW rebuild
+     * v5.4.0: Uses BaseStorage's getNoun (type-first paths)
      */
     getNounVector(id: string): Promise<number[] | null>;
     /**
      * Save HNSW graph data for a noun
-     * Storage path: entities/nouns/hnsw/{shard}/{id}.json
+     *
+     * v5.4.0: Uses BaseStorage's getNoun/saveNoun (type-first paths)
+     * CRITICAL: Uses mutex locking to prevent read-modify-write races
      */
     saveHNSWData(nounId: string, hnswData: {
         level: number;
@@ -387,7 +266,7 @@ export declare class GcsStorage extends BaseStorage {
     }): Promise<void>;
     /**
      * Get HNSW graph data for a noun
-     * Storage path: entities/nouns/hnsw/{shard}/{id}.json
+     * v5.4.0: Uses BaseStorage's getNoun (type-first paths)
      */
     getHNSWData(nounId: string): Promise<{
         level: number;