@soulcraft/brainy 3.50.1 → 4.0.0

package/dist/storage/adapters/opfsStorage.js

@@ -36,6 +36,11 @@ export class OPFSStorage extends BaseStorage {
         this.statistics = null;
         this.activeLocks = new Set();
         this.lockPrefix = 'opfs-lock-';
+        // Quota monitoring configuration (v4.0.0)
+        this.quotaWarningThreshold = 0.8; // Warn at 80% usage
+        this.quotaCriticalThreshold = 0.95; // Critical at 95% usage
+        this.lastQuotaCheck = 0;
+        this.quotaCheckInterval = 60000; // Check every 60 seconds
         // Check if OPFS is available
         this.isAvailable =
             typeof navigator !== 'undefined' &&
@@ -194,19 +199,15 @@ export class OPFSStorage extends BaseStorage {
             for (const [level, nounIds] of Object.entries(data.connections)) {
                 connections.set(Number(level), new Set(nounIds));
             }
+            // v4.0.0: Return ONLY vector data (no metadata field)
             const node = {
                 id: data.id,
                 vector: data.vector,
                 connections,
                 level: data.level || 0
             };
-            // Get metadata (entity data in 2-file system)
-            const metadata = await this.getNounMetadata(id);
-            // Combine into complete noun object
-            return {
-                ...node,
-                metadata: metadata || {}
-            };
+            // Return pure vector structure
+            return node;
         }
         catch (error) {
             // Noun not found or other error
@@ -346,21 +347,17 @@ export class OPFSStorage extends BaseStorage {
     }
     /**
      * 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
      */
     async getVerb_internal(id) {
-        // Get vector data (lightweight)
+        // v4.0.0: Return ONLY vector + core relational data (no metadata field)
         const edge = await this.getEdge(id);
         if (!edge) {
             return null;
         }
-        // Get metadata (relationship data in 2-file system)
-        const metadata = await this.getVerbMetadata(id);
-        // Combine into complete verb object
-        return {
-            ...edge,
-            metadata: metadata || {}
-        };
+        // Return pure vector + core fields structure
+        return edge;
     }
     /**
      * Get an edge from storage
@@ -393,7 +390,7 @@ export class OPFSStorage extends BaseStorage {
                 augmentation: 'unknown',
                 version: '1.0'
             };
-            // ARCHITECTURAL FIX (v3.50.1): Return HNSWVerb with core relational fields
+            // v4.0.0: Return HNSWVerb with core relational fields (NO metadata field)
             return {
                 id: data.id,
                 vector: data.vector,
@@ -401,9 +398,9 @@ export class OPFSStorage extends BaseStorage {
                 // CORE RELATIONAL DATA (read from vector file)
                 verb: data.verb,
                 sourceId: data.sourceId,
-                targetId: data.targetId,
-                // User metadata (retrieved separately via getVerbMetadata())
-                metadata: data.metadata
+                targetId: data.targetId
+                // ✅ NO metadata field in v4.0.0
+                // User metadata retrieved separately via getVerbMetadata()
             };
         }
         catch (error) {
@@ -445,7 +442,7 @@ export class OPFSStorage extends BaseStorage {
                                     augmentation: 'unknown',
                                     version: '1.0'
                                 };
-                                // ARCHITECTURAL FIX (v3.50.1): Include core relational fields
+                                // v4.0.0: Include core relational fields (NO metadata field)
                                 allEdges.push({
                                     id: data.id,
                                     vector: data.vector,
@@ -453,9 +450,9 @@ export class OPFSStorage extends BaseStorage {
                                     // CORE RELATIONAL DATA
                                     verb: data.verb,
                                     sourceId: data.sourceId,
-                                    targetId: data.targetId,
-                                    // User metadata
-                                    metadata: data.metadata
+                                    targetId: data.targetId
+                                    // ✅ NO metadata field in v4.0.0
+                                    // User metadata retrieved separately via getVerbMetadata()
                                 });
                             }
                             catch (error) {
@@ -884,6 +881,108 @@ export class OPFSStorage extends BaseStorage {
             };
         }
     }
+    /**
+     * Get detailed quota status with warnings (v4.0.0)
+     * Monitors storage usage and warns when approaching quota limits
+     *
+     * @returns Promise that resolves to quota status with warning levels
+     *
+     * @example
+     * const status = await storage.getQuotaStatus()
+     * if (status.warning) {
+     *   console.warn(`Storage ${status.usagePercent}% full: ${status.warningMessage}`)
+     * }
+     */
+    async getQuotaStatus() {
+        this.lastQuotaCheck = Date.now();
+        try {
+            if (!navigator.storage || !navigator.storage.estimate) {
+                return {
+                    usage: 0,
+                    quota: null,
+                    usagePercent: 0,
+                    remaining: null,
+                    status: 'ok',
+                    warning: false
+                };
+            }
+            const estimate = await navigator.storage.estimate();
+            const usage = estimate.usage || 0;
+            const quota = estimate.quota || null;
+            if (!quota) {
+                return {
+                    usage,
+                    quota: null,
+                    usagePercent: 0,
+                    remaining: null,
+                    status: 'ok',
+                    warning: false
+                };
+            }
+            const usagePercent = (usage / quota) * 100;
+            const remaining = quota - usage;
+            // Determine status
+            let status = 'ok';
+            let warning = false;
+            let warningMessage;
+            if (usagePercent >= this.quotaCriticalThreshold * 100) {
+                status = 'critical';
+                warning = true;
+                warningMessage = `Critical: Storage ${usagePercent.toFixed(1)}% full. Only ${(remaining / 1024 / 1024).toFixed(1)}MB remaining. Please delete old data.`;
+            }
+            else if (usagePercent >= this.quotaWarningThreshold * 100) {
+                status = 'warning';
+                warning = true;
+                warningMessage = `Warning: Storage ${usagePercent.toFixed(1)}% full. ${(remaining / 1024 / 1024).toFixed(1)}MB remaining.`;
+            }
+            if (warning) {
+                console.warn(`[OPFS Quota] ${warningMessage}`);
+            }
+            return {
+                usage,
+                quota,
+                usagePercent,
+                remaining,
+                status,
+                warning,
+                warningMessage
+            };
+        }
+        catch (error) {
+            console.error('Failed to get quota status:', error);
+            return {
+                usage: 0,
+                quota: null,
+                usagePercent: 0,
+                remaining: null,
+                status: 'ok',
+                warning: false
+            };
+        }
+    }
+    /**
+     * Monitor quota during operations (v4.0.0)
+     * Automatically checks quota at regular intervals and warns if approaching limits
+     * Call this before write operations to ensure quota is available
+     *
+     * @returns Promise that resolves when quota check is complete
+     *
+     * @example
+     * await storage.monitorQuota()  // Checks quota if interval has passed
+     * await storage.saveNoun(noun)  // Proceed with write operation
+     */
+    async monitorQuota() {
+        const now = Date.now();
+        // Only check if interval has passed
+        if (now - this.lastQuotaCheck < this.quotaCheckInterval) {
+            return;
+        }
+        const status = await this.getQuotaStatus();
+        // If critical, throw error to prevent data loss
+        if (status.status === 'critical' && status.warningMessage) {
+            throw new Error(`Storage quota critical: ${status.warningMessage}`);
+        }
+    }
     /**
      * Get the statistics key for a specific date
      * @param date The date to get the key for
@@ -1304,22 +1403,25 @@ export class OPFSStorage extends BaseStorage {
         }
         // Get the subset of files for this page
         const pageFiles = nounFiles.slice(startIndex, startIndex + limit);
-        // Load nouns from files
+        // v4.0.0: Load nouns from files and combine with metadata
         const items = [];
         for (const fileName of pageFiles) {
             // fileName is in format "shard/uuid.json", extract just the UUID
             const id = fileName.split('/')[1].replace('.json', '');
             const noun = await this.getNoun_internal(id);
             if (noun) {
+                // Load metadata for filtering and combining
+                const metadata = await this.getNounMetadata(id);
+                if (!metadata)
+                    continue;
                 // Apply filters if provided
                 if (options.filter) {
-                    const metadata = await this.getNounMetadata(id);
                     // Filter by noun type
                     if (options.filter.nounType) {
                         const nounTypes = Array.isArray(options.filter.nounType)
                             ? options.filter.nounType
                             : [options.filter.nounType];
-                        if (metadata && !nounTypes.includes(metadata.type || metadata.noun)) {
+                        if (!nounTypes.includes((metadata.type || metadata.noun))) {
                             continue;
                         }
                     }
@@ -1328,14 +1430,12 @@ export class OPFSStorage extends BaseStorage {
                         const services = Array.isArray(options.filter.service)
                             ? options.filter.service
                             : [options.filter.service];
-                        if (metadata && !services.includes(metadata.createdBy?.augmentation)) {
+                        if (!metadata.createdBy?.augmentation || !services.includes(metadata.createdBy.augmentation)) {
                             continue;
                         }
                     }
                     // Filter by metadata
                     if (options.filter.metadata) {
-                        if (!metadata)
-                            continue;
                         let matches = true;
                         for (const [key, value] of Object.entries(options.filter.metadata)) {
                             if (metadata[key] !== value) {
@@ -1347,7 +1447,15 @@ export class OPFSStorage extends BaseStorage {
                             continue;
                     }
                 }
-                items.push(noun);
+                // v4.0.0: Create HNSWNounWithMetadata by combining noun with metadata
+                const nounWithMetadata = {
+                    id: noun.id,
+                    vector: [...noun.vector],
+                    connections: new Map(noun.connections),
+                    level: noun.level || 0,
+                    metadata: metadata
+                };
+                items.push(nounWithMetadata);
             }
         }
         // Determine if there are more items
@@ -1400,69 +1508,82 @@ export class OPFSStorage extends BaseStorage {
         }
         // Get the subset of files for this page
         const pageFiles = verbFiles.slice(startIndex, startIndex + limit);
-        // Load verbs from files and convert to GraphVerb
+        // v4.0.0: Load verbs from files and combine with metadata
         const items = [];
         for (const fileName of pageFiles) {
             // fileName is in format "shard/uuid.json", extract just the UUID
             const id = fileName.split('/')[1].replace('.json', '');
             const hnswVerb = await this.getVerb_internal(id);
             if (hnswVerb) {
-                // Convert HNSWVerb to GraphVerb
-                const graphVerb = await this.convertHNSWVerbToGraphVerb(hnswVerb);
-                if (graphVerb) {
-                    // Apply filters if provided
-                    if (options.filter) {
-                        // Filter by verb type
-                        if (options.filter.verbType) {
-                            const verbTypes = Array.isArray(options.filter.verbType)
-                                ? options.filter.verbType
-                                : [options.filter.verbType];
-                            if (graphVerb.verb && !verbTypes.includes(graphVerb.verb)) {
-                                continue;
-                            }
+                // Load metadata for filtering and combining
+                const metadata = await this.getVerbMetadata(id);
+                if (!metadata)
+                    continue;
+                // Apply filters if provided
+                if (options.filter) {
+                    // Filter by verb type
+                    // v4.0.0: verb field is in HNSWVerb structure (NOT in metadata)
+                    if (options.filter.verbType) {
+                        const verbTypes = Array.isArray(options.filter.verbType)
+                            ? options.filter.verbType
+                            : [options.filter.verbType];
+                        if (!hnswVerb.verb || !verbTypes.includes(hnswVerb.verb)) {
+                            continue;
                         }
-                        // Filter by source ID
-                        if (options.filter.sourceId) {
-                            const sourceIds = Array.isArray(options.filter.sourceId)
-                                ? options.filter.sourceId
-                                : [options.filter.sourceId];
-                            if (graphVerb.source && !sourceIds.includes(graphVerb.source)) {
-                                continue;
-                            }
+                    }
+                    // Filter by source ID
+                    // v4.0.0: sourceId field is in HNSWVerb structure (NOT in metadata)
+                    if (options.filter.sourceId) {
+                        const sourceIds = Array.isArray(options.filter.sourceId)
+                            ? options.filter.sourceId
+                            : [options.filter.sourceId];
+                        if (!hnswVerb.sourceId || !sourceIds.includes(hnswVerb.sourceId)) {
+                            continue;
                         }
-                        // Filter by target ID
-                        if (options.filter.targetId) {
-                            const targetIds = Array.isArray(options.filter.targetId)
-                                ? options.filter.targetId
-                                : [options.filter.targetId];
-                            if (graphVerb.target && !targetIds.includes(graphVerb.target)) {
-                                continue;
-                            }
+                    }
+                    // Filter by target ID
+                    // v4.0.0: targetId field is in HNSWVerb structure (NOT in metadata)
+                    if (options.filter.targetId) {
+                        const targetIds = Array.isArray(options.filter.targetId)
+                            ? options.filter.targetId
+                            : [options.filter.targetId];
+                        if (!hnswVerb.targetId || !targetIds.includes(hnswVerb.targetId)) {
+                            continue;
                         }
-                        // Filter by service
-                        if (options.filter.service) {
-                            const services = Array.isArray(options.filter.service)
-                                ? options.filter.service
-                                : [options.filter.service];
-                            if (graphVerb.createdBy?.augmentation && !services.includes(graphVerb.createdBy.augmentation)) {
-                                continue;
-                            }
+                    }
+                    // Filter by service
+                    if (options.filter.service) {
+                        const services = Array.isArray(options.filter.service)
+                            ? options.filter.service
+                            : [options.filter.service];
+                        if (!metadata.createdBy?.augmentation || !services.includes(metadata.createdBy.augmentation)) {
+                            continue;
                         }
-                        // Filter by metadata
-                        if (options.filter.metadata && graphVerb.metadata) {
-                            let matches = true;
-                            for (const [key, value] of Object.entries(options.filter.metadata)) {
-                                if (graphVerb.metadata[key] !== value) {
-                                    matches = false;
-                                    break;
-                                }
+                    }
+                    // Filter by metadata
+                    if (options.filter.metadata) {
+                        let matches = true;
+                        for (const [key, value] of Object.entries(options.filter.metadata)) {
+                            if (metadata[key] !== value) {
+                                matches = false;
+                                break;
                             }
-                            if (!matches)
-                                continue;
                         }
+                        if (!matches)
+                            continue;
                     }
-                    items.push(graphVerb);
                 }
+                // v4.0.0: Create HNSWVerbWithMetadata by combining verb with metadata
+                const verbWithMetadata = {
+                    id: hnswVerb.id,
+                    vector: [...hnswVerb.vector],
+                    connections: new Map(hnswVerb.connections),
+                    verb: hnswVerb.verb,
+                    sourceId: hnswVerb.sourceId,
+                    targetId: hnswVerb.targetId,
+                    metadata: metadata
+                };
+                items.push(verbWithMetadata);
             }
         }
         // Determine if there are more items

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

@@ -11,7 +11,7 @@
  *
  * Based on latest GCS and S3 implementations with R2-specific enhancements
  */
-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;
@@ -130,6 +130,8 @@ export declare class R2Storage extends BaseStorage {
     private saveNodeDirect;
     /**
      * Get a noun from storage (internal implementation)
+     * 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>;
     /**
@@ -159,6 +161,11 @@ export declare class R2Storage extends BaseStorage {
     protected saveVerb_internal(verb: HNSWVerb): Promise<void>;
     protected saveEdge(edge: Edge): Promise<void>;
     private saveEdgeDirect;
+    /**
+     * Get a verb from storage (internal implementation)
+     * 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>;
     protected getEdge(id: string): Promise<Edge | null>;
     protected deleteVerb_internal(id: string): Promise<void>;
@@ -200,14 +207,14 @@ export declare class R2Storage extends BaseStorage {
             metadata?: Record<string, any>;
         };
     }): Promise<{
-        items: HNSWNoun[];
+        items: HNSWNounWithMetadata[];
         totalCount?: number;
         hasMore: boolean;
         nextCursor?: string;
     }>;
     protected getNounsByNounType_internal(nounType: string): Promise<HNSWNoun[]>;
-    protected getVerbsBySource_internal(sourceId: string): Promise<GraphVerb[]>;
-    protected getVerbsByTarget_internal(targetId: string): Promise<GraphVerb[]>;
-    protected getVerbsByType_internal(type: string): Promise<GraphVerb[]>;
+    protected getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
+    protected getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
+    protected getVerbsByType_internal(type: string): Promise<HNSWVerbWithMetadata[]>;
 }
 export {};

package/dist/storage/adapters/r2Storage.js

@@ -326,17 +326,17 @@ export class R2Storage extends BaseStorage {
     }
     /**
      * Get a noun from storage (internal implementation)
+     * v4.0.0: Returns ONLY vector data (no metadata field)
+     * Base class combines with metadata via getNoun() -> HNSWNounWithMetadata
      */
     async getNoun_internal(id) {
+        // v4.0.0: Return ONLY vector data (no metadata field)
         const node = await this.getNode(id);
         if (!node) {
             return null;
         }
-        const metadata = await this.getNounMetadata(id);
-        return {
-            ...node,
-            metadata: metadata || {}
-        };
+        // Return pure vector structure
+        return node;
     }
     /**
      * Get a node from storage
@@ -589,16 +589,19 @@ export class R2Storage extends BaseStorage {
             throw new Error(`Failed to save edge ${edge.id}: ${error}`);
         }
     }
+    /**
+     * Get a verb from storage (internal implementation)
+     * v4.0.0: Returns ONLY vector + core relational fields (no metadata field)
+     * Base class combines with metadata via getVerb() -> HNSWVerbWithMetadata
+     */
     async getVerb_internal(id) {
+        // v4.0.0: Return ONLY vector + core relational data (no metadata field)
         const edge = await this.getEdge(id);
         if (!edge) {
             return null;
         }
-        const metadata = await this.getVerbMetadata(id);
-        return {
-            ...edge,
-            metadata: metadata || {}
-        };
+        // Return pure vector + core fields structure
+        return edge;
     }
     async getEdge(id) {
         await this.ensureInitialized();
@@ -620,7 +623,7 @@ export class R2Storage extends BaseStorage {
             for (const [level, verbIds] of Object.entries(data.connections || {})) {
                 connections.set(Number(level), new Set(verbIds));
             }
-            // ARCHITECTURAL FIX (v3.50.1): Return HNSWVerb with core relational fields
+            // v4.0.0: Return HNSWVerb with core relational fields (NO metadata field)
             const edge = {
                 id: data.id,
                 vector: data.vector,
@@ -628,9 +631,9 @@ export class R2Storage extends BaseStorage {
                 // CORE RELATIONAL DATA (read from vector file)
                 verb: data.verb,
                 sourceId: data.sourceId,
-                targetId: data.targetId,
-                // User metadata (retrieved separately via getVerbMetadata())
-                metadata: data.metadata
+                targetId: data.targetId
+                // ✅ NO metadata field in v4.0.0
+                // User metadata retrieved separately via getVerbMetadata()
             };
             this.verbCacheManager.set(id, edge);
             this.releaseBackpressure(true, requestId);
@@ -860,7 +863,52 @@ export class R2Storage extends BaseStorage {
                 continue;
             const noun = await this.getNoun_internal(id);
             if (noun) {
-                items.push(noun);
+                // v4.0.0: Load metadata and combine with noun to create HNSWNounWithMetadata
+                const metadata = await this.getNounMetadata(id);
+                if (!metadata)
+                    continue;
+                // Apply filters if provided
+                if (options.filter) {
+                    // Filter by noun type
+                    if (options.filter.nounType) {
+                        const nounTypes = Array.isArray(options.filter.nounType)
+                            ? options.filter.nounType
+                            : [options.filter.nounType];
+                        if (!nounTypes.includes((metadata.type || metadata.noun))) {
+                            continue;
+                        }
+                    }
+                    // Filter by service
+                    if (options.filter.service) {
+                        const services = Array.isArray(options.filter.service)
+                            ? options.filter.service
+                            : [options.filter.service];
+                        if (!metadata.createdBy?.augmentation || !services.includes(metadata.createdBy.augmentation)) {
+                            continue;
+                        }
+                    }
+                    // Filter by metadata
+                    if (options.filter.metadata) {
+                        let matches = true;
+                        for (const [key, value] of Object.entries(options.filter.metadata)) {
+                            if (metadata[key] !== value) {
+                                matches = false;
+                                break;
+                            }
+                        }
+                        if (!matches)
+                            continue;
+                    }
+                }
+                // v4.0.0: Create HNSWNounWithMetadata by combining noun with metadata
+                const nounWithMetadata = {
+                    id: noun.id,
+                    vector: [...noun.vector],
+                    connections: new Map(noun.connections),
+                    level: noun.level || 0,
+                    metadata: metadata
+                };
+                items.push(nounWithMetadata);
             }
         }
         return {