@soulcraft/brainy 5.12.0 → 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,39 +1473,21 @@ 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
-            }
-        }
-        return null;
+        // 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)
@@ -1511,74 +1526,19 @@ export class BaseStorage extends BaseStorageAdapter {
         const results = new Map();
         if (ids.length === 0)
             return results;
-        // Group IDs by cached type for efficient path construction
-        const idsByType = new Map();
-        const uncachedIds = [];
-        for (const id of ids) {
-            const cachedType = this.nounTypeCache.get(id);
-            if (cachedType) {
-                const idsForType = idsByType.get(cachedType) || [];
-                idsForType.push(id);
-                idsByType.set(cachedType, idsForType);
-            }
-            else {
-                uncachedIds.push(id);
-            }
-        }
-        // Build paths for known types
-        const pathsToFetch = [];
-        for (const [type, typeIds] of idsByType.entries()) {
-            for (const id of typeIds) {
-                pathsToFetch.push({
-                    path: getNounMetadataPath(type, id),
-                    id
-                });
-            }
-        }
-        // For uncached IDs, we need to search across types (expensive but unavoidable)
-        // Strategy: Try most common types first (Document, Thing, Person), then others
-        const commonTypes = [NounType.Document, NounType.Thing, NounType.Person, NounType.File];
-        const commonTypeSet = new Set(commonTypes);
-        const otherTypes = [];
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-            const type = TypeUtils.getNounFromIndex(i);
-            if (!commonTypeSet.has(type)) {
-                otherTypes.push(type);
-            }
-        }
-        const searchOrder = [...commonTypes, ...otherTypes];
-        for (const id of uncachedIds) {
-            for (const type of searchOrder) {
-                // Build path manually to avoid type issues
-                const shard = getShardIdFromUuid(id);
-                const path = `entities/nouns/${type}/metadata/${shard}/${id}.json`;
-                pathsToFetch.push({ path, id });
-            }
-        }
-        // Batch read all paths
+        // 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));
-        // Process results and update cache
-        const foundUncached = new Set();
-        for (let i = 0; i < pathsToFetch.length; i++) {
-            const { path, id } = pathsToFetch[i];
+        // Map results back to IDs
+        for (const { path, id } of pathsToFetch) {
             const metadata = batchResults.get(path);
             if (metadata) {
                 results.set(id, metadata);
-                // Cache the type for uncached IDs (only on first find)
-                if (uncachedIds.includes(id) && !foundUncached.has(id)) {
-                    // Extract type from path: "entities/nouns/metadata/{type}/{shard}/{id}.json"
-                    const parts = path.split('/');
-                    const typeStr = parts[3]; // "document", "thing", etc.
-                    // Find matching type by string comparison
-                    for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-                        const type = TypeUtils.getNounFromIndex(i);
-                        if (type === typeStr) {
-                            this.nounTypeCache.set(id, type);
-                            break;
-                        }
-                    }
-                    foundUncached.add(id);
-                }
             }
         }
         return results;
@@ -1736,36 +1696,13 @@ export class BaseStorage extends BaseStorageAdapter {
         };
     }
     /**
-     * Delete noun metadata from storage
-     * v5.4.0: Uses type-first paths (must match saveNounMetadata_internal)
+     * Delete noun metadata from storage (v6.0.0: ID-first, O(1) delete)
      */
     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;
-        }
-        // 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;
-                }
-            }
-            catch (error) {
-                // Not in this type, continue searching
-            }
-        }
+        // 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)
@@ -1777,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
@@ -1789,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
@@ -1797,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
@@ -1820,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
@@ -1924,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
@@ -1957,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';
     }
     /**
@@ -2051,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)
@@ -2068,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,
@@ -2193,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) {
@@ -2202,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,
@@ -2283,13 +2202,15 @@ 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;
     }
     /**
@@ -2335,52 +2256,46 @@ export class BaseStorage extends BaseStorageAdapter {
         }
         // Convert sourceIds to Set for O(1) lookup
         const sourceIdSet = new Set(sourceIds);
-        // Determine which verb types to scan
-        const typesToScan = [];
-        if (verbType) {
-            typesToScan.push(verbType);
-        }
-        else {
-            // Scan all verb types
-            for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-                typesToScan.push(TypeUtils.getVerbFromIndex(i));
-            }
-        }
-        // Scan verb types and collect matching verbs
-        for (const type of typesToScan) {
-            const typeDir = `entities/verbs/${type}/vectors`;
+        // 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 of this type
-                const verbFiles = await this.listObjectsInBranch(typeDir);
+                // 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.endsWith('.json'))
+                    if (!verbPath.includes('/vectors.json'))
                         continue;
                     verbPaths.push(verbPath);
-                    // Extract ID from path: "entities/verbs/{type}/vectors/{shard}/{id}.json"
+                    // Extract ID from path: "entities/verbs/{shard}/{id}/vector.json"
                     const parts = verbPath.split('/');
-                    const filename = parts[parts.length - 1];
-                    const verbId = filename.replace('.json', '');
+                    const verbId = parts[parts.length - 2]; // ID is second-to-last segment
                     pathToId.set(verbPath, verbId);
                     // Prepare metadata path
-                    metadataPaths.push(getVerbMetadataPath(type, verbId));
+                    metadataPaths.push(getVerbMetadataPath(verbId));
                 }
-                // Batch read all verb files for this type
+                // 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, verbData] of verbDataMap.entries()) {
-                    if (!verbData || !verbData.sourceId)
+                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(type, verbId);
+                    const metadataPath = getVerbMetadataPath(verbId);
                     const metadata = metadataMap.get(metadataPath) || {};
                     const hydratedVerb = {
                         ...verbData,
@@ -2402,7 +2317,7 @@ export class BaseStorage extends BaseStorageAdapter {
                 }
             }
             catch (error) {
-                // Skip types that have no data
+                // Skip shards that have no data
             }
         }
         return results;
@@ -2413,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,
@@ -2460,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