@soulcraft/brainy 2.1.0 → 3.0.0

package/dist/augmentations/AugmentationMetadataContract.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Augmentation Metadata Contract System
+ *
+ * Prevents accidental metadata corruption while allowing intentional enrichment
+ * Each augmentation declares its metadata intentions upfront
+ */
+export interface AugmentationMetadataContract {
+    name: string;
+    version: string;
+    reads?: {
+        userFields?: string[];
+        internalFields?: string[];
+        augmentationFields?: string[];
+    };
+    writes?: {
+        userFields?: Array<{
+            field: string;
+            type: 'create' | 'update' | 'merge' | 'delete';
+            description: string;
+            example?: any;
+        }>;
+        augmentationFields?: Array<{
+            field: string;
+            description: string;
+        }>;
+        internalFields?: Array<{
+            field: string;
+            permission: 'granted' | 'requested';
+            reason: string;
+        }>;
+    };
+    conflictResolution?: {
+        strategy: 'error' | 'warn' | 'merge' | 'skip' | 'override';
+        priority?: number;
+    };
+    guarantees?: {
+        preservesExisting?: boolean;
+        reversible?: boolean;
+        idempotent?: boolean;
+        validatesTypes?: boolean;
+    };
+}
+/**
+ * Runtime metadata safety enforcer
+ */
+export declare class MetadataSafetyEnforcer {
+    private contracts;
+    private modifications;
+    /**
+     * Register an augmentation's contract
+     */
+    registerContract(contract: AugmentationMetadataContract): void;
+    /**
+     * Check if an augmentation can modify a field
+     */
+    canModifyField(augName: string, field: string, value: any): {
+        allowed: boolean;
+        reason?: string;
+        warnings?: string[];
+    };
+    /**
+     * Create safe metadata proxy for an augmentation
+     */
+    createSafeProxy(metadata: any, augName: string): any;
+}
+/**
+ * Example augmentation contracts
+ */
+export declare const EXAMPLE_CONTRACTS: Record<string, AugmentationMetadataContract>;
+/**
+ * Augmentation base class with safety
+ */
+export declare abstract class SafeAugmentation {
+    protected enforcer: MetadataSafetyEnforcer;
+    protected contract: AugmentationMetadataContract;
+    constructor(contract: AugmentationMetadataContract);
+    /**
+     * Get safe metadata proxy
+     */
+    protected getSafeMetadata(metadata: any): any;
+    /**
+     * Abstract method to implement augmentation logic
+     */
+    abstract execute(metadata: any): Promise<any>;
+}
+/**
+ * Example: Category enricher implementation
+ */
+export declare class CategoryEnricherAugmentation extends SafeAugmentation {
+    constructor();
+    execute(metadata: any): Promise<any>;
+    private detectCategory;
+    private detectSubcategories;
+}

package/dist/augmentations/AugmentationMetadataContract.js

