@soulcraft/brainy 5.3.5 → 5.4.0

package/dist/storage/baseStorage.js

@@ -5,7 +5,7 @@
 import { GraphAdjacencyIndex } from '../graph/graphAdjacencyIndex.js';
 import { BaseStorageAdapter } from './adapters/baseStorageAdapter.js';
 import { validateNounType, validateVerbType } from '../utils/typeValidation.js';
-import { NounType } from '../types/graphTypes.js';
+import { NounType, TypeUtils, NOUN_TYPE_COUNT, VERB_TYPE_COUNT } from '../types/graphTypes.js';
 import { getShardIdFromUuid } from './sharding.js';
 import { RefManager } from './cow/RefManager.js';
 import { BlobStorage } from './cow/BlobStorage.js';
@@ -32,6 +32,38 @@ export function getDirectoryPath(entityType, dataType) {
         return dataType === 'vector' ? VERBS_DIR : VERBS_METADATA_DIR;
     }
 }
+/**
+ * Type-first path generators (v5.4.0)
+ * Built-in type-aware organization for all storage adapters
+ */
+/**
+ * Get type-first path for noun vectors
+ */
+function getNounVectorPath(type, id) {
+    const shard = getShardIdFromUuid(id);
+    return `entities/nouns/${type}/vectors/${shard}/${id}.json`;
+}
+/**
+ * Get type-first path for noun metadata
+ */
+function getNounMetadataPath(type, id) {
+    const shard = getShardIdFromUuid(id);
+    return `entities/nouns/${type}/metadata/${shard}/${id}.json`;
+}
+/**
+ * Get type-first path for verb vectors
+ */
+function getVerbVectorPath(type, id) {
+    const shard = getShardIdFromUuid(id);
+    return `entities/verbs/${type}/vectors/${shard}/${id}.json`;
+}
+/**
+ * Get type-first path for verb metadata
+ */
+function getVerbMetadataPath(type, id) {
+    const shard = getShardIdFromUuid(id);
+    return `entities/verbs/${type}/metadata/${shard}/${id}.json`;
+}
 /**
  * Base storage adapter that implements common functionality
  * This is an abstract class that should be extended by specific storage adapters
@@ -43,6 +75,14 @@ export class BaseStorage extends BaseStorageAdapter {
         this.readOnly = false;
         this.currentBranch = 'main';
         this.cowEnabled = false;
+        // Type-first indexing support (v5.4.0)
+        // Built into all storage adapters for billion-scale efficiency
+        this.nounCountsByType = new Uint32Array(NOUN_TYPE_COUNT); // 124 bytes
+        this.verbCountsByType = new Uint32Array(VERB_TYPE_COUNT); // 160 bytes
+        // Total: 284 bytes (99.76% reduction vs Map-based tracking)
+        // Type cache for O(1) lookups after first access
+        this.nounTypeCache = new Map();
+        this.verbTypeCache = new Map();
     }
     /**
      * Analyze a storage key to determine its routing and path
@@ -116,6 +156,17 @@ export class BaseStorage extends BaseStorageAdapter {
             };
         }
     }
+    /**
+     * Initialize the storage adapter (v5.4.0)
+     * Loads type statistics for built-in type-aware indexing
+     *
+     * IMPORTANT: If your adapter overrides init(), call await super.init() first!
+     */
+    async init() {
+        // Load type statistics from storage (if they exist)
+        await this.loadTypeStatistics();
+        this.isInitialized = true;
+    }
     /**
      * Ensure the storage adapter is initialized
      */
@@ -274,6 +325,13 @@ export class BaseStorage extends BaseStorageAdapter {
      * @protected - Available to subclasses for COW implementation
      */
     resolveBranchPath(basePath, branch) {
+        // CRITICAL FIX (v5.3.6): COW metadata (_cow/*) must NEVER be branch-scoped
+        // Refs, commits, and blobs are global metadata with their own internal branching.
+        // Branch-scoping COW paths causes fork() to write refs to wrong locations,
+        // leading to "Branch does not exist" errors on checkout (see Workshop bug report).
+        if (basePath.startsWith('_cow/')) {
+            return basePath; // COW metadata is global across all branches
+        }
         if (!this.cowEnabled) {
             return basePath; // COW disabled, use direct path
         }
@@ -763,6 +821,90 @@ export class BaseStorage extends BaseStorageAdapter {
             };
         }
     }
