@soulcraft/brainy 3.50.2 → 4.0.0

package/dist/storage/adapters/typeAwareStorageAdapter.d.ts

@@ -18,7 +18,7 @@
  * @since Phase 1 - Type-First Implementation
  */
 import { BaseStorage } from '../baseStorage.js';
-import { GraphVerb, HNSWNoun, HNSWVerb, StatisticsData } from '../../coreTypes.js';
+import { HNSWNoun, HNSWVerb, HNSWVerbWithMetadata, NounMetadata, VerbMetadata, StatisticsData } from '../../coreTypes.js';
 import { NounType, VerbType } from '../../types/graphTypes.js';
 /**
  * Options for TypeAwareStorageAdapter
@@ -68,7 +68,10 @@ export declare class TypeAwareStorageAdapter extends BaseStorage {
      */
     private saveTypeStatistics;
     /**
-     * Get noun type from noun object or cache
+     * Get noun type from cache
+     *
+     * v4.0.0: Metadata is stored separately, so we rely on the cache
+     * which is populated when saveNounMetadata is called
      */
     private getNounType;
     /**
@@ -110,21 +113,50 @@ export declare class TypeAwareStorageAdapter extends BaseStorage {
     /**
      * Get verbs by source
      */
-    protected getVerbsBySource_internal(sourceId: string): Promise<GraphVerb[]>;
+    protected getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs by target
      */
-    protected getVerbsByTarget_internal(targetId: string): Promise<GraphVerb[]>;
+    protected getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs by type (O(1) with type-first paths!)
      *
-     * ARCHITECTURAL FIX (v3.50.1): Type is now in HNSWVerb, cached on read
+     * v4.0.0: Load verbs and combine with metadata
      */
