@soulcraft/brainy 3.44.0 → 3.45.0

package/dist/storage/storageFactory.js

@@ -6,6 +6,7 @@ import { MemoryStorage } from './adapters/memoryStorage.js';
 import { OPFSStorage } from './adapters/opfsStorage.js';
 import { S3CompatibleStorage, R2Storage } from './adapters/s3CompatibleStorage.js';
 import { GcsStorage } from './adapters/gcsStorage.js';
+import { TypeAwareStorageAdapter } from './adapters/typeAwareStorageAdapter.js';
 // FileSystemStorage is dynamically imported to avoid issues in browser environments
 import { isBrowser } from '../utils/environment.js';
 /**
@@ -156,6 +157,23 @@ export async function createStorage(options = {}) {
                     console.warn('GCS native storage configuration is missing, falling back to memory storage');
                     return new MemoryStorage();
                 }
+            case 'type-aware': {
+                console.log('Using Type-Aware Storage (type-first architecture)');
+                // Create underlying storage adapter
+                const underlyingType = options.typeAwareStorage?.underlyingType || 'auto';
+                const underlyingOptions = options.typeAwareStorage?.underlyingOptions || {};
+                // Recursively create the underlying storage
+                const underlying = await createStorage({
+                    ...underlyingOptions,
+                    type: underlyingType
+                });
+                // Wrap with TypeAwareStorageAdapter
+                // Cast to BaseStorage since all concrete storage adapters extend BaseStorage
+                return new TypeAwareStorageAdapter({
+                    underlyingStorage: underlying,
+                    verbose: options.typeAwareStorage?.verbose || false
+                });
+            }
             default:
                 console.warn(`Unknown storage type: ${options.type}, falling back to memory storage`);
                 return new MemoryStorage();
@@ -269,7 +287,7 @@ export async function createStorage(options = {}) {
 /**
  * Export storage adapters
  */
-export { MemoryStorage, OPFSStorage, S3CompatibleStorage, R2Storage, GcsStorage };
+export { MemoryStorage, OPFSStorage, S3CompatibleStorage, R2Storage, GcsStorage, TypeAwareStorageAdapter };
 // Export FileSystemStorage conditionally
 // NOTE: FileSystemStorage is now only imported dynamically to avoid fs imports in browser builds
 // export { FileSystemStorage } from './adapters/fileSystemStorage.js'

package/dist/types/brainyDataInterface.d.ts

@@ -0,0 +1,52 @@
+/**
+ * BrainyInterface - Modern API Only
+ *
+ * This interface defines the MODERN methods from Brainy 3.0.
+ * Used to break circular dependencies while enforcing modern API usage.
+ *
+ * NO DEPRECATED METHODS - Only clean, modern API patterns.
+ */
+import { Vector } from '../coreTypes.js';
+import { AddParams, RelateParams, Result, Entity, FindParams, SimilarParams } from './brainy.types.js';
+export interface BrainyInterface<T = unknown> {
+    /**
+     * Initialize the database
+     */
+    init(): Promise<void>;
+    /**
+     * Modern add method - unified entity creation
+     * @param params Parameters for adding entities
+     * @returns The ID of the created entity
+     */
+    add(params: AddParams<T>): Promise<string>;
+    /**
+     * Modern relate method - unified relationship creation
+     * @param params Parameters for creating relationships
+     * @returns The ID of the created relationship
+     */
+    relate(params: RelateParams<T>): Promise<string>;
+    /**
+     * Modern find method - unified search and discovery
+     * @param query Search query or parameters object
+     * @returns Array of search results
+     */
+    find(query: string | FindParams<T>): Promise<Result<T>[]>;
+    /**
+     * Modern get method - retrieve entities by ID
+     * @param id The entity ID to retrieve
+     * @returns Entity or null if not found
+     */
+    get(id: string): Promise<Entity<T> | null>;
+    /**
+     * Modern similar method - find similar entities
+     * @param params Parameters for similarity search
+     * @returns Array of similar entities with scores
+     */
+    similar(params: SimilarParams<T>): Promise<Result<T>[]>;
+    /**
+     * Generate embedding vector from text
+     * @param text The text to embed
+     * @returns Vector representation of the text
+     */
+    embed(text: string): Promise<Vector>;
+}

