@soulcraft/brainy 4.7.1 → 4.7.3

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [4.7.3](https://github.com/soulcraftlabs/brainy/compare/v4.7.2...v4.7.3) (2025-10-27)
+
+- fix(storage): CRITICAL - preserve vectors when updating HNSW connections (v4.7.3) (46e7482)
+
+
 ### [4.4.0](https://github.com/soulcraftlabs/brainy/compare/v4.3.2...v4.4.0) (2025-10-24)
 
 - docs: update CHANGELOG for v4.4.0 release (a3c8a28)

package/dist/storage/adapters/azureBlobStorage.js

@@ -1275,13 +1275,38 @@ 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);
-            const content = JSON.stringify(hnswData, null, 2);
-            await blockBlobClient.upload(content, content.length, {
-                blobHTTPHeaders: { blobContentType: 'application/json' }
-            });
+            try {
+                // Read existing node data
+                const downloadResponse = await blockBlobClient.download(0);
+                const existingData = await this.streamToBuffer(downloadResponse.readableStreamBody);
+                const existingNode = JSON.parse(existingData.toString());
+                // Preserve id and vector, update only HNSW graph metadata
+                const updatedNode = {
+                    ...existingNode,
+                    level: hnswData.level,
+                    connections: hnswData.connections
+                };
+                const content = JSON.stringify(updatedNode, null, 2);
+                await blockBlobClient.upload(content, content.length, {
+                    blobHTTPHeaders: { blobContentType: 'application/json' }
+                });
+            }
+            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;
+                }
+            }
         }
         catch (error) {
             this.logger.error(`Failed to save HNSW data for ${nounId}:`, error);

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

@@ -24,7 +24,6 @@ export declare class FileSystemStorage extends BaseStorage {
     private indexDir;
     private systemDir;
     private lockDir;
-    private useDualWrite;
     private activeLocks;
     private lockTimers;
     private allTimers;
@@ -262,17 +261,9 @@ export declare class FileSystemStorage extends BaseStorage {
      */
     protected getStatisticsData(): Promise<StatisticsData | null>;
     /**
-     * Save statistics with backward compatibility (dual write)
+     * Save statistics to storage
      */
     private saveStatisticsWithBackwardCompat;
-    /**
-     * Get statistics with backward compatibility (dual read)
-     */
-    private getStatisticsWithBackwardCompat;
-    /**
-     * Merge statistics from multiple sources
-     */
-    private mergeStatistics;
     /**
      * Initialize counts from filesystem storage
      */

package/dist/storage/adapters/fileSystemStorage.js

@@ -2,8 +2,7 @@
  * File System Storage Adapter
  * File system storage adapter for Node.js environments
  */
-import { BaseStorage, NOUNS_DIR, VERBS_DIR, METADATA_DIR, NOUN_METADATA_DIR, VERB_METADATA_DIR, INDEX_DIR, SYSTEM_DIR, STATISTICS_KEY } from '../baseStorage.js';
-import { StorageCompatibilityLayer } from '../backwardCompatibility.js';
+import { BaseStorage, SYSTEM_DIR, STATISTICS_KEY } from '../baseStorage.js';
 // Node.js modules - dynamically imported to avoid issues in browser environments
 let fs;
 let path;
@@ -50,7 +49,6 @@ export class FileSystemStorage extends BaseStorage {
         this.SHARDING_DEPTH = 1;
         this.MAX_SHARDS = 256; // Hex range: 00-ff
         this.cachedShardingDepth = this.SHARDING_DEPTH; // Always use fixed depth
-        this.useDualWrite = true; // Write to both locations during migration
         this.activeLocks = new Set();
         this.lockTimers = new Map(); // Track timers for cleanup
         this.allTimers = new Set(); // Track all timers for cleanup
@@ -89,13 +87,14 @@ export class FileSystemStorage extends BaseStorage {
         }
         try {
             // Initialize directory paths now that path module is loaded
-            this.nounsDir = path.join(this.rootDir, NOUNS_DIR);
-            this.verbsDir = path.join(this.rootDir, VERBS_DIR);
-            this.metadataDir = path.join(this.rootDir, METADATA_DIR);
-            this.nounMetadataDir = path.join(this.rootDir, NOUN_METADATA_DIR);
-            this.verbMetadataDir = path.join(this.rootDir, VERB_METADATA_DIR);
-            this.indexDir = path.join(this.rootDir, INDEX_DIR); // Legacy
-            this.systemDir = path.join(this.rootDir, SYSTEM_DIR); // New
+            // Clean directory structure (v4.7.2+)
+            this.nounsDir = path.join(this.rootDir, 'entities/nouns/hnsw');
+            this.verbsDir = path.join(this.rootDir, 'entities/verbs/hnsw');
+            this.metadataDir = path.join(this.rootDir, 'entities/nouns/metadata'); // Legacy reference
+            this.nounMetadataDir = path.join(this.rootDir, 'entities/nouns/metadata');
+            this.verbMetadataDir = path.join(this.rootDir, 'entities/verbs/metadata');
+            this.indexDir = path.join(this.rootDir, 'indexes');
+            this.systemDir = path.join(this.rootDir, SYSTEM_DIR);
             this.lockDir = path.join(this.rootDir, 'locks');
             // Create the root directory if it doesn't exist
             await this.ensureDirectoryExists(this.rootDir);
@@ -1351,7 +1350,7 @@ export class FileSystemStorage extends BaseStorage {
         }
         try {
             // Get existing statistics to merge with new data
-            const existingStats = await this.getStatisticsWithBackwardCompat();
+            const existingStats = await this.getStatisticsData();
             if (existingStats) {
                 // Merge statistics data
                 const mergedStats = {
@@ -1386,122 +1385,25 @@ export class FileSystemStorage extends BaseStorage {
      * Get statistics data from storage
      */
     async getStatisticsData() {
-        return this.getStatisticsWithBackwardCompat();
-    }
-    /**
-     * Save statistics with backward compatibility (dual write)
-     */
-    async saveStatisticsWithBackwardCompat(statistics) {
-        // Always write to new location
-        const newPath = path.join(this.systemDir, `${STATISTICS_KEY}.json`);
-        await this.ensureDirectoryExists(this.systemDir);
-        await fs.promises.writeFile(newPath, JSON.stringify(statistics, null, 2));
-        // During migration period, also write to old location if it exists
-        if (this.useDualWrite && await this.directoryExists(this.indexDir)) {
-            const oldPath = path.join(this.indexDir, `${STATISTICS_KEY}.json`);
-            try {
-                await fs.promises.writeFile(oldPath, JSON.stringify(statistics, null, 2));
-            }
-            catch (error) {
-                // Log but don't fail if old location write fails
-                StorageCompatibilityLayer.logMigrationEvent('Failed to write to legacy location', { path: oldPath, error });
-            }
-        }
-    }
-    /**
-     * Get statistics with backward compatibility (dual read)
-     */
-    async getStatisticsWithBackwardCompat() {
-        let newStats = null;
-        let oldStats = null;
-        // Try to read from new location first
         try {
-            const newPath = path.join(this.systemDir, `${STATISTICS_KEY}.json`);
-            const data = await fs.promises.readFile(newPath, 'utf-8');
-            newStats = JSON.parse(data);
+            const statsPath = path.join(this.systemDir, `${STATISTICS_KEY}.json`);
+            const data = await fs.promises.readFile(statsPath, 'utf-8');
+            return JSON.parse(data);
         }
         catch (error) {
             if (error.code !== 'ENOENT') {
-                console.error('Error reading statistics from new location:', error);
-            }
-        }
-        // Try to read from old location as fallback
-        if (!newStats && await this.directoryExists(this.indexDir)) {
-            try {
-                const oldPath = path.join(this.indexDir, `${STATISTICS_KEY}.json`);
-                const data = await fs.promises.readFile(oldPath, 'utf-8');
-                oldStats = JSON.parse(data);
-                // If we found data in old location but not new, migrate it
-                if (oldStats && !newStats) {
-                    StorageCompatibilityLayer.logMigrationEvent('Migrating statistics from legacy location');
-                    await this.saveStatisticsWithBackwardCompat(oldStats);
-                }
-            }
-            catch (error) {
-                if (error.code !== 'ENOENT') {
-                    console.error('Error reading statistics from old location:', error);
-                }
+                console.error('Error reading statistics:', error);
             }
+            return null;
         }
-        // Merge statistics from both locations
-        return this.mergeStatistics(newStats, oldStats);
     }
     /**
-     * Merge statistics from multiple sources
+     * Save statistics to storage
      */
-    mergeStatistics(storageStats, localStats) {
-        // Handle null cases
-        if (!storageStats && !localStats) {
-            // CRITICAL FIX (v3.37.4): Statistics files don't exist yet (first init)
-            // Return minimal stats with counts instead of zeros
-            // This prevents HNSW from seeing entityCount=0 during index rebuild
-            return {
-                nounCount: {},
-                verbCount: {},
-                metadataCount: {},
-                hnswIndexSize: 0,
-                totalNodes: this.totalNounCount,
-                totalEdges: this.totalVerbCount,
-                totalMetadata: 0,
-                lastUpdated: new Date().toISOString()
-            };
-        }
-        if (!storageStats)
-            return localStats;
-        if (!localStats)
-            return storageStats;
-        // Merge noun counts by taking the maximum of each type
-        const mergedNounCount = {
-            ...storageStats.nounCount
-        };
-        for (const [type, count] of Object.entries(localStats.nounCount)) {
-            mergedNounCount[type] = Math.max(mergedNounCount[type] || 0, count);
-        }
-        // Merge verb counts by taking the maximum of each type
-        const mergedVerbCount = {
-            ...storageStats.verbCount
-        };
-        for (const [type, count] of Object.entries(localStats.verbCount)) {
-            mergedVerbCount[type] = Math.max(mergedVerbCount[type] || 0, count);
-        }
-        // Merge metadata counts by taking the maximum of each type
-        const mergedMetadataCount = {
-            ...storageStats.metadataCount
-        };
-        for (const [type, count] of Object.entries(localStats.metadataCount)) {
-            mergedMetadataCount[type] = Math.max(mergedMetadataCount[type] || 0, count);
-        }
-        return {
-            nounCount: mergedNounCount,
-            verbCount: mergedVerbCount,
-            metadataCount: mergedMetadataCount,
-            hnswIndexSize: Math.max(storageStats.hnswIndexSize || 0, localStats.hnswIndexSize || 0),
-            totalNodes: Math.max(storageStats.totalNodes || 0, localStats.totalNodes || 0),
-            totalEdges: Math.max(storageStats.totalEdges || 0, localStats.totalEdges || 0),
-            totalMetadata: Math.max(storageStats.totalMetadata || 0, localStats.totalMetadata || 0),
-            operations: storageStats.operations || localStats.operations,
-            lastUpdated: new Date().toISOString()
-        };
+    async saveStatisticsWithBackwardCompat(statistics) {
+        const statsPath = path.join(this.systemDir, `${STATISTICS_KEY}.json`);
+        await this.ensureDirectoryExists(this.systemDir);
+        await fs.promises.writeFile(statsPath, JSON.stringify(statistics, null, 2));
     }
     // =============================================
     // Count Management for O(1) Scalability
@@ -2254,12 +2156,34 @@ export class FileSystemStorage extends BaseStorage {
      */
     async saveHNSWData(nounId, hnswData) {
         await this.ensureInitialized();
-        // Use sharded path for HNSW data
-        const shard = nounId.substring(0, 2).toLowerCase();
-        const hnswDir = path.join(this.rootDir, 'entities', 'nouns', 'hnsw', shard);
-        await this.ensureDirectoryExists(hnswDir);
-        const filePath = path.join(hnswDir, `${nounId}.json`);
-        await fs.promises.writeFile(filePath, JSON.stringify(hnswData, null, 2));
+        // 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 filePath = this.getNodePath(nounId);
+        try {
+            // Read existing node data
+            const existingData = await fs.promises.readFile(filePath, 'utf-8');
+            const existingNode = JSON.parse(existingData);
+            // 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));
+        }
+        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));
+            }
+            else {
+                throw error;
+            }
+        }
     }
     /**
      * Get HNSW graph data for a noun

package/dist/storage/adapters/gcsStorage.js

@@ -1469,14 +1469,41 @@ export class GcsStorage extends BaseStorage {
     async saveHNSWData(nounId, hnswData) {
         await this.ensureInitialized();
         try {
-            // Use sharded path for HNSW data
+            // 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);
-            await file.save(JSON.stringify(hnswData, null, 2), {
-                contentType: 'application/json',
-                resumable: false
-            });
+            try {
+                // Read existing node data
+                const [existingData] = await file.download();
+                const existingNode = JSON.parse(existingData.toString());
+                // 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 file.save(JSON.stringify(updatedNode, null, 2), {
+                    contentType: 'application/json',
+                    resumable: false
+                });
+            }
+            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;
+                }
+            }
         }
         catch (error) {
             this.logger.error(`Failed to save HNSW data for ${nounId}:`, error);

package/dist/storage/adapters/opfsStorage.js

@@ -1693,17 +1693,32 @@ export class OPFSStorage extends BaseStorage {
     async saveHNSWData(nounId, hnswData) {
         await this.ensureInitialized();
         try {
-            // Get or create the hnsw directory under nouns
+            // 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 });
-            // Use sharded path for HNSW data
             const shard = getShardIdFromUuid(nounId);
             const shardDir = await hnswDir.getDirectoryHandle(shard, { create: true });
-            // Create or get the file in the shard directory
             const fileHandle = await shardDir.getFileHandle(`${nounId}.json`, { create: true });
-            // Write the HNSW data to the file
-            const writable = await fileHandle.createWritable();
-            await writable.write(JSON.stringify(hnswData, null, 2));
-            await writable.close();
+            try {
+                // Read existing node data
+                const file = await fileHandle.getFile();
+                const existingData = await file.text();
+                const existingNode = JSON.parse(existingData);
+                // Preserve id and vector, update only HNSW graph metadata
+                const updatedNode = {
+                    ...existingNode,
+                    level: hnswData.level,
+                    connections: hnswData.connections
+                };
+                const writable = await fileHandle.createWritable();
+                await writable.write(JSON.stringify(updatedNode, null, 2));
+                await writable.close();
+            }
+            catch (error) {
+                // If node doesn't exist or read fails, create with just HNSW data
+                const writable = await fileHandle.createWritable();
+                await writable.write(JSON.stringify(hnswData, null, 2));
+                await writable.close();
+            }
         }
         catch (error) {
             console.error(`Failed to save HNSW data for ${nounId}:`, error);

package/dist/storage/adapters/r2Storage.js

@@ -753,9 +753,30 @@ export class R2Storage extends BaseStorage {
     }
     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`;
-        await this.writeObjectToPath(key, hnswData);
+        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);
+            }
+        }
+        catch (error) {
+            // If read fails, create with just HNSW data
+            await this.writeObjectToPath(key, hnswData);
+        }
     }
     async getHNSWData(nounId) {
         await this.ensureInitialized();

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -3055,16 +3055,45 @@ export class S3CompatibleStorage extends BaseStorage {
     async saveHNSWData(nounId, hnswData) {
         await this.ensureInitialized();
         try {
-            const { PutObjectCommand } = await import('@aws-sdk/client-s3');
-            // Use sharded path for HNSW data
+            const { PutObjectCommand, GetObjectCommand } = await import('@aws-sdk/client-s3');
+            // 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`;
-            await this.s3Client.send(new PutObjectCommand({
-                Bucket: this.bucketName,
-                Key: key,
-                Body: JSON.stringify(hnswData, null, 2),
-                ContentType: 'application/json'
-            }));
+            try {
+                // Read existing node data
+                const getResponse = await this.s3Client.send(new GetObjectCommand({
+                    Bucket: this.bucketName,
+                    Key: key
+                }));
+                const existingData = await getResponse.Body.transformToString();
+                const existingNode = JSON.parse(existingData);
+                // Preserve id and vector, update only HNSW graph metadata
+                const updatedNode = {
+                    ...existingNode,
+                    level: hnswData.level,
+                    connections: hnswData.connections
+                };
+                await this.s3Client.send(new PutObjectCommand({
+                    Bucket: this.bucketName,
+                    Key: key,
+                    Body: JSON.stringify(updatedNode, null, 2),
+                    ContentType: 'application/json'
+                }));
+            }
+            catch (error) {
+                // If node doesn't exist yet, create it with just HNSW data
+                if (error.name === 'NoSuchKey' || error.Code === 'NoSuchKey') {
+                    await this.s3Client.send(new PutObjectCommand({
+                        Bucket: this.bucketName,
+                        Key: key,
+                        Body: JSON.stringify(hnswData, null, 2),
+                        ContentType: 'application/json'
+                    }));
+                }
+                else {
+                    throw error;
+                }
+            }
         }
         catch (error) {
             this.logger.error(`Failed to save HNSW data for ${nounId}:`, error);

package/dist/storage/backwardCompatibility.d.ts

@@ -1,5 +1,6 @@
 /**
- * Storage backward compatibility layer for legacy data migrations
+ * DEPRECATED (v4.7.2): Backward compatibility stubs
+ * TODO: Remove in v4.7.3 after migrating s3CompatibleStorage
  */
 export declare class StorageCompatibilityLayer {
     static logMigrationEvent(event: string, details?: any): void;

package/dist/storage/backwardCompatibility.js

@@ -1,26 +1,23 @@
 /**
- * Storage backward compatibility layer for legacy data migrations
+ * DEPRECATED (v4.7.2): Backward compatibility stubs
+ * TODO: Remove in v4.7.3 after migrating s3CompatibleStorage
  */
 export class StorageCompatibilityLayer {
     static logMigrationEvent(event, details) {
-        // Simplified logging for migration events
-        if (process.env.DEBUG_MIGRATION) {
-            console.log(`[Migration] ${event}`, details);
-        }
+        // No-op
     }
     static async migrateIfNeeded(storagePath) {
-        // No-op for now - can be extended later if needed
+        // No-op
     }
 }
-// Helper to get default paths
 export function getDefaultStoragePaths(basePath) {
     return {
-        nouns: `${basePath}/nouns`,
-        verbs: `${basePath}/verbs`,
-        metadata: `${basePath}/metadata`,
-        index: `${basePath}/index`,
-        system: `${basePath}/system`,
-        statistics: `${basePath}/statistics.json`
+        nouns: `${basePath}/entities/nouns/hnsw`,
+        verbs: `${basePath}/entities/verbs/hnsw`,
+        metadata: `${basePath}/entities/nouns/metadata`,
+        index: `${basePath}/indexes`,
+        system: `${basePath}/_system`,
+        statistics: `${basePath}/_system/statistics.json`
     };
 }
 //# sourceMappingURL=backwardCompatibility.js.map

package/dist/storage/baseStorage.d.ts

@@ -5,26 +5,16 @@
 import { GraphAdjacencyIndex } from '../graph/graphAdjacencyIndex.js';
 import { GraphVerb, HNSWNoun, HNSWVerb, NounMetadata, VerbMetadata, HNSWNounWithMetadata, HNSWVerbWithMetadata, StatisticsData } from '../coreTypes.js';
 import { BaseStorageAdapter } from './adapters/baseStorageAdapter.js';
-export declare const ENTITIES_DIR = "entities";
-export declare const NOUNS_VECTOR_DIR = "entities/nouns/vectors";
 export declare const NOUNS_METADATA_DIR = "entities/nouns/metadata";
-export declare const VERBS_VECTOR_DIR = "entities/verbs/vectors";
 export declare const VERBS_METADATA_DIR = "entities/verbs/metadata";
-export declare const INDEXES_DIR = "indexes";
-export declare const METADATA_INDEX_DIR = "indexes/metadata";
-export declare const NOUNS_DIR = "nouns";
-export declare const VERBS_DIR = "verbs";
-export declare const METADATA_DIR = "metadata";
-export declare const NOUN_METADATA_DIR = "noun-metadata";
-export declare const VERB_METADATA_DIR = "verb-metadata";
-export declare const INDEX_DIR = "index";
 export declare const SYSTEM_DIR = "_system";
 export declare const STATISTICS_KEY = "statistics";
-export declare const STORAGE_SCHEMA_VERSION = 3;
-export declare const USE_ENTITY_BASED_STRUCTURE = true;
-/**
- * Get the appropriate directory path based on configuration
- */
+export declare const NOUNS_DIR = "entities/nouns/hnsw";
+export declare const VERBS_DIR = "entities/verbs/hnsw";
+export declare const METADATA_DIR = "entities/nouns/metadata";
+export declare const NOUN_METADATA_DIR = "entities/nouns/metadata";
+export declare const VERB_METADATA_DIR = "entities/verbs/metadata";
+export declare const INDEX_DIR = "indexes";
 export declare function getDirectoryPath(entityType: 'noun' | 'verb', dataType: 'vector' | 'metadata'): string;
 /**
  * Base storage adapter that implements common functionality

package/dist/storage/baseStorage.js

@@ -6,49 +6,26 @@ import { GraphAdjacencyIndex } from '../graph/graphAdjacencyIndex.js';
 import { BaseStorageAdapter } from './adapters/baseStorageAdapter.js';
 import { validateNounType, validateVerbType } from '../utils/typeValidation.js';
 import { getShardIdFromUuid } from './sharding.js';
-// Common directory/prefix names
-// Option A: Entity-Based Directory Structure
-export const ENTITIES_DIR = 'entities';
-export const NOUNS_VECTOR_DIR = 'entities/nouns/vectors';
+// Clean directory structure (v4.7.2+)
+// All storage adapters use this consistent structure
 export const NOUNS_METADATA_DIR = 'entities/nouns/metadata';
-export const VERBS_VECTOR_DIR = 'entities/verbs/vectors';
 export const VERBS_METADATA_DIR = 'entities/verbs/metadata';
-export const INDEXES_DIR = 'indexes';
-export const METADATA_INDEX_DIR = 'indexes/metadata';
-// Legacy paths - kept for backward compatibility during migration
-export const NOUNS_DIR = 'nouns'; // Legacy: now maps to entities/nouns/vectors
-export const VERBS_DIR = 'verbs'; // Legacy: now maps to entities/verbs/vectors
-export const METADATA_DIR = 'metadata'; // Legacy: now maps to entities/nouns/metadata
-export const NOUN_METADATA_DIR = 'noun-metadata'; // Legacy: now maps to entities/nouns/metadata
-export const VERB_METADATA_DIR = 'verb-metadata'; // Legacy: now maps to entities/verbs/metadata
-export const INDEX_DIR = 'index'; // Legacy - kept for backward compatibility
-export const SYSTEM_DIR = '_system'; // System config & metadata indexes
+export const SYSTEM_DIR = '_system';
 export const STATISTICS_KEY = 'statistics';
-// Migration version to track compatibility
-export const STORAGE_SCHEMA_VERSION = 3; // v3: Entity-Based Directory Structure (Option A)
-// Configuration flag to enable new directory structure
-export const USE_ENTITY_BASED_STRUCTURE = true; // Set to true to use Option A structure
-/**
- * Get the appropriate directory path based on configuration
- */
+// DEPRECATED (v4.7.2): Temporary stubs for adapters not yet migrated
+// TODO: Remove in v4.7.3 after migrating remaining adapters
+export const NOUNS_DIR = 'entities/nouns/hnsw';
+export const VERBS_DIR = 'entities/verbs/hnsw';
+export const METADATA_DIR = 'entities/nouns/metadata';
+export const NOUN_METADATA_DIR = 'entities/nouns/metadata';
+export const VERB_METADATA_DIR = 'entities/verbs/metadata';
+export const INDEX_DIR = 'indexes';
 export function getDirectoryPath(entityType, dataType) {
-    if (USE_ENTITY_BASED_STRUCTURE) {
-        // Option A: Entity-Based Structure
-        if (entityType === 'noun') {
-            return dataType === 'vector' ? NOUNS_VECTOR_DIR : NOUNS_METADATA_DIR;
-        }
-        else {
-            return dataType === 'vector' ? VERBS_VECTOR_DIR : VERBS_METADATA_DIR;
-        }
+    if (entityType === 'noun') {
+        return dataType === 'vector' ? NOUNS_DIR : NOUNS_METADATA_DIR;
     }
     else {
-        // Legacy structure
-        if (entityType === 'noun') {
-            return dataType === 'vector' ? NOUNS_DIR : METADATA_DIR;
-        }
-        else {
-            return dataType === 'vector' ? VERBS_DIR : VERB_METADATA_DIR;
-        }
+        return dataType === 'vector' ? VERBS_DIR : VERBS_METADATA_DIR;
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "4.7.1",
+  "version": "4.7.3",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",