+    /**
+     * Get nouns with pagination (v5.4.0: Type-first implementation)
+     *
+     * CRITICAL: This method is required for brain.find() to work!
+     * Iterates through all noun types to find entities.
+     */
+    async getNounsWithPagination(options) {
+        await this.ensureInitialized();
+        const { limit, offset, filter } = options;
+        const allNouns = [];
+        // v5.4.0: Iterate through all noun types (type-first architecture)
+        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
+            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`;
+            try {
+                // List all noun files for this type
+                const nounFiles = await this.listObjectsInBranch(typeDir);
+                for (const nounPath of nounFiles) {
+                    // Skip if not a .json file
+                    if (!nounPath.endsWith('.json'))
+                        continue;
+                    try {
+                        const noun = await this.readWithInheritance(nounPath);
+                        if (noun) {
+                            // Load metadata
+                            const metadataPath = getNounMetadataPath(type, noun.id);
+                            const metadata = await this.readWithInheritance(metadataPath);
+                            if (metadata) {
+                                // Apply service filter if specified
+                                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)
+                                allNouns.push({
+                                    ...noun,
+                                    type: metadata.noun || type, // Required: Extract type from metadata
+                                    confidence: metadata.confidence,
+                                    weight: metadata.weight,
+                                    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,
+                                    data: metadata.data,
+                                    createdBy: metadata.createdBy,
+                                    metadata: metadata || {}
+                                });
+                            }
+                        }
+                    }
+                    catch (error) {
+                        // Skip nouns that fail to load
+                    }
+                }
+            }
+            catch (error) {
+                // Skip types that have no data
+            }
+        }
+        // Apply pagination
+        const totalCount = allNouns.length;
+        const paginatedNouns = allNouns.slice(offset, offset + limit);
+        const hasMore = offset + limit < totalCount;
+        return {
+            items: paginatedNouns,
+            totalCount,
+            hasMore,
+            nextCursor: hasMore && paginatedNouns.length > 0
+                ? paginatedNouns[paginatedNouns.length - 1].id
+                : undefined
+        };
+    }
     /**
      * Get verbs with pagination and filtering
      * @param options Pagination and filtering options
@@ -1026,12 +1168,16 @@ 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);
         // Determine if this is a new entity by checking if metadata already exists
-        const keyInfo = this.analyzeKey(id, 'noun-metadata');
-        const existingMetadata = await this.readWithInheritance(keyInfo.fullPath);
+        const existingMetadata = await this.readWithInheritance(path);
         const isNew = !existingMetadata;
         // Save the metadata (COW-aware - writes to branch-specific path)
-        await this.writeObjectToBranch(keyInfo.fullPath, metadata);
+        await this.writeObjectToBranch(path, metadata);
         // CRITICAL FIX (v4.1.2): Increment count for new entities
         // This runs AFTER metadata is saved, guaranteeing type information is available
         // Uses synchronous increment since storage operations are already serialized
@@ -1046,21 +1192,65 @@ export class BaseStorage extends BaseStorageAdapter {
     }
     /**
      * Get noun metadata from storage (v4.0.0: now typed)
-     * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
+     * v5.4.0: Uses type-first paths (must match saveNounMetadata_internal)
      */
     async getNounMetadata(id) {
         await this.ensureInitialized();
-        const keyInfo = this.analyzeKey(id, 'noun-metadata');
-        return this.readWithInheritance(keyInfo.fullPath);
+        // 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;
     }
     /**
      * Delete noun metadata from storage
-     * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
+     * v5.4.0: Uses type-first paths (must match saveNounMetadata_internal)
      */
     async deleteNounMetadata(id) {
         await this.ensureInitialized();
-        const keyInfo = this.analyzeKey(id, 'noun-metadata');
-        return this.deleteObjectFromBranch(keyInfo.fullPath);
+        // 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
+            }
+        }
     }
     /**
      * Save verb metadata to storage (v4.0.0: now typed)
@@ -1072,7 +1262,7 @@ export class BaseStorage extends BaseStorageAdapter {
     }
     /**
      * Internal method for saving verb metadata (v4.0.0: now typed)
-     * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
+     * v5.4.0: Uses type-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
@@ -1084,19 +1274,29 @@ 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
+        const verbType = metadata.verb;
+        if (!verbType) {
+            // Backward compatibility: fallback to old path if no verb type
+            const keyInfo = this.analyzeKey(id, 'verb-metadata');
+            await this.writeObjectToBranch(keyInfo.fullPath, metadata);
+            return;
+        }
+        // v5.4.0: Use type-first path
+        const path = getVerbMetadataPath(verbType, id);
         // Determine if this is a new verb by checking if metadata already exists
-        const keyInfo = this.analyzeKey(id, 'verb-metadata');
-        const existingMetadata = await this.readWithInheritance(keyInfo.fullPath);
+        const existingMetadata = await this.readWithInheritance(path);
         const isNew = !existingMetadata;
         // Save the metadata (COW-aware - writes to branch-specific path)
-        await this.writeObjectToBranch(keyInfo.fullPath, metadata);
+        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
-        // Verb type is now stored in metadata (as of v4.1.2) to avoid loading HNSWVerb
         // Uses synchronous increment since storage operations are already serialized
         // Fixes Bug #2: Count synchronization failure during relate() and import()
-        if (isNew && metadata.verb) {
-            this.incrementVerbCount(metadata.verb);
+        if (isNew) {
+            this.incrementVerbCount(verbType);
             // Persist counts asynchronously (fire and forget)
             this.scheduleCountPersist().catch(() => {
                 // Ignore persist errors - will retry on next operation
@@ -1105,21 +1305,497 @@ export class BaseStorage extends BaseStorageAdapter {
     }
     /**
      * Get verb metadata from storage (v4.0.0: now typed)
-     * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
+     * v5.4.0: Uses type-first paths (must match saveVerbMetadata_internal)
      */
     async getVerbMetadata(id) {
         await this.ensureInitialized();
-        const keyInfo = this.analyzeKey(id, 'verb-metadata');
-        return this.readWithInheritance(keyInfo.fullPath);
+        // 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
+            }
+        }
+        return null;
     }
     /**
      * Delete verb metadata from storage
-     * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
+     * v5.4.0: Uses type-first paths (must match saveVerbMetadata_internal)
      */
     async deleteVerbMetadata(id) {
         await this.ensureInitialized();
-        const keyInfo = this.analyzeKey(id, 'verb-metadata');
-        return this.deleteObjectFromBranch(keyInfo.fullPath);
+        // 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
+            }
+        }
+    }
+    // ============================================================================
+    // TYPE-FIRST HELPER METHODS (v5.4.0)
+    // Built-in type-aware support for all storage adapters
+    // ============================================================================
+    /**
+     * Load type statistics from storage
+     * Rebuilds type counts if needed (called during init)
+     */
+    async loadTypeStatistics() {
+        try {
+            const stats = await this.readObjectFromPath(`${SYSTEM_DIR}/type-statistics.json`);
+            if (stats) {
+                // Restore counts from saved statistics
+                if (stats.nounCounts && stats.nounCounts.length === NOUN_TYPE_COUNT) {
+                    this.nounCountsByType = new Uint32Array(stats.nounCounts);
+                }
+                if (stats.verbCounts && stats.verbCounts.length === VERB_TYPE_COUNT) {
+                    this.verbCountsByType = new Uint32Array(stats.verbCounts);
+                }
+            }
+        }
+        catch (error) {
+            // No existing type statistics, starting fresh
+        }
+    }
+    /**
+     * Save type statistics to storage
+     * Periodically called when counts are updated
+     */
+    async saveTypeStatistics() {
+        const stats = {
+            nounCounts: Array.from(this.nounCountsByType),
+            verbCounts: Array.from(this.verbCountsByType),
+            updatedAt: Date.now()
+        };
+        await this.writeObjectToPath(`${SYSTEM_DIR}/type-statistics.json`, stats);
+    }
+    /**
+     * Get noun type from cache or metadata
+     * Relies on nounTypeCache populated during metadata saves
+     */
+    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
+        console.warn(`[BaseStorage] Unknown noun type for ${noun.id}, defaulting to 'thing'`);
+        return 'thing';
+    }
+    /**
+     * Get verb type from verb object
+     * Verb type is a required field in HNSWVerb
+     */
+    getVerbType(verb) {
+        // v3.50.1+: verb is a required field in HNSWVerb
+        if ('verb' in verb && verb.verb) {
+            return verb.verb;
+        }
+        // Fallback for GraphVerb (type alias)
+        if ('type' in verb && verb.type) {
+            return verb.type;
+        }
+        // This should never happen with current data
+        console.warn(`[BaseStorage] Verb missing type field for ${verb.id}, defaulting to 'relatedTo'`);
+        return 'relatedTo';
+    }
+    // ============================================================================
+    // ABSTRACT METHOD IMPLEMENTATIONS (v5.4.0)
+    // Converted from abstract to concrete - all adapters now have built-in type-aware
+    // ============================================================================
+    /**
+     * Save a noun to storage (type-first path)
+     */
+    async saveNoun_internal(noun) {
+        const type = this.getNounType(noun);
+        const path = getNounVectorPath(type, 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)
+        if (this.nounCountsByType[typeIndex] % 100 === 0) {
+            await this.saveTypeStatistics();
+        }
+    }
+    /**
+     * Get a noun from storage (type-first path)
+     */
+    async getNoun_internal(id) {
+        // Try cache first
+        const cachedType = this.nounTypeCache.get(id);
+        if (cachedType) {
+            const path = getNounVectorPath(cachedType, id);
+            // COW-aware read (v5.0.1): Use COW helper for branch isolation
+            return await this.readWithInheritance(path);
+        }
+        // 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);
+                    return noun;
+                }
+            }
+            catch (error) {
+                // Not in this type, continue searching
+            }
+        }
+        return null;
+    }
+    /**
+     * Get nouns by noun type (O(1) with type-first paths!)
+     */
+    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
+        const nouns = [];
+        for (const path of paths) {
+            try {
+                // COW-aware read (v5.0.1): Use COW helper for branch isolation
+                const noun = await this.readWithInheritance(path);
+                if (noun) {
+                    nouns.push(noun);
+                    // Cache the type
+                    this.nounTypeCache.set(noun.id, type);
+                }
+            }
+            catch (error) {
+                console.warn(`[BaseStorage] Failed to load noun from ${path}:`, error);
+            }
+        }
+        return nouns;
+    }
+    /**
+     * Delete a noun from storage (type-first path)
+     */
+    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
+            }
+        }
+    }
+    /**
+     * Save a verb to storage (type-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);
+        // 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);
+        // Periodically save statistics
+        if (this.verbCountsByType[typeIndex] % 100 === 0) {
+            await this.saveTypeStatistics();
+        }
+    }
+    /**
+     * Get a verb from storage (type-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);
+            // COW-aware read (v5.0.1): Use COW helper for branch isolation
+            const verb = await this.readWithInheritance(path);
+            return verb;
+        }
+        // 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);
+                    return verb;
+                }
+            }
+            catch (error) {
+                // Not in this type, continue
+            }
+        }
+        return null;
+    }
+    /**
+     * Get verbs by source (COW-aware implementation)
+     * v5.4.0: Fixed to directly list verb files instead of directories
+     */
+    async getVerbsBySource_internal(sourceId) {
+        // v5.4.0: Type-first implementation - scan across all verb types
+        // COW-aware: uses readWithInheritance for each verb
+        await this.ensureInitialized();
+        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`;
+            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);
+                for (const verbPath of verbFiles) {
+                    // Skip if not a .json file
+                    if (!verbPath.endsWith('.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 metadata = await this.readWithInheritance(metadataPath);
+                            // v5.4.0: Extract standard fields from metadata to top-level (like nouns)
+                            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 || {}
+                            });
+                        }
+                    }
+                    catch (error) {
+                        // Skip verbs that fail to load
+                    }
+                }
+            }
+            catch (error) {
+                // Skip types that have no data
+            }
+        }
+        return results;
+    }
+    /**
+     * Get verbs by target (COW-aware implementation)
+     * v5.4.0: Fixed to directly list verb files instead of directories
+     */
+    async getVerbsByTarget_internal(targetId) {
+        // v5.4.0: Type-first implementation - scan across all verb types
+        // COW-aware: uses readWithInheritance for each verb
+        await this.ensureInitialized();
+        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`;
+            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);
+                for (const verbPath of verbFiles) {
+                    // Skip if not a .json file
+                    if (!verbPath.endsWith('.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 metadata = await this.readWithInheritance(metadataPath);
+                            // v5.4.0: Extract standard fields from metadata to top-level (like nouns)
+                            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 || {}
+                            });
+                        }
+                    }
+                    catch (error) {
+                        // Skip verbs that fail to load
+                    }
+                }
+            }
+            catch (error) {
+                // Skip types that have no data
+            }
+        }
+        return results;
+    }
+    /**
+     * Get verbs by type (O(1) with type-first paths!)
+     */
+    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);
+        const verbs = [];
+        for (const path of paths) {
+            try {
+                // COW-aware read (v5.0.1): Use COW helper for branch isolation
+                const hnswVerb = await this.readWithInheritance(path);
+                if (!hnswVerb)
+                    continue;
+                // 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);
+                // Create HNSWVerbWithMetadata (verbs don't have level field)
+                // Convert connections from plain object to Map<number, Set<string>>
+                const connectionsMap = new Map();
+                if (hnswVerb.connections && typeof hnswVerb.connections === 'object') {
+                    for (const [level, ids] of Object.entries(hnswVerb.connections)) {
+                        connectionsMap.set(Number(level), new Set(ids));
+                    }
+                }
+                // 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: connectionsMap,
+                    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) {
+                console.warn(`[BaseStorage] Failed to load verb from ${path}:`, error);
+            }
+        }
+        return verbs;
+    }
+    /**
+     * Delete a verb from storage (type-first path)
+     */
+    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
+            }
+        }
     }
     /**
      * Helper method to convert a Map to a plain object for serialization