@soulcraft/brainy 5.4.0 → 5.6.0

package/dist/types/typeMigration.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Type Migration Utilities for Stage 3 Taxonomy (v6.0.0)
+ *
+ * Provides migration helpers for code using removed types from v5.x
+ *
+ * ## Removed Types
+ *
+ * ### Nouns (2 removed):
+ * - `user` → merged into `person`
+ * - `topic` → merged into `concept`
+ *
+ * ### Verbs (4 removed):
+ * - `succeeds` → use inverse of `precedes`
+ * - `belongsTo` → use inverse of `owns`
+ * - `createdBy` → use inverse of `creates`
+ * - `supervises` → use inverse of `reportsTo`
+ */
+import { NounType, VerbType } from './graphTypes.js';
+/**
+ * Migration mapping for removed noun types
+ */
+export declare const REMOVED_NOUN_TYPES: {
+    readonly user: "person";
+    readonly topic: "concept";
+};
+/**
+ * Migration mapping for removed verb types
+ * Note: Some verbs should use inverse relationships in Stage 3
+ */
+export declare const REMOVED_VERB_TYPES: {
+    readonly succeeds: "precedes";
+    readonly belongsTo: "owns";
+    readonly createdBy: "creates";
+    readonly supervises: "reportsTo";
+};
+/**
+ * Check if a type was removed in Stage 3
+ */
+export declare function isRemovedNounType(type: string): type is keyof typeof REMOVED_NOUN_TYPES;
+/**
+ * Check if a verb type was removed in Stage 3
+ */
+export declare function isRemovedVerbType(type: string): type is keyof typeof REMOVED_VERB_TYPES;
+/**
+ * Migrate a noun type from v5.x to v6.0 Stage 3
+ * Returns the migrated type or the original if no migration needed
+ */
+export declare function migrateNounType(type: string): NounType;
+/**
+ * Migrate a verb type from v5.x to v6.0 Stage 3
+ * Returns the migrated type or the original if no migration needed
+ *
+ * WARNING: Some verbs require inverting source/target relationships!
+ * See VERB_REQUIRES_INVERSION for details.
+ */
+export declare function migrateVerbType(type: string): VerbType;
+/**
+ * Verbs that require inverting source/target when migrating
+ *
+ * Example:
+ * - Old: `A createdBy B` → New: `B creates A`
+ * - Old: `A belongsTo B` → New: `B owns A`
+ * - Old: `A supervises B` → New: `B reportsTo A`
+ * - Old: `A succeeds B` → New: `B precedes A`
+ */
+export declare const VERB_REQUIRES_INVERSION: Set<string>;
+/**
+ * Check if a verb type requires inverting source/target during migration
+ */
+export declare function requiresInversion(oldVerbType: string): boolean;
+/**
+ * Migrate a relationship, handling source/target inversion if needed
+ *
+ * @returns Object with migrated verb and potentially inverted source/target
+ */
+export declare function migrateRelationship(params: {
+    verb: string;
+    source: string;
+    target: string;
+}): {
+    verb: VerbType;
+    source: string;
+    target: string;
+    inverted: boolean;
+};
+/**
+ * Stage 3 Type Compatibility Check
+ * Helps developers identify code that needs updating for v6.0
+ */
+export declare function checkTypeCompatibility(nounTypes: string[], verbTypes: string[]): {
+    valid: boolean;
+    removedNouns: string[];
+    removedVerbs: string[];
+    warnings: string[];
+};

package/dist/types/typeMigration.js

