@soulcraft/brainy 5.3.6 → 5.5.0

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

@@ -11,7 +11,7 @@
  *
  * Based on latest GCS and S3 implementations with R2-specific enhancements
  */
-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;
@@ -19,6 +19,12 @@ type Edge = HNSWVerb;
  * Dedicated Cloudflare R2 storage adapter
  * Optimized for R2's unique characteristics and global edge network
  *
+ * v5.4.0: Type-aware storage now built into BaseStorage
+ * - Removed 10 *_internal method overrides (now inherit from BaseStorage's type-first implementation)
+ * - Removed getNounsWithPagination override
+ * - 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
+ *
  * Configuration:
  * ```typescript
  * const r2Storage = new R2Storage({
@@ -59,6 +65,7 @@ export declare class R2Storage extends BaseStorage {
     private nounCacheManager;
     private verbCacheManager;
     private logger;
+    private hnswLocks;
     /**
      * Initialize the R2 storage adapter
      * @param options Configuration options for Cloudflare R2
@@ -133,10 +140,6 @@ export declare class R2Storage extends BaseStorage {
      * Flush verb buffer to R2
      */
     private flushVerbBuffer;
-    /**
-     * Save a noun to storage (internal implementation)
-     */
-    protected saveNoun_internal(noun: HNSWNoun): Promise<void>;
     /**
      * Save a node to storage
      */
@@ -145,20 +148,10 @@ export declare class R2Storage extends BaseStorage {
      * Save a node directly to R2 (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 R2
      */
@@ -175,17 +168,9 @@ export declare class R2Storage extends BaseStorage {
      * List all objects under a specific prefix in R2
      */
     protected listObjectsUnderPath(prefix: string): Promise<string[]>;
-    protected saveVerb_internal(verb: HNSWVerb): Promise<void>;
     protected saveEdge(edge: Edge): Promise<void>;
     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>;
     protected getEdge(id: string): Promise<Edge | null>;
-    protected deleteVerb_internal(id: string): Promise<void>;
     protected initializeCounts(): Promise<void>;
     private initializeCountsFromScan;
     protected persistCounts(): Promise<void>;
@@ -215,23 +200,5 @@ export declare class R2Storage extends BaseStorage {
         quota: number | null;
         details?: Record<string, any>;
     }>;
-    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;
-    }>;
-    protected getNounsByNounType_internal(nounType: string): Promise<HNSWNoun[]>;
-    protected getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
-    protected getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
-    protected getVerbsByType_internal(type: string): Promise<HNSWVerbWithMetadata[]>;
 }
 export {};

package/dist/storage/adapters/r2Storage.js

@@ -11,7 +11,6 @@
  *
  * Based on latest GCS and S3 implementations with R2-specific enhancements
  */
-import { NounType } from '../../coreTypes.js';
 import { BaseStorage, SYSTEM_DIR, STATISTICS_KEY, getDirectoryPath } from '../baseStorage.js';
 import { BrainyError } from '../../errors/brainyError.js';
 import { CacheManager } from '../cacheManager.js';
@@ -26,6 +25,12 @@ const MAX_R2_PAGE_SIZE = 1000;
  * Dedicated Cloudflare R2 storage adapter
  * Optimized for R2's unique characteristics and global edge network
  *
+ * v5.4.0: Type-aware storage now built into BaseStorage
+ * - Removed 10 *_internal method overrides (now inherit from BaseStorage's type-first implementation)
+ * - Removed getNounsWithPagination override
+ * - 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
+ *
  * Configuration:
  * ```typescript
  * const r2Storage = new R2Storage({
@@ -67,6 +72,8 @@ export class R2Storage extends BaseStorage {
         this.forceHighVolumeMode = false;
         // Module logger
         this.logger = createModuleLogger('R2Storage');
+        // v5.4.0: HNSW mutex locks to prevent read-modify-write races
+        this.hnswLocks = new Map();
         this.bucketName = options.bucketName;
         this.accountId = options.accountId;
         this.accessKeyId = options.accessKeyId;
@@ -283,12 +290,6 @@ export class R2Storage extends BaseStorage {
         });
         await Promise.all(writes);
     }
-    /**
-     * Save a noun to storage (internal implementation)
-     */
-    async saveNoun_internal(noun) {
-        return this.saveNode(noun);
-    }
     /**
      * Save a node to storage
      */
@@ -353,20 +354,6 @@ export class R2Storage extends BaseStorage {
             throw new Error(`Failed to save node ${node.id}: ${error}`);
         }
     }
-    /**
-     * 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
-     */
-    async getNoun_internal(id) {
-        // v4.0.0: Return ONLY vector data (no metadata field)
-        const node = await this.getNode(id);
-        if (!node) {
-            return null;
-        }
-        // Return pure vector structure
-        return node;
-    }
     /**
      * Get a node from storage
      */
@@ -429,45 +416,6 @@ export class R2Storage extends BaseStorage {
             throw BrainyError.fromError(error, `getNoun(${id})`);
         }
     }
