@soulcraft/brainy 2.1.0 → 3.0.0

package/dist/augmentations/metadataEnforcer.js

@@ -0,0 +1,171 @@
+/**
+ * Runtime enforcement of metadata contracts
+ * Ensures augmentations only access declared fields
+ */
+export class MetadataEnforcer {
+    /**
+     * Enforce metadata access based on augmentation contract
+     * Returns a wrapped metadata object that enforces the contract
+     */
+    static enforce(augmentation, metadata, operation = 'write') {
+        // Handle simple contracts
+        if (augmentation.metadata === 'none') {
+            // No access at all
+            if (operation === 'read')
+                return null;
+            throw new Error(`Augmentation '${augmentation.name}' has metadata='none' - cannot access metadata`);
+        }
+        if (augmentation.metadata === 'readonly') {
+            if (operation === 'read') {
+                // Return frozen deep clone for read-only access
+                return deepFreeze(deepClone(metadata));
+            }
+            throw new Error(`Augmentation '${augmentation.name}' has metadata='readonly' - cannot write`);
+        }
+        // Handle specific field access
+        const access = augmentation.metadata;
+        if (operation === 'read') {
+            // For reads, filter to allowed fields
+            if (access.reads === '*') {
+                return deepClone(metadata); // Can read everything
+            }
+            if (!access.reads) {
+                return {}; // No read access
+            }
+            // Filter to specific fields
+            const filtered = {};
+            for (const field of access.reads) {
+                if (field.includes('.')) {
+                    // Handle nested fields like '_brainy.deleted'
+                    const parts = field.split('.');
+                    let source = metadata;
+                    let target = filtered;
+                    for (let i = 0; i < parts.length - 1; i++) {
+                        const part = parts[i];
+                        if (!source[part])
+                            break;
+                        if (!target[part])
+                            target[part] = {};
+                        source = source[part];
+                        target = target[part];
+                    }
+                    const lastPart = parts[parts.length - 1];
+                    if (source && lastPart in source) {
+                        target[lastPart] = source[lastPart];
+                    }
+                }
+                else {
+                    // Simple field
+                    if (field in metadata) {
+                        filtered[field] = metadata[field];
+                    }
+                }
+            }
+            return filtered;
+        }
+        // For writes, create a proxy that validates
+        return new Proxy(metadata, {
+            set(target, prop, value) {
+                const field = String(prop);
+                // Check if write is allowed
+                if (access.writes === '*') {
+                    // Can write anything
+                    target[prop] = value;
+                    return true;
+                }
+                if (!access.writes || !access.writes.includes(field)) {
+                    throw new Error(`Augmentation '${augmentation.name}' cannot write to field '${field}'. ` +
+                        `Allowed writes: ${access.writes?.join(', ') || 'none'}`);
+                }
+                // Check namespace if specified
+                if (access.namespace && !field.startsWith(access.namespace)) {
+                    console.warn(`Augmentation '${augmentation.name}' writing outside its namespace. ` +
+                        `Expected: ${access.namespace}.*, got: ${field}`);
+                }
+                target[prop] = value;
+                return true;
+            },
+            deleteProperty(target, prop) {
+                const field = String(prop);
+                // Deletion counts as a write
+                if (access.writes === '*' || access.writes?.includes(field)) {
+                    delete target[prop];
+                    return true;
+                }
+                throw new Error(`Augmentation '${augmentation.name}' cannot delete field '${field}'`);
+            }
+        });
+    }
+    /**
+     * Validate that an augmentation's actual behavior matches its contract
+     * Used in testing to verify contracts are accurate
+     */
+    static async validateContract(augmentation, testMetadata = { test: 'data', _brainy: { deleted: false } }) {
+        const violations = [];
+        // Test read access
+        try {
+            const readable = this.enforce(augmentation, testMetadata, 'read');
+            if (augmentation.metadata === 'none' && readable !== null) {
+                violations.push(`Contract says 'none' but got readable metadata`);
+            }
+        }
+        catch (error) {
+            violations.push(`Read enforcement error: ${error}`);
+        }
+        // Test write access
+        try {
+            const writable = this.enforce(augmentation, testMetadata, 'write');
+            if (augmentation.metadata === 'none') {
+                violations.push(`Contract says 'none' but got writable metadata`);
+            }
+            if (augmentation.metadata === 'readonly') {
+                // Try to write - should fail
+                try {
+                    writable.testWrite = 'value';
+                    violations.push(`Contract says 'readonly' but write succeeded`);
+                }
+                catch {
+                    // Expected to fail
+                }
+            }
+        }
+        catch (error) {
+            // Expected for 'none' and 'readonly' on write
+            if (augmentation.metadata !== 'none' && augmentation.metadata !== 'readonly') {
+                violations.push(`Write enforcement error: ${error}`);
+            }
+        }
+        return {
+            valid: violations.length === 0,
+            violations
+        };
+    }
+}
+// Helper functions
+function deepClone(obj) {
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    if (obj instanceof Date)
+        return new Date(obj);
+    if (obj instanceof Array)
+        return obj.map(item => deepClone(item));
+    const cloned = {};
+    for (const key in obj) {
+        if (obj.hasOwnProperty(key)) {
+            cloned[key] = deepClone(obj[key]);
+        }
+    }
+    return cloned;
+}
+function deepFreeze(obj) {
+    Object.freeze(obj);
+    Object.getOwnPropertyNames(obj).forEach(prop => {
+        if (obj[prop] !== null &&
+            (typeof obj[prop] === 'object' || typeof obj[prop] === 'function') &&
+            !Object.isFrozen(obj[prop])) {
+            deepFreeze(obj[prop]);
+        }
+    });
+    return obj;
+}
+//# sourceMappingURL=metadataEnforcer.js.map