package/dist/types/brainyDataInterface.js

@@ -0,0 +1,10 @@
+/**
+ * BrainyInterface - Modern API Only
+ *
+ * This interface defines the MODERN methods from Brainy 3.0.
+ * Used to break circular dependencies while enforcing modern API usage.
+ *
+ * NO DEPRECATED METHODS - Only clean, modern API patterns.
+ */
+export {};
+//# sourceMappingURL=brainyDataInterface.js.map

package/dist/types/graphTypes.d.ts

@@ -428,4 +428,136 @@ export declare const VerbType: {
     readonly Competes: "competes";
 };
 export type VerbType = (typeof VerbType)[keyof typeof VerbType];
+/**
+ * Noun type enum for O(1) lookups and type safety
+ * Maps each noun type to a unique index (0-30)
+ * Used for fixed-size array operations and bitmap indices
+ */
+export declare enum NounTypeEnum {
+    person = 0,
+    organization = 1,
+    location = 2,
+    thing = 3,
+    concept = 4,
+    event = 5,
+    document = 6,
+    media = 7,
+    file = 8,
+    message = 9,
+    content = 10,
+    collection = 11,
+    dataset = 12,
+    product = 13,
+    service = 14,
+    user = 15,
+    task = 16,
+    project = 17,
+    process = 18,
+    state = 19,
+    role = 20,
+    topic = 21,
+    language = 22,
+    currency = 23,
+    measurement = 24,
+    hypothesis = 25,
+    experiment = 26,
+    contract = 27,
+    regulation = 28,
+    interface = 29,
+    resource = 30
+}
+/**
+ * Verb type enum for O(1) lookups and type safety
+ * Maps each verb type to a unique index (0-39)
+ * Used for fixed-size array operations and bitmap indices
+ */
+export declare enum VerbTypeEnum {
+    relatedTo = 0,
+    contains = 1,
+    partOf = 2,
+    locatedAt = 3,
+    references = 4,
+    precedes = 5,
+    succeeds = 6,
+    causes = 7,
+    dependsOn = 8,
+    requires = 9,
+    creates = 10,
+    transforms = 11,
+    becomes = 12,
+    modifies = 13,
+    consumes = 14,
+    owns = 15,
+    attributedTo = 16,
+    createdBy = 17,
+    belongsTo = 18,
+    memberOf = 19,
+    worksWith = 20,
+    friendOf = 21,
+    follows = 22,
+    likes = 23,
+    reportsTo = 24,
+    supervises = 25,
+    mentors = 26,
+    communicates = 27,
+    describes = 28,
+    defines = 29,
+    categorizes = 30,
+    measures = 31,
+    evaluates = 32,
+    uses = 33,
+    implements = 34,
+    extends = 35,
+    inherits = 36,
+    conflicts = 37,
+    synchronizes = 38,
+    competes = 39
+}
+/**
+ * Total number of noun types (for array allocations)
+ */
+export declare const NOUN_TYPE_COUNT = 31;
+/**
+ * Total number of verb types (for array allocations)
+ */
+export declare const VERB_TYPE_COUNT = 40;
+/**
+ * Type utilities for O(1) conversions between string types and numeric indices
+ * Enables efficient fixed-size array operations and bitmap indexing
+ */
+export declare const TypeUtils: {
+    /**
+     * Get numeric index for a noun type
+     * @param type - NounType string (e.g., 'person')
+     * @returns Numeric index (0-30)
+     */
+    getNounIndex: (type: NounType) => number;
+    /**
+     * Get numeric index for a verb type
+     * @param type - VerbType string (e.g., 'relatedTo')
+     * @returns Numeric index (0-39)
+     */
+    getVerbIndex: (type: VerbType) => number;
+    /**
+     * Get noun type string from numeric index
+     * @param index - Numeric index (0-30)
+     * @returns NounType string or 'thing' as default
+     */
+    getNounFromIndex: (index: number) => NounType;
+    /**
+     * Get verb type string from numeric index
+     * @param index - Numeric index (0-39)
+     * @returns VerbType string or 'relatedTo' as default
+     */
+    getVerbFromIndex: (index: number) => VerbType;
+};
+/**
+ * Type-specific metadata for optimization hints
+ * Provides per-type configuration for bloom filters, chunking, and indexing
+ */
+export declare const TypeMetadata: Record<NounType, {
+    expectedFields: number;
+    bloomBits: number;
+    avgChunkSize: number;
+}>;
 export {};