-    /**
-     * Delete a noun from storage (internal implementation)
-     */
-    async deleteNoun_internal(id) {
-        await this.ensureInitialized();
-        const requestId = await this.applyBackpressure();
-        try {
-            this.logger.trace(`Deleting noun ${id}`);
-            const key = this.getNounKey(id);
-            // Delete from R2 using S3 DeleteObject
-            const { DeleteObjectCommand } = await import('@aws-sdk/client-s3');
-            await this.s3Client.send(new DeleteObjectCommand({
-                Bucket: this.bucketName,
-                Key: key
-            }));
-            // Remove from cache
-            this.nounCacheManager.delete(id);
-            // Decrement noun count
-            const metadata = await this.getNounMetadata(id);
-            if (metadata && metadata.type) {
-                await this.decrementEntityCountSafe(metadata.type);
-            }
-            this.logger.trace(`Noun ${id} deleted successfully`);
-            this.releaseBackpressure(true, requestId);
-        }
-        catch (error) {
-            this.releaseBackpressure(false, requestId);
-            if (error.name === 'NoSuchKey' || error.$metadata?.httpStatusCode === 404) {
-                this.logger.trace(`Noun ${id} not found (already deleted)`);
-                return;
-            }
-            if (this.isThrottlingError(error)) {
-                await this.handleThrottling(error);
-                throw error;
-            }
-            this.logger.error(`Failed to delete noun ${id}:`, error);
-            throw new Error(`Failed to delete noun ${id}: ${error}`);
-        }
-    }
     /**
      * Write an object to a specific path in R2
      */
@@ -563,9 +511,6 @@ export class R2Storage extends BaseStorage {
         }
     }
     // Verb storage methods (similar to noun methods - implementing key methods for space)
-    async saveVerb_internal(verb) {
-        return this.saveEdge(verb);
-    }
     async saveEdge(edge) {
         await this.ensureInitialized();
         this.checkVolumeMode();
@@ -616,20 +561,6 @@ export class R2Storage extends BaseStorage {
             throw new Error(`Failed to save edge ${edge.id}: ${error}`);
         }
     }
-    /**
-     * 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
-     */
-    async getVerb_internal(id) {
-        // v4.0.0: Return ONLY vector + core relational data (no metadata field)
-        const edge = await this.getEdge(id);
-        if (!edge) {
-            return null;
-        }
-        // Return pure vector + core fields structure
-        return edge;
-    }
     async getEdge(id) {
         await this.ensureInitialized();
         const cached = this.verbCacheManager.get(id);
@@ -678,35 +609,6 @@ export class R2Storage extends BaseStorage {
             throw BrainyError.fromError(error, `getVerb(${id})`);
         }
     }
