@soulcraft/brainy 3.50.2 → 4.0.0

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

@@ -2,26 +2,29 @@
  * Base Storage Adapter
  * Provides common functionality for all storage adapters, including statistics tracking
  */
-import { StatisticsData, StorageAdapter, HNSWNoun, GraphVerb } from '../../coreTypes.js';
+import { StatisticsData, StorageAdapter, HNSWNoun, HNSWVerb, HNSWNounWithMetadata, HNSWVerbWithMetadata, NounMetadata, VerbMetadata } from '../../coreTypes.js';
 /**
  * Base class for storage adapters that implements statistics tracking
  */
 export declare abstract class BaseStorageAdapter implements StorageAdapter {
     abstract init(): Promise<void>;
     abstract saveNoun(noun: HNSWNoun): Promise<void>;
-    abstract getNoun(id: string): Promise<HNSWNoun | null>;
-    abstract getNounsByNounType(nounType: string): Promise<HNSWNoun[]>;
+    abstract saveNounMetadata(id: string, metadata: NounMetadata): Promise<void>;
+    abstract deleteNounMetadata(id: string): Promise<void>;
+    abstract getNoun(id: string): Promise<HNSWNounWithMetadata | null>;
+    abstract getNounsByNounType(nounType: string): Promise<HNSWNounWithMetadata[]>;
     abstract deleteNoun(id: string): Promise<void>;
-    abstract saveVerb(verb: GraphVerb): Promise<void>;
-    abstract getVerb(id: string): Promise<GraphVerb | null>;
-    abstract getVerbsBySource(sourceId: string): Promise<GraphVerb[]>;
-    abstract getVerbsByTarget(targetId: string): Promise<GraphVerb[]>;
-    abstract getVerbsByType(type: string): Promise<GraphVerb[]>;
+    abstract saveVerb(verb: HNSWVerb): Promise<void>;
+    abstract saveVerbMetadata(id: string, metadata: VerbMetadata): Promise<void>;
+    abstract deleteVerbMetadata(id: string): Promise<void>;
+    abstract getVerb(id: string): Promise<HNSWVerbWithMetadata | null>;
+    abstract getVerbsBySource(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
+    abstract getVerbsByTarget(targetId: string): Promise<HNSWVerbWithMetadata[]>;
+    abstract getVerbsByType(type: string): Promise<HNSWVerbWithMetadata[]>;
     abstract deleteVerb(id: string): Promise<void>;
     abstract saveMetadata(id: string, metadata: any): Promise<void>;
     abstract getMetadata(id: string): Promise<any | null>;
     abstract getNounMetadata(id: string): Promise<any | null>;
-    abstract saveVerbMetadata(id: string, metadata: any): Promise<void>;
     abstract getVerbMetadata(id: string): Promise<any | null>;
     abstract getNounVector(id: string): Promise<number[] | null>;
     abstract saveHNSWData(nounId: string, hnswData: {
@@ -64,7 +67,7 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
             metadata?: Record<string, any>;
         };
     }): Promise<{
-        items: HNSWNoun[];
+        items: HNSWNounWithMetadata[];
         totalCount?: number;
         hasMore: boolean;
         nextCursor?: string;
@@ -88,7 +91,7 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
             metadata?: Record<string, any>;
         };
     }): Promise<{
-        items: GraphVerb[];
+        items: HNSWVerbWithMetadata[];
         totalCount?: number;
         hasMore: boolean;
         nextCursor?: string;
@@ -108,7 +111,7 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
             metadata?: Record<string, any>;
         };
     }): Promise<{
-        items: HNSWNoun[];
+        items: HNSWNounWithMetadata[];
         totalCount?: number;
         hasMore: boolean;
         nextCursor?: string;
@@ -130,7 +133,7 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
             metadata?: Record<string, any>;
         };
     }): Promise<{
-        items: GraphVerb[];
+        items: HNSWVerbWithMetadata[];
         totalCount?: number;
         hasMore: boolean;
         nextCursor?: string;

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

@@ -2,7 +2,7 @@
  * File System Storage Adapter
  * File system storage adapter for Node.js environments
  */
-import { GraphVerb, HNSWNoun, HNSWVerb, StatisticsData } from '../../coreTypes.js';
+import { HNSWNoun, HNSWVerb, HNSWNounWithMetadata, HNSWVerbWithMetadata, StatisticsData } from '../../coreTypes.js';
 import { BaseStorage } from '../baseStorage.js';
 type HNSWNode = HNSWNoun;
 type Edge = HNSWVerb;
@@ -28,11 +28,17 @@ export declare class FileSystemStorage extends BaseStorage {
     private activeLocks;
     private lockTimers;
     private allTimers;
+    private compressionEnabled;
+    private compressionLevel;
     /**
      * Initialize the storage adapter
      * @param rootDirectory The root directory for storage
+     * @param options Optional configuration
      */
-    constructor(rootDirectory: string);
+    constructor(rootDirectory: string, options?: {
+        compression?: boolean;
+        compressionLevel?: number;
+    });
     /**
      * Initialize the storage adapter
      */
@@ -103,22 +109,26 @@ export declare class FileSystemStorage extends BaseStorage {
     /**
      * Primitive operation: Write object to path
      * All metadata operations use this internally via base class routing
+     * v4.0.0: Supports gzip compression for 60-80% disk savings
      */
     protected writeObjectToPath(pathStr: string, data: any): Promise<void>;
     /**
      * Primitive operation: Read object from path
      * All metadata operations use this internally via base class routing
      * Enhanced error handling for corrupted metadata files (Bug #3 mitigation)
+     * v4.0.0: Supports reading both compressed (.gz) and uncompressed files for backward compatibility
      */
     protected readObjectFromPath(pathStr: string): Promise<any | null>;
     /**
      * Primitive operation: Delete object from path
      * All metadata operations use this internally via base class routing
+     * v4.0.0: Deletes both compressed and uncompressed versions (for cleanup)
      */
     protected deleteObjectFromPath(pathStr: string): Promise<void>;
     /**
      * Primitive operation: List objects under path prefix
      * All metadata operations use this internally via base class routing
+     * v4.0.0: Handles both .json and .json.gz files, normalizes paths
      */
     protected listObjectsUnderPath(prefix: string): Promise<string[]>;
     /**
@@ -135,7 +145,7 @@ export declare class FileSystemStorage extends BaseStorage {
         cursor?: string;
         filter?: any;
     }): Promise<{
-        items: HNSWNoun[];
+        items: HNSWNounWithMetadata[];
         totalCount: number;
         hasMore: boolean;
         nextCursor?: string;
@@ -167,7 +177,8 @@ export declare class FileSystemStorage extends BaseStorage {
     protected saveNoun_internal(noun: HNSWNoun): Promise<void>;
     /**
      * Get a noun from storage (internal implementation)
-     * Combines vector data from getNode() with metadata from getNounMetadata()
+     * v4.0.0: Returns ONLY vector data (no metadata field)
+     * Base class combines with metadata via getNoun() -> HNSWNounWithMetadata
      */
     protected getNoun_internal(id: string): Promise<HNSWNoun | null>;
     /**
@@ -184,21 +195,22 @@ export declare class FileSystemStorage extends BaseStorage {
     protected saveVerb_internal(verb: HNSWVerb): Promise<void>;
     /**
      * Get a verb from storage (internal implementation)
-     * Combines vector data from getEdge() with metadata from getVerbMetadata()
+     * v4.0.0: Returns ONLY vector + core relational fields (no metadata field)
+     * Base class combines with metadata via getVerb() -> HNSWVerbWithMetadata
      */
     protected getVerb_internal(id: string): Promise<HNSWVerb | null>;
     /**
      * 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
      */
-    protected getVerbsByType_internal(type: string): Promise<GraphVerb[]>;
+    protected getVerbsByType_internal(type: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs with pagination
      * This method reads verb files from the filesystem and returns them with pagination
@@ -214,7 +226,7 @@ export declare class FileSystemStorage extends BaseStorage {
             metadata?: Record<string, any>;
         };
     }): Promise<{
-        items: GraphVerb[];
+        items: HNSWVerbWithMetadata[];
         totalCount?: number;
         hasMore: boolean;
         nextCursor?: string;