@soulcraft/brainy 5.3.5 → 5.4.0

package/dist/storage/adapters/gcsStorage.js

@@ -8,7 +8,6 @@
  * 3. Service Account Credentials Object
  * 4. HMAC Keys (fallback for backward compatibility)
  */
-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';
@@ -16,7 +15,7 @@ import { createModuleLogger, prodLog } from '../../utils/logger.js';
 import { getGlobalBackpressure } from '../../utils/adaptiveBackpressure.js';
 import { getWriteBuffer } from '../../utils/writeBuffer.js';
 import { getCoalescer } from '../../utils/requestCoalescer.js';
-import { getShardIdFromUuid, getShardIdByIndex, TOTAL_SHARDS } from '../sharding.js';
+import { getShardIdFromUuid } from '../sharding.js';
 // GCS API limits
 // Maximum value for maxResults parameter in GCS API calls
 // Values above this cause "Invalid unsigned integer" errors
@@ -30,6 +29,12 @@ const MAX_GCS_PAGE_SIZE = 5000;
  * 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 class GcsStorage extends BaseStorage {
     /**
@@ -65,6 +70,8 @@ export class GcsStorage extends BaseStorage {
         this.forceHighVolumeMode = false; // Environment variable override
         // Module logger
         this.logger = createModuleLogger('GcsStorage');
+        // v5.4.0: HNSW mutex locks to prevent read-modify-write races
+        this.hnswLocks = new Map();
         // Configuration options
         this.skipInitialScan = false;
         this.skipCountsFile = false;
@@ -320,12 +327,7 @@ export class GcsStorage extends BaseStorage {
         });
         await Promise.all(writes);
     }
-    /**
-     * Save a noun to storage (internal implementation)
-     */
-    async saveNoun_internal(noun) {
-        return this.saveNode(noun);
-    }
+    // v5.4.0: Removed saveNoun_internal - now inherit from BaseStorage's type-first implementation
     /**
      * Save a node to storage
      */
@@ -396,20 +398,7 @@ export class GcsStorage 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;
-    }
+    // v5.4.0: Removed getNoun_internal - now inherit from BaseStorage's type-first implementation
     /**
      * Get a node from storage
      */
@@ -504,45 +493,7 @@ export class GcsStorage 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}`);
-            // Get the GCS key
-            const key = this.getNounKey(id);
-            // Delete from GCS
-            const file = this.bucket.file(key);
-            await file.delete();
-            // 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.code === 404) {
-                // Already deleted
-                this.logger.trace(`Noun ${id} not found (already deleted)`);
-                return;
-            }
-            // Handle throttling
-            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}`);
-        }
-    }
+    // v5.4.0: Removed deleteNoun_internal - now inherit from BaseStorage's type-first implementation
     /**
      * Write an object to a specific path in GCS
      * Primitive operation required by base class
@@ -631,12 +582,7 @@ export class GcsStorage extends BaseStorage {
             throw new Error(`Failed to list objects under ${prefix}: ${error}`);
         }
     }
-    /**
-     * Save a verb to storage (internal implementation)
-     */
-    async saveVerb_internal(verb) {
-        return this.saveEdge(verb);
-    }
+    // v5.4.0: Removed saveVerb_internal - now inherit from BaseStorage's type-first implementation
     /**
      * Save an edge to storage
      */
@@ -702,20 +648,7 @@ export class GcsStorage 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;
-    }
+    // v5.4.0: Removed getVerb_internal - now inherit from BaseStorage's type-first implementation
     /**
      * Get an edge from storage
      */
@@ -775,402 +708,12 @@ export class GcsStorage extends BaseStorage {
             throw BrainyError.fromError(error, `getVerb(${id})`);
         }
     }