-    async deleteVerb_internal(id) {
-        await this.ensureInitialized();
-        const requestId = await this.applyBackpressure();
-        try {
-            const key = this.getVerbKey(id);
-            const { DeleteObjectCommand } = await import('@aws-sdk/client-s3');
-            await this.s3Client.send(new DeleteObjectCommand({
-                Bucket: this.bucketName,
-                Key: key
-            }));
-            this.verbCacheManager.delete(id);
-            const metadata = await this.getVerbMetadata(id);
-            if (metadata && metadata.type) {
-                await this.decrementVerbCount(metadata.type);
-            }
-            this.releaseBackpressure(true, requestId);
-        }
-        catch (error) {
-            this.releaseBackpressure(false, requestId);
-            if (error.name === 'NoSuchKey' || error.$metadata?.httpStatusCode === 404) {
-                return;
-            }
-            if (this.isThrottlingError(error)) {
-                await this.handleThrottling(error);
-                throw error;
-            }
-            throw new Error(`Failed to delete verb ${id}: ${error}`);
-        }
-    }
     // Pagination and count management (simplified for space - full implementation similar to GCS)
     async initializeCounts() {
         const key = `${this.systemPrefix}counts.json`;
@@ -776,42 +678,55 @@ export class R2Storage extends BaseStorage {
     }
     // HNSW Index Persistence (Phase 2 support)
     async getNounVector(id) {
-        await this.ensureInitialized();
-        const noun = await this.getNode(id);
+        const noun = await this.getNoun(id);
         return noun ? noun.vector : null;
     }
     async saveHNSWData(nounId, hnswData) {
-        await this.ensureInitialized();
-        // CRITICAL FIX (v4.7.3): Must preserve existing node data (id, vector) when updating HNSW metadata
-        const shard = getShardIdFromUuid(nounId);
-        const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
+        const lockKey = `hnsw/${nounId}`;
+        // Wait for pending operations
+        while (this.hnswLocks.has(lockKey)) {
+            await this.hnswLocks.get(lockKey);
+        }
+        // Acquire lock
+        let releaseLock;
+        const lockPromise = new Promise(resolve => { releaseLock = resolve; });
+        this.hnswLocks.set(lockKey, lockPromise);
         try {
-            // Read existing node data
-            const existingNode = await this.readObjectFromPath(key);
-            if (existingNode) {
-                // Preserve id and vector, update only HNSW graph metadata
-                const updatedNode = {
-                    ...existingNode,
-                    level: hnswData.level,
-                    connections: hnswData.connections
-                };
-                await this.writeObjectToPath(key, updatedNode);
-            }
-            else {
-                // Node doesn't exist yet, create with just HNSW data
-                await this.writeObjectToPath(key, hnswData);
-            }
+            const existingNoun = await this.getNoun(nounId);
+            if (!existingNoun) {
+                throw new Error(`Cannot save HNSW data: noun ${nounId} not found`);
+            }
+            const connectionsMap = new Map();
+            for (const [level, nodeIds] of Object.entries(hnswData.connections)) {
+                connectionsMap.set(Number(level), new Set(nodeIds));
+            }
+            const updatedNoun = {
+                ...existingNoun,
+                level: hnswData.level,
+                connections: connectionsMap
+            };
+            await this.saveNoun(updatedNoun);
         }
-        catch (error) {
-            // If read fails, create with just HNSW data
-            await this.writeObjectToPath(key, hnswData);
+        finally {
+            this.hnswLocks.delete(lockKey);
+            releaseLock();
         }
     }
     async getHNSWData(nounId) {
-        await this.ensureInitialized();
-        const shard = getShardIdFromUuid(nounId);
-        const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
-        return await this.readObjectFromPath(key);
+        const noun = await this.getNoun(nounId);
+        if (!noun) {
+            return null;
+        }
+        const connectionsRecord = {};
+        if (noun.connections) {
+            for (const [level, nodeIds] of noun.connections.entries()) {
+                connectionsRecord[String(level)] = Array.from(nodeIds);
+            }
+        }
+        return {
+            level: noun.level || 0,
+            connections: connectionsRecord
+        };
     }
     async saveHNSWSystem(systemData) {
         await this.ensureInitialized();
@@ -889,108 +804,5 @@ export class R2Storage extends BaseStorage {
             }
         };
     }
-    // Pagination support (simplified - full implementation would match GCS pattern)
-    async getNounsWithPagination(options = {}) {
-        await this.ensureInitialized();
-        // Simplified pagination - full implementation would be similar to GCS
-        const limit = options.limit || 100;
-        const { ListObjectsV2Command } = await import('@aws-sdk/client-s3');
-        const response = await this.s3Client.send(new ListObjectsV2Command({
-            Bucket: this.bucketName,
-            Prefix: this.nounPrefix,
-            MaxKeys: limit,
-            ContinuationToken: options.cursor
-        }));
-        const items = [];
-        const contents = response.Contents || [];
-        for (const obj of contents) {
-            if (!obj.Key?.endsWith('.json'))
-                continue;
-            const id = obj.Key.split('/').pop()?.replace('.json', '');
-            if (!id)
-                continue;
-            const noun = await this.getNoun_internal(id);
-            if (noun) {
-                // v4.0.0: Load metadata and combine with noun to create HNSWNounWithMetadata
-                // FIX v4.7.4: Don't skip nouns without metadata - metadata is optional in v4.0.0
-                const metadata = await this.getNounMetadata(id);
-                // Apply filters if provided
-                if (options.filter && metadata) {
-                    // Filter by noun type
-                    if (options.filter.nounType) {
-                        const nounTypes = Array.isArray(options.filter.nounType)
-                            ? options.filter.nounType
-                            : [options.filter.nounType];
-                        if (!nounTypes.includes((metadata.type || metadata.noun))) {
-                            continue;
-                        }
-                    }
-                    // Filter by service
-                    if (options.filter.service) {
-                        const services = Array.isArray(options.filter.service)
-                            ? options.filter.service
-                            : [options.filter.service];
-                        if (!metadata.createdBy?.augmentation || !services.includes(metadata.createdBy.augmentation)) {
-                            continue;
-                        }
-                    }
-                    // Filter by metadata
-                    if (options.filter.metadata) {
-                        let matches = true;
-                        for (const [key, value] of Object.entries(options.filter.metadata)) {
-                            if (metadata[key] !== value) {
-                                matches = false;
-                                break;
-                            }
-                        }
-                        if (!matches)
-                            continue;
-                    }
-                }
-                // v4.8.0: Extract standard fields from metadata to top-level
-                const metadataObj = (metadata || {});
-                const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
-                const nounWithMetadata = {
-                    id: noun.id,
-                    vector: [...noun.vector],
-                    connections: new Map(noun.connections),
-                    level: noun.level || 0,
-                    type: nounType || NounType.Thing,
-                    createdAt: createdAt || Date.now(),
-                    updatedAt: updatedAt || Date.now(),
-                    confidence: confidence,
-                    weight: weight,
-                    service: service,
-                    data: data,
-                    createdBy,
-                    metadata: customMetadata
-                };
-                items.push(nounWithMetadata);
-            }
-        }
-        return {
-            items,
-            totalCount: this.totalNounCount,
-            hasMore: !!response.IsTruncated,
-            nextCursor: response.NextContinuationToken
-        };
-    }
-    async getNounsByNounType_internal(nounType) {
-        const result = await this.getNounsWithPagination({
-            limit: 10000,
-            filter: { nounType }
-        });
-        return result.items;
-    }
-    async getVerbsBySource_internal(sourceId) {
-        // Simplified - full implementation would include proper filtering
-        return [];
-    }
-    async getVerbsByTarget_internal(targetId) {
-        return [];
-    }
-    async getVerbsByType_internal(type) {
-        return [];
-    }
 }
 //# sourceMappingURL=r2Storage.js.map

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