@@ -0,0 +1,306 @@
+/**
+ * Augmentation Metadata Contract System
+ *
+ * Prevents accidental metadata corruption while allowing intentional enrichment
+ * Each augmentation declares its metadata intentions upfront
+ */
+/**
+ * Runtime metadata safety enforcer
+ */
+export class MetadataSafetyEnforcer {
+    constructor() {
+        this.contracts = new Map();
+        this.modifications = new Map(); // field -> augmentations that modify it
+    }
+    /**
+     * Register an augmentation's contract
+     */
+    registerContract(contract) {
+        this.contracts.set(contract.name, contract);
+        // Track which augmentations modify which fields
+        if (contract.writes?.userFields) {
+            for (const fieldDef of contract.writes.userFields) {
+                if (!this.modifications.has(fieldDef.field)) {
+                    this.modifications.set(fieldDef.field, new Set());
+                }
+                this.modifications.get(fieldDef.field).add(contract.name);
+            }
+        }
+    }
+    /**
+     * Check if an augmentation can modify a field
+     */
+    canModifyField(augName, field, value) {
+        const contract = this.contracts.get(augName);
+        if (!contract) {
+            return {
+                allowed: false,
+                reason: `Augmentation '${augName}' has no registered contract`
+            };
+        }
+        // Check if field is in user namespace
+        if (!field.startsWith('_brainy.') && !field.startsWith('_augmentations.')) {
+            // It's a user field
+            const declaredField = contract.writes?.userFields?.find(f => f.field === field);
+            if (!declaredField) {
+                return {
+                    allowed: false,
+                    reason: `Augmentation '${augName}' did not declare intent to modify '${field}'`
+                };
+            }
+            // Check for conflicts
+            const modifiers = this.modifications.get(field);
+            if (modifiers && modifiers.size > 1) {
+                const others = Array.from(modifiers).filter(a => a !== augName);
+                return {
+                    allowed: true, // Still allowed but with warning
+                    warnings: [`Field '${field}' is also modified by: ${others.join(', ')}`]
+                };
+            }
+            return { allowed: true };
+        }
+        // Check internal fields
+        if (field.startsWith('_brainy.')) {
+            const internalField = contract.writes?.internalFields?.find(f => field === `_brainy.${f.field}`);
+            if (!internalField) {
+                return {
+                    allowed: false,
+                    reason: `Augmentation '${augName}' cannot modify internal field '${field}'`
+                };
+            }
+            if (internalField.permission !== 'granted') {
+                return {
+                    allowed: false,
+                    reason: `Permission not granted for internal field '${field}'`
+                };
+            }
+            return { allowed: true };
+        }
+        // Check augmentation namespace
+        if (field.startsWith('_augmentations.')) {
+            const parts = field.split('.');
+            const targetAug = parts[1];
+            // Can only modify own namespace
+            if (targetAug !== augName) {
+                return {
+                    allowed: false,
+                    reason: `Cannot modify another augmentation's namespace: ${targetAug}`
+                };
+            }
+            return { allowed: true };
+        }
+        return { allowed: true };
+    }
+    /**
+     * Create safe metadata proxy for an augmentation
+     */
+    createSafeProxy(metadata, augName) {
+        const self = this;
+        return new Proxy(metadata, {
+            set(target, prop, value) {
+                const field = String(prop);
+                // Check permission
+                const permission = self.canModifyField(augName, field, value);
+                if (!permission.allowed) {
+                    throw new Error(`[${augName}] ${permission.reason}`);
+                }
+                if (permission.warnings) {
+                    console.warn(`[${augName}] Warning:`, ...permission.warnings);
+                }
+                // Track modification for audit
+                if (!target._audit) {
+                    target._audit = [];
+                }
+                target._audit.push({
+                    augmentation: augName,
+                    field,
+                    oldValue: target[prop],
+                    newValue: value,
+                    timestamp: Date.now()
+                });
+                target[prop] = value;
+                return true;
+            },
+            deleteProperty(target, prop) {
+                const field = String(prop);
+                const permission = self.canModifyField(augName, field, undefined);
+                if (!permission.allowed) {
+                    throw new Error(`[${augName}] Cannot delete field: ${permission.reason}`);
+                }
+                delete target[prop];
+                return true;
+            }
+        });
+    }
+}
+/**
+ * Example augmentation contracts
+ */
+export const EXAMPLE_CONTRACTS = {
+    // Enrichment augmentation that adds categories
+    categoryEnricher: {
+        name: 'categoryEnricher',
+        version: '1.0.0',
+        reads: {
+            userFields: ['title', 'description', 'content']
+        },
+        writes: {
+            userFields: [
+                {
+                    field: 'category',
+                    type: 'create',
+                    description: 'Auto-detected category',
+                    example: 'technology'
+                },
+                {
+                    field: 'subcategories',
+                    type: 'create',
+                    description: 'List of relevant subcategories',
+                    example: ['web', 'framework']
+                }
+            ],
+            augmentationFields: [
+                {
+                    field: 'confidence',
+                    description: 'Confidence score of categorization'
+                }
+            ]
+        },
+        guarantees: {
+            preservesExisting: true,
+            idempotent: true
+        }
+    },
+    // Translation augmentation
+    translator: {
+        name: 'translator',
+        version: '1.0.0',
+        reads: {
+            userFields: ['title', 'description']
+        },
+        writes: {
+            userFields: [
+                {
+                    field: 'translations',
+                    type: 'merge',
+                    description: 'Translations in multiple languages',
+                    example: { es: 'Título', fr: 'Titre' }
+                },
+                {
+                    field: 'detectedLanguage',
+                    type: 'create',
+                    description: 'Detected source language',
+                    example: 'en'
+                }
+            ]
+        },
+        conflictResolution: {
+            strategy: 'merge',
+            priority: 10
+        }
+    },
+    // Sentiment analyzer
+    sentimentAnalyzer: {
+        name: 'sentimentAnalyzer',
+        version: '1.0.0',
+        reads: {
+            userFields: ['content', 'description', 'reviews']
+        },
+        writes: {
+            userFields: [
+                {
+                    field: 'sentiment',
+                    type: 'update',
+                    description: 'Overall sentiment score',
+                    example: { score: 0.8, label: 'positive' }
+                }
+            ],
+            augmentationFields: [
+                {
+                    field: 'analysis',
+                    description: 'Detailed sentiment breakdown'
+                }
+            ]
+        },
+        guarantees: {
+            reversible: true,
+            validatesTypes: true
+        }
+    },
+    // System augmentation with internal access
+    garbageCollector: {
+        name: 'garbageCollector',
+        version: '1.0.0',
+        reads: {
+            internalFields: ['_brainy.createdAt', '_brainy.lastAccessed']
+        },
+        writes: {
+            internalFields: [
+                {
+                    field: 'deleted',
+                    permission: 'granted',
+                    reason: 'Soft delete expired items'
+                },
+                {
+                    field: 'archived',
+                    permission: 'granted',
+                    reason: 'Archive old items'
+                }
+            ]
+        }
+    }
+};
+/**
+ * Augmentation base class with safety
+ */
+export class SafeAugmentation {
+    constructor(contract) {
+        this.contract = contract;
+        this.enforcer = new MetadataSafetyEnforcer();
+        this.enforcer.registerContract(contract);
+    }
+    /**
+     * Get safe metadata proxy
+     */
+    getSafeMetadata(metadata) {
+        return this.enforcer.createSafeProxy(metadata, this.contract.name);
+    }
+}
+/**
+ * Example: Category enricher implementation
+ */
+export class CategoryEnricherAugmentation extends SafeAugmentation {
+    constructor() {
+        super(EXAMPLE_CONTRACTS.categoryEnricher);
+    }
+    async execute(metadata) {
+        const safe = this.getSafeMetadata(metadata);
+        // Read declared fields
+        const title = safe.title;
+        const description = safe.description;
+        // Analyze and categorize
+        const category = this.detectCategory(title, description);
+        const subcategories = this.detectSubcategories(title, description);
+        // Write to declared fields (will be checked by proxy)
+        safe.category = category; // ✅ Allowed - declared in contract
+        safe.subcategories = subcategories; // ✅ Allowed
+        // Try to write undeclared field
+        // safe.randomField = 'test' // ❌ Would throw error!
+        // Write to our augmentation namespace
+        if (!safe._augmentations)
+            safe._augmentations = {};
+        if (!safe._augmentations.categoryEnricher) {
+            safe._augmentations.categoryEnricher = {};
+        }
+        safe._augmentations.categoryEnricher.confidence = 0.95; // ✅ Allowed
+        return safe;
+    }
+    detectCategory(title, description) {
+        // Simplified logic
+        return 'technology';
+    }
+    detectSubcategories(title, description) {
+        return ['web', 'framework'];
+    }
+}
+//# sourceMappingURL=AugmentationMetadataContract.js.map