-    protected getVerbsByType_internal(verbType: string): Promise<GraphVerb[]>;
+    protected getVerbsByType_internal(verbType: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Delete verb (type-first path)
      */
     protected deleteVerb_internal(id: string): Promise<void>;
+    /**
+     * Save noun metadata (override to cache type for type-aware routing)
+     *
+     * v4.0.0: Extract and cache noun type when metadata is saved
+     */
+    saveNounMetadata(id: string, metadata: NounMetadata): Promise<void>;
+    /**
+     * Get noun metadata (override to use type-aware paths)
+     */
+    getNounMetadata(id: string): Promise<NounMetadata | null>;
+    /**
+     * Delete noun metadata (override to use type-aware paths)
+     */
+    deleteNounMetadata(id: string): Promise<void>;
+    /**
+     * Save verb metadata (override to use type-aware paths)
+     *
+     * Note: Verb type comes from HNSWVerb.verb field, not metadata
+     * We need to read the verb to get the type for path routing
+     */
+    saveVerbMetadata(id: string, metadata: VerbMetadata): Promise<void>;
+    /**
+     * Get verb metadata (override to use type-aware paths)
+     */
+    getVerbMetadata(id: string): Promise<VerbMetadata | null>;
+    /**
+     * Delete verb metadata (override to use type-aware paths)
+     */
+    deleteVerbMetadata(id: string): Promise<void>;
     /**
      * Write object to path (delegate to underlying storage)
      */

package/dist/storage/adapters/typeAwareStorageAdapter.js

@@ -136,19 +136,19 @@ export class TypeAwareStorageAdapter extends BaseStorage {
         await this.u.writeObjectToPath(`${SYSTEM_DIR}/type-statistics.json`, stats);
     }
     /**
-     * Get noun type from noun object or cache
+     * Get noun type from cache
+     *
+     * v4.0.0: Metadata is stored separately, so we rely on the cache
+     * which is populated when saveNounMetadata is called
      */
     getNounType(noun) {
-        // Try metadata first (most reliable)
-        if (noun.metadata?.noun) {
-            return noun.metadata.noun;
-        }
-        // Try cache
+        // 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(`[TypeAwareStorage] Unknown noun type for ${noun.id}, defaulting to 'thing'`);
         return 'thing';
     }
@@ -340,21 +340,35 @@ export class TypeAwareStorageAdapter extends BaseStorage {
         const verbs = [];
         for (let i = 0; i < VERB_TYPE_COUNT; i++) {
             const type = TypeUtils.getVerbFromIndex(i);
-            const prefix = `entities/verbs/${type}/metadata/`;
+            const prefix = `entities/verbs/${type}/vectors/`;
             const paths = await this.u.listObjectsUnderPath(prefix);
             for (const path of paths) {
                 try {
-                    const metadata = await this.u.readObjectFromPath(path);
-                    if (metadata && metadata.sourceId === sourceId) {
-                        // Load the full GraphVerb
-                        const id = path.split('/').pop()?.replace('.json', '');
-                        if (id) {
-                            const verb = await this.getVerb(id);
-                            if (verb) {
-                                verbs.push(verb);
-                            }
-                        }
-                    }
+                    const id = path.split('/').pop()?.replace('.json', '');
+                    if (!id)
+                        continue;
+                    // Load the HNSWVerb
+                    const hnswVerb = await this.u.readObjectFromPath(path);
+                    if (!hnswVerb)
+                        continue;
+                    // Check sourceId from HNSWVerb (v4.0.0: core fields are in HNSWVerb)
+                    if (hnswVerb.sourceId !== sourceId)
+                        continue;
+                    // Load metadata separately
+                    const metadata = await this.getVerbMetadata(id);
+                    if (!metadata)
+                        continue;
+                    // Create HNSWVerbWithMetadata (verbs don't have level field)
+                    const verbWithMetadata = {
+                        id: hnswVerb.id,
+                        vector: [...hnswVerb.vector],
+                        connections: new Map(hnswVerb.connections),
+                        verb: hnswVerb.verb,
+                        sourceId: hnswVerb.sourceId,
+                        targetId: hnswVerb.targetId,
+                        metadata: metadata
+                    };
+                    verbs.push(verbWithMetadata);
                 }
                 catch (error) {
                     // Continue searching
@@ -371,20 +385,35 @@ export class TypeAwareStorageAdapter extends BaseStorage {
         const verbs = [];
         for (let i = 0; i < VERB_TYPE_COUNT; i++) {
             const type = TypeUtils.getVerbFromIndex(i);
-            const prefix = `entities/verbs/${type}/metadata/`;
+            const prefix = `entities/verbs/${type}/vectors/`;
             const paths = await this.u.listObjectsUnderPath(prefix);
             for (const path of paths) {
                 try {
-                    const metadata = await this.u.readObjectFromPath(path);
-                    if (metadata && metadata.targetId === targetId) {
-                        const id = path.split('/').pop()?.replace('.json', '');
-                        if (id) {
-                            const verb = await this.getVerb(id);
-                            if (verb) {
-                                verbs.push(verb);
-                            }
-                        }
-                    }
+                    const id = path.split('/').pop()?.replace('.json', '');
+                    if (!id)
+                        continue;
+                    // Load the HNSWVerb
+                    const hnswVerb = await this.u.readObjectFromPath(path);
+                    if (!hnswVerb)
+                        continue;
+                    // Check targetId from HNSWVerb (v4.0.0: core fields are in HNSWVerb)
+                    if (hnswVerb.targetId !== targetId)
+                        continue;
+                    // Load metadata separately
+                    const metadata = await this.getVerbMetadata(id);
+                    if (!metadata)
+                        continue;
+                    // Create HNSWVerbWithMetadata (verbs don't have level field)
+                    const verbWithMetadata = {
+                        id: hnswVerb.id,
+                        vector: [...hnswVerb.vector],
+                        connections: new Map(hnswVerb.connections),
+                        verb: hnswVerb.verb,
+                        sourceId: hnswVerb.sourceId,
+                        targetId: hnswVerb.targetId,
+                        metadata: metadata
+                    };
+                    verbs.push(verbWithMetadata);
                 }
                 catch (error) {
                     // Continue
@@ -396,7 +425,7 @@ export class TypeAwareStorageAdapter extends BaseStorage {
     /**
      * Get verbs by type (O(1) with type-first paths!)
      *
-     * ARCHITECTURAL FIX (v3.50.1): Type is now in HNSWVerb, cached on read
+     * v4.0.0: Load verbs and combine with metadata
      */
     async getVerbsByType_internal(verbType) {
         const type = verbType;
@@ -406,15 +435,25 @@ export class TypeAwareStorageAdapter extends BaseStorage {
         for (const path of paths) {
             try {
                 const hnswVerb = await this.u.readObjectFromPath(path);
-                if (hnswVerb) {
-                    // Cache type from HNSWVerb for future O(1) retrievals
-                    this.verbTypeCache.set(hnswVerb.id, hnswVerb.verb);
-                    // Convert to GraphVerb
-                    const graphVerb = await this.convertHNSWVerbToGraphVerb(hnswVerb);
-                    if (graphVerb) {
-                        verbs.push(graphVerb);
-                    }
-                }
+                if (!hnswVerb)
+                    continue;
+                // Cache type from HNSWVerb for future O(1) retrievals
+                this.verbTypeCache.set(hnswVerb.id, hnswVerb.verb);
+                // Load metadata separately
+                const metadata = await this.getVerbMetadata(hnswVerb.id);
+                if (!metadata)
+                    continue;
+                // Create HNSWVerbWithMetadata (verbs don't have level field)
+                const verbWithMetadata = {
+                    id: hnswVerb.id,
+                    vector: [...hnswVerb.vector],
+                    connections: new Map(hnswVerb.connections),
+                    verb: hnswVerb.verb,
+                    sourceId: hnswVerb.sourceId,
+                    targetId: hnswVerb.targetId,
+                    metadata: metadata
+                };
+                verbs.push(verbWithMetadata);
             }
             catch (error) {
                 console.warn(`[TypeAwareStorage] Failed to load verb from ${path}:`, error);
@@ -455,6 +494,146 @@ export class TypeAwareStorageAdapter extends BaseStorage {
             }
         }
     }
+    /**
+     * Save noun metadata (override to cache type for type-aware routing)
+     *
+     * v4.0.0: Extract and cache noun type when metadata is saved
+     */
+    async saveNounMetadata(id, metadata) {
+        // Extract and cache the type
+        const type = (metadata.noun || 'thing');
+        this.nounTypeCache.set(id, type);
+        // Save to type-aware path
+        const path = getNounMetadataPath(type, id);
+        await this.u.writeObjectToPath(path, metadata);
+    }
+    /**
+     * Get noun metadata (override to use type-aware paths)
+     */
+    async getNounMetadata(id) {
+        // Try cache first
+        const cachedType = this.nounTypeCache.get(id);
+        if (cachedType) {
+            const path = getNounMetadataPath(cachedType, id);
+            return await this.u.readObjectFromPath(path);
+        }
+        // Search across all types
+        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
+            const type = TypeUtils.getNounFromIndex(i);
+            const path = getNounMetadataPath(type, id);
+            try {
+                const metadata = await this.u.readObjectFromPath(path);
+                if (metadata) {
+                    // Cache the type for next time
+                    const metadataType = (metadata.noun || 'thing');
+                    this.nounTypeCache.set(id, metadataType);
+                    return metadata;
+                }
+            }
+            catch (error) {
+                // Not in this type, continue searching
+            }
+        }
+        return null;
+    }
+    /**
+     * Delete noun metadata (override to use type-aware paths)
+     */
+    async deleteNounMetadata(id) {
+        const cachedType = this.nounTypeCache.get(id);
+        if (cachedType) {
+            const path = getNounMetadataPath(cachedType, id);
+            await this.u.deleteObjectFromPath(path);
+            return;
+        }
+        // Search across all types
+        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
+            const type = TypeUtils.getNounFromIndex(i);
+            const path = getNounMetadataPath(type, id);
+            try {
+                await this.u.deleteObjectFromPath(path);
+                return;
+            }
+            catch (error) {
+                // Not in this type, continue
+            }
+        }
+    }
+    /**
+     * Save verb metadata (override to use type-aware paths)
+     *
+     * Note: Verb type comes from HNSWVerb.verb field, not metadata
+     * We need to read the verb to get the type for path routing
+     */
+    async saveVerbMetadata(id, metadata) {
+        // Get verb type from cache or by reading the verb
+        let type = this.verbTypeCache.get(id);
+        if (!type) {
+            // Need to read the verb to get its type
+            const verb = await this.getVerb_internal(id);
+            if (verb) {
+                type = verb.verb;
+                this.verbTypeCache.set(id, type);
+            }
+            else {
+                type = 'relatedTo';
+            }
+        }
+        // Save to type-aware path
+        const path = getVerbMetadataPath(type, id);
+        await this.u.writeObjectToPath(path, metadata);
+    }
+    /**
+     * Get verb metadata (override to use type-aware paths)
+     */
+    async getVerbMetadata(id) {
+        // Try cache first
+        const cachedType = this.verbTypeCache.get(id);
+        if (cachedType) {
+            const path = getVerbMetadataPath(cachedType, id);
+            return await this.u.readObjectFromPath(path);
+        }
+        // Search across all types
+        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
+            const type = TypeUtils.getVerbFromIndex(i);
+            const path = getVerbMetadataPath(type, id);
+            try {
+                const metadata = await this.u.readObjectFromPath(path);
+                if (metadata) {
+                    // Cache the type for next time
+                    this.verbTypeCache.set(id, type);
+                    return metadata;
+                }
+            }
+            catch (error) {
+                // Not in this type, continue
+            }
+        }
+        return null;
+    }
+    /**
+     * Delete verb metadata (override to use type-aware paths)
+     */
+    async deleteVerbMetadata(id) {
+        const cachedType = this.verbTypeCache.get(id);
+        if (cachedType) {
+            const path = getVerbMetadataPath(cachedType, id);
+            await this.u.deleteObjectFromPath(path);
+            return;
+        }
+        // Search across all types
+        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
+            const type = TypeUtils.getVerbFromIndex(i);
+            const path = getVerbMetadataPath(type, id);
+            try {
+                await this.u.deleteObjectFromPath(path);
+                return;
+            }
+            catch (error) {
+                // Not in this type, continue
+            }
+        }
+    }
     /**
      * Write object to path (delegate to underlying storage)
      */

package/dist/storage/baseStorage.d.ts

@@ -3,7 +3,7 @@
  * Provides common functionality for all storage adapters
  */
 import { GraphAdjacencyIndex } from '../graph/graphAdjacencyIndex.js';
-import { GraphVerb, HNSWNoun, HNSWVerb, StatisticsData } from '../coreTypes.js';
+import { GraphVerb, HNSWNoun, HNSWVerb, NounMetadata, VerbMetadata, HNSWNounWithMetadata, HNSWVerbWithMetadata, StatisticsData } from '../coreTypes.js';
 import { BaseStorageAdapter } from './adapters/baseStorageAdapter.js';
 export declare const ENTITIES_DIR = "entities";
 export declare const NOUNS_VECTOR_DIR = "entities/nouns/vectors";
@@ -52,40 +52,43 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      */
     protected ensureInitialized(): Promise<void>;
     /**
-     * Save a noun to storage
+     * Save a noun to storage (v4.0.0: vector only, metadata saved separately)
+     * @param noun Pure HNSW vector data (no metadata)
      */
     saveNoun(noun: HNSWNoun): Promise<void>;
     /**
-     * Get a noun from storage
+     * Get a noun from storage (v4.0.0: returns combined HNSWNounWithMetadata)
+     * @param id Entity ID
+     * @returns Combined vector + metadata or null
      */
-    getNoun(id: string): Promise<HNSWNoun | null>;
+    getNoun(id: string): Promise<HNSWNounWithMetadata | null>;
     /**
      * Get nouns by noun type
      * @param nounType The noun type to filter by
      * @returns Promise that resolves to an array of nouns of the specified noun type
      */
-    getNounsByNounType(nounType: string): Promise<HNSWNoun[]>;
+    getNounsByNounType(nounType: string): Promise<HNSWNounWithMetadata[]>;
     /**
      * Delete a noun from storage
      */
     deleteNoun(id: string): Promise<void>;
     /**
-     * Save a verb to storage
+     * Save a verb to storage (v4.0.0: verb only, metadata saved separately)
      *
-     * ARCHITECTURAL FIX (v3.50.1): HNSWVerb now includes verb/sourceId/targetId
-     * These are core relational fields, not metadata. They're stored in the vector
-     * file for fast access and to align with actual usage patterns.
+     * @param verb Pure HNSW verb with core relational fields (verb, sourceId, targetId)
      */
-    saveVerb(verb: GraphVerb): Promise<void>;
+    saveVerb(verb: HNSWVerb): Promise<void>;
     /**
-     * Get a verb from storage
+     * Get a verb from storage (v4.0.0: returns combined HNSWVerbWithMetadata)
+     * @param id Entity ID
+     * @returns Combined verb + metadata or null
      */
-    getVerb(id: string): Promise<GraphVerb | null>;
+    getVerb(id: string): Promise<HNSWVerbWithMetadata | null>;
     /**
      * Convert HNSWVerb to GraphVerb by combining with metadata
+     * DEPRECATED: For backward compatibility only. Use getVerb() which returns HNSWVerbWithMetadata.
      *
-     * ARCHITECTURAL FIX (v3.50.1): Core fields (verb/sourceId/targetId) are now in HNSWVerb
-     * Only optional fields (weight, timestamps, etc.) come from metadata file
+     * @deprecated Use getVerb() instead which returns HNSWVerbWithMetadata
      */
     protected convertHNSWVerbToGraphVerb(hnswVerb: HNSWVerb): Promise<GraphVerb | null>;
     /**
@@ -96,15 +99,15 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     /**
      * Get verbs by source
      */
-    getVerbsBySource(sourceId: string): Promise<GraphVerb[]>;
+    getVerbsBySource(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs by target
      */
-    getVerbsByTarget(targetId: string): Promise<GraphVerb[]>;
+    getVerbsByTarget(targetId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs by type
      */
-    getVerbsByType(type: string): Promise<GraphVerb[]>;
+    getVerbsByType(type: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Internal method for loading all nouns - used by performance optimizations
      * @internal - Do not use directly, use getNouns() with pagination instead
@@ -127,7 +130,7 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
             metadata?: Record<string, any>;
         };
     }): Promise<{
-        items: HNSWNoun[];
+        items: HNSWNounWithMetadata[];
         totalCount?: number;
         hasMore: boolean;
         nextCursor?: string;
@@ -151,7 +154,7 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
             metadata?: Record<string, any>;
         };
     }): Promise<{
-        items: GraphVerb[];
+        items: HNSWVerbWithMetadata[];
         totalCount?: number;
         hasMore: boolean;
         nextCursor?: string;
@@ -211,52 +214,52 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      */
     protected abstract listObjectsUnderPath(prefix: string): Promise<string[]>;
     /**
-     * Save metadata to storage
+     * Save metadata to storage (v4.0.0: now typed)
      * Routes to correct location (system or entity) based on key format
      */
-    saveMetadata(id: string, metadata: any): Promise<void>;
+    saveMetadata(id: string, metadata: NounMetadata): Promise<void>;
     /**
-     * Get metadata from storage
+     * Get metadata from storage (v4.0.0: now typed)
      * Routes to correct location (system or entity) based on key format
      */
-    getMetadata(id: string): Promise<any | null>;
+    getMetadata(id: string): Promise<NounMetadata | null>;
     /**
-     * Save noun metadata to storage
+     * Save noun metadata to storage (v4.0.0: now typed)
      * Routes to correct sharded location based on UUID
      */
-    saveNounMetadata(id: string, metadata: any): Promise<void>;
+    saveNounMetadata(id: string, metadata: NounMetadata): Promise<void>;
     /**
-     * Internal method for saving noun metadata
+     * Internal method for saving noun metadata (v4.0.0: now typed)
      * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
      * @protected
      */
-    protected saveNounMetadata_internal(id: string, metadata: any): Promise<void>;
+    protected saveNounMetadata_internal(id: string, metadata: NounMetadata): Promise<void>;
     /**
-     * Get noun metadata from storage
+     * Get noun metadata from storage (v4.0.0: now typed)
      * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
      */
-    getNounMetadata(id: string): Promise<any | null>;
+    getNounMetadata(id: string): Promise<NounMetadata | null>;
     /**
      * Delete noun metadata from storage
      * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
      */
     deleteNounMetadata(id: string): Promise<void>;
     /**
-     * Save verb metadata to storage
+     * Save verb metadata to storage (v4.0.0: now typed)
      * Routes to correct sharded location based on UUID
      */
-    saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    saveVerbMetadata(id: string, metadata: VerbMetadata): Promise<void>;
     /**
-     * Internal method for saving verb metadata
+     * Internal method for saving verb metadata (v4.0.0: now typed)
      * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
      * @protected
      */
-    protected saveVerbMetadata_internal(id: string, metadata: any): Promise<void>;
+    protected saveVerbMetadata_internal(id: string, metadata: VerbMetadata): Promise<void>;
     /**
-     * Get verb metadata from storage
+     * Get verb metadata from storage (v4.0.0: now typed)
      * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
      */
-    getVerbMetadata(id: string): Promise<any | null>;
+    getVerbMetadata(id: string): Promise<VerbMetadata | null>;
     /**
      * Delete verb metadata from storage
      * Uses routing logic to handle both UUIDs (sharded) and system keys (unsharded)
@@ -296,17 +299,17 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * Get verbs by source
      * This method should be implemented by each specific adapter
      */
-    protected abstract getVerbsBySource_internal(sourceId: string): Promise<GraphVerb[]>;
+    protected abstract getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs by target
      * This method should be implemented by each specific adapter
      */
-    protected abstract getVerbsByTarget_internal(targetId: string): Promise<GraphVerb[]>;
+    protected abstract getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs by type
      * This method should be implemented by each specific adapter
      */
-    protected abstract getVerbsByType_internal(type: string): Promise<GraphVerb[]>;
+    protected abstract getVerbsByType_internal(type: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Delete a verb from storage
      * This method should be implemented by each specific adapter