@soulcraft/brainy 5.3.6 → 5.5.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/dist/vfs/types.d.ts

@@ -166,6 +166,10 @@ export interface ReaddirOptions {
     sort?: 'name' | 'size' | 'modified' | 'created';
     order?: 'asc' | 'desc';
 }
+export interface StatOptions {
+}
+export interface ExistsOptions {
+}
 export interface CopyOptions {
     overwrite?: boolean;
     preserveTimestamps?: boolean;
@@ -299,9 +303,9 @@ export interface IVirtualFileSystem {
         parent: VFSEntity | null;
         stats: VFSStats;
     }>;
-    stat(path: string): Promise<VFSStats>;
+    stat(path: string, options?: StatOptions): Promise<VFSStats>;
     lstat(path: string): Promise<VFSStats>;
-    exists(path: string): Promise<boolean>;
+    exists(path: string, options?: ExistsOptions): Promise<boolean>;
     chmod(path: string, mode: number): Promise<void>;
     chown(path: string, uid: number, gid: number): Promise<void>;
     utimes(path: string, atime: Date, mtime: Date): Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "5.3.6",
-  "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.5.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",