@@ -0,0 +1,141 @@
+/**
+ * Type Migration Utilities for Stage 3 Taxonomy (v6.0.0)
+ *
+ * Provides migration helpers for code using removed types from v5.x
+ *
+ * ## Removed Types
+ *
+ * ### Nouns (2 removed):
+ * - `user` → merged into `person`
+ * - `topic` → merged into `concept`
+ *
+ * ### Verbs (4 removed):
+ * - `succeeds` → use inverse of `precedes`
+ * - `belongsTo` → use inverse of `owns`
+ * - `createdBy` → use inverse of `creates`
+ * - `supervises` → use inverse of `reportsTo`
+ */
+import { NounType, VerbType } from './graphTypes.js';
+/**
+ * Migration mapping for removed noun types
+ */
+export const REMOVED_NOUN_TYPES = {
+    user: NounType.Person,
+    topic: NounType.Concept
+};
+/**
+ * Migration mapping for removed verb types
+ * Note: Some verbs should use inverse relationships in Stage 3
+ */
+export const REMOVED_VERB_TYPES = {
+    succeeds: VerbType.Precedes, // Use with inverted source/target
+    belongsTo: VerbType.Owns, // Use with inverted source/target
+    createdBy: VerbType.Creates, // Use with inverted source/target
+    supervises: VerbType.ReportsTo // Use with inverted source/target
+};
+/**
+ * Check if a type was removed in Stage 3
+ */
+export function isRemovedNounType(type) {
+    return type in REMOVED_NOUN_TYPES;
+}
+/**
+ * Check if a verb type was removed in Stage 3
+ */
+export function isRemovedVerbType(type) {
+    return type in REMOVED_VERB_TYPES;
+}
+/**
+ * Migrate a noun type from v5.x to v6.0 Stage 3
+ * Returns the migrated type or the original if no migration needed
+ */
+export function migrateNounType(type) {
+    if (isRemovedNounType(type)) {
+        console.warn(`⚠️  NounType "${type}" was removed in v6.0. Migrating to "${REMOVED_NOUN_TYPES[type]}"`);
+        return REMOVED_NOUN_TYPES[type];
+    }
+    return type;
+}
+/**
+ * Migrate a verb type from v5.x to v6.0 Stage 3
+ * Returns the migrated type or the original if no migration needed
+ *
+ * WARNING: Some verbs require inverting source/target relationships!
+ * See VERB_REQUIRES_INVERSION for details.
+ */
+export function migrateVerbType(type) {
+    if (isRemovedVerbType(type)) {
+        console.warn(`⚠️  VerbType "${type}" was removed in v6.0. Migrating to "${REMOVED_VERB_TYPES[type]}" (may require source/target inversion)`);
+        return REMOVED_VERB_TYPES[type];
+    }
+    return type;
+}
+/**
+ * Verbs that require inverting source/target when migrating
+ *
+ * Example:
+ * - Old: `A createdBy B` → New: `B creates A`
+ * - Old: `A belongsTo B` → New: `B owns A`
+ * - Old: `A supervises B` → New: `B reportsTo A`
+ * - Old: `A succeeds B` → New: `B precedes A`
+ */
+export const VERB_REQUIRES_INVERSION = new Set([
+    'succeeds',
+    'belongsTo',
+    'createdBy',
+    'supervises'
+]);
+/**
+ * Check if a verb type requires inverting source/target during migration
+ */
+export function requiresInversion(oldVerbType) {
+    return VERB_REQUIRES_INVERSION.has(oldVerbType);
+}
+/**
+ * Migrate a relationship, handling source/target inversion if needed
+ *
+ * @returns Object with migrated verb and potentially inverted source/target
+ */
+export function migrateRelationship(params) {
+    const verb = migrateVerbType(params.verb);
+    const inverted = requiresInversion(params.verb);
+    if (inverted) {
+        return {
+            verb,
+            source: params.target, // Swap source and target
+            target: params.source,
+            inverted: true
+        };
+    }
+    return {
+        verb,
+        source: params.source,
+        target: params.target,
+        inverted: false
+    };
+}
+/**
+ * Stage 3 Type Compatibility Check
+ * Helps developers identify code that needs updating for v6.0
+ */
+export function checkTypeCompatibility(nounTypes, verbTypes) {
+    const removedNouns = nounTypes.filter(isRemovedNounType);
+    const removedVerbs = verbTypes.filter(isRemovedVerbType);
+    const warnings = [];
+    if (removedNouns.length > 0) {
+        warnings.push(`Found ${removedNouns.length} removed noun type(s): ${removedNouns.join(', ')}. ` +
+            `These were merged in Stage 3. Use Person instead of User, Concept instead of Topic.`);
+    }
+    if (removedVerbs.length > 0) {
+        warnings.push(`Found ${removedVerbs.length} removed verb type(s): ${removedVerbs.join(', ')}. ` +
+            `These require using inverse relationships in Stage 3. ` +
+            `Example: "A createdBy B" becomes "B creates A".`);
+    }
+    return {
+        valid: removedNouns.length === 0 && removedVerbs.length === 0,
+        removedNouns,
+        removedVerbs,
+        warnings
+    };
+}
+//# sourceMappingURL=typeMigration.js.map

