@soulcraft/brainy 6.3.0 → 6.3.1

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 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.
 
+### [6.3.1](https://github.com/soulcraftlabs/brainy/compare/v6.3.0...v6.3.1) (2025-12-09)
+
+- fix(versioning): clean architecture with index pollution prevention (f145fa1)
+- chore(release): 6.3.0 - singleton GraphAdjacencyIndex architecture fix (292be1b)
+- fix(architecture): singleton GraphAdjacencyIndex via storage.getGraphIndex() (v6.3.0) (c15892e)
+- chore(release): 6.2.9 - fix critical VFS bugs (directory corruption) (810b756)
+- fix(vfs): resolve two critical VFS bugs causing directory listing corruption (2ba69ec)
+- chore(release): 6.2.8 - deferred HNSW persistence for 30-50× faster cloud adds (1da6048)
+- perf(hnsw): deferred persistence mode for 30-50× faster cloud storage adds (4d1d567)
+- chore(release): 6.2.7 - simplify cloud storage to always-on write buffering (a33b759)
+- perf(storage): simplify cloud adapters to always-on write buffering (26510ce)
+- chore(release): 6.2.6 - fix cloud storage read-after-write consistency (6449bb1)
+- fix(storage): populate cache before write buffer for read-after-write consistency (2d27bd0)
+- chore(release): 6.2.5 - fix counts.byType() accumulation bug (e4bbd7f)
+- fix(counts): counts.byType() returns inflated values due to accumulation bug (9456c2c)
+- chore(release): 6.2.4 - fix asOf() COW property name mismatch (ea53c11)
+- fix(cow): asOf() fails with "COW not enabled" due to property name mismatch (b3ae18b)
+- chore(release): 6.2.3 - fix counts.byType({ excludeVFS: true }) returning empty (0ba6da4)
+- fix(counts): counts.byType({ excludeVFS: true }) now returns correct type counts (9b2ff2d)
+
+
 ### [6.2.2](https://github.com/soulcraftlabs/brainy/compare/v6.2.1...v6.2.2) (2025-11-25)
 
 - refactor: remove 3,700+ LOC of unused HNSW implementations (e3146ce)

package/dist/brainy.d.ts

@@ -4,6 +4,7 @@
  * Beautiful, Professional, Planet-Scale, Fun to Use
  * NO STUBS, NO MOCKS, REAL IMPLEMENTATION
  */
+import { BaseStorage } from './storage/baseStorage.js';
 import { Vector } from './coreTypes.js';
 import { ImprovedNeuralAPI } from './neural/improvedNeuralAPI.js';
 import { NaturalLanguageProcessor } from './neural/naturalLanguageProcessor.js';
@@ -1629,6 +1630,60 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
         };
         density: number;
     }>;
