@sochdb/sochdb 0.4.0 → 0.4.1

package/dist/types/memory/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Memory System - Main Export
+ *
+ * LLM-native memory system with extraction, consolidation, and retrieval.
+ */
+export * from './types';
+export * from './extraction';
+export * from './consolidation';
+export * from './retrieval';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}

package/dist/types/memory/retrieval.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Hybrid Retriever for Memory System
+ *
+ * Combines vector and keyword search with RRF (Reciprocal Rank Fusion).
+ */
+import { EmbeddedDatabase } from '../embedded';
+import { AllowedSet, RetrievalConfig, RetrievalResponse } from './types';
+/**
+ * Hybrid Retriever with RRF fusion
+ */
+export declare class HybridRetriever {
+    private db;
+    private namespace;
+    private collection;
+    private config;
+    private prefix;
+    private bm25;
+    private indexed;
+    constructor(db: EmbeddedDatabase, namespace: string, collection: string, config?: RetrievalConfig);
+    /**
+     * Create retriever from database
+     */
+    static fromDatabase(db: EmbeddedDatabase, namespace: string, collection: string, config?: RetrievalConfig): HybridRetriever;
+    /**
+     * Index documents for retrieval
+     */
+    indexDocuments(documents: Array<{
+        id: string;
+        content: string;
+        embedding: number[];
+        metadata?: Record<string, any>;
+    }>): Promise<void>;
+    /**
+     * Retrieve documents with hybrid search
+     */
+    retrieve(queryText: string, queryVector: number[], allowed: AllowedSet, k?: number): Promise<RetrievalResponse>;
+    /**
+     * Explain ranking for a specific document
+     */
+    explain(queryText: string, queryVector: number[], docId: string): Promise<{
+        vectorRank?: number;
+        keywordRank?: number;
+        expectedRrfScore?: number;
+    }>;
+}
+//# sourceMappingURL=retrieval.d.ts.map

package/dist/types/memory/retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval.d.ts","sourceRoot":"","sources":["../../../src/memory/retrieval.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,UAAU,EACV,eAAe,EACf,iBAAiB,EAElB,MAAM,SAAS,CAAC;AA6GjB;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,EAAE,CAAmB;IAC7B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,OAAO,CAAkB;gBAG/B,EAAE,EAAE,gBAAgB,EACpB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,eAAe;IAe1B;;OAEG;IACH,MAAM,CAAC,YAAY,CACjB,EAAE,EAAE,gBAAgB,EACpB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,eAAe,GACvB,eAAe;IAIlB;;OAEG;IACG,cAAc,CAAC,SAAS,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB3I;;OAEG;IACG,QAAQ,CACZ,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,EAAE,UAAU,EACnB,CAAC,CAAC,EAAE,MAAM,GACT,OAAO,CAAC,iBAAiB,CAAC;IAsF7B;;OAEG;IACG,OAAO,CACX,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EAAE,EACrB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAyBrF"}

