@soulcraft/brainy 4.9.1 → 4.10.0

package/dist/storage/adapters/azureBlobStorage.js

@@ -1332,44 +1332,69 @@ export class AzureBlobStorage extends BaseStorage {
      */
     async saveHNSWData(nounId, hnswData) {
         await this.ensureInitialized();
-        try {
-            // 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 blockBlobClient = this.containerClient.getBlockBlobClient(key);
+        // 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 ETags to prevent race conditions
+        // Uses Azure Blob ETags with ifMatch 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 blockBlobClient = this.containerClient.getBlockBlobClient(key);
+        const maxRetries = 5;
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
             try {
-                // Read existing node data
-                const downloadResponse = await blockBlobClient.download(0);
-                const existingData = await this.streamToBuffer(downloadResponse.readableStreamBody);
-                const existingNode = JSON.parse(existingData.toString());
+                // Get current ETag and data
+                let currentETag;
+                let existingNode = {};
+                try {
+                    const downloadResponse = await blockBlobClient.download(0);
+                    const existingData = await this.streamToBuffer(downloadResponse.readableStreamBody);
+                    existingNode = JSON.parse(existingData.toString());
+                    currentETag = downloadResponse.etag;
+                }
+                catch (error) {
+                    // File doesn't exist yet - will create new
+                    if (error.statusCode !== 404 && error.code !== 'BlobNotFound') {
+                        throw error;
+                    }
+                }
                 // Preserve id and vector, update only HNSW graph metadata
                 const updatedNode = {
-                    ...existingNode,
+                    ...existingNode, // Preserve all existing fields (id, vector, etc.)
                     level: hnswData.level,
                     connections: hnswData.connections
                 };
                 const content = JSON.stringify(updatedNode, null, 2);
+                // ATOMIC WRITE: Use ETag precondition
+                // If currentETag exists, only write if ETag matches (no concurrent modification)
+                // If no ETag, only write if blob doesn't exist (ifNoneMatch: *)
                 await blockBlobClient.upload(content, content.length, {
-                    blobHTTPHeaders: { blobContentType: 'application/json' }
+                    blobHTTPHeaders: { blobContentType: 'application/json' },
+                    conditions: currentETag
+                        ? { ifMatch: currentETag }
+                        : { ifNoneMatch: '*' } // Only create if doesn't exist
                 });
+                // Success! Exit retry loop
+                return;
             }
             catch (error) {
-                // If node doesn't exist yet, create it with just HNSW data
-                if (error.statusCode === 404 || error.code === 'BlobNotFound') {
-                    const content = JSON.stringify(hnswData, null, 2);
-                    await blockBlobClient.upload(content, content.length, {
-                        blobHTTPHeaders: { blobContentType: 'application/json' }
-                    });
-                }
-                else {
-                    throw error;
+                // Precondition failed - concurrent modification detected
+                if (error.statusCode === 412 || error.code === 'ConditionNotMet') {
+                    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}`);
             }
         }
-        catch (error) {
-            this.logger.error(`Failed to save HNSW data for ${nounId}:`, error);
-            throw new Error(`Failed to save HNSW data for ${nounId}: ${error}`);
-        }
     }
     /**
      * Get HNSW graph data for a noun
@@ -1394,20 +1419,54 @@ export class AzureBlobStorage extends BaseStorage {
     }
     /**
      * Save HNSW system data (entry point, max level)
+     *
+     * CRITICAL FIX (v4.10.1): Optimistic locking with ETags to prevent race conditions
      */
     async saveHNSWSystem(systemData) {
         await this.ensureInitialized();
-        try {
-            const key = `${this.systemPrefix}hnsw-system.json`;
-            const blockBlobClient = this.containerClient.getBlockBlobClient(key);
-            const content = JSON.stringify(systemData, null, 2);
-            await blockBlobClient.upload(content, content.length, {
-                blobHTTPHeaders: { blobContentType: 'application/json' }
-            });
-        }
-        catch (error) {
-            this.logger.error('Failed to save HNSW system data:', error);
-            throw new Error(`Failed to save HNSW system data: ${error}`);
+        const key = `${this.systemPrefix}hnsw-system.json`;
+        const blockBlobClient = this.containerClient.getBlockBlobClient(key);
+        const maxRetries = 5;
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+            try {
+                // Get current ETag
+                let currentETag;
+                try {
+                    const properties = await blockBlobClient.getProperties();
+                    currentETag = properties.etag;
+                }
+                catch (error) {
+                    // File doesn't exist yet
+                    if (error.statusCode !== 404 && error.code !== 'BlobNotFound') {
+                        throw error;
+                    }
+                }
+                const content = JSON.stringify(systemData, null, 2);
+                // ATOMIC WRITE: Use ETag precondition
+                await blockBlobClient.upload(content, content.length, {
+                    blobHTTPHeaders: { blobContentType: 'application/json' },
+                    conditions: currentETag
+                        ? { ifMatch: currentETag }
+                        : { ifNoneMatch: '*' }
+                });
+                // Success!
+                return;
+            }
+            catch (error) {
+                // Precondition failed - concurrent modification
+                if (error.statusCode === 412 || error.code === 'ConditionNotMet') {
+                    if (attempt === maxRetries - 1) {
+                        this.logger.error(`Max retries (${maxRetries}) exceeded for HNSW system data`);
+                        throw new Error('Failed to save HNSW system data: max retries exceeded due to concurrent modifications');
+                    }
+                    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 system data:', error);
+                throw new Error(`Failed to save HNSW system data: ${error}`);
+            }
         }
     }
     /**

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

@@ -391,6 +391,8 @@ export declare class FileSystemStorage extends BaseStorage {
     } | null>;
     /**
      * Save HNSW system data (entry point, max level)
+     *
+     * CRITICAL FIX (v4.10.1): Atomic write to prevent race conditions during concurrent updates
      */
     saveHNSWSystem(systemData: {
         entryPointId: string | null;

package/dist/storage/adapters/fileSystemStorage.js

@@ -2177,30 +2177,48 @@ export class FileSystemStorage extends BaseStorage {
         // 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): Atomic write to prevent race conditions during concurrent HNSW updates
+        // Uses temp file + atomic rename strategy (POSIX guarantees rename() atomicity)
+        // Prevents data corruption when multiple entities connect to same neighbor simultaneously
         const filePath = this.getNodePath(nounId);
+        const tempPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).substring(2)}`;
         try {
-            // Read existing node data
-            const existingData = await fs.promises.readFile(filePath, 'utf-8');
-            const existingNode = JSON.parse(existingData);
+            // Read existing node data (if exists)
+            let existingNode = {};
+            try {
+                const existingData = await fs.promises.readFile(filePath, 'utf-8');
+                existingNode = JSON.parse(existingData);
+            }
+            catch (error) {
+                // File doesn't exist yet - will create new
+                if (error.code !== 'ENOENT') {
+                    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
             };
-            // Write back the COMPLETE node with updated HNSW data
-            await fs.promises.writeFile(filePath, JSON.stringify(updatedNode, null, 2));
+            // ATOMIC WRITE SEQUENCE:
+            // 1. Write to temp file
+            await this.ensureDirectoryExists(path.dirname(tempPath));
+            await fs.promises.writeFile(tempPath, JSON.stringify(updatedNode, null, 2));
+            // 2. Atomic rename temp → final (POSIX atomicity guarantee)
+            // This operation is guaranteed atomic by POSIX - either succeeds completely or fails
+            // Multiple concurrent renames will serialize at the kernel level
+            await fs.promises.rename(tempPath, filePath);
         }
         catch (error) {
-            // If node doesn't exist yet, create it with just HNSW data
-            // This should only happen during initial node creation
-            if (error.code === 'ENOENT') {
-                await this.ensureDirectoryExists(path.dirname(filePath));
-                await fs.promises.writeFile(filePath, JSON.stringify(hnswData, null, 2));
+            // Clean up temp file on any error
+            try {
+                await fs.promises.unlink(tempPath);
             }
-            else {
-                throw error;
+            catch (cleanupError) {
+                // Ignore cleanup errors - temp file may not exist
             }
+            throw error;
         }
     }
     /**
@@ -2223,11 +2241,30 @@ export class FileSystemStorage extends BaseStorage {
     }
     /**
      * Save HNSW system data (entry point, max level)
+     *
+     * CRITICAL FIX (v4.10.1): Atomic write to prevent race conditions during concurrent updates
      */
     async saveHNSWSystem(systemData) {
         await this.ensureInitialized();
         const filePath = path.join(this.systemDir, 'hnsw-system.json');
-        await fs.promises.writeFile(filePath, JSON.stringify(systemData, null, 2));
+        const tempPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).substring(2)}`;
+        try {
+            // Write to temp file
+            await this.ensureDirectoryExists(path.dirname(tempPath));
+            await fs.promises.writeFile(tempPath, JSON.stringify(systemData, null, 2));
+            // Atomic rename temp → final (POSIX atomicity guarantee)
+            await fs.promises.rename(tempPath, filePath);
+        }
+        catch (error) {
+            // Clean up temp file on any error
+            try {
+                await fs.promises.unlink(tempPath);
+            }
+            catch (cleanupError) {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
     }
     /**
      * Get HNSW system data

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

@@ -381,6 +381,8 @@ export declare class GcsStorage extends BaseStorage {
     /**
      * Save HNSW system data (entry point, max level)
      * Storage path: system/hnsw-system.json
+     *
+     * CRITICAL FIX (v4.10.1): Optimistic locking with generation numbers to prevent race conditions
      */
     saveHNSWSystem(systemData: {
         entryPointId: string | null;

package/dist/storage/adapters/gcsStorage.js

@@ -1487,47 +1487,72 @@ export class GcsStorage extends BaseStorage {
      */
     async saveHNSWData(nounId, hnswData) {
         await this.ensureInitialized();
-        try {
-            // 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
-            const shard = getShardIdFromUuid(nounId);
-            const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
-            const file = this.bucket.file(key);
+        // 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 {
-                // Read existing node data
-                const [existingData] = await file.download();
-                const existingNode = JSON.parse(existingData.toString());
+                // 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
                 };
-                // Write back the COMPLETE node with updated HNSW data
+                // 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
+                    resumable: false,
+                    preconditionOpts: currentGeneration
+                        ? { ifGenerationMatch: currentGeneration }
+                        : { ifGenerationMatch: '0' } // Only create if doesn't exist
                 });
+                // Success! Exit retry loop
+                return;
             }
             catch (error) {
-                // If node doesn't exist yet, create it with just HNSW data
-                // This should only happen during initial node creation
-                if (error.code === 404) {
-                    await file.save(JSON.stringify(hnswData, null, 2), {
-                        contentType: 'application/json',
-                        resumable: false
-                    });
-                }
-                else {
-                    throw 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}`);
             }
         }
-        catch (error) {
-            this.logger.error(`Failed to save HNSW data for ${nounId}:`, error);
-            throw new Error(`Failed to save HNSW data for ${nounId}: ${error}`);
-        }
     }
     /**
      * Get HNSW graph data for a noun
@@ -1553,20 +1578,54 @@ export class GcsStorage extends BaseStorage {
     /**
      * Save HNSW system data (entry point, max level)
      * Storage path: system/hnsw-system.json
+     *
+     * CRITICAL FIX (v4.10.1): Optimistic locking with generation numbers to prevent race conditions
      */
     async saveHNSWSystem(systemData) {
         await this.ensureInitialized();
-        try {
-            const key = `${this.systemPrefix}hnsw-system.json`;
-            const file = this.bucket.file(key);
-            await file.save(JSON.stringify(systemData, null, 2), {
-                contentType: 'application/json',
-                resumable: false
-            });
-        }
-        catch (error) {
-            this.logger.error('Failed to save HNSW system data:', error);
-            throw new Error(`Failed to save HNSW system data: ${error}`);
+        const key = `${this.systemPrefix}hnsw-system.json`;
+        const file = this.bucket.file(key);
+        const maxRetries = 5;
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+            try {
+                // Get current generation
+                let currentGeneration;
+                try {
+                    const [metadata] = await file.getMetadata();
+                    currentGeneration = metadata.generation?.toString();
+                }
+                catch (error) {
+                    // File doesn't exist yet
+                    if (error.code !== 404) {
+                        throw error;
+                    }
+                }
+                // ATOMIC WRITE: Use generation precondition
+                await file.save(JSON.stringify(systemData, null, 2), {
+                    contentType: 'application/json',
+                    resumable: false,
+                    preconditionOpts: currentGeneration
+                        ? { ifGenerationMatch: currentGeneration }
+                        : { ifGenerationMatch: '0' }
+                });
+                // Success!
+                return;
+            }
+            catch (error) {
+                // Precondition failed - concurrent modification
+                if (error.code === 412) {
+                    if (attempt === maxRetries - 1) {
+                        this.logger.error(`Max retries (${maxRetries}) exceeded for HNSW system data`);
+                        throw new Error('Failed to save HNSW system data: max retries exceeded due to concurrent modifications');
+                    }
+                    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 system data:', error);
+                throw new Error(`Failed to save HNSW system data: ${error}`);
+            }
         }
     }
     /**

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

@@ -192,8 +192,13 @@ export declare class MemoryStorage extends BaseStorage {
      * Get vector for a noun
      */
     getNounVector(id: string): Promise<number[] | null>;
+    private hnswLocks;
     /**
      * Save HNSW graph data for a noun
+     *
+     * CRITICAL FIX (v4.10.1): Mutex locking to prevent race conditions during concurrent HNSW updates
+     * Even in-memory operations can race due to async/await interleaving
+     * Prevents data corruption when multiple entities connect to same neighbor simultaneously
      */
     saveHNSWData(nounId: string, hnswData: {
         level: number;
@@ -208,6 +213,8 @@ export declare class MemoryStorage extends BaseStorage {
     } | null>;
     /**
      * Save HNSW system data (entry point, max level)
+     *
+     * CRITICAL FIX (v4.10.1): Mutex locking to prevent race conditions
      */
     saveHNSWSystem(systemData: {
         entryPointId: string | null;

package/dist/storage/adapters/memoryStorage.js

@@ -28,6 +28,9 @@ export class MemoryStorage extends BaseStorage {
         this.statistics = null;
         // Unified object store for primitive operations (replaces metadata, nounMetadata, verbMetadata)
         this.objectStore = new Map();
+        // CRITICAL FIX (v4.10.1): Mutex locks for HNSW concurrency control
+        // Even in-memory operations need serialization to prevent async race conditions
+        this.hnswLocks = new Map();
     }
     /**
      * Initialize the storage adapter
@@ -668,13 +671,42 @@ export class MemoryStorage extends BaseStorage {
     }
     /**
      * Save HNSW graph data for a noun
+     *
+     * CRITICAL FIX (v4.10.1): Mutex locking to prevent race conditions during concurrent HNSW updates
+     * Even in-memory operations can race due to async/await interleaving
+     * Prevents data corruption when multiple entities connect to same neighbor simultaneously
      */
     async saveHNSWData(nounId, hnswData) {
-        // For memory storage, HNSW data is already in the noun object
-        // This method is a no-op since saveNoun already stores the full graph
-        // But we store it separately for consistency with other adapters
         const path = `hnsw/${nounId}.json`;
-        await this.writeObjectToPath(path, hnswData);
+        // MUTEX LOCK: Wait for any pending operations on this entity
+        while (this.hnswLocks.has(path)) {
+            await this.hnswLocks.get(path);
+        }
+        // Acquire lock by creating a promise that we'll resolve when done
+        let releaseLock;
+        const lockPromise = new Promise(resolve => { releaseLock = resolve; });
+        this.hnswLocks.set(path, lockPromise);
+        try {
+            // Read existing data (if exists)
+            let existingNode = {};
+            const existing = this.objectStore.get(path);
+            if (existing) {
+                existingNode = existing;
+            }
+            // Preserve id and vector, update only HNSW graph metadata
+            const updatedNode = {
+                ...existingNode, // Preserve all existing fields
+                level: hnswData.level,
+                connections: hnswData.connections
+            };
+            // Write atomically (in-memory, but now serialized by mutex)
+            this.objectStore.set(path, JSON.parse(JSON.stringify(updatedNode)));
+        }
+        finally {
+            // Release lock
+            this.hnswLocks.delete(path);
+            releaseLock();
+        }
     }
     /**
      * Get HNSW graph data for a noun
@@ -686,10 +718,28 @@ export class MemoryStorage extends BaseStorage {
     }
     /**
      * Save HNSW system data (entry point, max level)
+     *
+     * CRITICAL FIX (v4.10.1): Mutex locking to prevent race conditions
      */
     async saveHNSWSystem(systemData) {
         const path = 'system/hnsw-system.json';
-        await this.writeObjectToPath(path, systemData);
+        // MUTEX LOCK: Wait for any pending operations
+        while (this.hnswLocks.has(path)) {
+            await this.hnswLocks.get(path);
+        }
+        // Acquire lock
+        let releaseLock;
+        const lockPromise = new Promise(resolve => { releaseLock = resolve; });
+        this.hnswLocks.set(path, lockPromise);
+        try {
+            // Write atomically (serialized by mutex)
+            this.objectStore.set(path, JSON.parse(JSON.stringify(systemData)));
+        }
+        finally {
+            // Release lock
+            this.hnswLocks.delete(path);
+            releaseLock();
+        }
     }
     /**
      * Get HNSW system data

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

@@ -306,9 +306,14 @@ export declare class OPFSStorage extends BaseStorage {
      * Get a noun's vector for HNSW rebuild
      */
     getNounVector(id: string): Promise<number[] | null>;
+    private hnswLocks;
     /**
      * Save HNSW graph data for a noun
      * Storage path: nouns/hnsw/{shard}/{id}.json
+     *
+     * CRITICAL FIX (v4.10.1): Mutex locking to prevent race conditions during concurrent HNSW updates
+     * Browser is single-threaded but async operations can interleave - mutex prevents this
+     * Prevents data corruption when multiple entities connect to same neighbor simultaneously
      */
     saveHNSWData(nounId: string, hnswData: {
         level: number;
@@ -325,6 +330,8 @@ export declare class OPFSStorage extends BaseStorage {
     /**
      * Save HNSW system data (entry point, max level)
      * Storage path: index/hnsw-system.json
+     *
+     * CRITICAL FIX (v4.10.1): Mutex locking to prevent race conditions
      */
     saveHNSWSystem(systemData: {
         entryPointId: string | null;

package/dist/storage/adapters/opfsStorage.js

@@ -42,6 +42,9 @@ export class OPFSStorage extends BaseStorage {
         this.quotaCriticalThreshold = 0.95; // Critical at 95% usage
         this.lastQuotaCheck = 0;
         this.quotaCheckInterval = 60000; // Check every 60 seconds
+        // CRITICAL FIX (v4.10.1): Mutex locks for HNSW concurrency control
+        // Browser environments are single-threaded but async operations can still interleave
+        this.hnswLocks = new Map();
         // Check if OPFS is available
         this.isAvailable =
             typeof navigator !== 'undefined' &&
@@ -1708,9 +1711,22 @@ export class OPFSStorage extends BaseStorage {
     /**
      * Save HNSW graph data for a noun
      * Storage path: nouns/hnsw/{shard}/{id}.json
+     *
+     * CRITICAL FIX (v4.10.1): Mutex locking to prevent race conditions during concurrent HNSW updates
+     * Browser is single-threaded but async operations can interleave - mutex prevents this
+     * Prevents data corruption when multiple entities connect to same neighbor simultaneously
      */
     async saveHNSWData(nounId, hnswData) {
         await this.ensureInitialized();
+        const lockKey = `hnsw/${nounId}`;
+        // MUTEX LOCK: 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 {
             // CRITICAL FIX (v4.7.3): Must preserve existing node data (id, vector) when updating HNSW metadata
             const hnswDir = await this.nounsDir.getDirectoryHandle('hnsw', { create: true });
@@ -1743,6 +1759,11 @@ export class OPFSStorage extends BaseStorage {
             console.error(`Failed to save HNSW data for ${nounId}:`, error);
             throw new Error(`Failed to save HNSW data for ${nounId}: ${error}`);
         }
+        finally {
+            // Release lock
+            this.hnswLocks.delete(lockKey);
+            releaseLock();
+        }
     }
     /**
      * Get HNSW graph data for a noun
@@ -1774,9 +1795,20 @@ export class OPFSStorage extends BaseStorage {
     /**
      * Save HNSW system data (entry point, max level)
      * Storage path: index/hnsw-system.json
+     *
+     * CRITICAL FIX (v4.10.1): Mutex locking to prevent race conditions
      */
     async saveHNSWSystem(systemData) {
         await this.ensureInitialized();
+        const lockKey = 'system/hnsw-system';
+        // MUTEX LOCK: Wait for any 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 {
             // Create or get the file in the index directory
             const fileHandle = await this.indexDir.getFileHandle('hnsw-system.json', { create: true });
@@ -1789,6 +1821,11 @@ export class OPFSStorage extends BaseStorage {
             console.error('Failed to save HNSW system data:', error);
             throw new Error(`Failed to save HNSW system data: ${error}`);
         }
+        finally {
+            // Release lock
+            this.hnswLocks.delete(lockKey);
+            releaseLock();
+        }
     }
     /**
      * Get HNSW system data (entry point, max level)