@soulcraft/brainy 5.11.1 → 6.0.0

package/dist/storage/baseStorage.js

@@ -39,32 +39,36 @@ export function getDirectoryPath(entityType, dataType) {
  * Built-in type-aware organization for all storage adapters
  */
 /**
- * Get type-first path for noun vectors
+ * Get ID-first path for noun vectors (v6.0.0)
+ * No type parameter needed - direct O(1) lookup by ID
  */
-function getNounVectorPath(type, id) {
+function getNounVectorPath(id) {
     const shard = getShardIdFromUuid(id);
-    return `entities/nouns/${type}/vectors/${shard}/${id}.json`;
+    return `entities/nouns/${shard}/${id}/vectors.json`;
 }
 /**
- * Get type-first path for noun metadata
+ * Get ID-first path for noun metadata (v6.0.0)
+ * No type parameter needed - direct O(1) lookup by ID
  */
-function getNounMetadataPath(type, id) {
+function getNounMetadataPath(id) {
     const shard = getShardIdFromUuid(id);
-    return `entities/nouns/${type}/metadata/${shard}/${id}.json`;
+    return `entities/nouns/${shard}/${id}/metadata.json`;
 }
 /**
- * Get type-first path for verb vectors
+ * Get ID-first path for verb vectors (v6.0.0)
+ * No type parameter needed - direct O(1) lookup by ID
  */
-function getVerbVectorPath(type, id) {
+function getVerbVectorPath(id) {
     const shard = getShardIdFromUuid(id);
-    return `entities/verbs/${type}/vectors/${shard}/${id}.json`;
+    return `entities/verbs/${shard}/${id}/vectors.json`;
 }
 /**
- * Get type-first path for verb metadata
+ * Get ID-first path for verb metadata (v6.0.0)
+ * No type parameter needed - direct O(1) lookup by ID
  */
-function getVerbMetadataPath(type, id) {
+function getVerbMetadataPath(id) {
     const shard = getShardIdFromUuid(id);
-    return `entities/verbs/${type}/metadata/${shard}/${id}.json`;
+    return `entities/verbs/${shard}/${id}/metadata.json`;
 }
 /**
  * Base storage adapter that implements common functionality
@@ -89,9 +93,9 @@ export class BaseStorage extends BaseStorageAdapter {
         this.nounCountsByType = new Uint32Array(NOUN_TYPE_COUNT); // 168 bytes (Stage 3: 42 types)
         this.verbCountsByType = new Uint32Array(VERB_TYPE_COUNT); // 508 bytes (Stage 3: 127 types)
         // Total: 676 bytes (99.2% reduction vs Map-based tracking)
-        // Type cache for O(1) lookups after first access
-        this.nounTypeCache = new Map();
-        this.verbTypeCache = new Map();
+        // v6.0.0: Type caches REMOVED - ID-first paths eliminate need for type lookups!
+        // With ID-first architecture, we construct paths directly from IDs: {SHARD}/{ID}/metadata.json
+        // Type is just a field in the metadata, indexed by MetadataIndexManager for queries
         // v5.5.0: Track if type counts have been rebuilt (prevent repeated rebuilds)
         this.typeCountsRebuilt = false;
     }
@@ -176,8 +180,33 @@ export class BaseStorage extends BaseStorageAdapter {
     async init() {
         // Load type statistics from storage (if they exist)
         await this.loadTypeStatistics();
+        // v6.0.0: Create GraphAdjacencyIndex (lazy-loaded, no rebuild)
+        // LSM-trees are initialized on first use via ensureInitialized()
+        // Index is populated incrementally as verbs are added via addVerb()
+        try {
+            prodLog.debug('[BaseStorage] Creating GraphAdjacencyIndex...');
+            this.graphIndex = new GraphAdjacencyIndex(this);
+            prodLog.debug(`[BaseStorage] GraphAdjacencyIndex instantiated (lazy-loaded), graphIndex=${!!this.graphIndex}`);
+        }
+        catch (error) {
+            prodLog.error('[BaseStorage] Failed to create GraphAdjacencyIndex:', error);
+            throw error;
+        }
         this.isInitialized = true;
     }
+    /**
+     * Rebuild GraphAdjacencyIndex from existing verbs (v6.0.0)
+     * Call this manually if you have existing verb data that needs to be indexed
+     * @public
+     */
+    async rebuildGraphIndex() {
+        if (!this.graphIndex) {
+            throw new Error('GraphAdjacencyIndex not initialized');
+        }
+        prodLog.info('[BaseStorage] Rebuilding graph index from existing data...');
+        await this.graphIndex.rebuild();
+        prodLog.info('[BaseStorage] Graph index rebuild complete');
+    }
     /**
      * Ensure the storage adapter is initialized
      */
@@ -851,60 +880,44 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async getNounsWithPagination(options) {
         await this.ensureInitialized();
-        const { limit, offset = 0, filter } = options; // cursor intentionally not extracted (not yet implemented)
+        const { limit, offset = 0, filter } = options;
         const collectedNouns = [];
-        const targetCount = offset + limit; // Early termination target
-        // v5.5.0 BUG FIX: Only use optimization if counts are reliable
-        const totalNounCountFromArray = this.nounCountsByType.reduce((sum, c) => sum + c, 0);
-        const useOptimization = totalNounCountFromArray > 0;
-        // v5.5.0: Iterate through noun types with billion-scale optimizations
-        for (let i = 0; i < NOUN_TYPE_COUNT && collectedNouns.length < targetCount; i++) {
-            // OPTIMIZATION 1: Skip empty types (only if counts are reliable)
-            if (useOptimization && this.nounCountsByType[i] === 0) {
-                continue;
-            }
-            const type = TypeUtils.getNounFromIndex(i);
-            // If filtering by type, skip other types
-            if (filter?.nounType) {
-                const filterTypes = Array.isArray(filter.nounType) ? filter.nounType : [filter.nounType];
-                if (!filterTypes.includes(type)) {
-                    continue;
-                }
-            }
-            const typeDir = `entities/nouns/${type}/vectors`;
+        const targetCount = offset + limit;
+        // v6.0.0: Iterate by shards (0x00-0xFF) instead of types
+        for (let shard = 0; shard < 256 && collectedNouns.length < targetCount; shard++) {
+            const shardHex = shard.toString(16).padStart(2, '0');
+            const shardDir = `entities/nouns/${shardHex}`;
             try {
-                // List all noun files for this type
-                const nounFiles = await this.listObjectsInBranch(typeDir);
+                const nounFiles = await this.listObjectsInBranch(shardDir);
                 for (const nounPath of nounFiles) {
-                    // OPTIMIZATION 2: Early termination (stop when we have enough)
-                    if (collectedNouns.length >= targetCount) {
+                    if (collectedNouns.length >= targetCount)
                         break;
-                    }
-                    // Skip if not a .json file
-                    if (!nounPath.endsWith('.json'))
+                    if (!nounPath.includes('/vectors.json'))
                         continue;
                     try {
-                        const rawNoun = await this.readWithInheritance(nounPath);
-                        if (rawNoun) {
-                            // v5.7.10: Deserialize connections Map from JSON storage format
-                            // Replaces v5.7.8 manual deserialization (removed 13 lines at 1156-1168)
-                            const noun = this.deserializeNoun(rawNoun);
-                            // Load metadata
-                            const metadataPath = getNounMetadataPath(type, noun.id);
-                            const metadata = await this.readWithInheritance(metadataPath);
+                        const noun = await this.readWithInheritance(nounPath);
+                        if (noun) {
+                            const deserialized = this.deserializeNoun(noun);
+                            const metadata = await this.getNounMetadata(deserialized.id);
                             if (metadata) {
-                                // Apply service filter if specified
+                                // Apply type filter
+                                if (filter?.nounType && metadata.noun) {
+                                    const types = Array.isArray(filter.nounType) ? filter.nounType : [filter.nounType];
+                                    if (!types.includes(metadata.noun)) {
+                                        continue;
+                                    }
+                                }
+                                // Apply service filter
                                 if (filter?.service) {
                                     const services = Array.isArray(filter.service) ? filter.service : [filter.service];
                                     if (metadata.service && !services.includes(metadata.service)) {
                                         continue;
                                     }
                                 }
-                                // Combine noun + metadata (v5.4.0: Extract standard fields to top-level)
+                                // Combine noun + metadata
                                 collectedNouns.push({
-                                    ...noun,
-                                    // v5.7.10: connections already deserialized by deserializeNoun()
-                                    type: metadata.noun || type, // Required: Extract type from metadata
+                                    ...deserialized,
+                                    type: (metadata.noun || 'thing'),
                                     confidence: metadata.confidence,
                                     weight: metadata.weight,
                                     createdAt: metadata.createdAt
@@ -927,15 +940,15 @@ export class BaseStorage extends BaseStorageAdapter {
                 }
             }
             catch (error) {
-                // Skip types that have no data
+                // Skip shards that have no data
             }
         }
-        // Apply pagination (v5.5.0: Efficient slicing after early termination)
+        // Apply pagination
         const paginatedNouns = collectedNouns.slice(offset, offset + limit);
-        const hasMore = collectedNouns.length > targetCount; // v5.7.11: Fixed >= to > (was causing infinite loop)
+        const hasMore = collectedNouns.length > targetCount;
         return {
             items: paginatedNouns,
-            totalCount: collectedNouns.length, // Accurate count of collected results
+            totalCount: collectedNouns.length,
             hasMore,
             nextCursor: hasMore && paginatedNouns.length > 0
                 ? paginatedNouns[paginatedNouns.length - 1].id
@@ -962,58 +975,70 @@ export class BaseStorage extends BaseStorageAdapter {
         const { limit, offset = 0, filter } = options; // cursor intentionally not extracted (not yet implemented)
         const collectedVerbs = [];
         const targetCount = offset + limit; // Early termination target
-        // v5.5.0 BUG FIX: Only use optimization if counts are reliable
-        const totalVerbCountFromArray = this.verbCountsByType.reduce((sum, c) => sum + c, 0);
-        const useOptimization = totalVerbCountFromArray > 0;
-        // v5.5.0: Iterate through verb types with billion-scale optimizations
-        for (let i = 0; i < VERB_TYPE_COUNT && collectedVerbs.length < targetCount; i++) {
-            // OPTIMIZATION 1: Skip empty types (only if counts are reliable)
-            if (useOptimization && this.verbCountsByType[i] === 0) {
-                continue;
-            }
-            const type = TypeUtils.getVerbFromIndex(i);
-            // If filtering by verbType, skip other types
-            if (filter?.verbType) {
-                const filterTypes = Array.isArray(filter.verbType) ? filter.verbType : [filter.verbType];
-                if (!filterTypes.includes(type)) {
-                    continue;
-                }
-            }
+        // Prepare filter sets for efficient lookup
+        const filterVerbTypes = filter?.verbType
+            ? new Set(Array.isArray(filter.verbType) ? filter.verbType : [filter.verbType])
+            : null;
+        const filterSourceIds = filter?.sourceId
+            ? new Set(Array.isArray(filter.sourceId) ? filter.sourceId : [filter.sourceId])
+            : null;
+        const filterTargetIds = filter?.targetId
+            ? new Set(Array.isArray(filter.targetId) ? filter.targetId : [filter.targetId])
+            : null;
+        // v6.0.0: Iterate by shards (0x00-0xFF) instead of types - single pass!
+        for (let shard = 0; shard < 256 && collectedVerbs.length < targetCount; shard++) {
+            const shardHex = shard.toString(16).padStart(2, '0');
+            const shardDir = `entities/verbs/${shardHex}`;
             try {
-                const verbsOfType = await this.getVerbsByType_internal(type);
-                // Apply filtering inline (memory efficient)
-                for (const verb of verbsOfType) {
-                    // OPTIMIZATION 2: Early termination (stop when we have enough)
-                    if (collectedVerbs.length >= targetCount) {
+                const verbFiles = await this.listObjectsInBranch(shardDir);
+                for (const verbPath of verbFiles) {
+                    if (collectedVerbs.length >= targetCount)
                         break;
-                    }
-                    // Apply filters if specified
-                    if (filter) {
-                        // Filter by sourceId
-                        if (filter.sourceId) {
-                            const sourceIds = Array.isArray(filter.sourceId)
-                                ? filter.sourceId
-                                : [filter.sourceId];
-                            if (!sourceIds.includes(verb.sourceId)) {
-                                continue;
-                            }
+                    if (!verbPath.includes('/vectors.json'))
+                        continue;
+                    try {
+                        const rawVerb = await this.readWithInheritance(verbPath);
+                        if (!rawVerb)
+                            continue;
+                        // v6.0.0: Deserialize connections Map from JSON storage format
+                        const verb = this.deserializeVerb(rawVerb);
+                        // Apply type filter
+                        if (filterVerbTypes && !filterVerbTypes.has(verb.verb)) {
+                            continue;
                         }
-                        // Filter by targetId
-                        if (filter.targetId) {
-                            const targetIds = Array.isArray(filter.targetId)
-                                ? filter.targetId
-                                : [filter.targetId];
-                            if (!targetIds.includes(verb.targetId)) {
-                                continue;
-                            }
+                        // Apply sourceId filter
+                        if (filterSourceIds && !filterSourceIds.has(verb.sourceId)) {
+                            continue;
+                        }
+                        // Apply targetId filter
+                        if (filterTargetIds && !filterTargetIds.has(verb.targetId)) {
+                            continue;
                         }
+                        // Load metadata
+                        const metadata = await this.getVerbMetadata(verb.id);
+                        // Combine verb + metadata
+                        collectedVerbs.push({
+                            ...verb,
+                            weight: metadata?.weight,
+                            confidence: metadata?.confidence,
+                            createdAt: metadata?.createdAt
+                                ? (typeof metadata.createdAt === 'number' ? metadata.createdAt : metadata.createdAt.seconds * 1000)
+                                : Date.now(),
+                            updatedAt: metadata?.updatedAt
+                                ? (typeof metadata.updatedAt === 'number' ? metadata.updatedAt : metadata.updatedAt.seconds * 1000)
+                                : Date.now(),
+                            service: metadata?.service,
+                            createdBy: metadata?.createdBy,
+                            metadata: metadata || {}
+                        });
+                    }
+                    catch (error) {
+                        // Skip verbs that fail to load
                     }
-                    // Verb passed all filters - add to collection
-                    collectedVerbs.push(verb);
                 }
             }
             catch (error) {
-                // Skip types that have no data (directory may not exist)
+                // Skip shards that have no data
             }
         }
         // Apply pagination (v5.5.0: Efficient slicing after early termination)
@@ -1386,11 +1411,8 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async saveNounMetadata_internal(id, metadata) {
         await this.ensureInitialized();
-        // v5.4.0: Extract and cache type for type-first routing
-        const type = (metadata.noun || 'thing');
-        this.nounTypeCache.set(id, type);
-        // v5.4.0: Use type-first path
-        const path = getNounMetadataPath(type, id);
+        // v6.0.0: ID-first path - no type needed!
+        const path = getNounMetadataPath(id);
         // Determine if this is a new entity by checking if metadata already exists
         const existingMetadata = await this.readWithInheritance(path);
         const isNew = !existingMetadata;
@@ -1411,6 +1433,17 @@ export class BaseStorage extends BaseStorageAdapter {
     /**
      * Get noun metadata from storage (METADATA-ONLY, NO VECTORS)
      *
+     * **Performance (v6.0.0)**: Direct O(1) ID-first lookup - NO type search needed!
+     * - **All lookups**: 1 read, ~500ms on cloud (consistent performance)
+     * - **No cache needed**: Type is in the metadata, not the path
+     * - **No type search**: ID-first paths eliminate 42-type search entirely
+     *
+     * **Clean architecture (v6.0.0)**:
+     * - Path: `entities/nouns/{SHARD}/{ID}/metadata.json`
+     * - Type is just a field in metadata (`noun: "document"`)
+     * - MetadataIndex handles type queries (no path scanning needed)
+     * - Scales to billions without any overhead
+     *
      * **Performance (v5.11.1)**: Fast path for metadata-only reads
      * - **Speed**: 10ms vs 43ms (76-81% faster than getNoun)
      * - **Bandwidth**: 300 bytes vs 6KB (95% less)
@@ -1440,71 +1473,236 @@ export class BaseStorage extends BaseStorageAdapter {
      * @returns Metadata or null if not found
      *
      * @performance
-     * - Type cache O(1) lookup for cached entities
-     * - Type scan O(N_types) for cache misses (typically <100ms)
-     * - Uses readWithInheritance() for COW branch support
+     * - O(1) direct ID lookup - always 1 read (~500ms on cloud, ~10ms local)
+     * - No caching complexity
+     * - No type search fallbacks
+     * - Works in distributed systems without sync issues
      *
      * @since v4.0.0
-     * @since v5.4.0 - Type-first paths
+     * @since v5.4.0 - Type-first paths (removed in v6.0.0)
      * @since v5.11.1 - Promoted to fast path for brain.get() optimization
+     * @since v6.0.0 - CLEAN FIX: ID-first paths eliminate all type-search complexity
      */
     async getNounMetadata(id) {
         await this.ensureInitialized();
-        // v5.4.0: Check type cache first (populated during save)
-        const cachedType = this.nounTypeCache.get(id);
-        if (cachedType) {
-            const path = getNounMetadataPath(cachedType, id);
-            return this.readWithInheritance(path);
-        }
-        // Fallback: search across all types (expensive but necessary if cache miss)
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-            const type = TypeUtils.getNounFromIndex(i);
-            const path = getNounMetadataPath(type, id);
-            try {
-                const metadata = await this.readWithInheritance(path);
-                if (metadata) {
-                    // Cache the type for next time
-                    this.nounTypeCache.set(id, type);
-                    return metadata;
-                }
-            }
-            catch (error) {
-                // Not in this type, continue searching
+        // v6.0.0: Clean, simple, O(1) lookup - no type needed!
+        const path = getNounMetadataPath(id);
+        return this.readWithInheritance(path);
+    }
+    /**
+     * Batch fetch noun metadata from storage (v5.12.0 - Cloud Storage Optimization)
+     *
+     * **Performance**: Reduces N sequential calls → 1-2 batch calls
+     * - Local storage: N × 10ms → 1 × 10ms parallel (N× faster)
+     * - Cloud storage: N × 300ms → 1 × 300ms batch (N× faster)
+     *
+     * **Use cases:**
+     * - VFS tree traversal (fetch all children at once)
+     * - brain.find() result hydration (batch load entities)
+     * - brain.getRelations() target entities (eliminate N+1)
+     * - Import operations (batch existence checks)
+     *
+     * @param ids Array of entity IDs to fetch
+     * @returns Map of id → metadata (only successful fetches included)
+     *
+     * @example
+     * ```typescript
+     * // Before (N+1 pattern)
+     * for (const id of ids) {
+     *   const metadata = await storage.getNounMetadata(id)  // N calls
+     * }
+     *
+     * // After (batched)
+     * const metadataMap = await storage.getNounMetadataBatch(ids)  // 1 call
+     * for (const id of ids) {
+     *   const metadata = metadataMap.get(id)
+     * }
+     * ```
+     *
+     * @since v5.12.0
+     */
+    async getNounMetadataBatch(ids) {
+        await this.ensureInitialized();
+        const results = new Map();
+        if (ids.length === 0)
+            return results;
+        // v6.0.0: ID-first paths - no type grouping or search needed!
+        // Build direct paths for all IDs
+        const pathsToFetch = ids.map(id => ({
+            path: getNounMetadataPath(id),
+            id
+        }));
+        // Batch read all paths (uses adapter's native batch API or parallel fallback)
+        const batchResults = await this.readBatchWithInheritance(pathsToFetch.map(p => p.path));
+        // Map results back to IDs
+        for (const { path, id } of pathsToFetch) {
+            const metadata = batchResults.get(path);
+            if (metadata) {
+                results.set(id, metadata);
             }
         }
-        return null;
+        return results;
     }
     /**
-     * Delete noun metadata from storage
-     * v5.4.0: Uses type-first paths (must match saveNounMetadata_internal)
+     * Batch read multiple storage paths with COW inheritance support (v5.12.0)
+     *
+     * Core batching primitive that all batch operations build upon.
+     * Handles write cache, branch inheritance, and adapter-specific batching.
+     *
+     * **Performance**:
+     * - Uses adapter's native batch API when available (GCS, S3, Azure)
+     * - Falls back to parallel reads for non-batch adapters
+     * - Respects rate limits via StorageBatchConfig
+     *
+     * @param paths Array of storage paths to read
+     * @param branch Optional branch (defaults to current branch)
+     * @returns Map of path → data (only successful reads included)
+     *
+     * @protected - Available to subclasses and batch operations
+     * @since v5.12.0
      */
-    async deleteNounMetadata(id) {
-        await this.ensureInitialized();
-        // v5.4.0: Use cached type for path
-        const cachedType = this.nounTypeCache.get(id);
-        if (cachedType) {
-            const path = getNounMetadataPath(cachedType, id);
-            await this.deleteObjectFromBranch(path);
-            // Remove from cache after deletion
-            this.nounTypeCache.delete(id);
-            return;
+    async readBatchWithInheritance(paths, branch) {
+        if (paths.length === 0)
+            return new Map();
+        const targetBranch = branch || this.currentBranch || 'main';
+        const results = new Map();
+        // Resolve all paths to branch-specific paths
+        const branchPaths = paths.map(path => ({
+            original: path,
+            resolved: this.resolveBranchPath(path, targetBranch)
+        }));
+        // Step 1: Check write cache first (synchronous, instant)
+        const pathsToFetch = [];
+        const pathMapping = new Map(); // resolved → original
+        for (const { original, resolved } of branchPaths) {
+            const cachedData = this.writeCache.get(resolved);
+            if (cachedData !== undefined) {
+                results.set(original, cachedData);
+            }
+            else {
+                pathsToFetch.push(resolved);
+                pathMapping.set(resolved, original);
+            }
         }
-        // If not in cache, search all types to find and delete
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-            const type = TypeUtils.getNounFromIndex(i);
-            const path = getNounMetadataPath(type, id);
-            try {
-                // Check if exists before deleting
-                const exists = await this.readWithInheritance(path);
-                if (exists) {
-                    await this.deleteObjectFromBranch(path);
-                    return;
+        if (pathsToFetch.length === 0) {
+            return results; // All in write cache
+        }
+        // Step 2: Batch read from adapter
+        // Check if adapter supports native batch operations
+        const batchData = await this.readBatchFromAdapter(pathsToFetch);
+        // Step 3: Process results and handle inheritance for missing items
+        const missingPaths = [];
+        for (const [resolvedPath, data] of batchData.entries()) {
+            const originalPath = pathMapping.get(resolvedPath);
+            if (originalPath && data !== null) {
+                results.set(originalPath, data);
+            }
+        }
+        // Identify paths that weren't found
+        for (const resolvedPath of pathsToFetch) {
+            if (!batchData.has(resolvedPath) || batchData.get(resolvedPath) === null) {
+                missingPaths.push(pathMapping.get(resolvedPath));
+            }
+        }
+        // Step 4: Handle COW inheritance for missing items (if not on main branch)
+        if (targetBranch !== 'main' && missingPaths.length > 0) {
+            // For now, fall back to individual inheritance lookups
+            // TODO v5.13.0: Optimize inheritance with batch commit walks
+            for (const originalPath of missingPaths) {
+                try {
+                    const data = await this.readWithInheritance(originalPath, targetBranch);
+                    if (data !== null) {
+                        results.set(originalPath, data);
+                    }
+                }
+                catch (error) {
+                    // Skip failed reads (they won't be in results map)
                 }
             }
+        }
+        return results;
+    }
+    /**
+     * Adapter-level batch read with automatic batching strategy (v5.12.0)
+     *
+     * Uses adapter's native batch API when available:
+     * - GCS: batch API (100 ops)
+     * - S3/R2: batch operations (1000 ops)
+     * - Azure: batch API (100 ops)
+     * - Others: parallel reads via Promise.all()
+     *
+     * Automatically chunks large batches based on adapter's maxBatchSize.
+     *
+     * @param paths Array of resolved storage paths
+     * @returns Map of path → data
+     *
+     * @private
+     * @since v5.12.0
+     */
+    async readBatchFromAdapter(paths) {
+        if (paths.length === 0)
+            return new Map();
+        // Check if this class implements batch operations (will be added to cloud adapters)
+        const selfWithBatch = this;
+        if (typeof selfWithBatch.readBatch === 'function') {
+            // Adapter has native batch support - use it
+            try {
+                return await selfWithBatch.readBatch(paths);
+            }
             catch (error) {
-                // Not in this type, continue searching
+                // Fall back to parallel reads on batch failure
+                prodLog.warn(`Batch read failed, falling back to parallel: ${error}`);
             }
         }
+        // Fallback: Parallel individual reads
+        // Respect adapter's maxConcurrent limit
+        const batchConfig = this.getBatchConfig();
+        const chunkSize = batchConfig.maxConcurrent || 50;
+        const results = new Map();
+        for (let i = 0; i < paths.length; i += chunkSize) {
+            const chunk = paths.slice(i, i + chunkSize);
+            const chunkResults = await Promise.allSettled(chunk.map(async (path) => ({
+                path,
+                data: await this.readObjectFromPath(path)
+            })));
+            for (const result of chunkResults) {
+                if (result.status === 'fulfilled' && result.value.data !== null) {
+                    results.set(result.value.path, result.value.data);
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Get batch configuration for this storage adapter (v5.12.0)
+     *
+     * Override in subclasses to provide adapter-specific batch limits.
+     * Defaults to conservative limits for safety.
+     *
+     * @public - Inherited from BaseStorageAdapter
+     * @since v5.12.0
+     */
+    getBatchConfig() {
+        // Conservative defaults - adapters should override with their actual limits
+        return {
+            maxBatchSize: 100,
+            batchDelayMs: 0,
+            maxConcurrent: 50,
+            supportsParallelWrites: true,
+            rateLimit: {
+                operationsPerSecond: 1000,
+                burstCapacity: 5000
+            }
+        };
+    }
+    /**
+     * Delete noun metadata from storage (v6.0.0: ID-first, O(1) delete)
+     */
+    async deleteNounMetadata(id) {
+        await this.ensureInitialized();
+        // v6.0.0: Direct O(1) delete with ID-first path
+        const path = getNounMetadataPath(id);
+        await this.deleteObjectFromBranch(path);
     }
     /**
      * Save verb metadata to storage (v4.0.0: now typed)
@@ -1516,7 +1714,7 @@ export class BaseStorage extends BaseStorageAdapter {
     }
     /**
      * Internal method for saving verb metadata (v4.0.0: now typed)
-     * v5.4.0: Uses type-first paths (must match getVerbMetadata)
+     * v5.4.0: Uses ID-first paths (must match getVerbMetadata)
      *
      * CRITICAL (v4.1.2): Count synchronization happens here
      * This ensures verb counts are updated AFTER metadata exists, fixing the race condition
@@ -1528,7 +1726,7 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async saveVerbMetadata_internal(id, metadata) {
         await this.ensureInitialized();
-        // v5.4.0: Extract verb type from metadata for type-first path
+        // v5.4.0: Extract verb type from metadata for ID-first path
         const verbType = metadata.verb;
         if (!verbType) {
             // Backward compatibility: fallback to old path if no verb type
@@ -1536,15 +1734,14 @@ export class BaseStorage extends BaseStorageAdapter {
             await this.writeObjectToBranch(keyInfo.fullPath, metadata);
             return;
         }
-        // v5.4.0: Use type-first path
-        const path = getVerbMetadataPath(verbType, id);
+        // v5.4.0: Use ID-first path
+        const path = getVerbMetadataPath(id);
         // Determine if this is a new verb by checking if metadata already exists
         const existingMetadata = await this.readWithInheritance(path);
         const isNew = !existingMetadata;
         // Save the metadata (COW-aware - writes to branch-specific path)
         await this.writeObjectToBranch(path, metadata);
         // v5.4.0: Cache verb type for faster lookups
-        this.verbTypeCache.set(id, verbType);
         // CRITICAL FIX (v4.1.2): Increment verb count for new relationships
         // This runs AFTER metadata is saved
         // Uses synchronous increment since storage operations are already serialized
@@ -1559,69 +1756,34 @@ export class BaseStorage extends BaseStorageAdapter {
     }
     /**
      * Get verb metadata from storage (v4.0.0: now typed)
-     * v5.4.0: Uses type-first paths (must match saveVerbMetadata_internal)
+     * v5.4.0: Uses ID-first paths (must match saveVerbMetadata_internal)
      */
     async getVerbMetadata(id) {
         await this.ensureInitialized();
-        // v5.4.0: Check type cache first (populated during save)
-        const cachedType = this.verbTypeCache.get(id);
-        if (cachedType) {
-            const path = getVerbMetadataPath(cachedType, id);
-            return this.readWithInheritance(path);
-        }
-        // Fallback: search across all types (expensive but necessary if cache miss)
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const path = getVerbMetadataPath(type, id);
-            try {
-                const metadata = await this.readWithInheritance(path);
-                if (metadata) {
-                    // Cache the type for next time
-                    this.verbTypeCache.set(id, type);
-                    return metadata;
-                }
-            }
-            catch (error) {
-                // Not in this type, continue searching
-            }
+        // v6.0.0: Direct O(1) lookup with ID-first paths - no type search needed!
+        const path = getVerbMetadataPath(id);
+        try {
+            const metadata = await this.readWithInheritance(path);
+            return metadata || null;
+        }
+        catch (error) {
+            // Entity not found
+            return null;
         }
-        return null;
     }
     /**
-     * Delete verb metadata from storage
-     * v5.4.0: Uses type-first paths (must match saveVerbMetadata_internal)
+     * Delete verb metadata from storage (v6.0.0: ID-first, O(1) delete)
      */
     async deleteVerbMetadata(id) {
         await this.ensureInitialized();
-        // v5.4.0: Use cached type for path
-        const cachedType = this.verbTypeCache.get(id);
-        if (cachedType) {
-            const path = getVerbMetadataPath(cachedType, id);
-            await this.deleteObjectFromBranch(path);
-            // Remove from cache after deletion
-            this.verbTypeCache.delete(id);
-            return;
-        }
-        // If not in cache, search all types to find and delete
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const path = getVerbMetadataPath(type, id);
-            try {
-                // Check if exists before deleting
-                const exists = await this.readWithInheritance(path);
-                if (exists) {
-                    await this.deleteObjectFromBranch(path);
-                    return;
-                }
-            }
-            catch (error) {
-                // Not in this type, continue searching
-            }
-        }
+        // v6.0.0: Direct O(1) delete with ID-first path
+        const path = getVerbMetadataPath(id);
+        await this.deleteObjectFromBranch(path);
     }
     // ============================================================================
-    // TYPE-FIRST HELPER METHODS (v5.4.0)
-    // Built-in type-aware support for all storage adapters
+    // ID-FIRST HELPER METHODS (v6.0.0)
+    // Direct O(1) ID lookups - no type needed!
+    // Clean, simple architecture for billion-scale performance
     // ============================================================================
     /**
      * Load type statistics from storage
@@ -1663,30 +1825,61 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async rebuildTypeCounts() {
         prodLog.info('[BaseStorage] Rebuilding type counts from storage...');
-        // Rebuild verb counts by checking each type directory
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const prefix = `entities/verbs/${type}/vectors/`;
+        // v6.0.0: Rebuild by scanning shards (0x00-0xFF) and reading metadata
+        this.nounCountsByType = new Uint32Array(NOUN_TYPE_COUNT);
+        this.verbCountsByType = new Uint32Array(VERB_TYPE_COUNT);
+        // Scan noun shards
+        for (let shard = 0; shard < 256; shard++) {
+            const shardHex = shard.toString(16).padStart(2, '0');
+            const shardDir = `entities/nouns/${shardHex}`;
             try {
-                const paths = await this.listObjectsInBranch(prefix);
-                this.verbCountsByType[i] = paths.length;
+                const paths = await this.listObjectsInBranch(shardDir);
+                for (const path of paths) {
+                    if (!path.includes('/metadata.json'))
+                        continue;
+                    try {
+                        const metadata = await this.readWithInheritance(path);
+                        if (metadata && metadata.noun) {
+                            const typeIndex = TypeUtils.getNounIndex(metadata.noun);
+                            if (typeIndex >= 0 && typeIndex < NOUN_TYPE_COUNT) {
+                                this.nounCountsByType[typeIndex]++;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        // Skip entities that fail to load
+                    }
+                }
             }
             catch (error) {
-                // Type directory doesn't exist - count is 0
-                this.verbCountsByType[i] = 0;
+                // Skip shards that don't exist
             }
         }
-        // Rebuild noun counts similarly
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-            const type = TypeUtils.getNounFromIndex(i);
-            const prefix = `entities/nouns/${type}/vectors/`;
+        // Scan verb shards
+        for (let shard = 0; shard < 256; shard++) {
+            const shardHex = shard.toString(16).padStart(2, '0');
+            const shardDir = `entities/verbs/${shardHex}`;
             try {
-                const paths = await this.listObjectsInBranch(prefix);
-                this.nounCountsByType[i] = paths.length;
+                const paths = await this.listObjectsInBranch(shardDir);
+                for (const path of paths) {
+                    if (!path.includes('/metadata.json'))
+                        continue;
+                    try {
+                        const metadata = await this.readWithInheritance(path);
+                        if (metadata && metadata.verb) {
+                            const typeIndex = TypeUtils.getVerbIndex(metadata.verb);
+                            if (typeIndex >= 0 && typeIndex < VERB_TYPE_COUNT) {
+                                this.verbCountsByType[typeIndex]++;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        // Skip entities that fail to load
+                    }
+                }
             }
             catch (error) {
-                // Type directory doesn't exist - count is 0
-                this.nounCountsByType[i] = 0;
+                // Skip shards that don't exist
             }
         }
         // Save rebuilt counts to storage
@@ -1696,18 +1889,13 @@ export class BaseStorage extends BaseStorageAdapter {
         prodLog.info(`[BaseStorage] Rebuilt counts: ${totalNouns} nouns, ${totalVerbs} verbs`);
     }
     /**
-     * Get noun type from cache or metadata
-     * Relies on nounTypeCache populated during metadata saves
+     * Get noun type (v6.0.0: type no longer needed for paths!)
+     * With ID-first paths, this is only used for internal statistics tracking.
+     * The actual type is stored in metadata and indexed by MetadataIndexManager.
      */
     getNounType(noun) {
-        // Check cache (populated when metadata is saved)
-        const cached = this.nounTypeCache.get(noun.id);
-        if (cached) {
-            return cached;
-        }
-        // Default to 'thing' if unknown
-        // This should only happen if saveNoun_internal is called before saveNounMetadata
-        prodLog.warn(`[BaseStorage] Unknown noun type for ${noun.id}, defaulting to 'thing'`);
+        // v6.0.0: Type cache removed - default to 'thing' for statistics
+        // The real type is in metadata, accessible via getNounMetadata(id)
         return 'thing';
     }
     /**
@@ -1790,15 +1978,14 @@ export class BaseStorage extends BaseStorageAdapter {
     // Converted from abstract to concrete - all adapters now have built-in type-aware
     // ============================================================================
     /**
-     * Save a noun to storage (type-first path)
+     * Save a noun to storage (ID-first path)
      */
     async saveNoun_internal(noun) {
         const type = this.getNounType(noun);
-        const path = getNounVectorPath(type, noun.id);
+        const path = getNounVectorPath(noun.id);
         // Update type tracking
         const typeIndex = TypeUtils.getNounIndex(type);
         this.nounCountsByType[typeIndex]++;
-        this.nounTypeCache.set(noun.id, type);
         // COW-aware write (v5.0.1): Use COW helper for branch isolation
         await this.writeObjectToBranch(path, noun);
         // Periodically save statistics (every 100 saves)
@@ -1807,120 +1994,89 @@ export class BaseStorage extends BaseStorageAdapter {
         }
     }
     /**
-     * Get a noun from storage (type-first path)
+     * Get a noun from storage (ID-first path)
      */
     async getNoun_internal(id) {
-        // Try cache first
-        const cachedType = this.nounTypeCache.get(id);
-        if (cachedType) {
-            const path = getNounVectorPath(cachedType, id);
+        // v6.0.0: Direct O(1) lookup with ID-first paths - no type search needed!
+        const path = getNounVectorPath(id);
+        try {
             // COW-aware read (v5.0.1): Use COW helper for branch isolation
-            const data = await this.readWithInheritance(path);
-            // v5.7.10: Deserialize connections Map from JSON storage format
-            return data ? this.deserializeNoun(data) : null;
-        }
-        // Need to search across all types (expensive, but cached after first access)
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-            const type = TypeUtils.getNounFromIndex(i);
-            const path = getNounVectorPath(type, id);
-            try {
-                // COW-aware read (v5.0.1): Use COW helper for branch isolation
-                const noun = await this.readWithInheritance(path);
-                if (noun) {
-                    // Cache the type for next time
-                    this.nounTypeCache.set(id, type);
-                    // v5.7.10: Deserialize connections Map from JSON storage format
-                    return this.deserializeNoun(noun);
-                }
-            }
-            catch (error) {
-                // Not in this type, continue searching
+            const noun = await this.readWithInheritance(path);
+            if (noun) {
+                // v5.7.10: Deserialize connections Map from JSON storage format
+                return this.deserializeNoun(noun);
             }
         }
+        catch (error) {
+            // Entity not found
+            return null;
+        }
         return null;
     }
     /**
-     * Get nouns by noun type (O(1) with type-first paths!)
+     * Get nouns by noun type (v6.0.0: Shard-based iteration!)
      */
     async getNounsByNounType_internal(nounType) {
-        const type = nounType;
-        const prefix = `entities/nouns/${type}/vectors/`;
-        // COW-aware list (v5.0.1): Use COW helper for branch isolation
-        const paths = await this.listObjectsInBranch(prefix);
-        // Load all nouns of this type
+        // v6.0.0: Iterate by shards (0x00-0xFF) instead of types
+        // Type is stored in metadata.noun field, we filter as we load
         const nouns = [];
-        for (const path of paths) {
+        for (let shard = 0; shard < 256; shard++) {
+            const shardHex = shard.toString(16).padStart(2, '0');
+            const shardDir = `entities/nouns/${shardHex}`;
             try {
-                // COW-aware read (v5.0.1): Use COW helper for branch isolation
-                const noun = await this.readWithInheritance(path);
-                if (noun) {
-                    // v5.7.10: Deserialize connections Map from JSON storage format
-                    nouns.push(this.deserializeNoun(noun));
-                    // Cache the type
-                    this.nounTypeCache.set(noun.id, type);
+                const nounFiles = await this.listObjectsInBranch(shardDir);
+                for (const nounPath of nounFiles) {
+                    if (!nounPath.includes('/vectors.json'))
+                        continue;
+                    try {
+                        const noun = await this.readWithInheritance(nounPath);
+                        if (noun) {
+                            const deserialized = this.deserializeNoun(noun);
+                            // Check type from metadata
+                            const metadata = await this.getNounMetadata(deserialized.id);
+                            if (metadata && metadata.noun === nounType) {
+                                nouns.push(deserialized);
+                            }
+                        }
+                    }
+                    catch (error) {
+                        // Skip nouns that fail to load
+                    }
                 }
             }
             catch (error) {
-                prodLog.warn(`[BaseStorage] Failed to load noun from ${path}:`, error);
+                // Skip shards that have no data
             }
         }
         return nouns;
     }
     /**
-     * Delete a noun from storage (type-first path)
+     * Delete a noun from storage (v6.0.0: ID-first, O(1) delete)
      */
     async deleteNoun_internal(id) {
-        // Try cache first
-        const cachedType = this.nounTypeCache.get(id);
-        if (cachedType) {
-            const path = getNounVectorPath(cachedType, id);
-            // COW-aware delete (v5.0.1): Use COW helper for branch isolation
-            await this.deleteObjectFromBranch(path);
-            // Update counts
-            const typeIndex = TypeUtils.getNounIndex(cachedType);
-            if (this.nounCountsByType[typeIndex] > 0) {
-                this.nounCountsByType[typeIndex]--;
-            }
-            this.nounTypeCache.delete(id);
-            return;
-        }
-        // Search across all types
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-            const type = TypeUtils.getNounFromIndex(i);
-            const path = getNounVectorPath(type, id);
-            try {
-                // COW-aware delete (v5.0.1): Use COW helper for branch isolation
-                await this.deleteObjectFromBranch(path);
-                // Update counts
-                if (this.nounCountsByType[i] > 0) {
-                    this.nounCountsByType[i]--;
-                }
-                this.nounTypeCache.delete(id);
-                return;
-            }
-            catch (error) {
-                // Not in this type, continue
-            }
-        }
+        // v6.0.0: Direct O(1) delete with ID-first path
+        const path = getNounVectorPath(id);
+        await this.deleteObjectFromBranch(path);
+        // Note: Type-specific counts will be decremented via metadata tracking
+        // The real type is in metadata, accessible if needed via getNounMetadata(id)
     }
     /**
-     * Save a verb to storage (type-first path)
+     * Save a verb to storage (ID-first path)
      */
     async saveVerb_internal(verb) {
         // Type is now a first-class field in HNSWVerb - no caching needed!
         const type = verb.verb;
-        const path = getVerbVectorPath(type, verb.id);
+        const path = getVerbVectorPath(verb.id);
+        prodLog.debug(`[BaseStorage] saveVerb_internal: id=${verb.id}, sourceId=${verb.sourceId}, targetId=${verb.targetId}, type=${type}`);
         // Update type tracking
         const typeIndex = TypeUtils.getVerbIndex(type);
         this.verbCountsByType[typeIndex]++;
-        this.verbTypeCache.set(verb.id, type);
         // COW-aware write (v5.0.1): Use COW helper for branch isolation
         await this.writeObjectToBranch(path, verb);
-        // v5.7.0: Update GraphAdjacencyIndex incrementally for billion-scale optimization
-        // CRITICAL: Only update if index already initialized to avoid circular dependency
-        // Index is lazy-loaded on first query, then maintained incrementally
-        if (this.graphIndex && this.graphIndex.isInitialized) {
-            // Fast incremental update - no rebuild needed
+        // v6.0.0: Update GraphAdjacencyIndex incrementally (always available after init())
+        // GraphAdjacencyIndex.addVerb() calls ensureInitialized() automatically
+        if (this.graphIndex) {
+            prodLog.debug(`[BaseStorage] Updating GraphAdjacencyIndex with verb ${verb.id}`);
             await this.graphIndex.addVerb({
                 id: verb.id,
                 sourceId: verb.sourceId,
@@ -1932,8 +2088,12 @@ export class BaseStorage extends BaseStorageAdapter {
                 type: verb.verb,
                 createdAt: { seconds: Math.floor(Date.now() / 1000), nanoseconds: 0 },
                 updatedAt: { seconds: Math.floor(Date.now() / 1000), nanoseconds: 0 },
-                createdBy: { augmentation: 'storage', version: '5.7.0' }
+                createdBy: { augmentation: 'storage', version: '6.0.0' }
             });
+            prodLog.debug(`[BaseStorage] GraphAdjacencyIndex updated successfully`);
+        }
+        else {
+            prodLog.warn(`[BaseStorage] graphIndex is null, cannot update index for verb ${verb.id}`);
         }
         // Periodically save statistics
         if (this.verbCountsByType[typeIndex] % 100 === 0) {
@@ -1941,69 +2101,89 @@ export class BaseStorage extends BaseStorageAdapter {
         }
     }
     /**
-     * Get a verb from storage (type-first path)
+     * Get a verb from storage (ID-first path)
      */
     async getVerb_internal(id) {
-        // Try cache first for O(1) retrieval
-        const cachedType = this.verbTypeCache.get(id);
-        if (cachedType) {
-            const path = getVerbVectorPath(cachedType, id);
+        // v6.0.0: Direct O(1) lookup with ID-first paths - no type search needed!
+        const path = getVerbVectorPath(id);
+        try {
             // COW-aware read (v5.0.1): Use COW helper for branch isolation
             const verb = await this.readWithInheritance(path);
-            // v5.7.10: Deserialize connections Map from JSON storage format
-            return verb ? this.deserializeVerb(verb) : null;
-        }
-        // Search across all types (only on first access)
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const path = getVerbVectorPath(type, id);
-            try {
-                // COW-aware read (v5.0.1): Use COW helper for branch isolation
-                const verb = await this.readWithInheritance(path);
-                if (verb) {
-                    // Cache the type for next time (read from verb.verb field)
-                    this.verbTypeCache.set(id, verb.verb);
-                    // v5.7.10: Deserialize connections Map from JSON storage format
-                    return this.deserializeVerb(verb);
-                }
-            }
-            catch (error) {
-                // Not in this type, continue
+            if (verb) {
+                // v5.7.10: Deserialize connections Map from JSON storage format
+                return this.deserializeVerb(verb);
             }
         }
+        catch (error) {
+            // Entity not found
+            return null;
+        }
         return null;
     }
     /**
-     * Get verbs by source (COW-aware implementation)
-     * v5.4.0: Fixed to directly list verb files instead of directories
+     * Get verbs by source (v6.0.0: Uses GraphAdjacencyIndex when available)
+     * Falls back to shard iteration during initialization to avoid circular dependency
      */
     async getVerbsBySource_internal(sourceId) {
-        // v5.7.1: Reverted to v5.6.3 implementation to fix circular dependency deadlock
-        // v5.7.0 called getGraphIndex() here, creating deadlock during initialization:
-        //   GraphAdjacencyIndex.rebuild() → storage.getVerbs() → getVerbsBySource_internal() → getGraphIndex() → [deadlock]
-        // v5.4.0: Type-first implementation - scan across all verb types
-        // COW-aware: uses readWithInheritance for each verb
         await this.ensureInitialized();
+        prodLog.debug(`[BaseStorage] getVerbsBySource_internal: sourceId=${sourceId}, graphIndex=${!!this.graphIndex}, isInitialized=${this.graphIndex?.isInitialized}`);
+        // v6.0.0: Fast path - use GraphAdjacencyIndex if available (lazy-loaded)
+        if (this.graphIndex && this.graphIndex.isInitialized) {
+            try {
+                const verbIds = await this.graphIndex.getVerbIdsBySource(sourceId);
+                prodLog.debug(`[BaseStorage] GraphAdjacencyIndex found ${verbIds.length} verb IDs for sourceId=${sourceId}`);
+                const results = [];
+                for (const verbId of verbIds) {
+                    const verb = await this.getVerb_internal(verbId);
+                    const metadata = await this.getVerbMetadata(verbId);
+                    if (verb && metadata) {
+                        results.push({
+                            ...verb,
+                            weight: metadata.weight,
+                            confidence: metadata.confidence,
+                            createdAt: metadata.createdAt
+                                ? (typeof metadata.createdAt === 'number' ? metadata.createdAt : metadata.createdAt.seconds * 1000)
+                                : Date.now(),
+                            updatedAt: metadata.updatedAt
+                                ? (typeof metadata.updatedAt === 'number' ? metadata.updatedAt : metadata.updatedAt.seconds * 1000)
+                                : Date.now(),
+                            service: metadata.service,
+                            createdBy: metadata.createdBy,
+                            metadata: metadata || {}
+                        });
+                    }
+                }
+                prodLog.debug(`[BaseStorage] GraphAdjacencyIndex path returned ${results.length} verbs`);
+                return results;
+            }
+            catch (error) {
+                prodLog.warn('[BaseStorage] GraphAdjacencyIndex lookup failed, falling back to shard iteration:', error);
+            }
+        }
+        // v6.0.0: Fallback - iterate by shards (WITH deserialization fix!)
+        prodLog.debug(`[BaseStorage] Using shard iteration fallback for sourceId=${sourceId}`);
         const results = [];
-        // Iterate through all verb types
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const typeDir = `entities/verbs/${type}/vectors`;
+        let shardsScanned = 0;
+        let verbsFound = 0;
+        for (let shard = 0; shard < 256; shard++) {
+            const shardHex = shard.toString(16).padStart(2, '0');
+            const shardDir = `entities/verbs/${shardHex}`;
             try {
-                // v5.4.0 FIX: List all verb files directly (not shard directories)
-                // listObjectsInBranch returns full paths to .json files, not directories
-                const verbFiles = await this.listObjectsInBranch(typeDir);
+                const verbFiles = await this.listObjectsInBranch(shardDir);
+                shardsScanned++;
                 for (const verbPath of verbFiles) {
-                    // Skip if not a .json file
-                    if (!verbPath.endsWith('.json'))
+                    if (!verbPath.includes('/vectors.json'))
                         continue;
                     try {
-                        const verb = await this.readWithInheritance(verbPath);
-                        if (verb && verb.sourceId === sourceId) {
-                            // v5.4.0: Use proper path helper instead of string replacement
-                            const metadataPath = getVerbMetadataPath(type, verb.id);
+                        const rawVerb = await this.readWithInheritance(verbPath);
+                        if (!rawVerb)
+                            continue;
+                        verbsFound++;
+                        // v6.0.0: CRITICAL - Deserialize connections Map from JSON storage format
+                        const verb = this.deserializeVerb(rawVerb);
+                        if (verb.sourceId === sourceId) {
+                            const metadataPath = getVerbMetadataPath(verb.id);
                             const metadata = await this.readWithInheritance(metadataPath);
-                            // v5.4.0: Extract standard fields from metadata to top-level (like nouns)
                             results.push({
                                 ...verb,
                                 weight: metadata?.weight,
@@ -2022,11 +2202,122 @@ export class BaseStorage extends BaseStorageAdapter {
                     }
                     catch (error) {
                         // Skip verbs that fail to load
+                        prodLog.debug(`[BaseStorage] Failed to load verb from ${verbPath}:`, error);
                     }
                 }
             }
             catch (error) {
-                // Skip types that have no data
+                // Skip shards that have no data
+            }
+        }
+        prodLog.debug(`[BaseStorage] Shard iteration: scanned ${shardsScanned} shards, found ${verbsFound} total verbs, matched ${results.length} for sourceId=${sourceId}`);
+        return results;
+    }
+    /**
+     * Batch get verbs by source IDs (v5.12.0 - Cloud Storage Optimization)
+     *
+     * **Performance**: Eliminates N+1 query pattern for relationship lookups
+     * - Current: N × getVerbsBySource() = N × (list all verbs + filter)
+     * - Batched: 1 × list all verbs + filter by N sourceIds
+     *
+     * **Use cases:**
+     * - VFS tree traversal (get Contains edges for multiple directories)
+     * - brain.getRelations() for multiple entities
+     * - Graph traversal (fetch neighbors of multiple nodes)
+     *
+     * @param sourceIds Array of source entity IDs
+     * @param verbType Optional verb type filter (e.g., VerbType.Contains for VFS)
+     * @returns Map of sourceId → verbs[]
+     *
+     * @example
+     * ```typescript
+     * // Before (N+1 pattern)
+     * for (const dirId of dirIds) {
+     *   const children = await storage.getVerbsBySource(dirId)  // N calls
+     * }
+     *
+     * // After (batched)
+     * const childrenByDir = await storage.getVerbsBySourceBatch(dirIds, VerbType.Contains)  // 1 scan
+     * for (const dirId of dirIds) {
+     *   const children = childrenByDir.get(dirId) || []
+     * }
+     * ```
+     *
+     * @since v5.12.0
+     */
+    async getVerbsBySourceBatch(sourceIds, verbType) {
+        await this.ensureInitialized();
+        const results = new Map();
+        if (sourceIds.length === 0)
+            return results;
+        // Initialize empty arrays for all requested sourceIds
+        for (const sourceId of sourceIds) {
+            results.set(sourceId, []);
+        }
+        // Convert sourceIds to Set for O(1) lookup
+        const sourceIdSet = new Set(sourceIds);
+        // v6.0.0: Iterate by shards (0x00-0xFF) instead of types
+        for (let shard = 0; shard < 256; shard++) {
+            const shardHex = shard.toString(16).padStart(2, '0');
+            const shardDir = `entities/verbs/${shardHex}`;
+            try {
+                // List all verb files in this shard
+                const verbFiles = await this.listObjectsInBranch(shardDir);
+                // Build paths for batch read
+                const verbPaths = [];
+                const metadataPaths = [];
+                const pathToId = new Map();
+                for (const verbPath of verbFiles) {
+                    if (!verbPath.includes('/vectors.json'))
+                        continue;
+                    verbPaths.push(verbPath);
+                    // Extract ID from path: "entities/verbs/{shard}/{id}/vector.json"
+                    const parts = verbPath.split('/');
+                    const verbId = parts[parts.length - 2]; // ID is second-to-last segment
+                    pathToId.set(verbPath, verbId);
+                    // Prepare metadata path
+                    metadataPaths.push(getVerbMetadataPath(verbId));
+                }
+                // Batch read all verb files for this shard
+                const verbDataMap = await this.readBatchWithInheritance(verbPaths);
+                const metadataMap = await this.readBatchWithInheritance(metadataPaths);
+                // Process results
+                for (const [verbPath, rawVerbData] of verbDataMap.entries()) {
+                    if (!rawVerbData || !rawVerbData.sourceId)
+                        continue;
+                    // v6.0.0: Deserialize connections Map from JSON storage format
+                    const verbData = this.deserializeVerb(rawVerbData);
+                    // Check if this verb's source is in our requested set
+                    if (!sourceIdSet.has(verbData.sourceId))
+                        continue;
+                    // If verbType specified, filter by type
+                    if (verbType && verbData.verb !== verbType)
+                        continue;
+                    // Found matching verb - hydrate with metadata
+                    const verbId = pathToId.get(verbPath);
+                    const metadataPath = getVerbMetadataPath(verbId);
+                    const metadata = metadataMap.get(metadataPath) || {};
+                    const hydratedVerb = {
+                        ...verbData,
+                        weight: metadata?.weight,
+                        confidence: metadata?.confidence,
+                        createdAt: metadata?.createdAt
+                            ? (typeof metadata.createdAt === 'number' ? metadata.createdAt : metadata.createdAt.seconds * 1000)
+                            : Date.now(),
+                        updatedAt: metadata?.updatedAt
+                            ? (typeof metadata.updatedAt === 'number' ? metadata.updatedAt : metadata.updatedAt.seconds * 1000)
+                            : Date.now(),
+                        service: metadata?.service,
+                        createdBy: metadata?.createdBy,
+                        metadata: metadata
+                    };
+                    // Add to results for this sourceId
+                    const sourceVerbs = results.get(verbData.sourceId);
+                    sourceVerbs.push(hydratedVerb);
+                }
+            }
+            catch (error) {
+                // Skip shards that have no data
             }
         }
         return results;
@@ -2037,31 +2328,57 @@ export class BaseStorage extends BaseStorageAdapter {
      * v5.4.0: Fixed to directly list verb files instead of directories
      */
     async getVerbsByTarget_internal(targetId) {
-        // v5.7.1: Reverted to v5.6.3 implementation to fix circular dependency deadlock
-        // v5.7.0 called getGraphIndex() here, creating deadlock during initialization
-        // v5.4.0: Type-first implementation - scan across all verb types
-        // COW-aware: uses readWithInheritance for each verb
         await this.ensureInitialized();
+        // v6.0.0: Fast path - use GraphAdjacencyIndex if available (lazy-loaded)
+        if (this.graphIndex && this.graphIndex.isInitialized) {
+            try {
+                const verbIds = await this.graphIndex.getVerbIdsByTarget(targetId);
+                const results = [];
+                for (const verbId of verbIds) {
+                    const verb = await this.getVerb_internal(verbId);
+                    const metadata = await this.getVerbMetadata(verbId);
+                    if (verb && metadata) {
+                        results.push({
+                            ...verb,
+                            weight: metadata.weight,
+                            confidence: metadata.confidence,
+                            createdAt: metadata.createdAt
+                                ? (typeof metadata.createdAt === 'number' ? metadata.createdAt : metadata.createdAt.seconds * 1000)
+                                : Date.now(),
+                            updatedAt: metadata.updatedAt
+                                ? (typeof metadata.updatedAt === 'number' ? metadata.updatedAt : metadata.updatedAt.seconds * 1000)
+                                : Date.now(),
+                            service: metadata.service,
+                            createdBy: metadata.createdBy,
+                            metadata: metadata || {}
+                        });
+                    }
+                }
+                return results;
+            }
+            catch (error) {
+                prodLog.warn('[BaseStorage] GraphAdjacencyIndex lookup failed, falling back to shard iteration:', error);
+            }
+        }
+        // v6.0.0: Fallback - iterate by shards (WITH deserialization fix!)
         const results = [];
-        // Iterate through all verb types
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const typeDir = `entities/verbs/${type}/vectors`;
+        for (let shard = 0; shard < 256; shard++) {
+            const shardHex = shard.toString(16).padStart(2, '0');
+            const shardDir = `entities/verbs/${shardHex}`;
             try {
-                // v5.4.0 FIX: List all verb files directly (not shard directories)
-                // listObjectsInBranch returns full paths to .json files, not directories
-                const verbFiles = await this.listObjectsInBranch(typeDir);
+                const verbFiles = await this.listObjectsInBranch(shardDir);
                 for (const verbPath of verbFiles) {
-                    // Skip if not a .json file
-                    if (!verbPath.endsWith('.json'))
+                    if (!verbPath.includes('/vectors.json'))
                         continue;
                     try {
-                        const verb = await this.readWithInheritance(verbPath);
-                        if (verb && verb.targetId === targetId) {
-                            // v5.4.0: Use proper path helper instead of string replacement
-                            const metadataPath = getVerbMetadataPath(type, verb.id);
+                        const rawVerb = await this.readWithInheritance(verbPath);
+                        if (!rawVerb)
+                            continue;
+                        // v6.0.0: CRITICAL - Deserialize connections Map from JSON storage format
+                        const verb = this.deserializeVerb(rawVerb);
+                        if (verb.targetId === targetId) {
+                            const metadataPath = getVerbMetadataPath(verb.id);
                             const metadata = await this.readWithInheritance(metadataPath);
-                            // v5.4.0: Extract standard fields from metadata to top-level (like nouns)
                             results.push({
                                 ...verb,
                                 weight: metadata?.weight,
@@ -2084,95 +2401,77 @@ export class BaseStorage extends BaseStorageAdapter {
                 }
             }
             catch (error) {
-                // Skip types that have no data
+                // Skip shards that have no data
             }
         }
         return results;
     }
     /**
-     * Get verbs by type (O(1) with type-first paths!)
+     * Get verbs by type (v6.0.0: Shard iteration with type filtering)
      */
     async getVerbsByType_internal(verbType) {
-        const type = verbType;
-        const prefix = `entities/verbs/${type}/vectors/`;
-        // COW-aware list (v5.0.1): Use COW helper for branch isolation
-        const paths = await this.listObjectsInBranch(prefix);
+        // v6.0.0: Iterate by shards (0x00-0xFF) instead of type-first paths
         const verbs = [];
-        for (const path of paths) {
+        for (let shard = 0; shard < 256; shard++) {
+            const shardHex = shard.toString(16).padStart(2, '0');
+            const shardDir = `entities/verbs/${shardHex}`;
             try {
-                // COW-aware read (v5.0.1): Use COW helper for branch isolation
-                const rawVerb = await this.readWithInheritance(path);
-                if (!rawVerb)
-                    continue;
-                // v5.7.10: Deserialize connections Map from JSON storage format
-                // Replaces v5.7.8 manual deserialization (lines 2599-2605)
-                const hnswVerb = this.deserializeVerb(rawVerb);
-                // Cache type from HNSWVerb for future O(1) retrievals
-                this.verbTypeCache.set(hnswVerb.id, hnswVerb.verb);
-                // Load metadata separately (optional in v4.0.0!)
-                // FIX: Don't skip verbs without metadata - metadata is optional!
-                const metadata = await this.getVerbMetadata(hnswVerb.id);
-                // v4.8.0: Extract standard fields from metadata to top-level
-                const metadataObj = (metadata || {});
-                const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
-                const verbWithMetadata = {
-                    id: hnswVerb.id,
-                    vector: [...hnswVerb.vector],
-                    connections: hnswVerb.connections, // v5.7.10: Already deserialized
-                    verb: hnswVerb.verb,
-                    sourceId: hnswVerb.sourceId,
-                    targetId: hnswVerb.targetId,
-                    createdAt: createdAt || Date.now(),
-                    updatedAt: updatedAt || Date.now(),
-                    confidence: confidence,
-                    weight: weight,
-                    service: service,
-                    data: data,
-                    createdBy,
-                    metadata: customMetadata
-                };
-                verbs.push(verbWithMetadata);
+                const verbFiles = await this.listObjectsInBranch(shardDir);
+                for (const verbPath of verbFiles) {
+                    if (!verbPath.includes('/vectors.json'))
+                        continue;
+                    try {
+                        const rawVerb = await this.readWithInheritance(verbPath);
+                        if (!rawVerb)
+                            continue;
+                        // v5.7.10: Deserialize connections Map from JSON storage format
+                        const hnswVerb = this.deserializeVerb(rawVerb);
+                        // Filter by verb type
+                        if (hnswVerb.verb !== verbType)
+                            continue;
+                        // Load metadata separately (optional in v4.0.0!)
+                        const metadata = await this.getVerbMetadata(hnswVerb.id);
+                        // v4.8.0: Extract standard fields from metadata to top-level
+                        const metadataObj = (metadata || {});
+                        const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
+                        const verbWithMetadata = {
+                            id: hnswVerb.id,
+                            vector: [...hnswVerb.vector],
+                            connections: hnswVerb.connections, // v5.7.10: Already deserialized
+                            verb: hnswVerb.verb,
+                            sourceId: hnswVerb.sourceId,
+                            targetId: hnswVerb.targetId,
+                            createdAt: createdAt || Date.now(),
+                            updatedAt: updatedAt || Date.now(),
+                            confidence: confidence,
+                            weight: weight,
+                            service: service,
+                            data: data,
+                            createdBy,
+                            metadata: customMetadata
+                        };
+                        verbs.push(verbWithMetadata);
+                    }
+                    catch (error) {
+                        // Skip verbs that fail to load
+                    }
+                }
             }
             catch (error) {
-                prodLog.warn(`[BaseStorage] Failed to load verb from ${path}:`, error);
+                // Skip shards that have no data
             }
         }
         return verbs;
     }
     /**
-     * Delete a verb from storage (type-first path)
+     * Delete a verb from storage (v6.0.0: ID-first, O(1) delete)
      */
     async deleteVerb_internal(id) {
-        // Try cache first
-        const cachedType = this.verbTypeCache.get(id);
-        if (cachedType) {
-            const path = getVerbVectorPath(cachedType, id);
-            // COW-aware delete (v5.0.1): Use COW helper for branch isolation
-            await this.deleteObjectFromBranch(path);
-            const typeIndex = TypeUtils.getVerbIndex(cachedType);
-            if (this.verbCountsByType[typeIndex] > 0) {
-                this.verbCountsByType[typeIndex]--;
-            }
-            this.verbTypeCache.delete(id);
-            return;
-        }
-        // Search across all types
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const path = getVerbVectorPath(type, id);
-            try {
-                // COW-aware delete (v5.0.1): Use COW helper for branch isolation
-                await this.deleteObjectFromBranch(path);
-                if (this.verbCountsByType[i] > 0) {
-                    this.verbCountsByType[i]--;
-                }
-                this.verbTypeCache.delete(id);
-                return;
-            }
-            catch (error) {
-                // Continue
-            }
-        }
+        // v6.0.0: Direct O(1) delete with ID-first path
+        const path = getVerbVectorPath(id);
+        await this.deleteObjectFromBranch(path);
+        // Note: Type-specific counts will be decremented via metadata tracking
+        // The real type is in metadata, accessible if needed via getVerbMetadata(id)
     }
     /**
      * Helper method to convert a Map to a plain object for serialization