package/dist/types/graphTypes.js

@@ -258,4 +258,176 @@ export const VerbType = {
     Synchronizes: 'synchronizes', // Coordination, timing, synchronized operations
     Competes: 'competes' // Competition, rivalry, competing relationships
 };
+/**
+ * Noun type enum for O(1) lookups and type safety
+ * Maps each noun type to a unique index (0-30)
+ * Used for fixed-size array operations and bitmap indices
+ */
+export var NounTypeEnum;
+(function (NounTypeEnum) {
+    NounTypeEnum[NounTypeEnum["person"] = 0] = "person";
+    NounTypeEnum[NounTypeEnum["organization"] = 1] = "organization";
+    NounTypeEnum[NounTypeEnum["location"] = 2] = "location";
+    NounTypeEnum[NounTypeEnum["thing"] = 3] = "thing";
+    NounTypeEnum[NounTypeEnum["concept"] = 4] = "concept";
+    NounTypeEnum[NounTypeEnum["event"] = 5] = "event";
+    NounTypeEnum[NounTypeEnum["document"] = 6] = "document";
+    NounTypeEnum[NounTypeEnum["media"] = 7] = "media";
+    NounTypeEnum[NounTypeEnum["file"] = 8] = "file";
+    NounTypeEnum[NounTypeEnum["message"] = 9] = "message";
+    NounTypeEnum[NounTypeEnum["content"] = 10] = "content";
+    NounTypeEnum[NounTypeEnum["collection"] = 11] = "collection";
+    NounTypeEnum[NounTypeEnum["dataset"] = 12] = "dataset";
+    NounTypeEnum[NounTypeEnum["product"] = 13] = "product";
+    NounTypeEnum[NounTypeEnum["service"] = 14] = "service";
+    NounTypeEnum[NounTypeEnum["user"] = 15] = "user";
+    NounTypeEnum[NounTypeEnum["task"] = 16] = "task";
+    NounTypeEnum[NounTypeEnum["project"] = 17] = "project";
+    NounTypeEnum[NounTypeEnum["process"] = 18] = "process";
+    NounTypeEnum[NounTypeEnum["state"] = 19] = "state";
+    NounTypeEnum[NounTypeEnum["role"] = 20] = "role";
+    NounTypeEnum[NounTypeEnum["topic"] = 21] = "topic";
+    NounTypeEnum[NounTypeEnum["language"] = 22] = "language";
+    NounTypeEnum[NounTypeEnum["currency"] = 23] = "currency";
+    NounTypeEnum[NounTypeEnum["measurement"] = 24] = "measurement";
+    NounTypeEnum[NounTypeEnum["hypothesis"] = 25] = "hypothesis";
+    NounTypeEnum[NounTypeEnum["experiment"] = 26] = "experiment";
+    NounTypeEnum[NounTypeEnum["contract"] = 27] = "contract";
+    NounTypeEnum[NounTypeEnum["regulation"] = 28] = "regulation";
+    NounTypeEnum[NounTypeEnum["interface"] = 29] = "interface";
+    NounTypeEnum[NounTypeEnum["resource"] = 30] = "resource";
+})(NounTypeEnum || (NounTypeEnum = {}));
+/**
+ * Verb type enum for O(1) lookups and type safety
+ * Maps each verb type to a unique index (0-39)
+ * Used for fixed-size array operations and bitmap indices
+ */
+export var VerbTypeEnum;
+(function (VerbTypeEnum) {
+    VerbTypeEnum[VerbTypeEnum["relatedTo"] = 0] = "relatedTo";
+    VerbTypeEnum[VerbTypeEnum["contains"] = 1] = "contains";
+    VerbTypeEnum[VerbTypeEnum["partOf"] = 2] = "partOf";
+    VerbTypeEnum[VerbTypeEnum["locatedAt"] = 3] = "locatedAt";
+    VerbTypeEnum[VerbTypeEnum["references"] = 4] = "references";
+    VerbTypeEnum[VerbTypeEnum["precedes"] = 5] = "precedes";
+    VerbTypeEnum[VerbTypeEnum["succeeds"] = 6] = "succeeds";
+    VerbTypeEnum[VerbTypeEnum["causes"] = 7] = "causes";
+    VerbTypeEnum[VerbTypeEnum["dependsOn"] = 8] = "dependsOn";
+    VerbTypeEnum[VerbTypeEnum["requires"] = 9] = "requires";
+    VerbTypeEnum[VerbTypeEnum["creates"] = 10] = "creates";
+    VerbTypeEnum[VerbTypeEnum["transforms"] = 11] = "transforms";
+    VerbTypeEnum[VerbTypeEnum["becomes"] = 12] = "becomes";
+    VerbTypeEnum[VerbTypeEnum["modifies"] = 13] = "modifies";
+    VerbTypeEnum[VerbTypeEnum["consumes"] = 14] = "consumes";
+    VerbTypeEnum[VerbTypeEnum["owns"] = 15] = "owns";
+    VerbTypeEnum[VerbTypeEnum["attributedTo"] = 16] = "attributedTo";
+    VerbTypeEnum[VerbTypeEnum["createdBy"] = 17] = "createdBy";
+    VerbTypeEnum[VerbTypeEnum["belongsTo"] = 18] = "belongsTo";
+    VerbTypeEnum[VerbTypeEnum["memberOf"] = 19] = "memberOf";
+    VerbTypeEnum[VerbTypeEnum["worksWith"] = 20] = "worksWith";
+    VerbTypeEnum[VerbTypeEnum["friendOf"] = 21] = "friendOf";
+    VerbTypeEnum[VerbTypeEnum["follows"] = 22] = "follows";
+    VerbTypeEnum[VerbTypeEnum["likes"] = 23] = "likes";
+    VerbTypeEnum[VerbTypeEnum["reportsTo"] = 24] = "reportsTo";
+    VerbTypeEnum[VerbTypeEnum["supervises"] = 25] = "supervises";
+    VerbTypeEnum[VerbTypeEnum["mentors"] = 26] = "mentors";
+    VerbTypeEnum[VerbTypeEnum["communicates"] = 27] = "communicates";
+    VerbTypeEnum[VerbTypeEnum["describes"] = 28] = "describes";
+    VerbTypeEnum[VerbTypeEnum["defines"] = 29] = "defines";
+    VerbTypeEnum[VerbTypeEnum["categorizes"] = 30] = "categorizes";
+    VerbTypeEnum[VerbTypeEnum["measures"] = 31] = "measures";
+    VerbTypeEnum[VerbTypeEnum["evaluates"] = 32] = "evaluates";
+    VerbTypeEnum[VerbTypeEnum["uses"] = 33] = "uses";
+    VerbTypeEnum[VerbTypeEnum["implements"] = 34] = "implements";
+    VerbTypeEnum[VerbTypeEnum["extends"] = 35] = "extends";
+    VerbTypeEnum[VerbTypeEnum["inherits"] = 36] = "inherits";
+    VerbTypeEnum[VerbTypeEnum["conflicts"] = 37] = "conflicts";
+    VerbTypeEnum[VerbTypeEnum["synchronizes"] = 38] = "synchronizes";
+    VerbTypeEnum[VerbTypeEnum["competes"] = 39] = "competes";
+})(VerbTypeEnum || (VerbTypeEnum = {}));
+/**
+ * Total number of noun types (for array allocations)
+ */
+export const NOUN_TYPE_COUNT = 31;
+/**
+ * Total number of verb types (for array allocations)
+ */
+export const VERB_TYPE_COUNT = 40;
+/**
+ * Type utilities for O(1) conversions between string types and numeric indices
+ * Enables efficient fixed-size array operations and bitmap indexing
+ */
+export const TypeUtils = {
+    /**
+     * Get numeric index for a noun type
+     * @param type - NounType string (e.g., 'person')
+     * @returns Numeric index (0-30)
+     */
+    getNounIndex: (type) => {
+        return NounTypeEnum[type];
+    },
+    /**
+     * Get numeric index for a verb type
+     * @param type - VerbType string (e.g., 'relatedTo')
+     * @returns Numeric index (0-39)
+     */
+    getVerbIndex: (type) => {
+        return VerbTypeEnum[type];
+    },
+    /**
+     * Get noun type string from numeric index
+     * @param index - Numeric index (0-30)
+     * @returns NounType string or 'thing' as default
+     */
+    getNounFromIndex: (index) => {
+        const entry = Object.entries(NounTypeEnum).find(([_, idx]) => idx === index);
+        return entry ? entry[0] : NounType.Thing;
+    },
+    /**
+     * Get verb type string from numeric index
+     * @param index - Numeric index (0-39)
+     * @returns VerbType string or 'relatedTo' as default
+     */
+    getVerbFromIndex: (index) => {
+        const entry = Object.entries(VerbTypeEnum).find(([_, idx]) => idx === index);
+        return entry ? entry[0] : VerbType.RelatedTo;
+    }
+};
+/**
+ * Type-specific metadata for optimization hints
+ * Provides per-type configuration for bloom filters, chunking, and indexing
+ */
+export const TypeMetadata = {
+    person: { expectedFields: 10, bloomBits: 256, avgChunkSize: 100 },
+    organization: { expectedFields: 12, bloomBits: 256, avgChunkSize: 80 },
+    document: { expectedFields: 8, bloomBits: 256, avgChunkSize: 100 },
+    event: { expectedFields: 6, bloomBits: 128, avgChunkSize: 50 },
+    location: { expectedFields: 7, bloomBits: 128, avgChunkSize: 60 },
+    thing: { expectedFields: 5, bloomBits: 128, avgChunkSize: 50 },
+    concept: { expectedFields: 4, bloomBits: 128, avgChunkSize: 40 },
+    media: { expectedFields: 6, bloomBits: 128, avgChunkSize: 50 },
+    file: { expectedFields: 5, bloomBits: 128, avgChunkSize: 50 },
+    message: { expectedFields: 7, bloomBits: 128, avgChunkSize: 60 },
+    content: { expectedFields: 5, bloomBits: 128, avgChunkSize: 50 },
+    collection: { expectedFields: 4, bloomBits: 128, avgChunkSize: 40 },
+    dataset: { expectedFields: 6, bloomBits: 128, avgChunkSize: 50 },
+    product: { expectedFields: 8, bloomBits: 256, avgChunkSize: 70 },
+    service: { expectedFields: 7, bloomBits: 128, avgChunkSize: 60 },
+    user: { expectedFields: 9, bloomBits: 256, avgChunkSize: 80 },
+    task: { expectedFields: 6, bloomBits: 128, avgChunkSize: 50 },
+    project: { expectedFields: 8, bloomBits: 256, avgChunkSize: 70 },
+    process: { expectedFields: 5, bloomBits: 128, avgChunkSize: 50 },
+    state: { expectedFields: 3, bloomBits: 128, avgChunkSize: 30 },
+    role: { expectedFields: 4, bloomBits: 128, avgChunkSize: 40 },
+    topic: { expectedFields: 4, bloomBits: 128, avgChunkSize: 40 },
+    language: { expectedFields: 3, bloomBits: 128, avgChunkSize: 30 },
+    currency: { expectedFields: 3, bloomBits: 128, avgChunkSize: 30 },
+    measurement: { expectedFields: 4, bloomBits: 128, avgChunkSize: 40 },
+    hypothesis: { expectedFields: 6, bloomBits: 128, avgChunkSize: 50 },
+    experiment: { expectedFields: 7, bloomBits: 128, avgChunkSize: 60 },
+    contract: { expectedFields: 8, bloomBits: 256, avgChunkSize: 70 },
+    regulation: { expectedFields: 6, bloomBits: 128, avgChunkSize: 50 },
+    interface: { expectedFields: 5, bloomBits: 128, avgChunkSize: 50 },
+    resource: { expectedFields: 5, bloomBits: 128, avgChunkSize: 50 }
+};
 //# sourceMappingURL=graphTypes.js.map