-    /**
-     * Delete a verb from storage (internal implementation)
-     */
-    async deleteVerb_internal(id) {
-        await this.ensureInitialized();
-        const requestId = await this.applyBackpressure();
-        try {
-            this.logger.trace(`Deleting verb ${id}`);
-            // Get the GCS key
-            const key = this.getVerbKey(id);
-            // Delete from GCS
-            const file = this.bucket.file(key);
-            await file.delete();
-            // Remove from cache
-            this.verbCacheManager.delete(id);
-            // Decrement verb count
-            const metadata = await this.getVerbMetadata(id);
-            if (metadata && metadata.type) {
-                await this.decrementVerbCount(metadata.type);
-            }
-            this.logger.trace(`Verb ${id} deleted successfully`);
-            this.releaseBackpressure(true, requestId);
-        }
-        catch (error) {
-            this.releaseBackpressure(false, requestId);
-            if (error.code === 404) {
-                // Already deleted
-                this.logger.trace(`Verb ${id} not found (already deleted)`);
-                return;
-            }
-            if (this.isThrottlingError(error)) {
-                await this.handleThrottling(error);
-                throw error;
-            }
-            this.logger.error(`Failed to delete verb ${id}:`, error);
-            throw new Error(`Failed to delete verb ${id}: ${error}`);
-        }
-    }
-    /**
-     * Get nouns with pagination
-     * v4.0.0: Returns HNSWNounWithMetadata[] (includes metadata field)
-     * Iterates through all UUID-based shards (00-ff) for consistent pagination
-     */
-    async getNounsWithPagination(options = {}) {
-        await this.ensureInitialized();
-        const limit = options.limit || 100;
-        const cursor = options.cursor;
-        // Get paginated nodes
-        const result = await this.getNodesWithPagination({
-            limit,
-            cursor,
-            useCache: true
-        });
-        // v4.0.0: Combine nodes with metadata to create HNSWNounWithMetadata[]
-        const items = [];
-        for (const node of result.nodes) {
-            // FIX v4.7.4: Don't skip nouns without metadata - metadata is optional in v4.0.0
-            const metadata = await this.getNounMetadata(node.id);
-            // Apply filters if provided
-            if (options.filter) {
-                // Filter by noun type
-                if (options.filter.nounType) {
-                    const nounTypes = Array.isArray(options.filter.nounType)
-                        ? options.filter.nounType
-                        : [options.filter.nounType];
-                    const nounType = metadata.type || metadata.noun;
-                    if (!nounType || !nounTypes.includes(nounType)) {
-                        continue;
-                    }
-                }
-                // Filter by metadata fields if specified
-                if (options.filter.metadata) {
-                    let metadataMatch = true;
-                    for (const [key, value] of Object.entries(options.filter.metadata)) {
-                        const metadataValue = metadata[key];
-                        if (metadataValue !== value) {
-                            metadataMatch = false;
-                            break;
-                        }
-                    }
-                    if (!metadataMatch)
-                        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: node.id,
-                vector: [...node.vector],
-                connections: new Map(node.connections),
-                level: node.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: result.totalCount,
-            hasMore: result.hasMore,
-            nextCursor: result.nextCursor
-        };
-    }
-    /**
-     * Get nodes with pagination (internal implementation)
-     * Iterates through UUID-based shards for consistent pagination
-     */
-    async getNodesWithPagination(options) {
-        await this.ensureInitialized(); // CRITICAL: Must initialize before using this.bucket
-        const limit = options.limit || 100;
-        const useCache = options.useCache !== false;
-        try {
-            const nodes = [];
-            // Parse cursor (format: "shardIndex:gcsPageToken")
-            let startShardIndex = 0;
-            let gcsPageToken;
-            if (options.cursor) {
-                const parts = options.cursor.split(':', 2);
-                startShardIndex = parseInt(parts[0]) || 0;
-                gcsPageToken = parts[1] || undefined;
-            }
-            // Iterate through shards starting from cursor position
-            for (let shardIndex = startShardIndex; shardIndex < TOTAL_SHARDS; shardIndex++) {
-                const shardId = getShardIdByIndex(shardIndex);
-                const shardPrefix = `${this.nounPrefix}${shardId}/`;
-                // List objects in this shard
-                // Cap maxResults to GCS API limit to prevent "Invalid unsigned integer" errors
-                const requestedPageSize = limit - nodes.length;
-                const cappedPageSize = Math.min(requestedPageSize, MAX_GCS_PAGE_SIZE);
-                const [files, , response] = await this.bucket.getFiles({
-                    prefix: shardPrefix,
-                    maxResults: cappedPageSize,
-                    pageToken: shardIndex === startShardIndex ? gcsPageToken : undefined
-                });
-                // Extract node IDs from file names
-                if (files && files.length > 0) {
-                    const nodeIds = files
-                        .filter((file) => file && file.name)
-                        .map((file) => {
-                        // Extract UUID from: entities/nouns/vectors/ab/ab123456-uuid.json
-                        let name = file.name;
-                        if (name.startsWith(shardPrefix)) {
-                            name = name.substring(shardPrefix.length);
-                        }
-                        if (name.endsWith('.json')) {
-                            name = name.substring(0, name.length - 5);
-                        }
-                        return name;
-                    })
-                        .filter((id) => id && id.length > 0);
-                    // Load nodes
-                    for (const id of nodeIds) {
-                        const node = await this.getNode(id);
-                        if (node) {
-                            nodes.push(node);
-                        }
-                        if (nodes.length >= limit) {
-                            break;
-                        }
-                    }
-                }
-                // Check if we have enough nodes or if there are more files in current shard
-                if (nodes.length >= limit) {
-                    const nextCursor = response?.nextPageToken
-                        ? `${shardIndex}:${response.nextPageToken}`
-                        : shardIndex + 1 < TOTAL_SHARDS
-                            ? `${shardIndex + 1}:`
-                            : undefined;
-                    return {
-                        nodes,
-                        totalCount: this.totalNounCount,
-                        hasMore: !!nextCursor,
-                        nextCursor
-                    };
-                }
-                // If this shard has more pages, create cursor for next page
-                if (response?.nextPageToken) {
-                    return {
-                        nodes,
-                        totalCount: this.totalNounCount,
-                        hasMore: true,
-                        nextCursor: `${shardIndex}:${response.nextPageToken}`
-                    };
-                }
-                // Continue to next shard
-            }
-            // No more shards or nodes
-            return {
-                nodes,
-                totalCount: this.totalNounCount,
-                hasMore: false,
-                nextCursor: undefined
-            };
-        }
-        catch (error) {
-            this.logger.error('Error in getNodesWithPagination:', error);
-            throw new Error(`Failed to get nodes with pagination: ${error}`);
-        }
-    }
-    /**
-     * Get nouns by noun type (internal implementation)
-     */
-    async getNounsByNounType_internal(nounType) {
-        const result = await this.getNounsWithPagination({
-            limit: 10000, // Large limit for backward compatibility
-            filter: { nounType }
-        });
-        return result.items;
-    }
-    /**
-     * Get verbs by source ID (internal implementation)
-     */
-    async getVerbsBySource_internal(sourceId) {
-        // Use the paginated approach to properly handle HNSWVerb to GraphVerb conversion
-        const result = await this.getVerbsWithPagination({
-            limit: Number.MAX_SAFE_INTEGER,
-            filter: { sourceId: [sourceId] }
-        });
-        return result.items;
-    }
-    /**
-     * Get verbs by target ID (internal implementation)
-     */
-    async getVerbsByTarget_internal(targetId) {
-        // Use the paginated approach to properly handle HNSWVerb to GraphVerb conversion
-        const result = await this.getVerbsWithPagination({
-            limit: Number.MAX_SAFE_INTEGER,
-            filter: { targetId: [targetId] }
-        });
-        return result.items;
-    }
-    /**
-     * Get verbs by type (internal implementation)
-     */
-    async getVerbsByType_internal(type) {
-        // Use the paginated approach to properly handle HNSWVerb to GraphVerb conversion
-        const result = await this.getVerbsWithPagination({
-            limit: Number.MAX_SAFE_INTEGER,
-            filter: { verbType: type }
-        });
-        return result.items;
-    }
-    /**
-     * Get verbs with pagination
-     * v4.0.0: Returns HNSWVerbWithMetadata[] (includes metadata field)
-     */
-    async getVerbsWithPagination(options = {}) {
-        await this.ensureInitialized();
-        const limit = options.limit || 100;
-        try {
-            // List verbs (simplified - not sharded yet in original implementation)
-            // Cap maxResults to GCS API limit to prevent "Invalid unsigned integer" errors
-            const cappedLimit = Math.min(limit, MAX_GCS_PAGE_SIZE);
-            const [files, , response] = await this.bucket.getFiles({
-                prefix: this.verbPrefix,
-                maxResults: cappedLimit,
-                pageToken: options.cursor
-            });
-            // If no files, return empty result
-            if (!files || files.length === 0) {
-                return {
-                    items: [],
-                    totalCount: 0,
-                    hasMore: false,
-                    nextCursor: undefined
-                };
-            }
-            // Extract verb IDs and load verbs as HNSW verbs
-            const hnswVerbs = [];
-            for (const file of files) {
-                if (!file.name)
-                    continue;
-                // Extract UUID from path
-                let name = file.name;
-                if (name.startsWith(this.verbPrefix)) {
-                    name = name.substring(this.verbPrefix.length);
-                }
-                if (name.endsWith('.json')) {
-                    name = name.substring(0, name.length - 5);
-                }
-                const verb = await this.getEdge(name);
-                if (verb) {
-                    hnswVerbs.push(verb);
-                }
-            }
-            // v4.0.0: Combine HNSWVerbs with metadata to create HNSWVerbWithMetadata[]
-            const items = [];
-            for (const hnswVerb of hnswVerbs) {
-                const metadata = await this.getVerbMetadata(hnswVerb.id);
-                // Apply filters
-                if (options.filter) {
-                    // v4.0.0: Core fields (verb, sourceId, targetId) are in HNSWVerb structure
-                    if (options.filter.sourceId) {
-                        const sourceIds = Array.isArray(options.filter.sourceId)
-                            ? options.filter.sourceId
-                            : [options.filter.sourceId];
-                        if (!hnswVerb.sourceId || !sourceIds.includes(hnswVerb.sourceId)) {
-                            continue;
-                        }
-                    }
-                    if (options.filter.targetId) {
-                        const targetIds = Array.isArray(options.filter.targetId)
-                            ? options.filter.targetId
-                            : [options.filter.targetId];
-                        if (!hnswVerb.targetId || !targetIds.includes(hnswVerb.targetId)) {
-                            continue;
-                        }
-                    }
-                    if (options.filter.verbType) {
-                        const verbTypes = Array.isArray(options.filter.verbType)
-                            ? options.filter.verbType
-                            : [options.filter.verbType];
-                        if (!hnswVerb.verb || !verbTypes.includes(hnswVerb.verb)) {
-                            continue;
-                        }
-                    }
-                    // Filter by metadata fields if specified
-                    if (options.filter.metadata && metadata) {
-                        let metadataMatch = true;
-                        for (const [key, value] of Object.entries(options.filter.metadata)) {
-                            const metadataValue = metadata[key];
-                            if (metadataValue !== value) {
-                                metadataMatch = false;
-                                break;
-                            }
-                        }
-                        if (!metadataMatch)
-                            continue;
-                    }
-                }
-                // v4.8.0: Extract standard fields from metadata to top-level
-                const metadataObj = (metadata || {});
-                const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
-                const verbWithMetadata = {
-                    id: hnswVerb.id,
-                    vector: [...hnswVerb.vector],
-                    connections: new Map(hnswVerb.connections),
-                    verb: hnswVerb.verb,
-                    sourceId: hnswVerb.sourceId,
-                    targetId: hnswVerb.targetId,
-                    createdAt: createdAt || Date.now(),
-                    updatedAt: updatedAt || Date.now(),
-                    confidence: confidence,
-                    weight: weight,
-                    service: service,
-                    data: data,
-                    createdBy,
-                    metadata: customMetadata
-                };
-                items.push(verbWithMetadata);
-            }
-            return {
-                items,
-                totalCount: this.totalVerbCount,
-                hasMore: !!response?.nextPageToken,
-                nextCursor: response?.nextPageToken
-            };
-        }
-        catch (error) {
-            this.logger.error('Error in getVerbsWithPagination:', error);
-            throw new Error(`Failed to get verbs with pagination: ${error}`);
-        }
-    }
-    /**
-     * Get nouns with filtering and pagination (public API)
-     */
-    async getNouns(options) {
-        const limit = options?.pagination?.limit || 100;
-        const cursor = options?.pagination?.cursor;
-        return this.getNounsWithPagination({
-            limit,
-            cursor,
-            filter: options?.filter
-        });
-    }
-    /**
-     * Get verbs with filtering and pagination (public API)
-     * v4.0.0: Returns HNSWVerbWithMetadata[] (includes metadata field)
-     */
-    async getVerbs(options) {
-        const limit = options?.pagination?.limit || 100;
-        const cursor = options?.pagination?.cursor;
-        return this.getVerbsWithPagination({
-            limit,
-            cursor,
-            filter: options?.filter
-        });
-    }
+    // v5.4.0: Removed deleteVerb_internal - now inherit from BaseStorage's type-first implementation
+    // v5.4.0: Removed pagination overrides - use BaseStorage's type-first implementation
+    // - getNounsWithPagination, getNodesWithPagination, getVerbsWithPagination
+    // - getNouns, getVerbs (public wrappers)
+    // v5.4.0: Removed 4 query *_internal methods - now inherit from BaseStorage's type-first implementation
+    // (getNounsByNounType_internal, getVerbsBySource_internal, getVerbsByTarget_internal, getVerbsByType_internal)
     /**
      * Batch fetch metadata for multiple noun IDs (efficient for large queries)
      * Uses smaller batches to prevent GCS socket exhaustion
@@ -1501,105 +1044,84 @@ export class GcsStorage extends BaseStorage {
     // HNSW Index Persistence (v3.35.0+)
     /**
      * Get a noun's vector for HNSW rebuild
+     * v5.4.0: Uses BaseStorage's getNoun (type-first paths)
      */
     async getNounVector(id) {
-        await this.ensureInitialized();
-        const noun = await this.getNode(id);
+        const noun = await this.getNoun(id);
         return noun ? noun.vector : 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
      */
     async saveHNSWData(nounId, hnswData) {
-        await this.ensureInitialized();
-        // CRITICAL FIX (v4.7.3): Must preserve existing node data (id, vector) when updating HNSW metadata
-        // Previous implementation overwrote the entire file, destroying vector data
-        // Now we READ the existing node, UPDATE only connections/level, then WRITE back the complete node
-        // CRITICAL FIX (v4.10.1): Optimistic locking with generation numbers to prevent race conditions
-        // Uses GCS generation preconditions - retries with exponential backoff on conflicts
-        // Prevents data corruption when multiple entities connect to same neighbor simultaneously
-        const shard = getShardIdFromUuid(nounId);
-        const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
-        const file = this.bucket.file(key);
-        const maxRetries = 5;
-        for (let attempt = 0; attempt < maxRetries; attempt++) {
-            try {
-                // Get current generation and data
-                let currentGeneration;
-                let existingNode = {};
-                try {
-                    // Download file and get metadata in parallel
-                    const [data, metadata] = await Promise.all([
-                        file.download(),
-                        file.getMetadata()
-                    ]);
-                    existingNode = JSON.parse(data[0].toString('utf-8'));
-                    currentGeneration = metadata[0].generation?.toString();
-                }
-                catch (error) {
-                    // File doesn't exist yet - will create new
-                    if (error.code !== 404) {
-                        throw error;
-                    }
-                }
-                // Preserve id and vector, update only HNSW graph metadata
-                const updatedNode = {
-                    ...existingNode, // Preserve all existing fields (id, vector, etc.)
-                    level: hnswData.level,
-                    connections: hnswData.connections
-                };
-                // ATOMIC WRITE: Use generation precondition
-                // If currentGeneration exists, only write if generation matches (no concurrent modification)
-                // If no generation, only write if file doesn't exist (ifGenerationMatch: 0)
-                await file.save(JSON.stringify(updatedNode, null, 2), {
-                    contentType: 'application/json',
-                    resumable: false,
-                    preconditionOpts: currentGeneration
-                        ? { ifGenerationMatch: currentGeneration }
-                        : { ifGenerationMatch: '0' } // Only create if doesn't exist
-                });
-                // Success! Exit retry loop
-                return;
+        const lockKey = `hnsw/${nounId}`;
+        // CRITICAL FIX (v4.10.1): Mutex lock to prevent read-modify-write races
+        // Problem: Without mutex, concurrent operations can:
+        //   1. Thread A reads noun (connections: [1,2,3])
+        //   2. Thread B reads noun (connections: [1,2,3])
+        //   3. Thread A adds connection 4, writes [1,2,3,4]
+        //   4. Thread B adds connection 5, writes [1,2,3,5] ← Connection 4 LOST!
+        // Solution: Mutex serializes operations per entity (like FileSystem/OPFS adapters)
+        // Production scale: Prevents corruption at 1000+ concurrent operations
+        // Wait for any pending operations on this entity
+        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 {
+            // v5.4.0: Use BaseStorage's getNoun (type-first paths)
+            // Read existing noun data (if exists)
+            const existingNoun = await this.getNoun(nounId);
+            if (!existingNoun) {
+                // Noun doesn't exist - cannot update HNSW data for non-existent noun
+                throw new Error(`Cannot save HNSW data: noun ${nounId} not found`);
             }
-            catch (error) {
-                // Precondition failed (412) - concurrent modification detected
-                if (error.code === 412) {
-                    if (attempt === maxRetries - 1) {
-                        this.logger.error(`Max retries (${maxRetries}) exceeded for ${nounId} - concurrent modification conflict`);
-                        throw new Error(`Failed to save HNSW data for ${nounId}: max retries exceeded due to concurrent modifications`);
-                    }
-                    // Exponential backoff: 50ms, 100ms, 200ms, 400ms, 800ms
-                    const backoffMs = 50 * Math.pow(2, attempt);
-                    await new Promise(resolve => setTimeout(resolve, backoffMs));
-                    continue;
-                }
-                // Other error - rethrow
-                this.logger.error(`Failed to save HNSW data for ${nounId}:`, error);
-                throw new Error(`Failed to save HNSW data for ${nounId}: ${error}`);
+            // Convert connections from Record to Map format for storage
+            const connectionsMap = new Map();
+            for (const [level, nodeIds] of Object.entries(hnswData.connections)) {
+                connectionsMap.set(Number(level), new Set(nodeIds));
             }
+            // Preserve id and vector, update only HNSW graph metadata
+            const updatedNoun = {
+                ...existingNoun,
+                level: hnswData.level,
+                connections: connectionsMap
+            };
+            // v5.4.0: Use BaseStorage's saveNoun (type-first paths, atomic write via writeObjectToBranch)
+            await this.saveNoun(updatedNoun);
+        }
+        finally {
+            // Release lock (ALWAYS runs, even if error thrown)
+            this.hnswLocks.delete(lockKey);
+            releaseLock();
         }
     }
     /**
      * 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)
      */
     async getHNSWData(nounId) {
-        await this.ensureInitialized();
-        try {
-            const shard = getShardIdFromUuid(nounId);
-            const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
-            const file = this.bucket.file(key);
-            const [contents] = await file.download();
-            return JSON.parse(contents.toString());
+        const noun = await this.getNoun(nounId);
+        if (!noun) {
+            return null;
         }
-        catch (error) {
-            if (error.code === 404) {
-                return null;
+        // Convert connections from Map to Record format
+        const connectionsRecord = {};
+        if (noun.connections) {
+            for (const [level, nodeIds] of noun.connections.entries()) {
+                connectionsRecord[String(level)] = Array.from(nodeIds);
             }
-            this.logger.error(`Failed to get HNSW data for ${nounId}:`, error);
-            throw new Error(`Failed to get HNSW data for ${nounId}: ${error}`);
         }
+        return {
+            level: noun.level || 0,
+            connections: connectionsRecord
+        };
     }
     /**
      * Save HNSW system data (entry point, max level)