package/dist/utils/intelligentTypeMapper.js

@@ -189,7 +189,7 @@ export class IntelligentTypeMapper {
             'references': VerbType.References,
             'cites': VerbType.References,
             'before': VerbType.Precedes,
-            'after': VerbType.Succeeds,
+            'after': VerbType.Precedes,
             'causes': VerbType.Causes,
             'needs': VerbType.Requires,
             'requires': VerbType.Requires,
@@ -198,7 +198,7 @@ export class IntelligentTypeMapper {
             'changes': VerbType.Modifies,
             'updates': VerbType.Modifies,
             'owns': VerbType.Owns,
-            'ownedBy': VerbType.BelongsTo, // Use BelongsTo for reverse ownership
+            'ownedBy': VerbType.Owns, // Use BelongsTo for reverse ownership
             'uses': VerbType.Uses,
             'usedBy': VerbType.Uses // Same relationship, just interpret direction
         };

package/dist/utils/metadataIndex.js

@@ -29,13 +29,13 @@ export class MetadataIndexManager {
         // Type-Field Affinity Tracking for intelligent NLP
         this.typeFieldAffinity = new Map(); // nounType -> field -> count
         this.totalEntitiesByType = new Map(); // nounType -> total count
-        // Phase 1b: Fixed-size type tracking (99.76% memory reduction vs Maps)
+        // Phase 1b: Fixed-size type tracking (Stage 3 CANONICAL: 99.2% memory reduction vs Maps)
         // Uint32Array provides O(1) access via type enum index
-        // 31 noun types × 4 bytes = 124 bytes (vs ~15KB with Map overhead)
-        // 40 verb types × 4 bytes = 160 bytes (vs ~20KB with Map overhead)
-        // Total: 284 bytes (vs ~35KB) = 99.2% memory reduction
-        this.entityCountsByTypeFixed = new Uint32Array(NOUN_TYPE_COUNT); // 124 bytes
-        this.verbCountsByTypeFixed = new Uint32Array(VERB_TYPE_COUNT); // 160 bytes
+        // 42 noun types × 4 bytes = 168 bytes (vs ~20KB with Map overhead)
+        // 127 verb types × 4 bytes = 508 bytes (vs ~62KB with Map overhead)
+        // Total: 676 bytes (vs ~85KB) = 99.2% memory reduction
+        this.entityCountsByTypeFixed = new Uint32Array(NOUN_TYPE_COUNT); // 168 bytes (Stage 3 CANONICAL: 42 types)
+        this.verbCountsByTypeFixed = new Uint32Array(VERB_TYPE_COUNT); // 508 bytes (Stage 3 CANONICAL: 127 types)
         // File locking for concurrent write protection (prevents race conditions)
         this.activeLocks = new Map();
         this.lockPromises = new Map();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "5.4.0",
-  "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
+  "version": "5.6.0",
+  "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/importManager.d.ts

@@ -1,78 +0,0 @@
-/**
- * Import Manager - Comprehensive data import with intelligent type detection
- *
- * Handles multiple data sources:
- * - Direct data (objects, arrays)
- * - Files (JSON, CSV, text)
- * - URLs (fetch and parse)
- * - Streams (for large files)
- *
- * Uses NeuralImportAugmentation for intelligent processing
- */
-import { NounType } from './types/graphTypes.js';
-export interface ImportOptions {
-    source?: 'data' | 'file' | 'url' | 'auto';
-    format?: 'json' | 'csv' | 'text' | 'yaml' | 'auto';
-    batchSize?: number;
-    autoDetect?: boolean;
-    typeHint?: NounType;
-    extractRelationships?: boolean;
-    csvDelimiter?: string;
-    csvHeaders?: boolean;
-    parallel?: boolean;
-    maxConcurrency?: number;
-}
-export interface ImportResult {
-    success: boolean;
-    nouns: string[];
-    verbs: string[];
-    errors: string[];
-    stats: {
-        total: number;
-        imported: number;
-        failed: number;
-        relationships: number;
-    };
-}
-export declare class ImportManager {
-    private neuralImport;
-    private typeMatcher;
-    private brain;
-    constructor(brain: any);
-    /**
-     * Initialize the import manager
-     */
-    init(): Promise<void>;
-    /**
-     * Main import method - handles all sources
-     */
-    import(source: string | Buffer | any[] | any, options?: ImportOptions): Promise<ImportResult>;
-    /**
-     * Import from file
-     */
-    importFile(filePath: string, options?: ImportOptions): Promise<ImportResult>;
-    /**
-     * Import from URL
-     */
-    importUrl(url: string, options?: ImportOptions): Promise<ImportResult>;
-    /**
-     * Detect source type
-     */
-    private detectSourceType;
-    /**
-     * Detect format from file path
-     */
-    private detectFormatFromPath;
-    /**
-     * Read file
-     */
-    private readFile;
-    /**
-     * Fetch from URL
-     */
-    private fetchFromUrl;
-}
-/**
- * Create an import manager instance
- */
-export declare function createImportManager(brain: any): ImportManager;

package/dist/importManager.js

@@ -1,267 +0,0 @@
-/**
- * Import Manager - Comprehensive data import with intelligent type detection
- *
- * Handles multiple data sources:
- * - Direct data (objects, arrays)
- * - Files (JSON, CSV, text)
- * - URLs (fetch and parse)
- * - Streams (for large files)
- *
- * Uses NeuralImportAugmentation for intelligent processing
- */
-import { VerbType } from './types/graphTypes.js';
-import { NeuralImportAugmentation } from './augmentations/neuralImport.js';
-import * as fs from './universal/fs.js';
-import * as path from './universal/path.js';
-import { prodLog } from './utils/logger.js';
-export class ImportManager {
-    constructor(brain) {
-        this.typeMatcher = null;
-        this.brain = brain;
-        this.neuralImport = new NeuralImportAugmentation();
-    }
-    /**
-     * Initialize the import manager
-     */
-    async init() {
-        // Initialize neural import with proper context
-        const context = {
-            brain: this.brain,
-            storage: this.brain.storage,
-            config: {},
-            log: (message, level) => {
-                if (level === 'error') {
-                    prodLog.error(message);
-                }
-                else if (level === 'warn') {
-                    prodLog.warn(message);
-                }
-                else {
-                    prodLog.info(message);
-                }
-            }
-        };
-        await this.neuralImport.initialize(context);
-        // Get type matcher
-        const { getBrainyTypes } = await import('./augmentations/typeMatching/brainyTypes.js');
-        this.typeMatcher = await getBrainyTypes();
-    }
-    /**
-     * Main import method - handles all sources
-     */
-    async import(source, options = {}) {
-        const result = {
-            success: false,
-            nouns: [],
-            verbs: [],
-            errors: [],
-            stats: {
-                total: 0,
-                imported: 0,
-                failed: 0,
-                relationships: 0
-            }
-        };
-        try {
-            // Detect source type
-            const sourceType = await this.detectSourceType(source, options.source);
-            // Get data based on source type
-            let data;
-            let format = options.format || 'auto';
-            switch (sourceType) {
-                case 'url':
-                    data = await this.fetchFromUrl(source);
-                    break;
-                case 'file':
-                    const filePath = source;
-                    data = await this.readFile(filePath);
-                    if (format === 'auto') {
-                        format = this.detectFormatFromPath(filePath);
-                    }
-                    break;
-                case 'data':
-                default:
-                    data = source;
-                    break;
-            }
-            // Process data through neural import
-            let items;
-            let relationships = [];
-            if (Buffer.isBuffer(data) || typeof data === 'string') {
-                // Use neural import for parsing and analysis
-                const analysis = await this.neuralImport.getNeuralAnalysis(data, format);
-                // Extract items and relationships
-                items = analysis.detectedEntities.map(entity => ({
-                    data: entity.originalData,
-                    type: entity.nounType,
-                    confidence: entity.confidence,
-                    id: entity.suggestedId
-                }));
-                if (options.extractRelationships !== false) {
-                    relationships = analysis.detectedRelationships;
-                }
-                // Log insights
-                for (const insight of analysis.insights) {
-                    prodLog.info(`🧠 ${insight.description} (confidence: ${insight.confidence})`);
-                }
-            }
-            else if (Array.isArray(data)) {
-                items = data;
-            }
-            else {
-                items = [data];
-            }
-            result.stats.total = items.length;
-            // Import items in batches
-            const batchSize = options.batchSize || 50;
-            for (let i = 0; i < items.length; i += batchSize) {
-                const batch = items.slice(i, i + batchSize);
-                // Process batch in parallel if enabled
-                const promises = batch.map(async (item) => {
-                    try {
-                        // Detect type if needed
-                        let nounType = item.type || options.typeHint;
-                        if (!nounType && options.autoDetect !== false && this.typeMatcher) {
-                            const match = await this.typeMatcher.matchNounType(item.data || item);
-                            nounType = match.type;
-                        }
-                        // Prepare the data to import
-                        const dataToImport = item.data || item;
-                        // Create metadata combining original data with import metadata
-                        const metadata = {
-                            ...(typeof dataToImport === 'object' ? dataToImport : {}),
-                            ...(item.data?.metadata || {}),
-                            nounType,
-                            _importedAt: new Date().toISOString(),
-                            _confidence: item.confidence
-                        };
-                        // Add to brain using modern API signature
-                        const id = await this.brain.add({ data: dataToImport, type: nounType || 'content', metadata });
-                        result.nouns.push(id);
-                        result.stats.imported++;
-                        return id;
-                    }
-                    catch (error) {
-                        result.errors.push(`Failed to import item: ${error.message}`);
-                        result.stats.failed++;
-                        return null;
-                    }
-                });
-                if (options.parallel !== false) {
-                    await Promise.all(promises);
-                }
-                else {
-                    for (const promise of promises) {
-                        await promise;
-                    }
-                }
-            }
-            // Import relationships
-            for (const rel of relationships) {
-                try {
-                    // Match verb type if needed
-                    let verbType = rel.verbType;
-                    if (!Object.values(VerbType).includes(verbType) && this.typeMatcher) {
-                        const match = await this.typeMatcher.matchVerbType({ id: rel.sourceId }, { id: rel.targetId }, rel.verbType);
-                        verbType = match.type;
-                    }
-                    const verbId = await this.brain.relate({
-                        from: rel.sourceId,
-                        to: rel.targetId,
-                        type: verbType,
-                        metadata: rel.metadata,
-                        weight: rel.weight
-                    });
-                    result.verbs.push(verbId);
-                    result.stats.relationships++;
-                }
-                catch (error) {
-                    result.errors.push(`Failed to create relationship: ${error.message}`);
-                }
-            }
-            result.success = result.stats.imported > 0;
-            prodLog.info(`✨ Import complete: ${result.stats.imported}/${result.stats.total} items, ${result.stats.relationships} relationships`);
-        }
-        catch (error) {
-            result.errors.push(`Import failed: ${error.message}`);
-            prodLog.error('Import failed:', error);
-        }
-        return result;
-    }
-    /**
-     * Import from file
-     */
-    async importFile(filePath, options = {}) {
-        return this.import(filePath, { ...options, source: 'file' });
-    }
-    /**
-     * Import from URL
-     */
-    async importUrl(url, options = {}) {
-        return this.import(url, { ...options, source: 'url' });
-    }
-    /**
-     * Detect source type
-     */
-    async detectSourceType(source, hint) {
-        if (hint && hint !== 'auto') {
-            return hint;
-        }
-        if (typeof source === 'string') {
-            // Check if URL
-            if (source.startsWith('http://') || source.startsWith('https://')) {
-                return 'url';
-            }
-            // Check if file path exists
-            try {
-                if (await fs.exists(source)) {
-                    return 'file';
-                }
-            }
-            catch (error) {
-                // File system check failed, not a file path
-                console.debug('File path check failed:', error);
-            }
-        }
-        return 'data';
-    }
-    /**
-     * Detect format from file path
-     */
-    detectFormatFromPath(filePath) {
-        const ext = path.extname(filePath).toLowerCase();
-        switch (ext) {
-            case '.json': return 'json';
-            case '.csv': return 'csv';
-            case '.txt': return 'text';
-            case '.md': return 'text';
-            case '.yaml':
-            case '.yml': return 'yaml';
-            default: return 'auto';
-        }
-    }
-    /**
-     * Read file
-     */
-    async readFile(filePath) {
-        const content = await fs.readFile(filePath, 'utf8');
-        return Buffer.from(content, 'utf8');
-    }
-    /**
-     * Fetch from URL
-     */
-    async fetchFromUrl(url) {
-        const response = await fetch(url);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
-        }
-        return response.text();
-    }
-}
-/**
- * Create an import manager instance
- */
-export function createImportManager(brain) {
-    return new ImportManager(brain);
-}
-//# sourceMappingURL=importManager.js.map