package/dist/utils/metadataIndex.d.ts

@@ -70,7 +70,6 @@ export declare class MetadataIndexManager {
     private activeLocks;
     private lockPromises;
     private lockTimers;
-    private sparseIndices;
     private chunkManager;
     private chunkingStrategy;
     private idMapper;
@@ -80,6 +79,12 @@ export declare class MetadataIndexManager {
      * This must be called after construction and before any queries
      */
     init(): Promise<void>;
+    /**
+     * Warm the cache by preloading common field sparse indices (v3.44.1)
+     * This improves cache hit rates by loading frequently-accessed fields at startup
+     * Target: >80% cache hit rate for typical workloads
+     */
+    warmCache(): Promise<void>;
     /**
      * Acquire an in-memory lock for coordinating concurrent metadata index writes
      * Uses in-memory locks since MetadataIndexManager doesn't have direct file system access
@@ -122,15 +127,18 @@ export declare class MetadataIndexManager {
     private saveSparseIndex;
     /**
      * Get IDs for a value using chunked sparse index with roaring bitmaps (v3.43.0)
+     * v3.44.1: Now fully lazy-loaded via UnifiedCache (no local sparseIndices Map)
      */
     private getIdsFromChunks;
     /**
      * Get IDs for a range using chunked sparse index with zone maps and roaring bitmaps (v3.43.0)
+     * v3.44.1: Now fully lazy-loaded via UnifiedCache (no local sparseIndices Map)
      */
     private getIdsFromChunksForRange;
     /**
      * Get roaring bitmap for a field-value pair without converting to UUIDs (v3.43.0)
      * This is used for fast multi-field intersection queries using hardware-accelerated bitmap AND
+     * v3.44.1: Now fully lazy-loaded via UnifiedCache (no local sparseIndices Map)
      * @returns RoaringBitmap32 containing integer IDs, or null if no matches
      */
     private getBitmapFromChunks;
@@ -155,10 +163,12 @@ export declare class MetadataIndexManager {
     }>): Promise<string[]>;
     /**
      * Add value-ID mapping to chunked index
+     * v3.44.1: Now fully lazy-loaded via UnifiedCache (no local sparseIndices Map)
      */
     private addToChunkedIndex;
     /**
      * Remove ID from chunked index
+     * v3.44.1: Now fully lazy-loaded via UnifiedCache (no local sparseIndices Map)
      */
     private removeFromChunkedIndex;
     /**
@@ -275,11 +285,14 @@ export declare class MetadataIndexManager {
     getCountForCriteria(field: string, value: any): Promise<number>;
     /**
      * Get index statistics with enhanced counting information
+     * v3.44.1: Sparse indices now lazy-loaded via UnifiedCache
+     * Note: This method may load sparse indices to calculate stats
      */
     getStats(): Promise<MetadataIndexStats>;
     /**
      * Rebuild entire index from scratch using pagination
      * Non-blocking version that yields control back to event loop
+     * v3.44.1: Sparse indices now lazy-loaded via UnifiedCache (no need to clear Map)
      */
     rebuild(): Promise<void>;
     /**