@soulcraft/brainy 4.0.2 → 4.1.1

package/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
-All notable changes to this project will be documented in this file. See [standard-version](https://github.com/soulcraftlabs/standard-version) for commit guidelines.
+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.1.1](https://github.com/soulcraftlabs/brainy/compare/v4.1.0...v4.1.1) (2025-10-20)
+
+
+### 🐛 Bug Fixes
+
+* correct Node.js version references from 24 to 22 in comments and code ([22513ff](https://github.com/soulcraftlabs/brainy/commit/22513ffcb40cc6498898400ac5d1bae19c5d02ed))
+
+## [4.1.0](https://github.com/soulcraftlabs/brainy/compare/v4.0.1...v4.1.0) (2025-10-20)
+
+
+### 📚 Documentation
+
+* restructure README for clarity and engagement ([26c5c78](https://github.com/soulcraftlabs/brainy/commit/26c5c784293293e2d922e0822b553b860262af1c))
+
+
+### ✨ Features
+
+* simplify GCS storage naming and add Cloud Run deployment options ([38343c0](https://github.com/soulcraftlabs/brainy/commit/38343c012846f0bdf70dc7402be0ef7ad93d7179))
 
 ## [4.0.0](https://github.com/soulcraftlabs/brainy/compare/v3.50.2...v4.0.0) (2025-10-17)
 

package/dist/brainy.js

@@ -2483,24 +2483,23 @@ export class Brainy {
      */
     normalizeConfig(config) {
         // Validate storage configuration
-        if (config?.storage?.type && !['auto', 'memory', 'filesystem', 'opfs', 'remote', 's3', 'r2', 'gcs', 'gcs-native'].includes(config.storage.type)) {
-            throw new Error(`Invalid storage type: ${config.storage.type}. Must be one of: auto, memory, filesystem, opfs, remote, s3, r2, gcs, gcs-native`);
+        if (config?.storage?.type && !['auto', 'memory', 'filesystem', 'opfs', 'remote', 's3', 'r2', 'gcs', 'gcs-native', 'azure'].includes(config.storage.type)) {
+            throw new Error(`Invalid storage type: ${config.storage.type}. Must be one of: auto, memory, filesystem, opfs, remote, s3, r2, gcs, gcs-native, azure`);
         }
-        // Validate storage type/config pairing (catch common mismatches)
+        // Warn about deprecated gcs-native
+        if (config?.storage?.type === 'gcs-native') {
+            console.warn('⚠️  DEPRECATED: type "gcs-native" is deprecated. Use type "gcs" instead.');
+            console.warn('   This will continue to work but may be removed in a future version.');
+        }
+        // Validate storage type/config pairing (now more lenient)
         if (config?.storage) {
             const storage = config.storage;
-            // Check for gcs/gcsNativeStorage mismatch
-            if (storage.type === 'gcs' && storage.gcsNativeStorage) {
-                throw new Error(`Storage type/config mismatch: type 'gcs' requires 'gcsStorage' config object (S3-compatible). ` +
-                    `You provided 'gcsNativeStorage' which requires type 'gcs-native'. ` +
-                    `Either change type to 'gcs-native' or use 'gcsStorage' instead of 'gcsNativeStorage'.`);
-            }
-            // Check for gcs-native/gcsStorage mismatch
-            if (storage.type === 'gcs-native' && storage.gcsStorage) {
-                throw new Error(`Storage type/config mismatch: type 'gcs-native' requires 'gcsNativeStorage' config object. ` +
-                    `You provided 'gcsStorage' which requires type 'gcs' (S3-compatible). ` +
-                    `Either change type to 'gcs' or use 'gcsNativeStorage' instead of 'gcsStorage'.`);
+            // Warn about legacy gcsStorage config with HMAC keys
+            if (storage.gcsStorage && storage.gcsStorage.accessKeyId && storage.gcsStorage.secretAccessKey) {
+                console.warn('⚠️  GCS with HMAC keys (gcsStorage) is legacy. Consider migrating to native GCS (gcsNativeStorage) with ADC.');
             }
+            // No longer throw errors for mismatches - storageFactory now handles this intelligently
+            // Both 'gcs' and 'gcs-native' can now use either gcsStorage or gcsNativeStorage
         }
         // Validate model configuration
         if (config?.model?.type && !['fast', 'accurate', 'custom'].includes(config.model.type)) {

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

@@ -55,6 +55,8 @@ export declare class GcsStorage extends BaseStorage {
     private nounCacheManager;
     private verbCacheManager;
     private logger;
+    private skipInitialScan;
+    private skipCountsFile;
     /**
      * Initialize the storage adapter
      * @param options Configuration options for Google Cloud Storage
@@ -65,6 +67,8 @@ export declare class GcsStorage extends BaseStorage {
         credentials?: object;
         accessKeyId?: string;
         secretAccessKey?: string;
+        skipInitialScan?: boolean;
+        skipCountsFile?: boolean;
         cacheConfig?: {
             hotCacheMaxSize?: number;
             hotCacheEvictionThreshold?: number;
@@ -347,6 +351,7 @@ export declare class GcsStorage extends BaseStorage {
     protected initializeCounts(): Promise<void>;
     /**
      * Initialize counts from storage scan (expensive - only for first-time init)
+     * Includes timeout handling to prevent Cloud Run startup failures
      */
     private initializeCountsFromScan;
     /**

package/dist/storage/adapters/gcsStorage.js

@@ -64,11 +64,16 @@ export class GcsStorage extends BaseStorage {
         this.forceHighVolumeMode = false; // Environment variable override
         // Module logger
         this.logger = createModuleLogger('GcsStorage');
+        // Configuration options
+        this.skipInitialScan = false;
+        this.skipCountsFile = false;
         this.bucketName = options.bucketName;
         this.keyFilename = options.keyFilename;
         this.credentials = options.credentials;
         this.accessKeyId = options.accessKeyId;
         this.secretAccessKey = options.secretAccessKey;
+        this.skipInitialScan = options.skipInitialScan || false;
+        this.skipCountsFile = options.skipCountsFile || false;
         this.readOnly = options.readOnly || false;
         // Set up prefixes for different types of data using entity-based structure
         this.nounPrefix = `${getDirectoryPath('noun', 'vector')}/`;
@@ -1215,21 +1220,22 @@ export class GcsStorage extends BaseStorage {
             // Get bucket metadata
             const [metadata] = await this.bucket.getMetadata();
             return {
-                type: 'gcs',
+                type: 'gcs', // Consistent with new naming (native SDK is just 'gcs')
                 used: 0, // GCS doesn't provide usage info easily
                 quota: null, // No quota in GCS
                 details: {
                     bucket: this.bucketName,
                     location: metadata.location,
                     storageClass: metadata.storageClass,
-                    created: metadata.timeCreated
+                    created: metadata.timeCreated,
+                    sdk: 'native' // Indicate we're using native SDK
                 }
             };
         }
         catch (error) {
             this.logger.error('Failed to get storage status:', error);
             return {
-                type: 'gcs',
+                type: 'gcs', // Consistent with new naming
                 used: 0,
                 quota: null
             };
@@ -1301,6 +1307,15 @@ export class GcsStorage extends BaseStorage {
      * Initialize counts from storage
      */
     async initializeCounts() {
+        // Skip counts file entirely if configured
+        if (this.skipCountsFile) {
+            prodLog.info('📊 Skipping counts file (skipCountsFile: true)');
+            this.totalNounCount = 0;
+            this.totalVerbCount = 0;
+            this.entityCounts = new Map();
+            this.verbCounts = new Map();
+            return;
+        }
         const key = `${this.systemPrefix}counts.json`;
         try {
             const file = this.bucket.file(key);
@@ -1314,38 +1329,68 @@ export class GcsStorage extends BaseStorage {
         }
         catch (error) {
             if (error.code === 404) {
-                // No counts file yet - initialize from scan (first-time setup or counts not persisted)
-                prodLog.info('📊 No counts file found - this is normal for first init or if <10 entities were added');
-                await this.initializeCountsFromScan();
+                // No counts file yet
+                if (this.skipInitialScan) {
+                    prodLog.info('📊 No counts file found - starting with zero counts (skipInitialScan: true)');
+                    this.totalNounCount = 0;
+                    this.totalVerbCount = 0;
+                    this.entityCounts = new Map();
+                    this.verbCounts = new Map();
+                }
+                else {
+                    // Initialize from scan (first-time setup or counts not persisted)
+                    prodLog.info('📊 No counts file found - scanning bucket to initialize counts');
+                    await this.initializeCountsFromScan();
+                }
             }
             else {
                 // CRITICAL FIX: Don't silently fail on network/permission errors
                 this.logger.error('❌ CRITICAL: Failed to load counts from GCS:', error);
                 prodLog.error(`❌ Error loading ${key}: ${error.message}`);
-                // Try to recover by scanning the bucket
-                prodLog.warn('⚠️  Attempting recovery by scanning GCS bucket...');
-                await this.initializeCountsFromScan();
+                if (this.skipInitialScan) {
+                    prodLog.warn('⚠️  Starting with zero counts due to error (skipInitialScan: true)');
+                    this.totalNounCount = 0;
+                    this.totalVerbCount = 0;
+                    this.entityCounts = new Map();
+                    this.verbCounts = new Map();
+                }
+                else {
+                    // Try to recover by scanning the bucket
+                    prodLog.warn('⚠️  Attempting recovery by scanning GCS bucket...');
+                    await this.initializeCountsFromScan();
+                }
             }
         }
     }
     /**
      * Initialize counts from storage scan (expensive - only for first-time init)
+     * Includes timeout handling to prevent Cloud Run startup failures
      */
     async initializeCountsFromScan() {
+        const SCAN_TIMEOUT_MS = 120000; // 2 minutes timeout
         try {
             prodLog.info('📊 Scanning GCS bucket to initialize counts...');
             prodLog.info(`🔍 Noun prefix: ${this.nounPrefix}`);
             prodLog.info(`🔍 Verb prefix: ${this.verbPrefix}`);
-            // Count nouns
-            const [nounFiles] = await this.bucket.getFiles({ prefix: this.nounPrefix });
+            prodLog.info(`⏱️  Timeout: ${SCAN_TIMEOUT_MS / 1000}s (configure skipInitialScan to avoid this)`);
+            // Create timeout promise
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new Error(`Bucket scan timeout after ${SCAN_TIMEOUT_MS / 1000}s`));
+                }, SCAN_TIMEOUT_MS);
+            });
+            // Count nouns with timeout
+            const nounScanPromise = this.bucket.getFiles({ prefix: this.nounPrefix });
+            const [nounFiles] = await Promise.race([nounScanPromise, timeoutPromise]);
             prodLog.info(`🔍 Found ${nounFiles?.length || 0} total files under noun prefix`);
             const jsonNounFiles = nounFiles?.filter((f) => f.name?.endsWith('.json')) || [];
             this.totalNounCount = jsonNounFiles.length;
             if (jsonNounFiles.length > 0 && jsonNounFiles.length <= 5) {
                 prodLog.info(`📄 Sample noun files: ${jsonNounFiles.slice(0, 5).map((f) => f.name).join(', ')}`);
             }
-            // Count verbs
-            const [verbFiles] = await this.bucket.getFiles({ prefix: this.verbPrefix });
+            // Count verbs with timeout
+            const verbScanPromise = this.bucket.getFiles({ prefix: this.verbPrefix });
+            const [verbFiles] = await Promise.race([verbScanPromise, timeoutPromise]);
             prodLog.info(`🔍 Found ${verbFiles?.length || 0} total files under verb prefix`);
             const jsonVerbFiles = verbFiles?.filter((f) => f.name?.endsWith('.json')) || [];
             this.totalVerbCount = jsonVerbFiles.length;
@@ -1362,15 +1407,39 @@ export class GcsStorage extends BaseStorage {
             }
         }
         catch (error) {
+            // Handle timeout specifically
+            if (error.message?.includes('Bucket scan timeout')) {
+                prodLog.error(`❌ TIMEOUT: Bucket scan exceeded ${SCAN_TIMEOUT_MS / 1000}s limit`);
+                prodLog.error(`   This typically happens with large buckets in Cloud Run deployments.`);
+                prodLog.error(`   Solutions:`);
+                prodLog.error(`     1. Increase Cloud Run timeout: timeoutSeconds: 600`);
+                prodLog.error(`     2. Use skipInitialScan: true in gcsNativeStorage config`);
+                prodLog.error(`     3. Pre-create counts file before deployment`);
+                prodLog.warn(`⚠️  Starting with zero counts due to timeout`);
+                this.totalNounCount = 0;
+                this.totalVerbCount = 0;
+                this.entityCounts = new Map();
+                this.verbCounts = new Map();
+                return;
+            }
             // CRITICAL FIX: Don't silently fail - this prevents data loss scenarios
             this.logger.error('❌ CRITICAL: Failed to initialize counts from GCS bucket scan:', error);
-            throw new Error(`Failed to initialize GCS storage counts: ${error}. This prevents container restarts from working correctly.`);
+            prodLog.error(`   Error: ${error.message || String(error)}`);
+            prodLog.warn(`⚠️  Starting with zero counts due to error`);
+            this.totalNounCount = 0;
+            this.totalVerbCount = 0;
+            this.entityCounts = new Map();
+            this.verbCounts = new Map();
         }
     }
     /**
      * Persist counts to storage
      */
     async persistCounts() {
+        // Skip if skipCountsFile is enabled
+        if (this.skipCountsFile) {
+            return;
+        }
         try {
             const key = `${this.systemPrefix}counts.json`;
             const counts = {

package/dist/storage/storageFactory.d.ts

@@ -23,8 +23,8 @@ export interface StorageOptions {
      * - 'filesystem': Use file system storage (Node.js only)
      * - 's3': Use Amazon S3 storage
      * - 'r2': Use Cloudflare R2 storage
-     * - 'gcs': Use Google Cloud Storage (S3-compatible with HMAC keys)
-     * - 'gcs-native': Use Google Cloud Storage (native SDK with ADC)
+     * - 'gcs': Use Google Cloud Storage (native SDK with ADC)
+     * - 'gcs-native': DEPRECATED - Use 'gcs' instead
      * - 'azure': Use Azure Blob Storage (native SDK with Managed Identity)
      * - 'type-aware': Use type-first storage adapter (wraps another adapter)
      */
@@ -101,7 +101,9 @@ export interface StorageOptions {
         secretAccessKey: string;
     };
     /**
-     * Configuration for Google Cloud Storage (S3-compatible with HMAC keys)
+     * Configuration for Google Cloud Storage (Legacy S3-compatible with HMAC keys)
+     * @deprecated Use gcsNativeStorage instead for better performance with ADC
+     * This is only needed if you must use HMAC keys for backward compatibility
      */
     gcsStorage?: {
         /**
@@ -127,6 +129,8 @@ export interface StorageOptions {
     };
     /**
      * Configuration for Google Cloud Storage (native SDK with ADC)
+     * This is the recommended way to use GCS with Brainy
+     * Supports Application Default Credentials for zero-config cloud deployments
      */
     gcsNativeStorage?: {
         /**
@@ -143,12 +147,27 @@ export interface StorageOptions {
         credentials?: object;
         /**
          * HMAC access key ID (backward compatibility, not recommended)
+         * @deprecated Use ADC, keyFilename, or credentials instead
          */
         accessKeyId?: string;
         /**
          * HMAC secret access key (backward compatibility, not recommended)
+         * @deprecated Use ADC, keyFilename, or credentials instead
          */
         secretAccessKey?: string;
+        /**
+         * Skip initial bucket scan for counting entities
+         * Useful for large buckets where the scan would timeout
+         * If true, counts start at 0 and are updated incrementally
+         * @default false
+         */
+        skipInitialScan?: boolean;
+        /**
+         * Skip loading and saving the counts file entirely
+         * Useful for very large datasets where counts aren't critical
+         * @default false
+         */
+        skipCountsFile?: boolean;
     };
     /**
      * Configuration for Azure Blob Storage (native SDK with Managed Identity)

package/dist/storage/storageFactory.js

@@ -125,39 +125,48 @@ export async function createStorage(options = {}) {
                     console.warn('R2 storage configuration is missing, falling back to memory storage');
                     return new MemoryStorage();
                 }
-            case 'gcs':
-                if (options.gcsStorage) {
-                    console.log('Using Google Cloud Storage (S3-compatible)');
-                    return new S3CompatibleStorage({
-                        bucketName: options.gcsStorage.bucketName,
-                        region: options.gcsStorage.region,
-                        endpoint: options.gcsStorage.endpoint || 'https://storage.googleapis.com',
-                        accessKeyId: options.gcsStorage.accessKeyId,
-                        secretAccessKey: options.gcsStorage.secretAccessKey,
-                        serviceType: 'gcs',
-                        cacheConfig: options.cacheConfig
-                    });
-                }
-                else {
+            case 'gcs-native':
+                // DEPRECATED: gcs-native is deprecated in favor of just 'gcs'
+                console.warn('⚠️  DEPRECATED: type "gcs-native" is deprecated. Use type "gcs" instead.');
+                console.warn('   This will continue to work but may be removed in a future version.');
+            // Fall through to 'gcs' case
+            case 'gcs': {
+                // Prefer gcsNativeStorage, but also accept gcsStorage for backward compatibility
+                const gcsNative = options.gcsNativeStorage;
+                const gcsLegacy = options.gcsStorage;
+                if (!gcsNative && !gcsLegacy) {
                     console.warn('GCS storage configuration is missing, falling back to memory storage');
                     return new MemoryStorage();
                 }
-            case 'gcs-native':
-                if (options.gcsNativeStorage) {
-                    console.log('Using Google Cloud Storage (native SDK)');
-                    return new GcsStorage({
-                        bucketName: options.gcsNativeStorage.bucketName,
-                        keyFilename: options.gcsNativeStorage.keyFilename,
-                        credentials: options.gcsNativeStorage.credentials,
-                        accessKeyId: options.gcsNativeStorage.accessKeyId,
-                        secretAccessKey: options.gcsNativeStorage.secretAccessKey,
+                // 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({
+                        bucketName: gcsLegacy.bucketName,
+                        region: gcsLegacy.region,
+                        endpoint: gcsLegacy.endpoint || 'https://storage.googleapis.com',
+                        accessKeyId: gcsLegacy.accessKeyId,
+                        secretAccessKey: gcsLegacy.secretAccessKey,
+                        serviceType: 'gcs',
                         cacheConfig: options.cacheConfig
                     });
                 }
-                else {
-                    console.warn('GCS native storage configuration is missing, falling back to memory storage');
-                    return new MemoryStorage();
-                }
+                // Use native GCS SDK (the correct default!)
+                const config = gcsNative || gcsLegacy;
+                console.log('Using Google Cloud Storage (native SDK)');
+                return new GcsStorage({
+                    bucketName: config.bucketName,
+                    keyFilename: gcsNative?.keyFilename,
+                    credentials: gcsNative?.credentials,
+                    accessKeyId: config.accessKeyId,
+                    secretAccessKey: config.secretAccessKey,
+                    skipInitialScan: gcsNative?.skipInitialScan,
+                    skipCountsFile: gcsNative?.skipCountsFile,
+                    cacheConfig: options.cacheConfig
+                });
+            }
             case 'azure':
                 if (options.azureStorage) {
                     console.log('Using Azure Blob Storage (native SDK)');
@@ -233,28 +242,38 @@ export async function createStorage(options = {}) {
             cacheConfig: options.cacheConfig
         });
     }
-    // If GCS native storage is specified, use it (prioritize native over S3-compatible)
-    if (options.gcsNativeStorage) {
-        console.log('Using Google Cloud Storage (native SDK)');
+    // If GCS storage is specified (native or legacy S3-compatible)
+    // Prefer gcsNativeStorage, but also accept gcsStorage for backward compatibility
+    const gcsNative = options.gcsNativeStorage;
+    const gcsLegacy = options.gcsStorage;
+    if (gcsNative || gcsLegacy) {
+        // 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
+            console.log('Using Google Cloud Storage (S3-compatible with HMAC - auto-detected)');
+            return new S3CompatibleStorage({
+                bucketName: gcsLegacy.bucketName,
+                region: gcsLegacy.region,
+                endpoint: gcsLegacy.endpoint || 'https://storage.googleapis.com',
+                accessKeyId: gcsLegacy.accessKeyId,
+                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({
-            bucketName: options.gcsNativeStorage.bucketName,
-            keyFilename: options.gcsNativeStorage.keyFilename,
-            credentials: options.gcsNativeStorage.credentials,
-            accessKeyId: options.gcsNativeStorage.accessKeyId,
-            secretAccessKey: options.gcsNativeStorage.secretAccessKey,
-            cacheConfig: options.cacheConfig
-        });
-    }
-    // If GCS storage is specified, use it (S3-compatible)
-    if (options.gcsStorage) {
-        console.log('Using Google Cloud Storage (S3-compatible)');
-        return new S3CompatibleStorage({
-            bucketName: options.gcsStorage.bucketName,
-            region: options.gcsStorage.region,
-            endpoint: options.gcsStorage.endpoint || 'https://storage.googleapis.com',
-            accessKeyId: options.gcsStorage.accessKeyId,
-            secretAccessKey: options.gcsStorage.secretAccessKey,
-            serviceType: 'gcs',
+            bucketName: config.bucketName,
+            keyFilename: gcsNative?.keyFilename,
+            credentials: gcsNative?.credentials,
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            skipInitialScan: gcsNative?.skipInitialScan,
+            skipCountsFile: gcsNative?.skipCountsFile,
             cacheConfig: options.cacheConfig
         });
     }

package/dist/utils/embedding.js

@@ -10,7 +10,7 @@ import { pipeline, env } from '@huggingface/transformers';
 if (typeof process !== 'undefined' && process.env) {
     process.env.ORT_DISABLE_MEMORY_ARENA = '1';
     process.env.ORT_DISABLE_MEMORY_PATTERN = '1';
-    // Force single-threaded operation for maximum stability (Node.js 24 compatibility)
+    // Force single-threaded operation for maximum stability (Node.js 22 LTS)
     process.env.ORT_INTRA_OP_NUM_THREADS = '1'; // Single thread for operators
     process.env.ORT_INTER_OP_NUM_THREADS = '1'; // Single thread for sessions
     process.env.ORT_NUM_THREADS = '1'; // Additional safety override

package/dist/utils/environment.js

@@ -56,8 +56,8 @@ export async function areWorkerThreadsAvailable() {
 export function areWorkerThreadsAvailableSync() {
     if (!isNode())
         return false;
-    // In Node.js 24.4.0+, worker_threads is always available
-    return parseInt(process.versions.node.split('.')[0]) >= 24;
+    // In Node.js 22+, worker_threads is always available
+    return parseInt(process.versions.node.split('.')[0]) >= 22;
 }
 /**
  * Determine if threading is available in the current environment

package/dist/utils/workerUtils.d.ts

@@ -1,6 +1,6 @@
 /**
  * Utility functions for executing functions in Worker Threads (Node.js) or Web Workers (Browser)
- * This implementation leverages Node.js 24's improved Worker Threads API for better performance
+ * This implementation leverages Node.js 22's stable Worker Threads API for maximum reliability
  */
 /**
  * Execute a function in a separate thread

package/dist/utils/workerUtils.js

@@ -1,6 +1,6 @@
 /**
  * Utility functions for executing functions in Worker Threads (Node.js) or Web Workers (Browser)
- * This implementation leverages Node.js 24's improved Worker Threads API for better performance
+ * This implementation leverages Node.js 22's stable Worker Threads API for maximum reliability
  */
 import { isBrowser, isNode } from './environment.js';
 // Worker pool to reuse workers
@@ -64,7 +64,7 @@ export function executeInThread(fnString, args) {
 }
 /**
  * Execute a function in a Node.js Worker Thread
- * Optimized for Node.js 24 with improved Worker Threads performance
+ * Optimized for Node.js 22 LTS with stable Worker Threads performance
  */
 function executeInNodeWorker(fnString, args) {
     return new Promise((resolve, reject) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "4.0.2",
+  "version": "4.1.1",
   "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",
@@ -163,8 +163,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.540.0",
-    "@azure/identity": "^4.13.0",
-    "@azure/storage-blob": "^12.29.1",
+    "@azure/identity": "^4.0.0",
+    "@azure/storage-blob": "^12.17.0",
     "@google-cloud/storage": "^7.14.0",
     "@huggingface/transformers": "^3.7.2",
     "@msgpack/msgpack": "^3.1.2",

package/dist/augmentations/KnowledgeAugmentation.d.ts

@@ -1,40 +0,0 @@
-/**
- * Knowledge Layer Augmentation for VFS
- *
- * Adds intelligent features to VFS without modifying core functionality:
- * - Event recording for all operations
- * - Semantic versioning based on content changes
- * - Entity and concept extraction
- * - Git bridge for import/export
- *
- * This is a TRUE augmentation - VFS works perfectly without it
- */
-import { Brainy } from '../brainy.js';
-import { BaseAugmentation } from './brainyAugmentation.js';
-export declare class KnowledgeAugmentation extends BaseAugmentation {
-    name: string;
-    timing: 'after';
-    metadata: 'none';
-    operations: any;
-    priority: number;
-    constructor(config?: any);
-    execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
-    private eventRecorder?;
-    private semanticVersioning?;
-    private entitySystem?;
-    private conceptSystem?;
-    private gitBridge?;
-    private originalMethods;
-    initialize(context: any): Promise<void>;
-    augment(brain: Brainy): Promise<void>;
-    /**
-     * Wrap a VFS method to add Knowledge Layer functionality
-     */
-    private wrapMethod;
-    /**
-     * Add Knowledge Layer methods to VFS
-     */
-    private addKnowledgeMethods;
-    private isSemanticChange;
-    cleanup(brain: Brainy): Promise<void>;
-}