@soulcraft/brainy 4.11.2 → 5.1.0

package/dist/storage/storageFactory.js

@@ -24,6 +24,31 @@ function getFileSystemPath(options) {
         './brainy-data' // Zero-config fallback
     );
 }
+/**
+ * Wrap any storage adapter with TypeAwareStorageAdapter
+ * v5.0.0: TypeAware is now the standard interface for ALL storage adapters
+ * This provides type-first organization, fixed-size type counts, and efficient type queries
+ *
+ * @param underlying - The base storage adapter (memory, filesystem, S3, etc.)
+ * @param options - Storage options (for COW configuration)
+ * @param verbose - Optional verbose logging
+ * @returns TypeAwareStorageAdapter wrapping the underlying storage
+ */
+async function wrapWithTypeAware(underlying, options, verbose = false) {
+    const wrapped = new TypeAwareStorageAdapter({
+        underlyingStorage: underlying,
+        verbose
+    });
+    // v5.0.1: COW will be initialized AFTER storage.init() in Brainy
+    // Store COW options for later initialization
+    if (typeof wrapped.initializeCOW === 'function') {
+        wrapped._cowOptions = {
+            branch: options?.branch || 'main',
+            enableCompression: options?.enableCompression !== false
+        };
+    }
+    return wrapped;
+}
 /**
  * Create a storage adapter based on the environment and configuration
  * @param options Options for creating the storage adapter
@@ -32,70 +57,70 @@ function getFileSystemPath(options) {
 export async function createStorage(options = {}) {
     // If memory storage is forced, use it regardless of other options
     if (options.forceMemoryStorage) {
-        console.log('Using memory storage (forced)');
-        return new MemoryStorage();
+        console.log('Using memory storage (forced) + TypeAware wrapper');
+        return await wrapWithTypeAware(new MemoryStorage(), options);
     }
     // If file system storage is forced, use it regardless of other options
     if (options.forceFileSystemStorage) {
         if (isBrowser()) {
             console.warn('FileSystemStorage is not available in browser environments, falling back to memory storage');
-            return new MemoryStorage();
+            return await wrapWithTypeAware(new MemoryStorage(), options);
         }
         const fsPath = getFileSystemPath(options);
-        console.log(`Using file system storage (forced): ${fsPath}`);
+        console.log(`Using file system storage (forced): ${fsPath} + TypeAware wrapper`);
         try {
             const { FileSystemStorage } = await import('./adapters/fileSystemStorage.js');
-            return new FileSystemStorage(fsPath);
+            return await wrapWithTypeAware(new FileSystemStorage(fsPath), options);
         }
         catch (error) {
             console.warn('Failed to load FileSystemStorage, falling back to memory storage:', error);
-            return new MemoryStorage();
+            return await wrapWithTypeAware(new MemoryStorage(), options);
         }
     }
     // If a specific storage type is specified, use it
     if (options.type && options.type !== 'auto') {
         switch (options.type) {
             case 'memory':
-                console.log('Using memory storage');
-                return new MemoryStorage();
+                console.log('Using memory storage + TypeAware wrapper');
+                return await wrapWithTypeAware(new MemoryStorage(), options);
             case 'opfs': {
                 // Check if OPFS is available
                 const opfsStorage = new OPFSStorage();
                 if (opfsStorage.isOPFSAvailable()) {
-                    console.log('Using OPFS storage');
+                    console.log('Using OPFS storage + TypeAware wrapper');
                     await opfsStorage.init();
                     // Request persistent storage if specified
                     if (options.requestPersistentStorage) {
                         const isPersistent = await opfsStorage.requestPersistentStorage();
                         console.log(`Persistent storage ${isPersistent ? 'granted' : 'denied'}`);
                     }
-                    return opfsStorage;
+                    return await wrapWithTypeAware(opfsStorage, options);
                 }
                 else {
                     console.warn('OPFS storage is not available, falling back to memory storage');
-                    return new MemoryStorage();
+                    return await wrapWithTypeAware(new MemoryStorage(), options);
                 }
             }
             case 'filesystem': {
                 if (isBrowser()) {
                     console.warn('FileSystemStorage is not available in browser environments, falling back to memory storage');
-                    return new MemoryStorage();
+                    return await wrapWithTypeAware(new MemoryStorage(), options);
                 }
                 const fsPath = getFileSystemPath(options);
-                console.log(`Using file system storage: ${fsPath}`);
+                console.log(`Using file system storage: ${fsPath} + TypeAware wrapper`);
                 try {
                     const { FileSystemStorage } = await import('./adapters/fileSystemStorage.js');
-                    return new FileSystemStorage(fsPath);
+                    return await wrapWithTypeAware(new FileSystemStorage(fsPath));
                 }
                 catch (error) {
                     console.warn('Failed to load FileSystemStorage, falling back to memory storage:', error);
-                    return new MemoryStorage();
+                    return await wrapWithTypeAware(new MemoryStorage(), options);
                 }
             }
             case 's3':
                 if (options.s3Storage) {
-                    console.log('Using Amazon S3 storage');
-                    return new S3CompatibleStorage({
+                    console.log('Using Amazon S3 storage + TypeAware wrapper');
+                    return await wrapWithTypeAware(new S3CompatibleStorage({
                         bucketName: options.s3Storage.bucketName,
                         region: options.s3Storage.region,
                         accessKeyId: options.s3Storage.accessKeyId,
@@ -104,26 +129,26 @@ export async function createStorage(options = {}) {
                         serviceType: 's3',
                         operationConfig: options.operationConfig,
                         cacheConfig: options.cacheConfig
-                    });
+                    }));
                 }
                 else {
                     console.warn('S3 storage configuration is missing, falling back to memory storage');
-                    return new MemoryStorage();
+                    return await wrapWithTypeAware(new MemoryStorage(), options);
                 }
             case 'r2':
                 if (options.r2Storage) {
-                    console.log('Using Cloudflare R2 storage (dedicated adapter)');
-                    return new R2Storage({
+                    console.log('Using Cloudflare R2 storage (dedicated adapter) + TypeAware wrapper');
+                    return await wrapWithTypeAware(new R2Storage({
                         bucketName: options.r2Storage.bucketName,
                         accountId: options.r2Storage.accountId,
                         accessKeyId: options.r2Storage.accessKeyId,
                         secretAccessKey: options.r2Storage.secretAccessKey,
                         cacheConfig: options.cacheConfig
-                    });
+                    }));
                 }
                 else {
                     console.warn('R2 storage configuration is missing, falling back to memory storage');
-                    return new MemoryStorage();
+                    return await wrapWithTypeAware(new MemoryStorage(), options);
                 }
             case 'gcs-native':
                 // DEPRECATED: gcs-native is deprecated in favor of just 'gcs'
@@ -136,14 +161,14 @@ export async function createStorage(options = {}) {
                 const gcsLegacy = options.gcsStorage;
                 if (!gcsNative && !gcsLegacy) {
                     console.warn('GCS storage configuration is missing, falling back to memory storage');
-                    return new MemoryStorage();
+                    return await wrapWithTypeAware(new MemoryStorage(), options);
                 }
                 // If using legacy gcsStorage with HMAC keys, use S3-compatible adapter
                 if (gcsLegacy && gcsLegacy.accessKeyId && gcsLegacy.secretAccessKey) {
                     console.warn('⚠️  GCS with HMAC keys detected. Consider using gcsNativeStorage with ADC instead.');
                     console.warn('   Native GCS with Application Default Credentials is recommended for better performance and security.');
                     // Use S3-compatible storage for HMAC keys
-                    return new S3CompatibleStorage({
+                    return await wrapWithTypeAware(new S3CompatibleStorage({
                         bucketName: gcsLegacy.bucketName,
                         region: gcsLegacy.region,
                         endpoint: gcsLegacy.endpoint || 'https://storage.googleapis.com',
@@ -151,12 +176,12 @@ export async function createStorage(options = {}) {
                         secretAccessKey: gcsLegacy.secretAccessKey,
                         serviceType: 'gcs',
                         cacheConfig: options.cacheConfig
-                    });
+                    }));
                 }
                 // Use native GCS SDK (the correct default!)
                 const config = gcsNative || gcsLegacy;
-                console.log('Using Google Cloud Storage (native SDK)');
-                return new GcsStorage({
+                console.log('Using Google Cloud Storage (native SDK) + TypeAware wrapper');
+                return await wrapWithTypeAware(new GcsStorage({
                     bucketName: config.bucketName,
                     keyFilename: gcsNative?.keyFilename,
                     credentials: gcsNative?.credentials,
@@ -165,50 +190,43 @@ export async function createStorage(options = {}) {
                     skipInitialScan: gcsNative?.skipInitialScan,
                     skipCountsFile: gcsNative?.skipCountsFile,
                     cacheConfig: options.cacheConfig
-                });
+                }));
             }
             case 'azure':
                 if (options.azureStorage) {
-                    console.log('Using Azure Blob Storage (native SDK)');
-                    return new AzureBlobStorage({
+                    console.log('Using Azure Blob Storage (native SDK) + TypeAware wrapper');
+                    return await wrapWithTypeAware(new AzureBlobStorage({
                         containerName: options.azureStorage.containerName,
                         accountName: options.azureStorage.accountName,
                         accountKey: options.azureStorage.accountKey,
                         connectionString: options.azureStorage.connectionString,
                         sasToken: options.azureStorage.sasToken,
                         cacheConfig: options.cacheConfig
-                    });
+                    }));
                 }
                 else {
                     console.warn('Azure storage configuration is missing, falling back to memory storage');
-                    return new MemoryStorage();
+                    return await wrapWithTypeAware(new MemoryStorage(), options);
                 }
-            case 'type-aware': {
-                console.log('Using Type-Aware Storage (type-first architecture)');
-                // Create underlying storage adapter
-                const underlyingType = options.typeAwareStorage?.underlyingType || 'auto';
-                const underlyingOptions = options.typeAwareStorage?.underlyingOptions || {};
-                // Recursively create the underlying storage
-                const underlying = await createStorage({
-                    ...underlyingOptions,
-                    type: underlyingType
-                });
-                // Wrap with TypeAwareStorageAdapter
-                // Cast to BaseStorage since all concrete storage adapters extend BaseStorage
-                return new TypeAwareStorageAdapter({
-                    underlyingStorage: underlying,
-                    verbose: options.typeAwareStorage?.verbose || false
+            case 'type-aware':
+                // v5.0.0: TypeAware is now the default for ALL adapters
+                // Redirect to the underlying type instead
+                console.warn('⚠️  type-aware is deprecated in v5.0.0 - TypeAware is now always enabled.');
+                console.warn('   Just use the underlying storage type (e.g., "filesystem", "s3", etc.)');
+                // Recursively create storage with underlying type
+                return await createStorage({
+                    ...options,
+                    type: options.typeAwareStorage?.underlyingType || 'auto'
                 });
-            }
             default:
                 console.warn(`Unknown storage type: ${options.type}, falling back to memory storage`);
-                return new MemoryStorage();
+                return await wrapWithTypeAware(new MemoryStorage(), options);
         }
     }
     // If custom S3-compatible storage is specified, use it
     if (options.customS3Storage) {
-        console.log(`Using custom S3-compatible storage: ${options.customS3Storage.serviceType || 'custom'}`);
-        return new S3CompatibleStorage({
+        console.log(`Using custom S3-compatible storage: ${options.customS3Storage.serviceType || 'custom'} + TypeAware wrapper`);
+        return await wrapWithTypeAware(new S3CompatibleStorage({
             bucketName: options.customS3Storage.bucketName,
             region: options.customS3Storage.region,
             endpoint: options.customS3Storage.endpoint,
@@ -216,23 +234,23 @@ export async function createStorage(options = {}) {
             secretAccessKey: options.customS3Storage.secretAccessKey,
             serviceType: options.customS3Storage.serviceType || 'custom',
             cacheConfig: options.cacheConfig
-        });
+        }));
     }
     // If R2 storage is specified, use it
     if (options.r2Storage) {
-        console.log('Using Cloudflare R2 storage (dedicated adapter)');
-        return new R2Storage({
+        console.log('Using Cloudflare R2 storage (dedicated adapter) + TypeAware wrapper');
+        return await wrapWithTypeAware(new R2Storage({
             bucketName: options.r2Storage.bucketName,
             accountId: options.r2Storage.accountId,
             accessKeyId: options.r2Storage.accessKeyId,
             secretAccessKey: options.r2Storage.secretAccessKey,
             cacheConfig: options.cacheConfig
-        });
+        }));
     }
     // If S3 storage is specified, use it
     if (options.s3Storage) {
-        console.log('Using Amazon S3 storage');
-        return new S3CompatibleStorage({
+        console.log('Using Amazon S3 storage + TypeAware wrapper');
+        return await wrapWithTypeAware(new S3CompatibleStorage({
             bucketName: options.s3Storage.bucketName,
             region: options.s3Storage.region,
             accessKeyId: options.s3Storage.accessKeyId,
@@ -240,7 +258,7 @@ export async function createStorage(options = {}) {
             sessionToken: options.s3Storage.sessionToken,
             serviceType: 's3',
             cacheConfig: options.cacheConfig
-        });
+        }));
     }
     // If GCS storage is specified (native or legacy S3-compatible)
     // Prefer gcsNativeStorage, but also accept gcsStorage for backward compatibility
@@ -252,8 +270,8 @@ export async function createStorage(options = {}) {
             console.warn('⚠️  GCS with HMAC keys detected. Consider using gcsNativeStorage with ADC instead.');
             console.warn('   Native GCS with Application Default Credentials is recommended for better performance and security.');
             // Use S3-compatible storage for HMAC keys
-            console.log('Using Google Cloud Storage (S3-compatible with HMAC - auto-detected)');
-            return new S3CompatibleStorage({
+            console.log('Using Google Cloud Storage (S3-compatible with HMAC - auto-detected) + TypeAware wrapper');
+            return await wrapWithTypeAware(new S3CompatibleStorage({
                 bucketName: gcsLegacy.bucketName,
                 region: gcsLegacy.region,
                 endpoint: gcsLegacy.endpoint || 'https://storage.googleapis.com',
@@ -261,12 +279,12 @@ export async function createStorage(options = {}) {
                 secretAccessKey: gcsLegacy.secretAccessKey,
                 serviceType: 'gcs',
                 cacheConfig: options.cacheConfig
-            });
+            }));
         }
         // Use native GCS SDK (the correct default!)
         const config = gcsNative || gcsLegacy;
-        console.log('Using Google Cloud Storage (native SDK - auto-detected)');
-        return new GcsStorage({
+        console.log('Using Google Cloud Storage (native SDK - auto-detected) + TypeAware wrapper');
+        return await wrapWithTypeAware(new GcsStorage({
             bucketName: config.bucketName,
             keyFilename: gcsNative?.keyFilename,
             credentials: gcsNative?.credentials,
@@ -275,19 +293,19 @@ export async function createStorage(options = {}) {
             skipInitialScan: gcsNative?.skipInitialScan,
             skipCountsFile: gcsNative?.skipCountsFile,
             cacheConfig: options.cacheConfig
-        });
+        }));
     }
     // If Azure storage is specified, use it
     if (options.azureStorage) {
-        console.log('Using Azure Blob Storage (native SDK)');
-        return new AzureBlobStorage({
+        console.log('Using Azure Blob Storage (native SDK) + TypeAware wrapper');
+        return await wrapWithTypeAware(new AzureBlobStorage({
             containerName: options.azureStorage.containerName,
             accountName: options.azureStorage.accountName,
             accountKey: options.azureStorage.accountKey,
             connectionString: options.azureStorage.connectionString,
             sasToken: options.azureStorage.sasToken,
             cacheConfig: options.cacheConfig
-        });
+        }));
     }
     // Auto-detect the best storage adapter based on the environment
     // First, check if we're in Node.js (prioritize for test environments)
@@ -298,10 +316,10 @@ export async function createStorage(options = {}) {
                 process.versions &&
                 process.versions.node) {
                 const fsPath = getFileSystemPath(options);
-                console.log(`Using file system storage (auto-detected): ${fsPath}`);
+                console.log(`Using file system storage (auto-detected): ${fsPath} + TypeAware wrapper`);
                 try {
                     const { FileSystemStorage } = await import('./adapters/fileSystemStorage.js');
-                    return new FileSystemStorage(fsPath);
+                    return await wrapWithTypeAware(new FileSystemStorage(fsPath));
                 }
                 catch (fsError) {
                     console.warn('Failed to load FileSystemStorage, falling back to memory storage:', fsError);
@@ -317,19 +335,19 @@ export async function createStorage(options = {}) {
     if (isBrowser()) {
         const opfsStorage = new OPFSStorage();
         if (opfsStorage.isOPFSAvailable()) {
-            console.log('Using OPFS storage (auto-detected)');
+            console.log('Using OPFS storage (auto-detected) + TypeAware wrapper');
             await opfsStorage.init();
             // Request persistent storage if specified
             if (options.requestPersistentStorage) {
                 const isPersistent = await opfsStorage.requestPersistentStorage();
                 console.log(`Persistent storage ${isPersistent ? 'granted' : 'denied'}`);
             }
-            return opfsStorage;
+            return await wrapWithTypeAware(opfsStorage, options);
         }
     }
     // Finally, fall back to memory storage
-    console.log('Using memory storage (auto-detected)');
-    return new MemoryStorage();
+    console.log('Using memory storage (auto-detected) + TypeAware wrapper');
+    return await wrapWithTypeAware(new MemoryStorage(), options);
 }
 /**
  * Export storage adapters

package/dist/types/brainy.types.d.ts

@@ -458,6 +458,7 @@ export interface BrainyConfig {
     storage?: {
         type: 'auto' | 'memory' | 'filesystem' | 's3' | 'r2' | 'opfs' | 'gcs';
         options?: any;
+        branch?: string;
     };
     model?: {
         type: 'fast' | 'accurate' | 'balanced' | 'custom';

package/dist/vfs/FSCompat.d.ts

@@ -6,7 +6,7 @@
  *
  * Usage:
  *   import { FSCompat } from '@soulcraft/brainy/vfs'
- *   const fs = new FSCompat(brain.vfs())
+ *   const fs = new FSCompat(brain.vfs)
  *
  *   // Now use like Node's fs
  *   await fs.promises.readFile('/path')

package/dist/vfs/FSCompat.js

@@ -6,7 +6,7 @@
  *
  * Usage:
  *   import { FSCompat } from '@soulcraft/brainy/vfs'
- *   const fs = new FSCompat(brain.vfs())
+ *   const fs = new FSCompat(brain.vfs)
  *
  *   // Now use like Node's fs
  *   await fs.promises.readFile('/path')

package/dist/vfs/VirtualFileSystem.js

@@ -42,10 +42,9 @@ export class VirtualFileSystem {
             return;
         // Merge config with defaults
         this.config = { ...this.getDefaultConfig(), ...config };
-        // Initialize Brainy if needed
-        if (!this.brain.isInitialized) {
-            await this.brain.init();
-        }
+        // v5.0.1: VFS is now auto-initialized during brain.init()
+        // Brain is guaranteed to be initialized when this is called
+        // Removed brain.init() check to prevent infinite recursion
         // Create or find root entity
         this.rootEntityId = await this.initializeRoot();
         // Initialize projection registry with auto-discovery of built-in projections
@@ -847,11 +846,11 @@ export class VirtualFileSystem {
             throw new VFSError(VFSErrorCode.EINVAL, 'VFS not initialized. Call await vfs.init() before using VFS operations.\n\n' +
                 '✅ After brain.import():\n' +
                 '  await brain.import(file, { vfsPath: "/imports/data" })\n' +
-                '  const vfs = brain.vfs()\n' +
+                '  const vfs = brain.vfs\n' +
                 '  await vfs.init()  // ← Required! Safe to call multiple times\n' +
                 '  const files = await vfs.readdir("/imports/data")\n\n' +
                 '✅ Direct VFS usage:\n' +
-                '  const vfs = brain.vfs()\n' +
+                '  const vfs = brain.vfs\n' +
                 '  await vfs.init()  // ← Always required before first use\n' +
                 '  await vfs.writeFile("/docs/readme.md", "Hello")\n\n' +
                 '📖 Docs: https://github.com/soulcraftlabs/brainy/blob/main/docs/vfs/QUICK_START.md', '<unknown>', 'VFS');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "4.11.2",
+  "version": "5.1.0",
   "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",