@soulcraft/brainy 5.3.5 → 5.4.0

package/dist/storage/cow/BlobStorage.d.ts

@@ -31,7 +31,7 @@ export interface BlobMetadata {
     size: number;
     compressedSize: number;
     compression: 'none' | 'zstd';
-    type: 'vector' | 'metadata' | 'tree' | 'commit' | 'raw';
+    type: 'vector' | 'metadata' | 'tree' | 'commit' | 'blob' | 'raw';
     createdAt: number;
     refCount: number;
 }
@@ -40,7 +40,7 @@ export interface BlobMetadata {
  */
 export interface BlobWriteOptions {
     compression?: 'none' | 'zstd' | 'auto';
-    type?: 'vector' | 'metadata' | 'tree' | 'commit' | 'raw';
+    type?: 'vector' | 'metadata' | 'tree' | 'commit' | 'blob' | 'raw';
     skipVerification?: boolean;
 }
 /**

package/dist/storage/cow/BlobStorage.js

@@ -122,7 +122,7 @@ export class BlobStorage {
             size: data.length,
             compressedSize,
             compression,
-            type: options.type || 'raw',
+            type: options.type || 'blob', // CRITICAL FIX: Use 'blob' default to match storage prefix
             createdAt: Date.now(),
             refCount: 1
         };
@@ -259,7 +259,7 @@ export class BlobStorage {
         }
         // Determine prefix by checking which one exists
         let prefix = 'blob';
-        for (const tryPrefix of ['commit', 'tree', 'blob']) {
+        for (const tryPrefix of ['commit', 'tree', 'blob', 'metadata', 'vector', 'raw']) {
             const exists = await this.adapter.get(`${tryPrefix}:${hash}`);
             if (exists !== undefined) {
                 prefix = tryPrefix;
@@ -283,8 +283,8 @@ export class BlobStorage {
      */
     async getMetadata(hash) {
         // Try to read metadata with type-aware prefix (backward compatible)
-        // Try commit, tree, then blob prefixes
-        for (const prefix of ['commit', 'tree', 'blob']) {
+        // Check all valid blob types: commit, tree, blob, metadata, vector, raw
+        for (const prefix of ['commit', 'tree', 'blob', 'metadata', 'vector', 'raw']) {
             const data = await this.adapter.get(`${prefix}-meta:${hash}`);
             if (data) {
                 return JSON.parse(data.toString());

package/dist/storage/storageFactory.d.ts

@@ -9,7 +9,6 @@ import { S3CompatibleStorage } from './adapters/s3CompatibleStorage.js';
 import { R2Storage } from './adapters/r2Storage.js';
 import { GcsStorage } from './adapters/gcsStorage.js';
 import { AzureBlobStorage } from './adapters/azureBlobStorage.js';
-import { TypeAwareStorageAdapter } from './adapters/typeAwareStorageAdapter.js';
 import { OperationConfig } from '../utils/operationUtils.js';
 /**
  * Options for creating a storage adapter
@@ -304,6 +303,6 @@ export interface StorageOptions {
  */
 export declare function createStorage(options?: StorageOptions): Promise<StorageAdapter>;
 /**
- * Export storage adapters
+ * Export storage adapters (v5.4.0: TypeAware is now built-in, no separate export)
  */
-export { MemoryStorage, OPFSStorage, S3CompatibleStorage, R2Storage, GcsStorage, AzureBlobStorage, TypeAwareStorageAdapter };
+export { MemoryStorage, OPFSStorage, S3CompatibleStorage, R2Storage, GcsStorage, AzureBlobStorage };

package/dist/storage/storageFactory.js

@@ -8,7 +8,7 @@ import { S3CompatibleStorage } from './adapters/s3CompatibleStorage.js';
 import { R2Storage } from './adapters/r2Storage.js';
 import { GcsStorage } from './adapters/gcsStorage.js';
 import { AzureBlobStorage } from './adapters/azureBlobStorage.js';
-import { TypeAwareStorageAdapter } from './adapters/typeAwareStorageAdapter.js';
+// TypeAwareStorageAdapter removed in v5.4.0 - type-aware now built into BaseStorage
 // FileSystemStorage is dynamically imported to avoid issues in browser environments
 import { isBrowser } from '../utils/environment.js';
 /**
@@ -25,29 +25,21 @@ function getFileSystemPath(options) {
     );
 }
 /**
- * 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
+ * Configure COW (Copy-on-Write) options on a storage adapter (v5.4.0)
+ * TypeAware is now built-in to all adapters, no wrapper needed!
  *
- * @param underlying - The base storage adapter (memory, filesystem, S3, etc.)
+ * @param storage - The storage adapter
  * @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
-    });
+function configureCOW(storage, options) {
     // 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 = {
+    if (typeof storage.initializeCOW === 'function') {
+        storage._cowOptions = {
             branch: options?.branch || 'main',
             enableCompression: options?.enableCompression !== false
         };
     }
-    return wrapped;
 }
 /**
  * Create a storage adapter based on the environment and configuration
@@ -57,70 +49,89 @@ async function wrapWithTypeAware(underlying, options, verbose = false) {
 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) + TypeAware wrapper');
-        return await wrapWithTypeAware(new MemoryStorage(), options);
+        console.log('Using memory storage (forced) with built-in type-aware');
+        const storage = new MemoryStorage();
+        configureCOW(storage, options);
+        return storage;
     }
     // 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 await wrapWithTypeAware(new MemoryStorage(), options);
+            const storage = new MemoryStorage();
+            configureCOW(storage, options);
+            return storage;
         }
         const fsPath = getFileSystemPath(options);
-        console.log(`Using file system storage (forced): ${fsPath} + TypeAware wrapper`);
+        console.log(`Using file system storage (forced): ${fsPath} with built-in type-aware`);
         try {
             const { FileSystemStorage } = await import('./adapters/fileSystemStorage.js');
-            return await wrapWithTypeAware(new FileSystemStorage(fsPath), options);
+            const storage = new FileSystemStorage(fsPath);
+            configureCOW(storage, options);
+            return storage;
         }
         catch (error) {
             console.warn('Failed to load FileSystemStorage, falling back to memory storage:', error);
-            return await wrapWithTypeAware(new MemoryStorage(), options);
+            const storage = new MemoryStorage();
+            configureCOW(storage, options);
+            return storage;
         }
     }
     // 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 + TypeAware wrapper');
-                return await wrapWithTypeAware(new MemoryStorage(), options);
+                console.log('Using memory storage with built-in type-aware');
+                const memStorage = new MemoryStorage();
+                configureCOW(memStorage, options);
+                return memStorage;
             case 'opfs': {
                 // Check if OPFS is available
                 const opfsStorage = new OPFSStorage();
                 if (opfsStorage.isOPFSAvailable()) {
-                    console.log('Using OPFS storage + TypeAware wrapper');
+                    console.log('Using OPFS storage with built-in type-aware');
                     await opfsStorage.init();
                     // Request persistent storage if specified
                     if (options.requestPersistentStorage) {
                         const isPersistent = await opfsStorage.requestPersistentStorage();
                         console.log(`Persistent storage ${isPersistent ? 'granted' : 'denied'}`);
                     }
-                    return await wrapWithTypeAware(opfsStorage, options);
+                    configureCOW(opfsStorage, options);
+                    return opfsStorage;
                 }
                 else {
                     console.warn('OPFS storage is not available, falling back to memory storage');
-                    return await wrapWithTypeAware(new MemoryStorage(), options);
+                    const storage = new MemoryStorage();
+                    configureCOW(storage, options);
+                    return storage;
                 }
             }
             case 'filesystem': {
                 if (isBrowser()) {
                     console.warn('FileSystemStorage is not available in browser environments, falling back to memory storage');
-                    return await wrapWithTypeAware(new MemoryStorage(), options);
+                    const storage = new MemoryStorage();
+                    configureCOW(storage, options);
+                    return storage;
                 }
                 const fsPath = getFileSystemPath(options);
-                console.log(`Using file system storage: ${fsPath} + TypeAware wrapper`);
+                console.log(`Using file system storage: ${fsPath} with built-in type-aware`);
                 try {
                     const { FileSystemStorage } = await import('./adapters/fileSystemStorage.js');
-                    return await wrapWithTypeAware(new FileSystemStorage(fsPath));
+                    const storage = new FileSystemStorage(fsPath);
+                    configureCOW(storage, options);
+                    return storage;
                 }
                 catch (error) {
                     console.warn('Failed to load FileSystemStorage, falling back to memory storage:', error);
-                    return await wrapWithTypeAware(new MemoryStorage(), options);
+                    const storage = new MemoryStorage();
+                    configureCOW(storage, options);
+                    return storage;
                 }
             }
             case 's3':
                 if (options.s3Storage) {
-                    console.log('Using Amazon S3 storage + TypeAware wrapper');
-                    return await wrapWithTypeAware(new S3CompatibleStorage({
+                    console.log('Using Amazon S3 storage with built-in type-aware');
+                    const storage = new S3CompatibleStorage({
                         bucketName: options.s3Storage.bucketName,
                         region: options.s3Storage.region,
                         accessKeyId: options.s3Storage.accessKeyId,
@@ -129,26 +140,34 @@ export async function createStorage(options = {}) {
                         serviceType: 's3',
                         operationConfig: options.operationConfig,
                         cacheConfig: options.cacheConfig
-                    }));
+                    });
+                    configureCOW(storage, options);
+                    return storage;
                 }
                 else {
                     console.warn('S3 storage configuration is missing, falling back to memory storage');
-                    return await wrapWithTypeAware(new MemoryStorage(), options);
+                    const storage = new MemoryStorage();
+                    configureCOW(storage, options);
+                    return storage;
                 }
             case 'r2':
                 if (options.r2Storage) {
-                    console.log('Using Cloudflare R2 storage (dedicated adapter) + TypeAware wrapper');
-                    return await wrapWithTypeAware(new R2Storage({
+                    console.log('Using Cloudflare R2 storage (dedicated adapter) with built-in type-aware');
+                    const storage = new R2Storage({
                         bucketName: options.r2Storage.bucketName,
                         accountId: options.r2Storage.accountId,
                         accessKeyId: options.r2Storage.accessKeyId,
                         secretAccessKey: options.r2Storage.secretAccessKey,
                         cacheConfig: options.cacheConfig
-                    }));
+                    });
+                    configureCOW(storage, options);
+                    return storage;
                 }
                 else {
                     console.warn('R2 storage configuration is missing, falling back to memory storage');
-                    return await wrapWithTypeAware(new MemoryStorage(), options);
+                    const storage = new MemoryStorage();
+                    configureCOW(storage, options);
+                    return storage;
                 }
             case 'gcs-native':
                 // DEPRECATED: gcs-native is deprecated in favor of just 'gcs'
@@ -161,14 +180,16 @@ 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 await wrapWithTypeAware(new MemoryStorage(), options);
+                    const storage = new MemoryStorage();
+                    configureCOW(storage, options);
+                    return storage;
                 }
                 // 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 await wrapWithTypeAware(new S3CompatibleStorage({
+                    const storage = new S3CompatibleStorage({
                         bucketName: gcsLegacy.bucketName,
                         region: gcsLegacy.region,
                         endpoint: gcsLegacy.endpoint || 'https://storage.googleapis.com',
@@ -176,12 +197,14 @@ export async function createStorage(options = {}) {
                         secretAccessKey: gcsLegacy.secretAccessKey,
                         serviceType: 'gcs',
                         cacheConfig: options.cacheConfig
-                    }));
+                    });
+                    configureCOW(storage, options);
+                    return storage;
                 }
                 // Use native GCS SDK (the correct default!)
                 const config = gcsNative || gcsLegacy;
                 console.log('Using Google Cloud Storage (native SDK) + TypeAware wrapper');
-                return await wrapWithTypeAware(new GcsStorage({
+                const storage = new GcsStorage({
                     bucketName: config.bucketName,
                     keyFilename: gcsNative?.keyFilename,
                     credentials: gcsNative?.credentials,
@@ -190,23 +213,29 @@ export async function createStorage(options = {}) {
                     skipInitialScan: gcsNative?.skipInitialScan,
                     skipCountsFile: gcsNative?.skipCountsFile,
                     cacheConfig: options.cacheConfig
-                }));
+                });
+                configureCOW(storage, options);
+                return storage;
             }
             case 'azure':
                 if (options.azureStorage) {
                     console.log('Using Azure Blob Storage (native SDK) + TypeAware wrapper');
-                    return await wrapWithTypeAware(new AzureBlobStorage({
+                    const storage = 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
-                    }));
+                    });
+                    configureCOW(storage, options);
+                    return storage;
                 }
                 else {
                     console.warn('Azure storage configuration is missing, falling back to memory storage');
-                    return await wrapWithTypeAware(new MemoryStorage(), options);
+                    const storage = new MemoryStorage();
+                    configureCOW(storage, options);
+                    return storage;
                 }
             case 'type-aware':
                 // v5.0.0: TypeAware is now the default for ALL adapters
@@ -220,13 +249,15 @@ export async function createStorage(options = {}) {
                 });
             default:
                 console.warn(`Unknown storage type: ${options.type}, falling back to memory storage`);
-                return await wrapWithTypeAware(new MemoryStorage(), options);
+                const storage = new MemoryStorage();
+                configureCOW(storage, options);
+                return storage;
         }
     }
     // If custom S3-compatible storage is specified, use it
     if (options.customS3Storage) {
         console.log(`Using custom S3-compatible storage: ${options.customS3Storage.serviceType || 'custom'} + TypeAware wrapper`);
-        return await wrapWithTypeAware(new S3CompatibleStorage({
+        const storage = new S3CompatibleStorage({
             bucketName: options.customS3Storage.bucketName,
             region: options.customS3Storage.region,
             endpoint: options.customS3Storage.endpoint,
@@ -234,23 +265,27 @@ export async function createStorage(options = {}) {
             secretAccessKey: options.customS3Storage.secretAccessKey,
             serviceType: options.customS3Storage.serviceType || 'custom',
             cacheConfig: options.cacheConfig
-        }));
+        });
+        configureCOW(storage, options);
+        return storage;
     }
     // If R2 storage is specified, use it
     if (options.r2Storage) {
         console.log('Using Cloudflare R2 storage (dedicated adapter) + TypeAware wrapper');
-        return await wrapWithTypeAware(new R2Storage({
+        const storage = new R2Storage({
             bucketName: options.r2Storage.bucketName,
             accountId: options.r2Storage.accountId,
             accessKeyId: options.r2Storage.accessKeyId,
             secretAccessKey: options.r2Storage.secretAccessKey,
             cacheConfig: options.cacheConfig
-        }));
+        });
+        configureCOW(storage, options);
+        return storage;
     }
     // If S3 storage is specified, use it
     if (options.s3Storage) {
         console.log('Using Amazon S3 storage + TypeAware wrapper');
-        return await wrapWithTypeAware(new S3CompatibleStorage({
+        const storage = new S3CompatibleStorage({
             bucketName: options.s3Storage.bucketName,
             region: options.s3Storage.region,
             accessKeyId: options.s3Storage.accessKeyId,
@@ -258,7 +293,9 @@ export async function createStorage(options = {}) {
             sessionToken: options.s3Storage.sessionToken,
             serviceType: 's3',
             cacheConfig: options.cacheConfig
-        }));
+        });
+        configureCOW(storage, options);
+        return storage;
     }
     // If GCS storage is specified (native or legacy S3-compatible)
     // Prefer gcsNativeStorage, but also accept gcsStorage for backward compatibility
@@ -271,7 +308,7 @@ export async function createStorage(options = {}) {
             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) + TypeAware wrapper');
-            return await wrapWithTypeAware(new S3CompatibleStorage({
+            const storage = new S3CompatibleStorage({
                 bucketName: gcsLegacy.bucketName,
                 region: gcsLegacy.region,
                 endpoint: gcsLegacy.endpoint || 'https://storage.googleapis.com',
@@ -279,12 +316,14 @@ export async function createStorage(options = {}) {
                 secretAccessKey: gcsLegacy.secretAccessKey,
                 serviceType: 'gcs',
                 cacheConfig: options.cacheConfig
-            }));
+            });
+            configureCOW(storage, options);
+            return storage;
         }
         // Use native GCS SDK (the correct default!)
         const config = gcsNative || gcsLegacy;
         console.log('Using Google Cloud Storage (native SDK - auto-detected) + TypeAware wrapper');
-        return await wrapWithTypeAware(new GcsStorage({
+        const storage = new GcsStorage({
             bucketName: config.bucketName,
             keyFilename: gcsNative?.keyFilename,
             credentials: gcsNative?.credentials,
@@ -293,19 +332,23 @@ export async function createStorage(options = {}) {
             skipInitialScan: gcsNative?.skipInitialScan,
             skipCountsFile: gcsNative?.skipCountsFile,
             cacheConfig: options.cacheConfig
-        }));
+        });
+        configureCOW(storage, options);
+        return storage;
     }
     // If Azure storage is specified, use it
     if (options.azureStorage) {
         console.log('Using Azure Blob Storage (native SDK) + TypeAware wrapper');
-        return await wrapWithTypeAware(new AzureBlobStorage({
+        const storage = 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
-        }));
+        });
+        configureCOW(storage, options);
+        return storage;
     }
     // Auto-detect the best storage adapter based on the environment
     // First, check if we're in Node.js (prioritize for test environments)
@@ -316,10 +359,12 @@ export async function createStorage(options = {}) {
                 process.versions &&
                 process.versions.node) {
                 const fsPath = getFileSystemPath(options);
-                console.log(`Using file system storage (auto-detected): ${fsPath} + TypeAware wrapper`);
+                console.log(`Using file system storage (auto-detected): ${fsPath} with built-in type-aware`);
                 try {
                     const { FileSystemStorage } = await import('./adapters/fileSystemStorage.js');
-                    return await wrapWithTypeAware(new FileSystemStorage(fsPath));
+                    const storage = new FileSystemStorage(fsPath);
+                    configureCOW(storage, options);
+                    return storage;
                 }
                 catch (fsError) {
                     console.warn('Failed to load FileSystemStorage, falling back to memory storage:', fsError);
@@ -342,17 +387,20 @@ export async function createStorage(options = {}) {
                 const isPersistent = await opfsStorage.requestPersistentStorage();
                 console.log(`Persistent storage ${isPersistent ? 'granted' : 'denied'}`);
             }
-            return await wrapWithTypeAware(opfsStorage, options);
+            configureCOW(opfsStorage, options);
+            return opfsStorage;
         }
     }
     // Finally, fall back to memory storage
-    console.log('Using memory storage (auto-detected) + TypeAware wrapper');
-    return await wrapWithTypeAware(new MemoryStorage(), options);
+    console.log('Using memory storage (auto-detected) with built-in type-aware');
+    const storage = new MemoryStorage();
+    configureCOW(storage, options);
+    return storage;
 }
 /**
- * Export storage adapters
+ * Export storage adapters (v5.4.0: TypeAware is now built-in, no separate export)
  */
-export { MemoryStorage, OPFSStorage, S3CompatibleStorage, R2Storage, GcsStorage, AzureBlobStorage, TypeAwareStorageAdapter };
+export { MemoryStorage, OPFSStorage, S3CompatibleStorage, R2Storage, GcsStorage, AzureBlobStorage };
 // Export FileSystemStorage conditionally
 // NOTE: FileSystemStorage is now only imported dynamically to avoid fs imports in browser builds
 // export { FileSystemStorage } from './adapters/fileSystemStorage.js'

package/dist/vfs/types.d.ts

@@ -166,6 +166,10 @@ export interface ReaddirOptions {
     sort?: 'name' | 'size' | 'modified' | 'created';
     order?: 'asc' | 'desc';
 }
+export interface StatOptions {
+}
+export interface ExistsOptions {
+}
 export interface CopyOptions {
     overwrite?: boolean;
     preserveTimestamps?: boolean;
@@ -299,9 +303,9 @@ export interface IVirtualFileSystem {
         parent: VFSEntity | null;
         stats: VFSStats;
     }>;
-    stat(path: string): Promise<VFSStats>;
+    stat(path: string, options?: StatOptions): Promise<VFSStats>;
     lstat(path: string): Promise<VFSStats>;
-    exists(path: string): Promise<boolean>;
+    exists(path: string, options?: ExistsOptions): Promise<boolean>;
     chmod(path: string, mode: number): Promise<void>;
     chown(path: string, uid: number, gid: number): Promise<void>;
     utimes(path: string, atime: Date, mtime: Date): Promise<void>;

package/package.json

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