@@ -3,7 +3,7 @@
  * Uses the AWS S3 client to interact with S3-compatible storage services
  * including Amazon S3, Cloudflare R2, and Google Cloud Storage
  */
-import { Change, HNSWNoun, HNSWVerb, HNSWNounWithMetadata, HNSWVerbWithMetadata, StatisticsData } from '../../coreTypes.js';
+import { Change, HNSWNoun, HNSWVerb, StatisticsData } from '../../coreTypes.js';
 import { BaseStorage, StorageBatchConfig } from '../baseStorage.js';
 import { OperationConfig } from '../../utils/operationUtils.js';
 type HNSWNode = HNSWNoun;
@@ -29,6 +29,12 @@ type Edge = HNSWVerb;
  * - credentials: GCS credentials (accessKeyId and secretAccessKey)
  * - endpoint: GCS endpoint (e.g., 'https://storage.googleapis.com')
  * - bucketName: GCS bucket name
+ *
+ * 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 S3CompatibleStorage extends BaseStorage {
     private s3Client;
@@ -75,6 +81,7 @@ export declare class S3CompatibleStorage extends BaseStorage {
     private nounCacheManager;
     private verbCacheManager;
     private logger;
+    private hnswLocks;
     /**
      * Initialize the storage adapter
      * @param options Configuration options for the S3-compatible storage
@@ -217,20 +224,10 @@ export declare class S3CompatibleStorage extends BaseStorage {
      * Get current batch size for operations
      */
     private getBatchSize;
-    /**
-     * Save a noun to storage (internal implementation)
-     */
-    protected saveNoun_internal(noun: HNSWNoun): Promise<void>;
     /**
      * Save a node to storage
      */
     protected saveNode(node: HNSWNode): Promise<void>;
-    /**
-     * 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
      */
@@ -274,44 +271,6 @@ export declare class S3CompatibleStorage extends BaseStorage {
      * Load nodes by IDs efficiently using cache or direct fetch
      */
     private loadNodesByIds;
-    /**
-     * Get nouns by noun type (internal implementation)
-     * @param nounType The noun type to filter by
-     * @returns Promise that resolves to an array of nouns of the specified noun type
-     */
-    protected getNounsByNounType_internal(nounType: string): Promise<HNSWNoun[]>;
-    /**
-     * Get nodes by noun type
-     * @param nounType The noun type to filter by
-     * @returns Promise that resolves to an array of nodes of the specified noun type
-     */
-    protected getNodesByNounType(nounType: string): Promise<HNSWNode[]>;
-    /**
-     * Delete a noun from storage (internal implementation)
-     */
-    protected deleteNoun_internal(id: string): Promise<void>;
-    /**
-     * Delete a node from storage
-     */
-    protected deleteNode(id: string): Promise<void>;
-    /**
-     * Save a verb to storage (internal implementation)
-     */
-    protected saveVerb_internal(verb: HNSWVerb): Promise<void>;
-    /**
-     * Save an edge to storage
-     */
-    protected saveEdge(edge: Edge): Promise<void>;
-    /**
-     * 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>;
     /**
      * Get all edges from storage
      * @deprecated This method is deprecated and will be removed in a future version.
@@ -344,47 +303,6 @@ export declare class S3CompatibleStorage extends BaseStorage {
      * @returns True if the edge matches the filter, false otherwise
      */
     private filterEdge;
-    /**
-     * Get verbs with pagination
-     * @param options Pagination options
-     * @returns Promise that resolves to a paginated result of verbs
-     */
-    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 verbs by source (internal implementation)
-     */
-    protected getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
-    /**
-     * Get verbs by target (internal implementation)
-     */
-    protected getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
-    /**
-     * Get verbs by type (internal implementation)
-     */
-    protected getVerbsByType_internal(type: string): Promise<HNSWVerbWithMetadata[]>;
-    /**
-     * Delete a verb from storage (internal implementation)
-     */
-    protected deleteVerb_internal(id: string): Promise<void>;
-    /**
-     * Delete an edge from storage
-     */
-    protected deleteEdge(id: string): Promise<void>;
     /**
      * Primitive operation: Write object to path
      * All metadata operations use this internally via base class routing
@@ -558,25 +476,6 @@ export declare class S3CompatibleStorage extends BaseStorage {
      * This method should be called periodically
      */
     private cleanupExpiredLocks;
-    /**
-     * Get nouns with pagination support
-     * @param options Pagination options
-     * @returns Promise that resolves to a paginated result of nouns
-     */
-    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;
-    }>;
     /**
      * Estimate total noun count by listing objects across all shards
      * This is more efficient than loading all nouns
@@ -605,11 +504,14 @@ export declare class S3CompatibleStorage extends BaseStorage {
     protected isCloudStorage(): boolean;
     /**
      * 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;
@@ -617,7 +519,7 @@ export declare class S3CompatibleStorage 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;