package/dist/augmentations/apiServerAugmentation.d.ts

@@ -42,6 +42,7 @@ export interface APIServerConfig {
 export declare class APIServerAugmentation extends BaseAugmentation {
     readonly name = "api-server";
     readonly timing: "after";
+    readonly metadata: "readonly";
     readonly operations: ("all")[];
     readonly priority = 5;
     private config;

package/dist/augmentations/apiServerAugmentation.js

@@ -23,6 +23,7 @@ export class APIServerAugmentation extends BaseAugmentation {
         super();
         this.name = 'api-server';
         this.timing = 'after';
+        this.metadata = 'readonly'; // API server reads metadata to serve data
         this.operations = ['all'];
         this.priority = 5; // Low priority, runs after other augmentations
         this.clients = new Map();

package/dist/augmentations/batchProcessingAugmentation.d.ts

@@ -29,6 +29,7 @@ interface BatchMetrics {
     adaptiveAdjustments: number;
 }
 export declare class BatchProcessingAugmentation extends BaseAugmentation {
+    readonly metadata: "readonly";
     name: string;
     timing: "around";
     operations: ("add" | "addNoun" | "addVerb" | "saveNoun" | "saveVerb" | "storage")[];

package/dist/augmentations/batchProcessingAugmentation.js

@@ -11,6 +11,7 @@ import { BaseAugmentation } from './brainyAugmentation.js';
 export class BatchProcessingAugmentation extends BaseAugmentation {
     constructor(config = {}) {
         super();
+        this.metadata = 'readonly'; // Reads metadata for batching decisions
         this.name = 'BatchProcessing';
         this.timing = 'around';
         this.operations = ['add', 'addNoun', 'addVerb', 'saveNoun', 'saveVerb', 'storage'];

package/dist/augmentations/brainyAugmentation.d.ts

@@ -11,6 +11,14 @@
  * - IntelligentVerbScoring: Enhances relationship analysis
  * - StreamingPipeline: Enables unlimited data processing
  */
+/**
+ * Metadata access declaration for augmentations
+ */
+export interface MetadataAccess {
+    reads?: string[] | '*';
+    writes?: string[] | '*';
+    namespace?: string;
+}
 export interface BrainyAugmentation {
     /**
      * Unique identifier for the augmentation
@@ -24,6 +32,13 @@ export interface BrainyAugmentation {
      * - 'replace': Replace the main operation entirely
      */
     timing: 'before' | 'after' | 'around' | 'replace';
+    /**
+     * Metadata access contract - REQUIRED
+     * - 'none': No metadata access at all
+     * - 'readonly': Can read any metadata but cannot write
+     * - MetadataAccess: Specific fields to read/write
+     */
+    metadata: 'none' | 'readonly' | MetadataAccess;
     /**
      * Which operations this augmentation applies to
      * Granular operation matching for precise augmentation targeting
@@ -90,6 +105,7 @@ export interface AugmentationContext {
 export declare abstract class BaseAugmentation implements BrainyAugmentation {
     abstract name: string;
     abstract timing: 'before' | 'after' | 'around' | 'replace';
+    abstract metadata: 'none' | 'readonly' | MetadataAccess;
     abstract operations: ('add' | 'addNoun' | 'addVerb' | 'saveNoun' | 'saveVerb' | 'updateMetadata' | 'delete' | 'deleteVerb' | 'clear' | 'get' | 'search' | 'searchText' | 'searchByNounTypes' | 'findSimilar' | 'searchWithCursor' | 'relate' | 'getConnections' | 'storage' | 'backup' | 'restore' | 'all')[];
     abstract priority: number;
     protected context?: AugmentationContext;

package/dist/augmentations/cacheAugmentation.d.ts

@@ -28,6 +28,7 @@ export interface CacheConfig {
 export declare class CacheAugmentation extends BaseAugmentation {
     readonly name = "cache";
     readonly timing: "around";
+    readonly metadata: "none";
     operations: ("search" | "add" | "delete" | "clear" | "all")[];
     readonly priority = 50;
     private searchCache;

package/dist/augmentations/cacheAugmentation.js

@@ -23,6 +23,7 @@ export class CacheAugmentation extends BaseAugmentation {
         super();
         this.name = 'cache';
         this.timing = 'around';
+        this.metadata = 'none'; // Cache doesn't access metadata
         this.operations = ['search', 'add', 'delete', 'clear', 'all'];
         this.priority = 50; // Mid-priority, runs after data operations
         this.searchCache = null;

package/dist/augmentations/conduitAugmentations.d.ts

@@ -17,6 +17,7 @@ export interface WebSocketConnection {
  */
 declare abstract class BaseConduitAugmentation extends BaseAugmentation {
     readonly timing: "after";
+    readonly metadata: "readonly";
     readonly operations: ("addNoun" | "delete" | "addVerb")[];
     readonly priority = 20;
     protected connections: Map<string, any>;

package/dist/augmentations/conduitAugmentations.js

@@ -14,6 +14,7 @@ class BaseConduitAugmentation extends BaseAugmentation {
     constructor() {
         super(...arguments);
         this.timing = 'after'; // Conduits run after operations to sync
+        this.metadata = 'readonly'; // Conduits read metadata to pass to external systems
         this.operations = ['addNoun', 'delete', 'addVerb'];
         this.priority = 20; // Medium-low priority
         this.connections = new Map();

package/dist/augmentations/connectionPoolAugmentation.d.ts

@@ -19,6 +19,7 @@ interface ConnectionPoolConfig {
 export declare class ConnectionPoolAugmentation extends BaseAugmentation {
     name: string;
     timing: "around";
+    metadata: "none";
     operations: ("storage")[];
     priority: number;
     private config;

package/dist/augmentations/connectionPoolAugmentation.js

@@ -11,6 +11,7 @@ export class ConnectionPoolAugmentation extends BaseAugmentation {
         super();
         this.name = 'ConnectionPool';
         this.timing = 'around';
+        this.metadata = 'none'; // Connection pooling doesn't access metadata
         this.operations = ['storage'];
         this.priority = 95; // Very high priority for storage operations
         this.connections = new Map();

package/dist/augmentations/entityRegistryAugmentation.d.ts

@@ -46,6 +46,7 @@ export interface EntityMapping {
  * Optimized for streaming data scenarios like Bluesky firehose processing
  */
 export declare class EntityRegistryAugmentation extends BaseAugmentation {
+    readonly metadata: "readonly";
     readonly name = "entity-registry";
     readonly description = "Fast external-ID to internal-UUID mapping for streaming data";
     readonly timing: 'before' | 'after' | 'around' | 'replace';
@@ -114,6 +115,7 @@ export declare class EntityRegistryAugmentation extends BaseAugmentation {
     private estimateMemoryUsage;
 }
 export declare class AutoRegisterEntitiesAugmentation extends BaseAugmentation {
+    readonly metadata: "readonly";
     readonly name = "auto-register-entities";
     readonly description = "Automatically register entities in the registry when added";
     readonly timing: 'before' | 'after' | 'around' | 'replace';

package/dist/augmentations/entityRegistryAugmentation.js

@@ -11,6 +11,7 @@ import { BaseAugmentation } from './brainyAugmentation.js';
 export class EntityRegistryAugmentation extends BaseAugmentation {
     constructor(config = {}) {
         super();
+        this.metadata = 'readonly'; // Reads metadata to register entities
         this.name = 'entity-registry';
         this.description = 'Fast external-ID to internal-UUID mapping for streaming data';
         this.timing = 'before';
@@ -355,6 +356,7 @@ export class EntityRegistryAugmentation extends BaseAugmentation {
 export class AutoRegisterEntitiesAugmentation extends BaseAugmentation {
     constructor() {
         super(...arguments);
+        this.metadata = 'readonly'; // Reads metadata for auto-registration
         this.name = 'auto-register-entities';
         this.description = 'Automatically register entities in the registry when added';
         this.timing = 'after';

package/dist/augmentations/indexAugmentation.d.ts

@@ -27,6 +27,7 @@ export interface IndexConfig {
  * - Zero-config with smart defaults
  */
 export declare class IndexAugmentation extends BaseAugmentation {
+    readonly metadata: "readonly";
     readonly name = "index";
     readonly timing: "after";
     operations: ("add" | "updateMetadata" | "delete" | "clear" | "all")[];

package/dist/augmentations/indexAugmentation.js

@@ -21,6 +21,7 @@ import { MetadataIndexManager } from '../utils/metadataIndex.js';
 export class IndexAugmentation extends BaseAugmentation {
     constructor(config = {}) {
         super();
+        this.metadata = 'readonly'; // Reads metadata to build indexes
         this.name = 'index';
         this.timing = 'after';
         this.operations = ['add', 'updateMetadata', 'delete', 'clear', 'all'];

package/dist/augmentations/intelligentVerbScoringAugmentation.d.ts

@@ -51,6 +51,10 @@ interface ScoringMetrics {
 export declare class IntelligentVerbScoringAugmentation extends BaseAugmentation {
     name: string;
     timing: "around";
+    readonly metadata: {
+        reads: string[];
+        writes: string[];
+    };
     operations: ("addVerb" | "relate")[];
     priority: number;
     get enabled(): boolean;

package/dist/augmentations/intelligentVerbScoringAugmentation.js

@@ -20,6 +20,10 @@ export class IntelligentVerbScoringAugmentation extends BaseAugmentation {
         super();
         this.name = 'IntelligentVerbScoring';
         this.timing = 'around';
+        this.metadata = {
+            reads: ['type', 'verb', 'source', 'target'],
+            writes: ['weight', 'confidence', 'intelligentScoring']
+        }; // Adds scoring metadata to verbs
         this.operations = ['addVerb', 'relate'];
         this.priority = 10; // Enhancement feature - runs after core operations
         this.relationshipStats = new Map();

package/dist/augmentations/metadataEnforcer.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Runtime enforcement of metadata contracts
+ * Ensures augmentations only access declared fields
+ */
+import { BrainyAugmentation } from './brainyAugmentation.js';
+export declare class MetadataEnforcer {
+    /**
+     * Enforce metadata access based on augmentation contract
+     * Returns a wrapped metadata object that enforces the contract
+     */
+    static enforce(augmentation: BrainyAugmentation, metadata: any, operation?: 'read' | 'write'): any;
+    /**
+     * Validate that an augmentation's actual behavior matches its contract
+     * Used in testing to verify contracts are accurate
+     */
+    static validateContract(augmentation: BrainyAugmentation, testMetadata?: any): Promise<{
+        valid: boolean;
+        violations: string[];
+    }>;
+}