@soulcraft/brainy 2.0.2 → 2.3.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,10 +55,15 @@ 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;
     private analysisCache;
+    private typeMatcher;
     constructor(config?: Partial<NeuralImportConfig>);
     protected onInitialize(): Promise<void>;
     protected onShutdown(): Promise<void>;
@@ -79,15 +84,23 @@ export declare class NeuralImportAugmentation extends BaseAugmentation {
      */
     private parseRawData;
     /**
-     * Parse CSV data
+     * Parse CSV data - handles quoted values, escaped quotes, and edge cases
      */
     private parseCSV;
+    /**
+     * Parse YAML data
+     */
+    private parseYAML;
+    /**
+     * Parse a YAML value (handle strings, numbers, booleans, null)
+     */
+    private parseYAMLValue;
     /**
      * Perform neural analysis on parsed data
      */
     private performNeuralAnalysis;
     /**
-     * Infer noun type from object structure
+     * Infer noun type from object structure using intelligent type matching
      */
     private inferNounType;
     /**
@@ -95,7 +108,7 @@ export declare class NeuralImportAugmentation extends BaseAugmentation {
      */
     private detectRelationships;
     /**
-     * Infer verb type from field name
+     * Infer verb type from field name using intelligent type matching
      */
     private inferVerbType;
     /**

package/dist/augmentations/neuralImport.js

@@ -8,6 +8,8 @@
  */
 import { BaseAugmentation } from './brainyAugmentation.js';
 import * as path from '../universal/path.js';
+import { getTypeMatcher } from './typeMatching/intelligentTypeMatcher.js';
+import { prodLog } from '../utils/logger.js';
 /**
  * Neural Import Augmentation - Unified Implementation
  * Processes data with AI before storage operations
@@ -17,9 +19,14 @@ 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();
+        this.typeMatcher = null;
         this.config = {
             confidenceThreshold: 0.7,
             enableWeights: true,
@@ -29,7 +36,13 @@ export class NeuralImportAugmentation extends BaseAugmentation {
         };
     }
     async onInitialize() {
-        this.log('🧠 Neural Import augmentation initialized');
+        try {
+            this.typeMatcher = await getTypeMatcher();
+            this.log('🧠 Neural Import augmentation initialized with intelligent type matching');
+        }
+        catch (error) {
+            this.log('⚠️ Failed to initialize type matcher, falling back to heuristics', 'warn');
+        }
     }
     async onShutdown() {
         this.analysisCache.clear();
@@ -128,13 +141,7 @@ export class NeuralImportAugmentation extends BaseAugmentation {
                 return this.parseCSV(content);
             case 'yaml':
             case 'yml':
-                // For now, basic YAML support - in full implementation would use yaml parser
-                try {
-                    return JSON.parse(content); // Placeholder
-                }
-                catch {
-                    return [{ text: content }];
-                }
+                return this.parseYAML(content);
             case 'txt':
             case 'text':
                 // Split text into sentences/paragraphs for analysis
@@ -145,24 +152,174 @@ export class NeuralImportAugmentation extends BaseAugmentation {
         }
     }
     /**
-     * Parse CSV data
+     * Parse CSV data - handles quoted values, escaped quotes, and edge cases
      */
     parseCSV(content) {
-        const lines = content.split('\n').filter(line => line.trim());
+        const lines = content.split('\n');
         if (lines.length === 0)
             return [];
-        const headers = lines[0].split(',').map(h => h.trim());
+        // Parse a CSV line handling quotes
+        const parseLine = (line) => {
+            const result = [];
+            let current = '';
+            let inQuotes = false;
+            let i = 0;
+            while (i < line.length) {
+                const char = line[i];
+                const nextChar = line[i + 1];
+                if (char === '"') {
+                    if (inQuotes && nextChar === '"') {
+                        // Escaped quote
+                        current += '"';
+                        i += 2;
+                    }
+                    else {
+                        // Toggle quote mode
+                        inQuotes = !inQuotes;
+                        i++;
+                    }
+                }
+                else if (char === ',' && !inQuotes) {
+                    // Field separator
+                    result.push(current.trim());
+                    current = '';
+                    i++;
+                }
+                else {
+                    current += char;
+                    i++;
+                }
+            }
+            // Add last field
+            result.push(current.trim());
+            return result;
+        };
+        // Parse headers
+        const headers = parseLine(lines[0]);
         const data = [];
+        // Parse data rows
         for (let i = 1; i < lines.length; i++) {
-            const values = lines[i].split(',').map(v => v.trim());
+            const line = lines[i].trim();
+            if (!line)
+                continue; // Skip empty lines
+            const values = parseLine(line);
             const row = {};
             headers.forEach((header, index) => {
-                row[header] = values[index] || '';
+                const value = values[index] || '';
+                // Try to parse numbers
+                const num = Number(value);
+                row[header] = !isNaN(num) && value !== '' ? num : value;
             });
             data.push(row);
         }
         return data;
     }
+    /**
+     * Parse YAML data
+     */
+    parseYAML(content) {
+        try {
+            // Simple YAML parser for basic structures
+            // For full YAML support, we'd use js-yaml library
+            const lines = content.split('\n');
+            const result = [];
+            let currentObject = null;
+            let currentIndent = 0;
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith('#'))
+                    continue; // Skip empty lines and comments
+                // Calculate indentation
+                const indent = line.length - line.trimStart().length;
+                // Check for array item
+                if (trimmed.startsWith('- ')) {
+                    const value = trimmed.substring(2).trim();
+                    if (indent === 0) {
+                        // Top-level array item
+                        if (value.includes(':')) {
+                            // Object in array
+                            currentObject = {};
+                            result.push(currentObject);
+                            const [key, val] = value.split(':').map(s => s.trim());
+                            currentObject[key] = this.parseYAMLValue(val);
+                        }
+                        else {
+                            result.push(this.parseYAMLValue(value));
+                        }
+                    }
+                    else if (currentObject) {
+                        // Nested array
+                        const lastKey = Object.keys(currentObject).pop();
+                        if (lastKey) {
+                            if (!Array.isArray(currentObject[lastKey])) {
+                                currentObject[lastKey] = [];
+                            }
+                            currentObject[lastKey].push(this.parseYAMLValue(value));
+                        }
+                    }
+                }
+                else if (trimmed.includes(':')) {
+                    // Key-value pair
+                    const colonIndex = trimmed.indexOf(':');
+                    const key = trimmed.substring(0, colonIndex).trim();
+                    const value = trimmed.substring(colonIndex + 1).trim();
+                    if (indent === 0) {
+                        // Top-level object
+                        if (!currentObject) {
+                            currentObject = {};
+                            result.push(currentObject);
+                        }
+                        currentObject[key] = this.parseYAMLValue(value);
+                        currentIndent = 0;
+                    }
+                    else if (currentObject) {
+                        // Nested object
+                        if (indent > currentIndent && !value) {
+                            // Start of nested object
+                            const lastKey = Object.keys(currentObject).pop();
+                            if (lastKey) {
+                                currentObject[lastKey] = { [key]: '' };
+                            }
+                        }
+                        else {
+                            currentObject[key] = this.parseYAMLValue(value);
+                        }
+                        currentIndent = indent;
+                    }
+                }
+            }
+            // If we built a single object and not an array, wrap it
+            if (result.length === 0 && currentObject) {
+                result.push(currentObject);
+            }
+            return result.length > 0 ? result : [{ text: content }];
+        }
+        catch (error) {
+            prodLog.warn('YAML parsing failed, treating as text:', error);
+            return [{ text: content }];
+        }
+    }
+    /**
+     * Parse a YAML value (handle strings, numbers, booleans, null)
+     */
+    parseYAMLValue(value) {
+        if (!value || value === '~' || value === 'null')
+            return null;
+        if (value === 'true')
+            return true;
+        if (value === 'false')
+            return false;
+        // Remove quotes if present
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            return value.slice(1, -1);
+        }
+        // Try to parse as number
+        const num = Number(value);
+        if (!isNaN(num) && value !== '')
+            return num;
+        return value;
+    }
     /**
      * Perform neural analysis on parsed data
      */