package/dist/augmentations/metricsAugmentation.d.ts

@@ -27,6 +27,7 @@ export interface MetricsConfig {
  * - Zero-config with smart defaults
  */
 export declare class MetricsAugmentation extends BaseAugmentation {
+    readonly metadata: "readonly";
     readonly name = "metrics";
     readonly timing: "after";
     operations: ("add" | "search" | "delete" | "clear" | "all")[];
@@ -126,13 +127,7 @@ export declare class MetricsAugmentation extends BaseAugmentation {
             averageSearchTimeMs: number;
             searchesLastHour: number;
             searchesLastDay: number;
-            topSearchTerms
-            /**
-             * Update storage size metrics
-             */
-            ? /**
-             * Update storage size metrics
-             */: string[];
+            topSearchTerms?: string[];
         } | undefined;
         verbStatistics?: {
             totalVerbs: number;

package/dist/augmentations/metricsAugmentation.js

@@ -21,6 +21,7 @@ import { StatisticsCollector } from '../utils/statisticsCollector.js';
 export class MetricsAugmentation extends BaseAugmentation {
     constructor(config = {}) {
         super();
+        this.metadata = 'readonly'; // Reads metadata for metrics
         this.name = 'metrics';
         this.timing = 'after';
         this.operations = ['add', 'search', 'delete', 'clear', 'all'];

package/dist/augmentations/monitoringAugmentation.d.ts

@@ -28,6 +28,7 @@ export interface MonitoringConfig {
  * - Zero-config with smart defaults
  */
 export declare class MonitoringAugmentation extends BaseAugmentation {
+    readonly metadata: "readonly";
     readonly name = "monitoring";
     readonly timing: "after";
     operations: ("search" | "add" | "delete" | "all")[];

package/dist/augmentations/monitoringAugmentation.js

@@ -23,6 +23,7 @@ import { DistributedConfigManager as ConfigManager } from '../distributed/config
 export class MonitoringAugmentation extends BaseAugmentation {
     constructor(config = {}) {
         super();
+        this.metadata = 'readonly'; // Reads metadata for monitoring
         this.name = 'monitoring';
         this.timing = 'after';
         this.operations = ['search', 'add', 'delete', 'all'];

package/dist/augmentations/neuralImport.d.ts

@@ -55,6 +55,10 @@ export interface NeuralImportConfig {
 export declare class NeuralImportAugmentation extends BaseAugmentation {
     readonly name = "neural-import";
     readonly timing: "before";
+    readonly metadata: {
+        reads: "*";
+        writes: string[];
+    };
     operations: ("add" | "addNoun" | "addVerb" | "all")[];
     readonly priority = 80;
     private config;

package/dist/augmentations/neuralImport.js

@@ -19,6 +19,10 @@ export class NeuralImportAugmentation extends BaseAugmentation {
         super();
         this.name = 'neural-import';
         this.timing = 'before'; // Process data before storage
+        this.metadata = {
+            reads: '*', // Needs to read data for analysis
+            writes: ['_neuralProcessed', '_neuralConfidence', '_detectedEntities', '_detectedRelationships', '_neuralInsights', 'nounType', 'verbType']
+        }; // Enriches metadata with neural analysis
         this.operations = ['add', 'addNoun', 'addVerb', 'all']; // Use 'all' to catch batch operations
         this.priority = 80; // High priority for data processing
         this.analysisCache = new Map();

package/dist/augmentations/requestDeduplicatorAugmentation.d.ts

@@ -13,6 +13,7 @@ interface DeduplicatorConfig {
 export declare class RequestDeduplicatorAugmentation extends BaseAugmentation {
     name: string;
     timing: "around";
+    metadata: "none";
     operations: ("search" | "searchText" | "searchByNounTypes" | "findSimilar" | "get")[];
     priority: number;
     private pendingRequests;

package/dist/augmentations/requestDeduplicatorAugmentation.js

@@ -10,6 +10,7 @@ export class RequestDeduplicatorAugmentation extends BaseAugmentation {
         super();
         this.name = 'RequestDeduplicator';
         this.timing = 'around';
+        this.metadata = 'none'; // Doesn't access metadata
         this.operations = ['search', 'searchText', 'searchByNounTypes', 'findSimilar', 'get'];
         this.priority = 50; // Performance optimization
         this.pendingRequests = new Map();

package/dist/augmentations/serverSearchAugmentations.d.ts

@@ -16,6 +16,7 @@ import { BrainyDataInterface } from '../types/brainyDataInterface.js';
 export declare class ServerSearchConduitAugmentation extends BaseAugmentation {
     readonly name = "server-search-conduit";
     readonly timing: "after";
+    readonly metadata: "readonly";
     operations: ("addNoun" | "delete" | "addVerb")[];
     readonly priority = 20;
     private localDb;
@@ -101,6 +102,7 @@ export declare class ServerSearchConduitAugmentation extends BaseAugmentation {
 export declare class ServerSearchActivationAugmentation extends BaseAugmentation {
     readonly name = "server-search-activation";
     readonly timing: "after";
+    readonly metadata: "readonly";
     operations: ("search" | "addNoun")[];
     readonly priority = 20;
     private conduitAugmentation;

package/dist/augmentations/serverSearchAugmentations.js

@@ -16,6 +16,7 @@ export class ServerSearchConduitAugmentation extends BaseAugmentation {
         super();
         this.name = 'server-search-conduit';
         this.timing = 'after';
+        this.metadata = 'readonly'; // Reads metadata to sync with server
         this.operations = ['addNoun', 'delete', 'addVerb'];
         this.priority = 20;
         this.localDb = null;
@@ -310,6 +311,7 @@ export class ServerSearchActivationAugmentation extends BaseAugmentation {
         super();
         this.name = 'server-search-activation';
         this.timing = 'after';
+        this.metadata = 'readonly'; // Reads metadata for server activation
         this.operations = ['search', 'addNoun'];
         this.priority = 20;
         this.conduitAugmentation = null;

package/dist/augmentations/storageAugmentation.d.ts

@@ -12,6 +12,7 @@ import { StorageAdapter } from '../coreTypes.js';
  */
 export declare abstract class StorageAugmentation extends BaseAugmentation implements BrainyAugmentation {
     readonly timing: "replace";
+    readonly metadata: "none";
     operations: ("storage")[];
     readonly priority = 100;
     protected storageAdapter: StorageAdapter | null;

package/dist/augmentations/storageAugmentation.js

@@ -14,6 +14,7 @@ export class StorageAugmentation extends BaseAugmentation {
     constructor() {
         super();
         this.timing = 'replace';
+        this.metadata = 'none'; // Storage doesn't directly access metadata
         this.operations = ['storage']; // Make mutable for TypeScript compatibility
         this.priority = 100; // High priority for storage
         this.storageAdapter = null;

package/dist/augmentations/synapseAugmentation.d.ts

@@ -27,6 +27,10 @@ export declare abstract class SynapseAugmentation extends BaseAugmentation {
     readonly timing: "after";
     readonly operations: ("all")[];
     readonly priority = 10;
+    readonly metadata: {
+        reads: "*";
+        writes: string[];
+    };
     abstract readonly synapseId: string;
     abstract readonly supportedTypes: string[];
     protected syncInProgress: boolean;

package/dist/augmentations/synapseAugmentation.js

@@ -29,6 +29,10 @@ export class SynapseAugmentation extends BaseAugmentation {
         this.timing = 'after';
         this.operations = ['all'];
         this.priority = 10;
+        this.metadata = {
+            reads: '*', // Needs to read for syncing
+            writes: ['_synapse', '_syncedAt']
+        }; // Adds synapse tracking metadata
         // State management
         this.syncInProgress = false;
         this.syncStats = {

package/dist/augmentations/walAugmentation.d.ts

@@ -24,6 +24,7 @@ interface WALConfig {
 export declare class WALAugmentation extends BaseAugmentation {
     name: string;
     timing: "around";
+    metadata: "readonly";
     operations: ("addNoun" | "addVerb" | "saveNoun" | "saveVerb" | "updateMetadata" | "delete" | "deleteVerb" | "clear")[];
     priority: number;
     private config;

package/dist/augmentations/walAugmentation.js

@@ -17,6 +17,7 @@ export class WALAugmentation extends BaseAugmentation {
         super();
         this.name = 'WAL';
         this.timing = 'around';
+        this.metadata = 'readonly'; // Reads metadata for logging/recovery
         this.operations = ['addNoun', 'addVerb', 'saveNoun', 'saveVerb', 'updateMetadata', 'delete', 'deleteVerb', 'clear'];
         this.priority = 100; // Critical system operation - highest priority
         this.operationCounter = 0;

package/dist/brainyData.d.ts

@@ -6,6 +6,7 @@ import { HNSWIndex } from './hnsw/hnswIndex.js';
 import { HNSWIndexOptimized, HNSWOptimizedConfig } from './hnsw/hnswIndexOptimized.js';
 import { DistanceFunction, GraphVerb, EmbeddingFunction, HNSWConfig, SearchResult, SearchCursor, PaginatedSearchResult, StorageAdapter, Vector, VectorDocument } from './coreTypes.js';
 import { MetadataIndexConfig } from './utils/metadataIndex.js';
+import { CleanupConfig } from './utils/periodicCleanup.js';
 import { NounType, VerbType } from './types/graphTypes.js';
 import { WebSocketConnection } from './types/augmentations.js';
 import { BrainyDataInterface } from './types/brainyDataInterface.js';
@@ -393,6 +394,12 @@ export interface BrainyDataConfig {
      * Default: false (enabled automatically for distributed setups)
      */
     health?: boolean;
+    /**
+     * Periodic cleanup configuration for old soft-deleted items
+     * Automatically removes soft-deleted items after a specified age to prevent memory buildup
+     * Default: enabled with 1 hour max age and 15 minute cleanup interval
+     */
+    cleanup?: Partial<CleanupConfig>;
 }
 export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
     hnswIndex: HNSWIndex | HNSWIndexOptimized;
@@ -426,6 +433,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
     private _nlpProcessor?;
     private _importManager?;
     private cacheAutoConfigurator;
+    private periodicCleanup;
     private timeoutConfig;
     private retryConfig;
     private cacheConfig;
@@ -485,6 +493,11 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      * Phase 3 of two-phase initialization
      */
     private initializeAugmentations;
+    /**
+     * Initialize periodic cleanup system for old soft-deleted items
+     * SAFETY-CRITICAL: Coordinates with both HNSW and metadata indexes
+     */
+    private initializePeriodicCleanup;
     private checkReadOnly;
     /**
      * Check if the database is frozen and throw an error if it is
@@ -1035,7 +1048,15 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
     deleteVerbs(ids: string[]): Promise<boolean[]>;
     deleteVerb(id: string, options?: {
         service?: string;
-        hard?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Restore a soft-deleted verb (complement to consistent soft delete)
+     * @param id The verb ID to restore
+     * @param options Options for the restore operation
+     * @returns Promise<boolean> True if restored, false if not found or not deleted
+     */
+    restoreVerb(id: string, options?: {
+        service?: string;
     }): Promise<boolean>;
     /**
      * Get the number of vectors in the database
@@ -1630,6 +1651,12 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      * @returns Success boolean
      */
     deleteNoun(id: string): Promise<boolean>;
+    /**
+     * Restore a soft-deleted noun (complement to consistent soft delete)
+     * @param id The noun ID to restore
+     * @returns Promise<boolean> True if restored, false if not found or not deleted
+     */
+    restoreNoun(id: string): Promise<boolean>;
     /**
      * Delete multiple nouns by IDs
      * @param ids Array of noun IDs