+    /**
+     * Search entities by metadata filters (internal API)
+     * Used by versioning system for querying version metadata
+     *
+     * @param filters - Metadata filter object (same format as `where` in find())
+     * @returns Array of matching entities
+     * @internal
+     */
+    searchByMetadata(filters: Record<string, any>): Promise<any[]>;
+    /**
+     * Get raw noun metadata (internal API)
+     * Used by versioning system for reading entity state
+     *
+     * @param id - Entity ID
+     * @returns Noun metadata or null if not found
+     * @internal
+     */
+    getNounMetadata(id: string): Promise<any | null>;
+    /**
+     * Save raw noun metadata (internal API)
+     * Used by versioning system for storing version index entries
+     *
+     * @param id - Entity ID
+     * @param data - Metadata to save
+     * @internal
+     */
+    saveNounMetadata(id: string, data: any): Promise<void>;
+    /**
+     * Delete noun metadata (internal API)
+     * Used by versioning system for removing version index entries
+     *
+     * @param id - Entity ID
+     * @internal
+     */
+    deleteNounMetadata(id: string): Promise<void>;
+    /**
+     * Current branch name (internal API)
+     * Used by versioning system for branch-aware operations
+     * @internal
+     */
+    get currentBranch(): string;
+    /**
+     * Reference manager for COW commits (internal API)
+     * Used by versioning system for commit operations
+     * @internal
+     */
+    get refManager(): any;
+    /**
+     * Storage adapter (internal API)
+     * Used by versioning system for direct storage access
+     * Returns BaseStorage which has saveMetadata/getMetadata for key-value storage
+     * @internal
+     */
+    get storageAdapter(): BaseStorage;
     /**
      * Parse natural language query using advanced NLP with 220+ patterns
      * The embedding model is always available as it's core to Brainy's functionality

package/dist/brainy.js

@@ -3554,6 +3554,92 @@ export class Brainy {
     async getStats(options) {
         return this.counts.getStats(options);
     }
+    // ============= INTERNAL VERSIONING API =============
+    // These methods are used by the versioning system (brain.versions.*)
+    // They expose internal storage and index operations needed for entity versioning
+    /**
+     * Search entities by metadata filters (internal API)
+     * Used by versioning system for querying version metadata
+     *
+     * @param filters - Metadata filter object (same format as `where` in find())
+     * @returns Array of matching entities
+     * @internal
+     */
+    async searchByMetadata(filters) {
+        await this.ensureInitialized();
+        const ids = await this.metadataIndex.getIdsForFilter(filters);
+        if (ids.length === 0)
+            return [];
+        const results = [];
+        const entitiesMap = await this.batchGet(ids);
+        for (const id of ids) {
+            const entity = entitiesMap.get(id);
+            if (entity) {
+                results.push(entity);
+            }
+        }
+        return results;
+    }
+    /**
+     * Get raw noun metadata (internal API)
+     * Used by versioning system for reading entity state
+     *
+     * @param id - Entity ID
+     * @returns Noun metadata or null if not found
+     * @internal
+     */
+    async getNounMetadata(id) {
+        await this.ensureInitialized();
+        return this.storage.getNounMetadata(id);
+    }
+    /**
+     * Save raw noun metadata (internal API)
+     * Used by versioning system for storing version index entries
+     *
+     * @param id - Entity ID
+     * @param data - Metadata to save
+     * @internal
+     */
+    async saveNounMetadata(id, data) {
+        await this.ensureInitialized();
+        await this.storage.saveNounMetadata(id, data);
+    }
+    /**
+     * Delete noun metadata (internal API)
+     * Used by versioning system for removing version index entries
+     *
+     * @param id - Entity ID
+     * @internal
+     */
+    async deleteNounMetadata(id) {
+        await this.ensureInitialized();
+        await this.storage.deleteNounMetadata(id);
+    }
+    /**
+     * Current branch name (internal API)
+     * Used by versioning system for branch-aware operations
+     * @internal
+     */
+    get currentBranch() {
+        return this.storage.currentBranch || 'main';
+    }
+    /**
+     * Reference manager for COW commits (internal API)
+     * Used by versioning system for commit operations
+     * @internal
+     */
+    get refManager() {
+        return this.storage.refManager;
+    }
+    /**
+     * Storage adapter (internal API)
+     * Used by versioning system for direct storage access
+     * Returns BaseStorage which has saveMetadata/getMetadata for key-value storage
+     * @internal
+     */
+    get storageAdapter() {
+        return this.storage;
+    }
     // ============= HELPER METHODS =============
     /**
      * Parse natural language query using advanced NLP with 220+ patterns

package/dist/versioning/VersionIndex.d.ts

@@ -1,33 +1,24 @@
 /**
- * VersionIndex - Fast Version Lookup Using Existing Index Infrastructure (v5.3.0)
+ * VersionIndex - Pure Key-Value Version Storage (v6.3.0)
  *
- * Integrates with Brainy's existing index system:
- * - Uses MetadataIndexManager for field indexing
- * - Leverages UnifiedCache for memory management
- * - Uses EntityIdMapper for efficient ID handling
- * - Uses ChunkManager for adaptive chunking
- * - Leverages Roaring Bitmaps for fast set operations
+ * Stores version metadata using simple key-value storage:
+ * - Version list per entity: __version_meta_{entityId}_{branch}
+ * - Content stored separately by VersionStorage
  *
- * Version metadata is stored as regular entities with type='_version'
- * This allows us to use existing index infrastructure without modification!
- *
- * Fields indexed:
- * - versionEntityId: Entity being versioned
- * - versionBranch: Branch version was created on
- * - versionNumber: Version number
- * - versionTag: Optional user tag
- * - versionTimestamp: Creation timestamp
- * - versionCommitHash: Commit hash
+ * Key Design Decisions:
+ * - Versions are NOT entities (no brain.add())
+ * - Versions do NOT pollute find() results
+ * - Simple O(1) lookups per entity
+ * - Versions per entity is typically small (10-1000)
  *
  * NO MOCKS - Production implementation
  */
