@soulcraft/brainy 5.5.0 → 5.6.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [5.6.1](https://github.com/soulcraftlabs/brainy/compare/v5.6.0...v5.6.1) (2025-11-11)
+
+### 🐛 Bug Fixes
+
+* **storage**: Fix `clear()` not deleting COW version control data ([#workshop-bug-report](https://github.com/soulcraftlabs/brainy/issues))
+  - Fixed all storage adapters to properly delete `_cow/` directory on clear()
+  - Fixed in-memory entity counters not being reset after clear()
+  - Prevents COW reinitialization after clear() by setting `cowEnabled = false`
+  - **Impact**: Resolves storage persistence bug (103MB → 0 bytes after clear)
+  - **Affected adapters**: FileSystemStorage, OPFSStorage, S3CompatibleStorage (GCSStorage, R2Storage, AzureBlobStorage already correct)
+
+### 📝 Technical Details
+
+* **Root causes identified**:
+  1. `_cow/` directory contents deleted but directory not removed
+  2. In-memory counters (`totalNounCount`, `totalVerbCount`) not reset
+  3. COW could auto-reinitialize on next operation
+* **Fixes applied**:
+  - FileSystemStorage: Use `fs.rm()` to delete entire `_cow/` directory
+  - OPFSStorage: Use `removeEntry('_cow', {recursive: true})`
+  - Cloud adapters: Already use `deleteObjectsWithPrefix('_cow/')`
+  - All adapters: Reset `totalNounCount = 0` and `totalVerbCount = 0`
+  - BaseStorage: Added guard in `initializeCOW()` to prevent reinitialization when `cowEnabled === false`
+
+## [5.6.0](https://github.com/soulcraftlabs/brainy/compare/v5.5.0...v5.6.0) (2025-11-11)
+
+### 🐛 Bug Fixes
+
+* **relations**: Fix `getRelations()` returning empty array for fresh instances
+  - Resolved initialization race condition in relationship loading
+  - Fresh Brain instances now correctly load persisted relationships
+
 ## [5.5.0](https://github.com/soulcraftlabs/brainy/compare/v5.4.0...v5.5.0) (2025-11-06)
 
 ### 🎯 Stage 3 CANONICAL Taxonomy - Complete Coverage

package/dist/augmentations/display/fieldPatterns.js

@@ -20,7 +20,7 @@ export const UNIVERSAL_FIELD_PATTERNS = [
         fields: ['firstName', 'lastName', 'fullName', 'realName'],
         displayField: 'title',
         confidence: 0.9,
-        applicableTypes: [NounType.Person, NounType.Person],
+        applicableTypes: [NounType.Person],
         transform: (value, context) => {
             const { metadata } = context;
             if (metadata.firstName && metadata.lastName) {
@@ -68,7 +68,7 @@ export const UNIVERSAL_FIELD_PATTERNS = [
         fields: ['bio', 'biography', 'profile', 'about'],
         displayField: 'description',
         confidence: 0.85,
-        applicableTypes: [NounType.Person, NounType.Person]
+        applicableTypes: [NounType.Person]
     },
     {
         fields: ['content', 'text', 'body', 'message'],
@@ -100,7 +100,7 @@ export const UNIVERSAL_FIELD_PATTERNS = [
         fields: ['role', 'position', 'jobTitle', 'occupation'],
         displayField: 'type',
         confidence: 0.8,
-        applicableTypes: [NounType.Person, NounType.Person],
+        applicableTypes: [NounType.Person],
         transform: (value) => String(value || 'Person')
     },
     {

package/dist/augmentations/display/intelligentComputation.d.ts

@@ -5,7 +5,7 @@
  * - BrainyTypes for semantic type detection
  * - Neural Import patterns for field analysis
  * - JSON processing utilities for field extraction
- * - Existing NounType/VerbType taxonomy (31+40 types)
+ * - Existing NounType/VerbType taxonomy (42+127 types)
  */
 import type { ComputedDisplayFields, DisplayConfig } from './types.js';
 import type { GraphVerb } from '../../coreTypes.js';

package/dist/augmentations/display/intelligentComputation.js

@@ -5,7 +5,7 @@
  * - BrainyTypes for semantic type detection
  * - Neural Import patterns for field analysis
  * - JSON processing utilities for field extraction
- * - Existing NounType/VerbType taxonomy (31+40 types)
+ * - Existing NounType/VerbType taxonomy (42+127 types)
  */
 import { getBrainyTypes } from '../typeMatching/brainyTypes.js';
 import { getFieldPatterns, getPriorityFields } from './fieldPatterns.js';

package/dist/augmentations/typeMatching/brainyTypes.d.ts

@@ -2,7 +2,7 @@
  * BrainyTypes - Intelligent type detection using semantic embeddings
  *
  * This module uses our existing TransformerEmbedding and similarity functions
- * to intelligently match data to our 31 noun types and 40 verb types.
+ * to intelligently match data to our 42 noun types and 127 verb types.
  *
  * Features:
  * - Semantic similarity matching using embeddings

package/dist/augmentations/typeMatching/brainyTypes.js

@@ -2,7 +2,7 @@
  * BrainyTypes - Intelligent type detection using semantic embeddings
  *
  * This module uses our existing TransformerEmbedding and similarity functions
- * to intelligently match data to our 31 noun types and 40 verb types.
+ * to intelligently match data to our 42 noun types and 127 verb types.
  *
  * Features:
  * - Semantic similarity matching using embeddings

package/dist/augmentations/typeMatching/intelligentTypeMatcher.d.ts

@@ -2,7 +2,7 @@
  * IntelligentTypeMatcher - Wrapper around BrainyTypes for testing
  *
  * Provides intelligent type detection using semantic embeddings
- * for matching data to our 31 noun types and 40 verb types.
+ * for matching data to our 42 noun types and 127 verb types.
  */
 import { NounType, VerbType } from '../../types/graphTypes.js';
 export interface TypeMatchOptions {

package/dist/augmentations/typeMatching/intelligentTypeMatcher.js

@@ -2,7 +2,7 @@
  * IntelligentTypeMatcher - Wrapper around BrainyTypes for testing
  *
  * Provides intelligent type detection using semantic embeddings
- * for matching data to our 31 noun types and 40 verb types.
+ * for matching data to our 42 noun types and 127 verb types.
  */
 import { VerbType } from '../../types/graphTypes.js';
 import { getBrainyTypes } from './brainyTypes.js';

package/dist/augmentations/universalDisplayAugmentation.d.ts

@@ -5,7 +5,7 @@
  *
  * Features:
  * - ✅ Leverages existing BrainyTypes for semantic type detection
- * - ✅ Complete icon coverage for all 31 NounTypes + 40+ VerbTypes
+ * - ✅ Complete icon coverage for all 42 NounTypes + 127 VerbTypes
  * - ✅ Zero performance impact with lazy computation and intelligent caching
  * - ✅ Perfect isolation - can be disabled, replaced, or configured
  * - ✅ Clean developer experience with zero conflicts

package/dist/augmentations/universalDisplayAugmentation.js

@@ -5,7 +5,7 @@
  *
  * Features:
  * - ✅ Leverages existing BrainyTypes for semantic type detection
- * - ✅ Complete icon coverage for all 31 NounTypes + 40+ VerbTypes
+ * - ✅ Complete icon coverage for all 42 NounTypes + 127 VerbTypes
  * - ✅ Zero performance impact with lazy computation and intelligent caching
  * - ✅ Perfect isolation - can be disabled, replaced, or configured
  * - ✅ Clean developer experience with zero conflicts

package/dist/brainy.js

@@ -3282,7 +3282,7 @@ export class Brainy {
                 return Object.fromEntries(this.metadataIndex.getAllEntityCounts());
             },
             // Phase 1b: O(1) count by type enum (Uint32Array-based, more efficient)
-            // Uses fixed-size type tracking: 284 bytes vs ~35KB with Maps (99.2% reduction)
+            // Uses fixed-size type tracking: 676 bytes vs ~35KB with Maps (98.1% reduction)
             byTypeEnum: (type) => {
                 return this.metadataIndex.getEntityCountByTypeEnum(type);
             },

package/dist/cli/commands/types.js

@@ -26,7 +26,7 @@ export async function types(options) {
         }
         // Display nouns
         if (showNouns) {
-            console.log(chalk.bold.cyan('\n📚 Noun Types (31):\n'));
+            console.log(chalk.bold.cyan('\n📚 Noun Types (42):\n'));
             const nounChunks = [];
             for (let i = 0; i < BrainyTypes.nouns.length; i += 3) {
                 nounChunks.push(BrainyTypes.nouns.slice(i, i + 3));
@@ -37,7 +37,7 @@ export async function types(options) {
         }
         // Display verbs
         if (showVerbs) {
-            console.log(chalk.bold.cyan('\n🔗 Verb Types (40):\n'));
+            console.log(chalk.bold.cyan('\n🔗 Verb Types (127):\n'));
             const verbChunks = [];
             for (let i = 0; i < BrainyTypes.verbs.length; i += 3) {
                 verbChunks.push(BrainyTypes.verbs.slice(i, i + 3));

package/dist/hnsw/typeAwareHNSWIndex.d.ts

@@ -7,7 +7,7 @@
  * - Storage: Already type-first from Phase 1a
  *
  * Architecture:
- * - One HNSWIndex per NounType (31 total)
+ * - One HNSWIndex per NounType (42 total)
  * - Lazy initialization (indexes created on first use)
  * - Type routing for optimal performance
  * - Falls back to multi-type search when type unknown
@@ -101,7 +101,7 @@ export declare class TypeAwareHNSWIndex {
      * **All-types search** (fallback):
      * ```typescript
      * await index.search(queryVector, 10)
-     * // Searches all 31 graphs (slower but comprehensive)
+     * // Searches all 42 graphs (slower but comprehensive)
      * ```
      *
      * @param queryVector Query vector
@@ -192,7 +192,7 @@ export declare class TypeAwareHNSWIndex {
      * Rebuild HNSW indexes from storage (type-aware)
      *
      * CRITICAL: This implementation uses type-filtered pagination to avoid
-     * loading ALL entities for each type (which would be 31 billion reads @ 1B scale).
+     * loading ALL entities for each type (which would be 42 billion reads @ 1B scale).
      *
      * Can rebuild all types or specific types.
      * Much faster than rebuilding a monolithic index.

package/dist/hnsw/typeAwareHNSWIndex.js

@@ -7,7 +7,7 @@
  * - Storage: Already type-first from Phase 1a
  *
  * Architecture:
- * - One HNSWIndex per NounType (31 total)
+ * - One HNSWIndex per NounType (42 total)
  * - Lazy initialization (indexes created on first use)
  * - Type routing for optimal performance
  * - Falls back to multi-type search when type unknown
@@ -84,7 +84,7 @@ export class TypeAwareHNSWIndex {
         // Validate type is a valid NounType
         const typeIndex = TypeUtils.getNounIndex(type);
         if (typeIndex === undefined || typeIndex === null || typeIndex < 0) {
-            throw new Error(`Invalid NounType: ${type}. Must be one of the 31 defined types.`);
+            throw new Error(`Invalid NounType: ${type}. Must be one of the 42 defined types.`);
         }
         if (!this.indexes.has(type)) {
             prodLog.info(`Creating HNSW index for type: ${type}`);
@@ -137,7 +137,7 @@ export class TypeAwareHNSWIndex {
      * **All-types search** (fallback):
      * ```typescript
      * await index.search(queryVector, 10)
-     * // Searches all 31 graphs (slower but comprehensive)
+     * // Searches all 42 graphs (slower but comprehensive)
      * ```
      *
      * @param queryVector Query vector
@@ -302,7 +302,7 @@ export class TypeAwareHNSWIndex {
      * Rebuild HNSW indexes from storage (type-aware)
      *
      * CRITICAL: This implementation uses type-filtered pagination to avoid
-     * loading ALL entities for each type (which would be 31 billion reads @ 1B scale).
+     * loading ALL entities for each type (which would be 42 billion reads @ 1B scale).
      *
      * Can rebuild all types or specific types.
      * Much faster than rebuilding a monolithic index.
@@ -341,7 +341,7 @@ export class TypeAwareHNSWIndex {
                 `(${(vectorMemory / 1024 / 1024).toFixed(1)}MB > ${(availableCache / 1024 / 1024).toFixed(1)}MB cache) - loading on-demand`);
         }
         // Load ALL nouns ONCE and route to correct type indexes
-        // This is O(N) instead of O(31*N) from the previous parallel approach
+        // This is O(N) instead of O(42*N) from the previous parallel approach
         let cursor = undefined;
         let hasMore = true;
         let totalLoaded = 0;

package/dist/importers/SmartExcelImporter.js

@@ -41,7 +41,7 @@ export class SmartExcelImporter {
             enableRelationshipInference: true,
             // CONCEPT EXTRACTION PRODUCTION-READY (v3.33.0+):
             // Type embeddings are now pre-computed at build time - zero runtime cost!
-            // All 31 noun types + 40 verb types instantly available
+            // All 42 noun types + 127 verb types instantly available
             //
             // Performance profile:
             // - Type embeddings: INSTANT (pre-computed at build time, ~100KB in-memory)

package/dist/neural/embeddedKeywordEmbeddings.d.ts

@@ -2,7 +2,7 @@
  * Pre-computed Keyword Embeddings for Unified Semantic Type Inference
  *
  * Generated by: scripts/buildKeywordEmbeddings.ts
- * Generated on: 2025-11-06T15:31:57.920Z
+ * Generated on: 2025-11-06T17:59:17.355Z
  * Total keywords: 1050 (716 nouns + 334 verbs)
  * Canonical: 919, Synonyms: 131
  * Embedding dimension: 384

package/dist/neural/embeddedKeywordEmbeddings.js

@@ -2,7 +2,7 @@
  * Pre-computed Keyword Embeddings for Unified Semantic Type Inference
  *
  * Generated by: scripts/buildKeywordEmbeddings.ts
- * Generated on: 2025-11-06T15:31:57.920Z
+ * Generated on: 2025-11-06T17:59:17.355Z
  * Total keywords: 1050 (716 nouns + 334 verbs)
  * Canonical: 919, Synonyms: 131
  * Embedding dimension: 384

package/dist/neural/embeddedTypeEmbeddings.d.ts

@@ -2,7 +2,7 @@
  * 🧠 BRAINY EMBEDDED TYPE EMBEDDINGS
  *
  * AUTO-GENERATED - DO NOT EDIT
- * Generated: 2025-11-06T16:58:34.845Z
+ * Generated: 2025-11-06T17:38:22.619Z
  * Noun Types: 42
  * Verb Types: 127
  *

package/dist/neural/embeddedTypeEmbeddings.js

@@ -2,7 +2,7 @@
  * 🧠 BRAINY EMBEDDED TYPE EMBEDDINGS
  *
  * AUTO-GENERATED - DO NOT EDIT
- * Generated: 2025-11-06T16:58:34.845Z
+ * Generated: 2025-11-06T17:38:22.619Z
  * Noun Types: 42
  * Verb Types: 127
  *
@@ -15,7 +15,7 @@ export const TYPE_METADATA = {
     verbTypes: 127,
     totalTypes: 169,
     embeddingDimensions: 384,
-    generatedAt: "2025-11-06T16:58:34.845Z",
+    generatedAt: "2025-11-06T17:38:22.619Z",
     sizeBytes: {
         embeddings: 259584,
         base64: 346112

package/dist/query/typeAwareQueryPlanner.d.ts

@@ -6,14 +6,14 @@
  * TypeAwareHNSWIndex graphs.
  *
  * Performance Impact:
- * - Single-type queries: 31x speedup (search 1/31 graphs)
- * - Multi-type queries: 6-15x speedup (search 2-5/31 graphs)
+ * - Single-type queries: 42x speedup (search 1/42 graphs)
+ * - Multi-type queries: 8-21x speedup (search 2-5/42 graphs)
  * - Overall: 40% latency reduction @ 1B scale
  *
  * Examples:
- * - "Find engineers" → single-type → [Person] → 31x speedup
- * - "People at Tesla" → multi-type → [Person, Organization] → 15.5x speedup
- * - "Everything about AI" → all-types → [all 31 types] → no speedup
+ * - "Find engineers" → single-type → [Person] → 42x speedup
+ * - "People at Tesla" → multi-type → [Person, Organization] → 21x speedup
+ * - "Everything about AI" → all-types → [all 42 types] → no speedup
  */
 import { NounType } from '../types/graphTypes.js';
 import { type TypeInference } from './semanticTypeInference.js';
@@ -38,11 +38,11 @@ export interface TypeAwareQueryPlan {
      */
     routing: QueryRoutingStrategy;
     /**
-     * Target types to search (1-31 types)
+     * Target types to search (1-42 types)
      */
     targetTypes: NounType[];
     /**
-     * Estimated speedup factor (1.0 = no speedup, 31.0 = 31x faster)
+     * Estimated speedup factor (1.0 = no speedup, 42.0 = 42x faster)
      */
     estimatedSpeedup: number;
     /**

package/dist/query/typeAwareQueryPlanner.js

@@ -6,14 +6,14 @@
  * TypeAwareHNSWIndex graphs.
  *
  * Performance Impact:
- * - Single-type queries: 31x speedup (search 1/31 graphs)
- * - Multi-type queries: 6-15x speedup (search 2-5/31 graphs)
+ * - Single-type queries: 42x speedup (search 1/42 graphs)
+ * - Multi-type queries: 8-21x speedup (search 2-5/42 graphs)
  * - Overall: 40% latency reduction @ 1B scale
  *
  * Examples:
- * - "Find engineers" → single-type → [Person] → 31x speedup
- * - "People at Tesla" → multi-type → [Person, Organization] → 15.5x speedup
- * - "Everything about AI" → all-types → [all 31 types] → no speedup
+ * - "Find engineers" → single-type → [Person] → 42x speedup
+ * - "People at Tesla" → multi-type → [Person, Organization] → 21x speedup
+ * - "Everything about AI" → all-types → [all 42 types] → no speedup
  */
 import { NounType, NOUN_TYPE_COUNT } from '../types/graphTypes.js';
 import { inferNouns } from './semanticTypeInference.js';
@@ -207,13 +207,13 @@ export class TypeAwareQueryPlanner {
         const allPct = ((this.stats.allTypesQueries / total) * 100).toFixed(1);
         const avgConf = (this.stats.avgConfidence * 100).toFixed(1);
         // Calculate weighted average speedup
-        const avgSpeedup = ((this.stats.singleTypeQueries * 31.0 +
+        const avgSpeedup = ((this.stats.singleTypeQueries * 42.0 +
             this.stats.multiTypeQueries * 10.0 +
             this.stats.allTypesQueries * 1.0) /
             total).toFixed(1);
         return `
 Query Statistics (${total} total):
-- Single-type: ${this.stats.singleTypeQueries} (${singlePct}%) - 31x speedup
+- Single-type: ${this.stats.singleTypeQueries} (${singlePct}%) - 42x speedup
 - Multi-type:  ${this.stats.multiTypeQueries} (${multiPct}%) - ~10x speedup
 - All-types:   ${this.stats.allTypesQueries} (${allPct}%) - 1x speedup
 - Avg confidence: ${avgConf}%

package/dist/storage/adapters/azureBlobStorage.js

@@ -851,12 +851,21 @@ export class AzureBlobStorage extends BaseStorage {
         try {
             this.logger.info('🧹 Clearing all data from Azure container...');
             // Delete all blobs in container
+            // v5.6.1: listBlobsFlat() returns ALL blobs including _cow/ prefix
+            // This correctly deletes COW version control data (commits, trees, blobs, refs)
             for await (const blob of this.containerClient.listBlobsFlat()) {
                 if (blob.name) {
                     const blockBlobClient = this.containerClient.getBlockBlobClient(blob.name);
                     await blockBlobClient.delete();
                 }
             }
+            // CRITICAL: Reset COW state to prevent automatic reinitialization
+            // When COW data is cleared, we must also clear the COW managers
+            // Otherwise initializeCOW() will auto-recreate initial commit on next operation
+            this.refManager = undefined;
+            this.blobStorage = undefined;
+            this.commitLog = undefined;
+            this.cowEnabled = false;
             // Clear caches
             this.nounCacheManager.clear();
             this.verbCacheManager.clear();

package/dist/storage/adapters/fileSystemStorage.js

@@ -874,9 +874,26 @@ export class FileSystemStorage extends BaseStorage {
         if (await this.directoryExists(this.indexDir)) {
             await removeDirectoryContents(this.indexDir);
         }
+        // v5.6.1: Remove COW (copy-on-write) version control data
+        // This directory stores all git-like versioning data (commits, trees, blobs, refs)
+        // Must be deleted to fully clear all data including version history
+        const cowDir = path.join(this.rootDir, '_cow');
+        if (await this.directoryExists(cowDir)) {
+            // Delete the entire _cow/ directory (not just contents)
+            await fs.promises.rm(cowDir, { recursive: true, force: true });
+            // CRITICAL: Reset COW state to prevent automatic reinitialization
+            // When COW data is cleared, we must also clear the COW managers
+            // Otherwise initializeCOW() will auto-recreate initial commit on next operation
+            this.refManager = undefined;
+            this.blobStorage = undefined;
+            this.commitLog = undefined;
+            this.cowEnabled = false;
+        }
         // Clear the statistics cache
         this.statisticsCache = null;
         this.statisticsModified = false;
+        this.totalNounCount = 0;
+        this.totalVerbCount = 0;
     }
     /**
      * Enhanced clear operation with safety mechanisms and performance optimizations

package/dist/storage/adapters/gcsStorage.js

@@ -778,6 +778,17 @@ export class GcsStorage extends BaseStorage {
             await deleteObjectsWithPrefix(this.metadataPrefix);
             await deleteObjectsWithPrefix(this.verbMetadataPrefix);
             await deleteObjectsWithPrefix(this.systemPrefix);
+            // v5.6.1: Clear COW (copy-on-write) version control data
+            // This includes all git-like versioning data (commits, trees, blobs, refs)
+            // Must be deleted to fully clear all data including version history
+            await deleteObjectsWithPrefix('_cow/');
+            // CRITICAL: Reset COW state to prevent automatic reinitialization
+            // When COW data is cleared, we must also clear the COW managers
+            // Otherwise initializeCOW() will auto-recreate initial commit on next operation
+            this.refManager = undefined;
+            this.blobStorage = undefined;
+            this.commitLog = undefined;
+            this.cowEnabled = false;
             // Clear caches
             this.nounCacheManager.clear();
             this.verbCacheManager.clear();

package/dist/storage/adapters/opfsStorage.js

@@ -387,9 +387,31 @@ export class OPFSStorage extends BaseStorage {
             await removeDirectoryContents(this.verbMetadataDir);
             // Remove all files in the index directory
             await removeDirectoryContents(this.indexDir);
+            // v5.6.1: Remove COW (copy-on-write) version control data
+            // This directory stores all git-like versioning data (commits, trees, blobs, refs)
+            // Must be deleted to fully clear all data including version history
+            try {
+                // Delete the entire _cow/ directory (not just contents)
+                await this.rootDir.removeEntry('_cow', { recursive: true });
+                // CRITICAL: Reset COW state to prevent automatic reinitialization
+                // When COW data is cleared, we must also clear the COW managers
+                // Otherwise initializeCOW() will auto-recreate initial commit on next operation
+                this.refManager = undefined;
+                this.blobStorage = undefined;
+                this.commitLog = undefined;
+                this.cowEnabled = false;
+            }
+            catch (error) {
+                // Ignore if _cow directory doesn't exist (not all instances use COW)
+                if (error.name !== 'NotFoundError') {
+                    throw error;
+                }
+            }
             // Clear the statistics cache
             this.statisticsCache = null;
             this.statisticsModified = false;
+            this.totalNounCount = 0;
+            this.totalVerbCount = 0;
         }
         catch (error) {
             console.error('Error clearing storage:', error);

package/dist/storage/adapters/r2Storage.js

@@ -771,13 +771,22 @@ export class R2Storage extends BaseStorage {
     async clear() {
         await this.ensureInitialized();
         prodLog.info('🧹 R2: Clearing all data from bucket...');
-        // Clear all prefixes
-        for (const prefix of [this.nounPrefix, this.verbPrefix, this.metadataPrefix, this.verbMetadataPrefix, this.systemPrefix]) {
+        // Clear all prefixes (v5.6.1: includes _cow/ for version control data)
+        // _cow/ stores all git-like versioning data (commits, trees, blobs, refs)
+        // Must be deleted to fully clear all data including version history
+        for (const prefix of [this.nounPrefix, this.verbPrefix, this.metadataPrefix, this.verbMetadataPrefix, this.systemPrefix, '_cow/']) {
             const objects = await this.listObjectsUnderPath(prefix);
             for (const key of objects) {
                 await this.deleteObjectFromPath(key);
             }
         }
+        // CRITICAL: Reset COW state to prevent automatic reinitialization
+        // When COW data is cleared, we must also clear the COW managers
+        // Otherwise initializeCOW() will auto-recreate initial commit on next operation
+        this.refManager = undefined;
+        this.blobStorage = undefined;
+        this.commitLog = undefined;
+        this.cowEnabled = false;
         this.nounCacheManager.clear();
         this.verbCacheManager.clear();
         this.totalNounCount = 0;

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -1621,9 +1621,22 @@ export class S3CompatibleStorage extends BaseStorage {
             await deleteObjectsWithPrefix(this.verbMetadataPrefix);
             // Delete all objects in the index directory
             await deleteObjectsWithPrefix(this.indexPrefix);
+            // v5.6.1: Delete COW (copy-on-write) version control data
+            // This includes all git-like versioning data (commits, trees, blobs, refs)
+            // Must be deleted to fully clear all data including version history
+            await deleteObjectsWithPrefix('_cow/');
+            // CRITICAL: Reset COW state to prevent automatic reinitialization
+            // When COW data is cleared, we must also clear the COW managers
+            // Otherwise initializeCOW() will auto-recreate initial commit on next operation
+            this.refManager = undefined;
+            this.blobStorage = undefined;
+            this.commitLog = undefined;
+            this.cowEnabled = false;
             // Clear the statistics cache
             this.statisticsCache = null;
             this.statisticsModified = false;
+            this.totalNounCount = 0;
+            this.totalVerbCount = 0;
         }
         catch (error) {
             prodLog.error('Failed to clear storage:', error);

package/dist/storage/baseStorage.d.ts

@@ -61,6 +61,7 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     protected verbCountsByType: Uint32Array<ArrayBuffer>;
     protected nounTypeCache: Map<string, NounType>;
     protected verbTypeCache: Map<string, VerbType>;
+    private typeCountsRebuilt;
     /**
      * Analyze a storage key to determine its routing and path
      * @param id - The key to analyze (UUID or system key)
@@ -224,7 +225,15 @@ export declare abstract 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.
+     * Iterates through noun types with billion-scale optimizations.
+     *
+     * ARCHITECTURE: Reads storage directly (not indexes) to avoid circular dependencies.
+     * Storage → Indexes (one direction only). GraphAdjacencyIndex built FROM storage.
+     *
+     * OPTIMIZATIONS (v5.5.0):
+     * - Skip empty types using nounCountsByType[] tracking (O(1) check)
+     * - Early termination when offset + limit entities collected
+     * - Memory efficient: Never loads full dataset
      */
     getNounsWithPagination(options: {
         limit: number;
@@ -241,6 +250,38 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
         hasMore: boolean;
         nextCursor?: string;
     }>;
+    /**
+     * Get verbs with pagination (v5.5.0: Type-first implementation with billion-scale optimizations)
+     *
+     * CRITICAL: This method is required for brain.getRelations() to work!
+     * Iterates through verb types with the same optimizations as nouns.
+     *
+     * ARCHITECTURE: Reads storage directly (not indexes) to avoid circular dependencies.
+     * Storage → Indexes (one direction only). GraphAdjacencyIndex built FROM storage.
+     *
+     * OPTIMIZATIONS (v5.5.0):
+     * - Skip empty types using verbCountsByType[] tracking (O(1) check)
+     * - Early termination when offset + limit verbs collected
+     * - Memory efficient: Never loads full dataset
+     * - Inline filtering for sourceId, targetId, verbType
+     */
+    getVerbsWithPagination(options: {
+        limit: number;
+        offset: number;
+        cursor?: string;
+        filter?: {
+            verbType?: string | string[];
+            sourceId?: string | string[];
+            targetId?: string | string[];
+            service?: string | string[];
+            metadata?: Record<string, any>;
+        };
+    }): Promise<{
+        items: HNSWVerbWithMetadata[];
+        totalCount: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
     /**
      * Get verbs with pagination and filtering
      * @param options Pagination and filtering options
@@ -393,6 +434,12 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * Periodically called when counts are updated
      */
     protected saveTypeStatistics(): Promise<void>;
+    /**
+     * Rebuild type counts from actual storage (v5.5.0)
+     * Called when statistics are missing or inconsistent
+     * Ensures verbCountsByType is always accurate for reliable pagination
+     */
+    protected rebuildTypeCounts(): Promise<void>;
     /**
      * Get noun type from cache or metadata
      * Relies on nounTypeCache populated during metadata saves