@@ -177,14 +334,14 @@ export class NeuralImportAugmentation extends BaseAugmentation {
                 const entityId = item.id || item.name || item.title || `entity_${Date.now()}_${Math.random()}`;
                 detectedEntities.push({
                     originalData: item,
-                    nounType: this.inferNounType(item),
+                    nounType: await this.inferNounType(item),
                     confidence: 0.85,
                     suggestedId: String(entityId),
                     reasoning: 'Detected from structured data',
                     alternativeTypes: []
                 });
                 // Detect relationships from references
-                this.detectRelationships(item, entityId, detectedRelationships);
+                await this.detectRelationships(item, entityId, detectedRelationships);
             }
         }
         // Generate insights
@@ -216,36 +373,31 @@ export class NeuralImportAugmentation extends BaseAugmentation {
         };
     }
     /**
-     * Infer noun type from object structure
+     * Infer noun type from object structure using intelligent type matching
      */
-    inferNounType(obj) {
-        // Simple heuristics for type detection
-        if (obj.email || obj.username)
-            return 'Person';
-        if (obj.title && obj.content)
-            return 'Document';
-        if (obj.price || obj.product)
-            return 'Product';
-        if (obj.date || obj.timestamp)
-            return 'Event';
-        if (obj.url || obj.link)
-            return 'Resource';
-        if (obj.lat || obj.longitude)
-            return 'Location';
-        // Default fallback
-        return 'Entity';
+    async inferNounType(obj) {
+        if (!this.typeMatcher) {
+            // Initialize type matcher if not available
+            this.typeMatcher = await getTypeMatcher();
+        }
+        const result = await this.typeMatcher.matchNounType(obj);
+        // Log if confidence is low for debugging
+        if (result.confidence < 0.5) {
+            this.log(`Low confidence (${result.confidence.toFixed(2)}) for noun type: ${result.type}`, 'warn');
+        }
+        return result.type;
     }
     /**
      * Detect relationships from object references
      */
-    detectRelationships(obj, sourceId, relationships) {
+    async detectRelationships(obj, sourceId, relationships) {
         // Look for reference patterns
         for (const [key, value] of Object.entries(obj)) {
             if (key.endsWith('Id') || key.endsWith('_id') || key === 'parentId' || key === 'userId') {
                 relationships.push({
                     sourceId,
                     targetId: String(value),
-                    verbType: this.inferVerbType(key),
+                    verbType: await this.inferVerbType(key, obj, { id: value }),
                     confidence: 0.75,
                     weight: 1,
                     reasoning: `Reference detected in field: ${key}`,
@@ -259,7 +411,7 @@ export class NeuralImportAugmentation extends BaseAugmentation {
                         relationships.push({
                             sourceId,
                             targetId: String(targetId),
-                            verbType: this.inferVerbType(key),
+                            verbType: await this.inferVerbType(key, obj, { id: targetId }),
                             confidence: 0.7,
                             weight: 1,
                             reasoning: `Array reference in field: ${key}`,
@@ -271,27 +423,19 @@ export class NeuralImportAugmentation extends BaseAugmentation {
         }
     }
     /**
-     * Infer verb type from field name
+     * Infer verb type from field name using intelligent type matching
      */
-    inferVerbType(fieldName) {
-        const normalized = fieldName.toLowerCase();
-        if (normalized.includes('parent'))
-            return 'childOf';
-        if (normalized.includes('user'))
-            return 'belongsTo';
-        if (normalized.includes('author'))
-            return 'authoredBy';
-        if (normalized.includes('owner'))
-            return 'ownedBy';
-        if (normalized.includes('creator'))
-            return 'createdBy';
-        if (normalized.includes('member'))
-            return 'memberOf';
-        if (normalized.includes('tag'))
-            return 'taggedWith';
-        if (normalized.includes('category'))
-            return 'categorizedAs';
-        return 'relatedTo';
+    async inferVerbType(fieldName, sourceObj, targetObj) {
+        if (!this.typeMatcher) {
+            // Initialize type matcher if not available
+            this.typeMatcher = await getTypeMatcher();
+        }
+        const result = await this.typeMatcher.matchVerbType(sourceObj, targetObj, fieldName);
+        // Log if confidence is low for debugging
+        if (result.confidence < 0.5) {
+            this.log(`Low confidence (${result.confidence.toFixed(2)}) for verb type: ${result.type}`, 'warn');
+        }
+        return result.type;
     }
     /**
      * Group entities by type

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;