-import type { EntityVersion } from './VersionManager.js';
-import type { VersionQuery } from './VersionManager.js';
+import type { EntityVersion, VersionQuery } from './VersionManager.js';
 /**
- * VersionIndex - Version lookup and querying using existing indexes
+ * VersionIndex - Pure key-value version metadata storage
  *
- * Strategy: Store version metadata as special entities with type='_version'
- * This leverages ALL existing index infrastructure automatically!
+ * Uses simple JSON storage instead of creating entities.
+ * This ensures versions never appear in find() results.
  */
 export declare class VersionIndex {
     private brain;
@@ -35,25 +26,21 @@ export declare class VersionIndex {
     constructor(brain: any);
     /**
      * Initialize version index
-     *
-     * No special setup needed - we use existing entity storage and indexes!
      */
     initialize(): Promise<void>;
     /**
      * Add version to index
      *
-     * Stores version metadata as a special entity with type='_version'
-     * This automatically indexes it using existing MetadataIndexManager!
+     * Stores version entry in key-value storage.
+     * Handles deduplication by content hash.
      *
-     * @param version Version metadata
+     * @param version Version metadata to store
      */
     addVersion(version: EntityVersion): Promise<void>;
     /**
      * Get versions for an entity
      *
-     * Uses existing MetadataIndexManager to query efficiently!
-     *
-     * @param query Version query
+     * @param query Version query with filters
      * @returns List of versions (newest first)
      */
     getVersions(query: VersionQuery): Promise<EntityVersion[]>;
@@ -92,35 +79,43 @@ export declare class VersionIndex {
      */
     removeVersion(entityId: string, version: number, branch: string): Promise<void>;
     /**
-     * Convert entity to EntityVersion format
-     *
-     * @param entity Entity from storage
-     * @returns EntityVersion or null if invalid
-     */
-    private entityToVersion;
-    /**
-     * Generate unique ID for version entity
-     *
-     * Format: _version:{entityId}:{version}:{branch}
+     * Clear all versions for an entity
      *
      * @param entityId Entity ID
-     * @param version Version number
      * @param branch Branch name
-     * @returns Version entity ID
+     * @returns Number of versions deleted
      */
-    private getVersionEntityId;
+    clearVersions(entityId: string, branch: string): Promise<number>;
     /**
      * Get all versioned entities (for cleanup/debugging)
      *
-     * @returns List of entity IDs that have versions
+     * Note: This is an expensive operation that requires scanning.
+     * In the simple key-value approach, we don't maintain a global index.
+     * This method returns an empty array - use storage-level scanning if needed.
+     *
+     * @returns Empty array (not supported in simple approach)
      */
     getVersionedEntities(): Promise<string[]>;
     /**
-     * Clear all versions for an entity
+     * Generate storage key for version metadata
      *
      * @param entityId Entity ID
      * @param branch Branch name
-     * @returns Number of versions deleted
+     * @returns Storage key
      */
-    clearVersions(entityId: string, branch: string): Promise<number>;
+    private getMetaKey;
+    /**
+     * Load version store from storage
+     *
+     * @param key Storage key
+     * @returns Version store or null
+     */
+    private loadStore;
+    /**
+     * Save version store to storage
+     *
+     * @param key Storage key
+     * @param store Version store
+     */
+    private saveStore;
 }