package/dist/types/memory/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Memory System Core Types
+ *
+ * Type definitions for LLM-native memory system with extraction,
+ * consolidation, and retrieval capabilities.
+ */
+/**
+ * Entity extracted from text
+ */
+export interface Entity {
+    id?: string;
+    name: string;
+    entityType: string;
+    properties?: Record<string, any>;
+    confidence?: number;
+    provenance?: string;
+    timestamp?: number;
+}
+/**
+ * Relation between two entities
+ */
+export interface Relation {
+    id?: string;
+    fromEntity: string;
+    relationType: string;
+    toEntity: string;
+    properties?: Record<string, any>;
+    confidence?: number;
+    provenance?: string;
+    timestamp?: number;
+}
+/**
+ * Assertion (subject-predicate-object triple)
+ */
+export interface Assertion {
+    id?: string;
+    subject: string;
+    predicate: string;
+    object: string;
+    confidence?: number;
+    provenance?: string;
+    timestamp?: number;
+}
+/**
+ * Raw assertion for consolidation
+ */
+export interface RawAssertion {
+    id?: string;
+    fact: Record<string, any>;
+    source: string;
+    confidence: number;
+    timestamp?: number;
+}
+/**
+ * Canonical fact after consolidation
+ */
+export interface CanonicalFact {
+    id: string;
+    mergedFact: Record<string, any>;
+    confidence: number;
+    sources: string[];
+    validFrom: number;
+    validUntil?: number;
+}
+/**
+ * Extraction result from LLM
+ */
+export interface ExtractionResult {
+    entities: Entity[];
+    relations: Relation[];
+    assertions: Assertion[];
+}
+/**
+ * Extraction schema for validation
+ */
+export interface ExtractionSchema {
+    entityTypes?: string[];
+    relationTypes?: string[];
+    minConfidence?: number;
+    requireProvenance?: boolean;
+}
+/**
+ * Consolidation configuration
+ */
+export interface ConsolidationConfig {
+    similarityThreshold?: number;
+    useTemporalUpdates?: boolean;
+    maxConflictAge?: number;
+}
+/**
+ * Retrieval configuration
+ */
+export interface RetrievalConfig {
+    k?: number;
+    alpha?: number;
+    enableRerank?: boolean;
+    rerankK?: number;
+}
+/**
+ * Retrieval result
+ */
+export interface RetrievalResult {
+    id: string;
+    score: number;
+    content: string;
+    metadata?: Record<string, any>;
+    vectorRank?: number;
+    keywordRank?: number;
+}
+/**
+ * Retrieval response
+ */
+export interface RetrievalResponse {
+    results: RetrievalResult[];
+    queryTime: number;
+    totalResults: number;
+}
+/**
+ * AllowedSet for pre-filtering
+ */
+export declare abstract class AllowedSet {
+    abstract contains(id: string, metadata?: Record<string, any>): boolean;
+    static fromIds(ids: string[]): AllowedSet;
+    static fromNamespace(namespace: string): AllowedSet;
+    static fromFilter(filterFn: (id: string, metadata?: Record<string, any>) => boolean): AllowedSet;
+    static allowAll(): AllowedSet;
+}
+/**
+ * Namespace policy
+ */
+export declare enum NamespacePolicy {
+    STRICT = "strict",
+    EXPLICIT = "explicit",
+    PERMISSIVE = "permissive"
+}
+/**
+ * Cross-namespace grant
+ */
+export interface NamespaceGrant {
+    id: string;
+    fromNamespace: string;
+    toNamespace: string;
+    operations: string[];
+    expiresAt?: number;
+    reason?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/memory/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/memory/types.ts"],"names":[],"mappings":"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"}

package/dist/types/namespace.d.ts

@@ -0,0 +1,129 @@
+/**
+ * SochDB Namespace API
+ *
+ * Provides type-safe namespace isolation with first-class namespace handles.
+ *
+ * @example
+ * ```typescript
+ * import { Database } from '@sochdb/sochdb';
+ *
+ * const db = await Database.open('./mydb');
+ * const ns = await db.createNamespace('tenant_123');
+ * const collection = await ns.createCollection('documents', { dimension: 384 });
+ * await collection.insert([1.0, 2.0, ...], { source: 'web' });
+ * const results = await collection.search(queryVector, 10);
+ * ```
+ */
+import { SochDBError } from './errors';
+export interface NamespaceConfig {
+    name: string;
+    displayName?: string;
+    labels?: Record<string, string>;
+    readOnly?: boolean;
+}
+export declare class NamespaceNotFoundError extends SochDBError {
+    constructor(namespace: string);
+}
+export declare class NamespaceExistsError extends SochDBError {
+    constructor(namespace: string);
+}
+export declare class CollectionNotFoundError extends SochDBError {
+    constructor(collection: string);
+}
+export declare class CollectionExistsError extends SochDBError {
+    constructor(collection: string);
+}
+export declare enum DistanceMetric {
+    Cosine = "cosine",
+    Euclidean = "euclidean",
+    DotProduct = "dot"
+}
+export interface CollectionConfig {
+    name: string;
+    dimension?: number;
+    metric?: DistanceMetric;
+    indexed?: boolean;
+    hnswM?: number;
+    hnswEfConstruction?: number;
+    metadata?: Record<string, any>;
+}
+export interface SearchRequest {
+    queryVector: number[];
+    k: number;
+    filter?: Record<string, any>;
+    includeMetadata?: boolean;
+}
+export interface SearchResult {
+    id: string;
+    score: number;
+    vector?: number[];
+    metadata?: Record<string, any>;
+}
+export declare class Collection {
+    private db;
+    private namespace;
+    private name;
+    private config;
+    constructor(db: any, namespace: string, name: string, config: CollectionConfig);
+    /**
+     * Insert a vector with optional metadata
+     */
+    insert(vector: number[], metadata?: Record<string, any>, id?: string): Promise<string>;
+    /**
+     * Insert multiple vectors
+     */
+    insertMany(vectors: number[][], metadatas?: Record<string, any>[], ids?: string[]): Promise<string[]>;
+    /**
+     * Search for similar vectors
+     */
+    search(request: SearchRequest): Promise<SearchResult[]>;
+    /**
+     * Get a vector by ID
+     */
+    get(id: string): Promise<{
+        vector: number[];
+        metadata?: Record<string, any>;
+    } | null>;
+    /**
+     * Delete a vector by ID
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Count vectors in collection
+     */
+    count(): Promise<number>;
+    private vectorKey;
+    private vectorKeyPrefix;
+    private metadataKey;
+    private generateId;
+    private cosineSimilarity;
+}
+export declare class Namespace {
+    private db;
+    private name;
+    private config;
+    constructor(db: any, name: string, config: NamespaceConfig);
+    /**
+     * Create a new collection in this namespace
+     */
+    createCollection(config: CollectionConfig): Promise<Collection>;
+    /**
+     * Get an existing collection
+     */
+    collection(name: string): Promise<Collection>;
+    /**
+     * Get or create a collection
+     */
+    getOrCreateCollection(config: CollectionConfig): Promise<Collection>;
+    /**
+     * Delete a collection
+     */
+    deleteCollection(name: string): Promise<boolean>;
+    /**
+     * List all collections in this namespace
+     */
+    listCollections(): Promise<string[]>;
+    getName(): string;
+    getConfig(): NamespaceConfig;
+}
+//# sourceMappingURL=namespace.d.ts.map

package/dist/types/namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace.d.ts","sourceRoot":"","sources":["../../src/namespace.ts"],"names":[],"mappings":"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"}

package/dist/types/queue.d.ts

@@ -0,0 +1,120 @@
+/**
+ * SochDB Priority Queue
+ *
+ * First-class queue API with ordered-key task entries, providing efficient
+ * priority queue operations without the O(N) blob rewrite anti-pattern.
+ *
+ * Features:
+ * - Ordered-key representation: Each task has its own key, no blob parsing
+ * - O(log N) enqueue/dequeue with ordered scans
+ * - Atomic claim protocol for concurrent workers
+ * - Visibility timeout for crash recovery
+ *
+ * @example
+ * ```typescript
+ * import { Database, PriorityQueue } from '@sochdb/sochdb';
+ *
+ * const db = await Database.open('./queue_db');
+ * const queue = PriorityQueue.fromDatabase(db, 'tasks');
+ *
+ * // Enqueue task
+ * await queue.enqueue(1, Buffer.from('high priority task'));
+ *
+ * // Dequeue and process
+ * const task = await queue.dequeue('worker-1');
+ * if (task) {
+ *   // Process task...
+ *   await queue.ack(task.taskId);
+ * }
+ * ```
+ */
+export declare enum TaskState {
+    PENDING = "pending",
+    CLAIMED = "claimed",
+    COMPLETED = "completed",
+    DEAD_LETTERED = "dead_lettered"
+}
+export interface QueueConfig {
+    name: string;
+    visibilityTimeout?: number;
+    maxRetries?: number;
+    deadLetterQueue?: string;
+}
+export interface QueueKey {
+    queueId: string;
+    priority: number;
+    readyTs: number;
+    sequence: number;
+    taskId: string;
+}
+export interface Task {
+    taskId: string;
+    priority: number;
+    payload: Buffer;
+    state: TaskState;
+    enqueuedAt: number;
+    claimedAt?: number;
+    claimedBy?: string;
+    completedAt?: number;
+    retries: number;
+    metadata?: Record<string, any>;
+}
+export interface QueueStats {
+    pending: number;
+    claimed: number;
+    completed: number;
+    deadLettered: number;
+    totalEnqueued: number;
+    totalDequeued: number;
+}
+export declare class PriorityQueue {
+    private db;
+    private config;
+    private static sequenceCounter;
+    constructor(db: any, config: QueueConfig);
+    /**
+     * Create queue from embedded database
+     */
+    static fromDatabase(db: any, name: string, config?: Partial<QueueConfig>): PriorityQueue;
+    /**
+     * Create queue from gRPC client
+     */
+    static fromClient(client: any, name: string, config?: Partial<QueueConfig>): PriorityQueue;
+    /**
+     * Enqueue a task with priority
+     * Lower priority number = higher urgency
+     */
+    enqueue(priority: number, payload: Buffer, metadata?: Record<string, any>): Promise<string>;
+    /**
+     * Dequeue the highest priority task
+     * Returns null if no tasks available
+     */
+    dequeue(workerId: string): Promise<Task | null>;
+    /**
+     * Acknowledge task completion
+     */
+    ack(taskId: string): Promise<void>;
+    /**
+     * Negative acknowledge - return task to queue
+     */
+    nack(taskId: string): Promise<void>;
+    /**
+     * Get queue statistics
+     */
+    stats(): Promise<QueueStats>;
+    /**
+     * Purge completed tasks
+     */
+    purge(): Promise<number>;
+    private generateTaskId;
+    private getTask;
+    private updateTask;
+    private getStat;
+    private incrementStat;
+    private decrementStat;
+}
+/**
+ * Create a queue instance
+ */
+export declare function createQueue(db: any, name: string, config?: Partial<QueueConfig>): PriorityQueue;
+//# sourceMappingURL=queue.d.ts.map

package/dist/types/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAQH,oBAAY,SAAS;IACnB,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,SAAS,cAAc;IACvB,aAAa,kBAAkB;CAChC;AAMD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AA6CD,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AA8CD,MAAM,WAAW,IAAI;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAMD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,qBAAa,aAAa;IAItB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,MAAM;IAJhB,OAAO,CAAC,MAAM,CAAC,eAAe,CAAK;gBAGzB,EAAE,EAAE,GAAG,EACP,MAAM,EAAE,WAAW;IAO7B;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,aAAa;IAQxF;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,aAAa;IAQ1F;;;OAGG;IACG,OAAO,CACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,OAAO,CAAC,MAAM,CAAC;IAkClB;;;OAGG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAUrD;;OAEG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBxC;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBzC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAWlC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAM9B,OAAO,CAAC,cAAc;YAIR,OAAO;YAKP,UAAU;YAIV,OAAO;YAMP,aAAa;YAMb,aAAa;CAK5B;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,GAAG,EACP,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,aAAa,CAEf"}

package/dist/types/semantic-cache.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Semantic Cache for LLM responses
+ *
+ * Cache LLM responses with similarity-based retrieval for cost savings.
+ * Uses database prefix scanning to store and retrieve cached responses.
+ */
+import { EmbeddedDatabase } from './embedded';
+export interface CacheEntry {
+    key: string;
+    value: string;
+    embedding: number[];
+    timestamp: number;
+    ttl?: number;
+    metadata?: Record<string, any>;
+}
+export interface CacheHit extends CacheEntry {
+    score: number;
+}
+export interface CacheStats {
+    count: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+    memoryUsage: number;
+}
+/**
+ * Semantic Cache with vector similarity matching
+ *
+ * @example
+ * ```typescript
+ * const cache = new SemanticCache(db, 'llm_responses');
+ *
+ * // Store response
+ * await cache.put(
+ *   'What is Python?',
+ *   'Python is a high-level programming language...',
+ *   embedding,
+ *   3600  // TTL in seconds
+ * );
+ *
+ * // Check cache
+ * const hit = await cache.get(queryEmbedding, 0.85);
+ * if (hit) {
+ *   console.log(`Cache HIT: ${hit.value} (similarity: ${hit.score})`);
+ * }
+ * ```
+ */
+export declare class SemanticCache {
+    private db;
+    private cacheName;
+    private prefix;
+    private hits;
+    private misses;
+    constructor(db: EmbeddedDatabase, cacheName: string);
+    /**
+     * Store a cached response
+     */
+    put(key: string, value: string, embedding: number[], ttlSeconds?: number, metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Retrieve cached response by similarity
+     *
+     * @param queryEmbedding - Query embedding vector
+     * @param threshold - Minimum cosine similarity (0-1)
+     * @returns Best matching cache entry or null
+     */
+    get(queryEmbedding: number[], threshold?: number): Promise<CacheHit | null>;
+    /**
+     * Delete a specific cache entry
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all entries in this cache
+     */
+    clear(): Promise<number>;
+    /**
+     * Get cache statistics
+     */
+    stats(): Promise<CacheStats>;
+    /**
+     * Purge expired entries
+     */
+    purgeExpired(): Promise<number>;
+}
+//# sourceMappingURL=semantic-cache.d.ts.map

package/dist/types/semantic-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-cache.d.ts","sourceRoot":"","sources":["../../src/semantic-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA2B9C,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,QAAS,SAAQ,UAAU;IAC1C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,EAAE,CAAmB;IAC7B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAEP,EAAE,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM;IAMnD;;OAEG;IACG,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EAAE,EACnB,UAAU,SAAI,EACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC;IAkBhB;;;;;;OAMG;IACG,GAAG,CACP,cAAc,EAAE,MAAM,EAAE,EACxB,SAAS,SAAO,GACf,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IA0C3B;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAyB9B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAoClC;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;CA6BtC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sochdb/sochdb",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "SochDB is an AI-native database with token-optimized output, O(|path|) lookups, built-in vector search, and durable transactions.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",