@soulcraft/brainy 5.7.13 → 5.8.0

package/dist/transaction/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Transaction System Errors
+ *
+ * Provides detailed error information for transaction failures.
+ */
+/**
+ * Base class for all transaction errors
+ */
+export declare class TransactionError extends Error {
+    readonly context?: Record<string, any>;
+    constructor(message: string, context?: Record<string, any>);
+}
+/**
+ * Error during transaction execution
+ */
+export declare class TransactionExecutionError extends TransactionError {
+    readonly operationIndex: number;
+    readonly operationName: string | undefined;
+    readonly cause: Error;
+    constructor(message: string, operationIndex: number, operationName: string | undefined, cause: Error);
+}
+/**
+ * Error during transaction rollback
+ */
+export declare class TransactionRollbackError extends TransactionError {
+    readonly originalError: Error;
+    readonly rollbackErrors: Error[];
+    constructor(message: string, originalError: Error, rollbackErrors: Error[]);
+}
+/**
+ * Error for invalid transaction state
+ */
+export declare class InvalidTransactionStateError extends TransactionError {
+    constructor(currentState: string, attemptedAction: string);
+}
+/**
+ * Error for transaction timeout
+ */
+export declare class TransactionTimeoutError extends TransactionError {
+    constructor(timeoutMs: number, operationIndex: number);
+}

package/dist/transaction/errors.js

@@ -0,0 +1,66 @@
+/**
+ * Transaction System Errors
+ *
+ * Provides detailed error information for transaction failures.
+ */
+/**
+ * Base class for all transaction errors
+ */
+export class TransactionError extends Error {
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+        this.name = 'TransactionError';
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * Error during transaction execution
+ */
+export class TransactionExecutionError extends TransactionError {
+    constructor(message, operationIndex, operationName, cause) {
+        super(message, {
+            operationIndex,
+            operationName,
+            cause: cause.message
+        });
+        this.operationIndex = operationIndex;
+        this.operationName = operationName;
+        this.cause = cause;
+        this.name = 'TransactionExecutionError';
+    }
+}
+/**
+ * Error during transaction rollback
+ */
+export class TransactionRollbackError extends TransactionError {
+    constructor(message, originalError, rollbackErrors) {
+        super(message, {
+            originalError: originalError.message,
+            rollbackErrorCount: rollbackErrors.length,
+            rollbackErrors: rollbackErrors.map(e => e.message)
+        });
+        this.originalError = originalError;
+        this.rollbackErrors = rollbackErrors;
+        this.name = 'TransactionRollbackError';
+    }
+}
+/**
+ * Error for invalid transaction state
+ */
+export class InvalidTransactionStateError extends TransactionError {
+    constructor(currentState, attemptedAction) {
+        super(`Cannot ${attemptedAction}: transaction is in state '${currentState}'`, { currentState, attemptedAction });
+        this.name = 'InvalidTransactionStateError';
+    }
+}
+/**
+ * Error for transaction timeout
+ */
+export class TransactionTimeoutError extends TransactionError {
+    constructor(timeoutMs, operationIndex) {
+        super(`Transaction timed out after ${timeoutMs}ms at operation ${operationIndex}`, { timeoutMs, operationIndex });
+        this.name = 'TransactionTimeoutError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/transaction/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Transaction System
+ *
+ * Provides atomicity for Brainy operations.
+ * All operations succeed or all rollback - no partial failures.
+ *
+ * @module transaction
+ */
+export * from './types.js';
+export * from './errors.js';
+export { Transaction } from './Transaction.js';
+export { TransactionManager, type TransactionStats } from './TransactionManager.js';
+export type { Operation, RollbackAction, TransactionState, TransactionContext, TransactionFunction, TransactionResult, TransactionOptions } from './types.js';
+export { TransactionError, TransactionExecutionError, TransactionRollbackError, InvalidTransactionStateError, TransactionTimeoutError } from './errors.js';

package/dist/transaction/index.js

@@ -0,0 +1,14 @@
+/**
+ * Transaction System
+ *
+ * Provides atomicity for Brainy operations.
+ * All operations succeed or all rollback - no partial failures.
+ *
+ * @module transaction
+ */
+export * from './types.js';
+export * from './errors.js';
+export { Transaction } from './Transaction.js';
+export { TransactionManager } from './TransactionManager.js';
+export { TransactionError, TransactionExecutionError, TransactionRollbackError, InvalidTransactionStateError, TransactionTimeoutError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/transaction/operations/IndexOperations.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Index Operations with Rollback Support
+ *
+ * Provides transactional operations for all indexes:
+ * - TypeAwareHNSWIndex (per-type vector indexes)
+ * - HNSWIndex (legacy/fallback vector index)
+ * - MetadataIndexManager (roaring bitmap filtering)
+ * - GraphAdjacencyIndex (LSM-tree graph storage)
+ *
+ * Each operation can be executed and rolled back atomically.
+ */
+import type { HNSWIndex } from '../../hnsw/hnswIndex.js';
+import type { TypeAwareHNSWIndex } from '../../hnsw/typeAwareHNSWIndex.js';
+import type { MetadataIndexManager } from '../../utils/metadataIndex.js';
+import type { GraphAdjacencyIndex } from '../../graph/graphAdjacencyIndex.js';
+import type { NounType } from '../../types/graphTypes.js';
+import type { GraphVerb } from '../../coreTypes.js';
+import type { Operation, RollbackAction } from '../types.js';
+/**
+ * Add to HNSW index with rollback support
+ *
+ * Rollback strategy:
+ * - Remove item from index
+ *
+ * Note: Works with both HNSWIndex and TypeAwareHNSWIndex
+ */
+export declare class AddToHNSWOperation implements Operation {
+    private readonly index;
+    private readonly id;
+    private readonly vector;
+    readonly name = "AddToHNSW";
+    constructor(index: HNSWIndex, id: string, vector: number[]);
+    execute(): Promise<RollbackAction>;
+    /**
+     * Check if item exists in index
+     */
+    private itemExists;
+}
+/**
+ * Add to TypeAwareHNSW index with rollback support
+ *
+ * Rollback strategy:
+ * - Remove item from type-specific index
+ */
+export declare class AddToTypeAwareHNSWOperation implements Operation {
+    private readonly index;
+    private readonly id;
+    private readonly vector;
+    private readonly nounType;
+    readonly name = "AddToTypeAwareHNSW";
+    constructor(index: TypeAwareHNSWIndex, id: string, vector: number[], nounType: NounType);
+    execute(): Promise<RollbackAction>;
+    /**
+     * Check if item exists in type-specific index
+     */
+    private itemExists;
+}
+/**
+ * Remove from HNSW index with rollback support
+ *
+ * Rollback strategy:
+ * - Re-add item to index with original vector
+ *
+ * Note: Requires storing the vector for rollback
+ */
+export declare class RemoveFromHNSWOperation implements Operation {
+    private readonly index;
+    private readonly id;
+    private readonly vector;
+    readonly name = "RemoveFromHNSW";
+    constructor(index: HNSWIndex, id: string, vector: number[]);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Remove from TypeAwareHNSW index with rollback support
+ *
+ * Rollback strategy:
+ * - Re-add item to type-specific index with original vector
+ */
+export declare class RemoveFromTypeAwareHNSWOperation implements Operation {
+    private readonly index;
+    private readonly id;
+    private readonly vector;
+    private readonly nounType;
+    readonly name = "RemoveFromTypeAwareHNSW";
+    constructor(index: TypeAwareHNSWIndex, id: string, vector: number[], // Required for rollback
+    nounType: NounType);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Add to metadata index with rollback support
+ *
+ * Rollback strategy:
+ * - Remove item from index
+ */
+export declare class AddToMetadataIndexOperation implements Operation {
+    private readonly index;
+    private readonly id;
+    private readonly entity;
+    readonly name = "AddToMetadataIndex";
+    constructor(index: MetadataIndexManager, id: string, entity: any);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Remove from metadata index with rollback support
+ *
+ * Rollback strategy:
+ * - Re-add item to index with original metadata
+ */
+export declare class RemoveFromMetadataIndexOperation implements Operation {
+    private readonly index;
+    private readonly id;
+    private readonly entity;
+    readonly name = "RemoveFromMetadataIndex";
+    constructor(index: MetadataIndexManager, id: string, entity: any);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Add verb to graph index with rollback support
+ *
+ * Rollback strategy:
+ * - Remove verb from graph index
+ */
+export declare class AddToGraphIndexOperation implements Operation {
+    private readonly index;
+    private readonly verb;
+    readonly name = "AddToGraphIndex";
+    constructor(index: GraphAdjacencyIndex, verb: GraphVerb);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Remove verb from graph index with rollback support
+ *
+ * Rollback strategy:
+ * - Re-add verb to graph index
+ */
+export declare class RemoveFromGraphIndexOperation implements Operation {
+    private readonly index;
+    private readonly verb;
+    readonly name = "RemoveFromGraphIndex";
+    constructor(index: GraphAdjacencyIndex, verb: GraphVerb);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Batch operation: Add multiple items to HNSW index
+ *
+ * Useful for bulk imports with transaction support.
+ * Rolls back all items if any fail.
+ */
+export declare class BatchAddToHNSWOperation implements Operation {
+    readonly name = "BatchAddToHNSW";
+    private operations;
+    constructor(index: HNSWIndex, items: Array<{
+        id: string;
+        vector: number[];
+    }>);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Batch operation: Add multiple entities to metadata index
+ *
+ * Useful for bulk imports with transaction support.
+ */
+export declare class BatchAddToMetadataIndexOperation implements Operation {
+    readonly name = "BatchAddToMetadataIndex";
+    private operations;
+    constructor(index: MetadataIndexManager, items: Array<{
+        id: string;
+        entity: any;
+    }>);
+    execute(): Promise<RollbackAction>;
+}

package/dist/transaction/operations/IndexOperations.js

@@ -0,0 +1,301 @@
+/**
+ * Index Operations with Rollback Support
+ *
+ * Provides transactional operations for all indexes:
+ * - TypeAwareHNSWIndex (per-type vector indexes)
+ * - HNSWIndex (legacy/fallback vector index)
+ * - MetadataIndexManager (roaring bitmap filtering)
+ * - GraphAdjacencyIndex (LSM-tree graph storage)
+ *
+ * Each operation can be executed and rolled back atomically.
+ */
+/**
+ * Add to HNSW index with rollback support
+ *
+ * Rollback strategy:
+ * - Remove item from index
+ *
+ * Note: Works with both HNSWIndex and TypeAwareHNSWIndex
+ */
+export class AddToHNSWOperation {
+    constructor(index, id, vector) {
+        this.index = index;
+        this.id = id;
+        this.vector = vector;
+        this.name = 'AddToHNSW';
+    }
+    async execute() {
+        // Check if item already exists (for rollback decision)
+        const existed = await this.itemExists(this.id);
+        // Add to index
+        await this.index.addItem({ id: this.id, vector: this.vector });
+        // Return rollback action
+        return async () => {
+            if (!existed) {
+                // Remove newly added item
+                await this.index.removeItem(this.id);
+            }
+            // If item existed before, we don't rollback (update is OK)
+            // This prevents index corruption from removing pre-existing items
+        };
+    }
+    /**
+     * Check if item exists in index
+     */
+    async itemExists(id) {
+        try {
+            // Try to get item - if exists, no error
+            await this.index.getItem?.(id);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Add to TypeAwareHNSW index with rollback support
+ *
+ * Rollback strategy:
+ * - Remove item from type-specific index
+ */
+export class AddToTypeAwareHNSWOperation {
+    constructor(index, id, vector, nounType) {
+        this.index = index;
+        this.id = id;
+        this.vector = vector;
+        this.nounType = nounType;
+        this.name = 'AddToTypeAwareHNSW';
+    }
+    async execute() {
+        // Check if item already exists
+        const existed = await this.itemExists(this.id, this.nounType);
+        // Add to type-specific index
+        await this.index.addItem({ id: this.id, vector: this.vector }, this.nounType);
+        // Return rollback action
+        return async () => {
+            if (!existed) {
+                // Remove newly added item from type-specific index
+                await this.index.removeItem(this.id, this.nounType);
+            }
+        };
+    }
+    /**
+     * Check if item exists in type-specific index
+     */
+    async itemExists(id, type) {
+        try {
+            const index = this.index.getIndexForType?.(type);
+            if (index) {
+                await index.getItem?.(id);
+                return true;
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Remove from HNSW index with rollback support
+ *
+ * Rollback strategy:
+ * - Re-add item to index with original vector
+ *
+ * Note: Requires storing the vector for rollback
+ */
+export class RemoveFromHNSWOperation {
+    constructor(index, id, vector // Required for rollback
+    ) {
+        this.index = index;
+        this.id = id;
+        this.vector = vector;
+        this.name = 'RemoveFromHNSW';
+    }
+    async execute() {
+        // Remove from index
+        await this.index.removeItem(this.id);
+        // Return rollback action
+        return async () => {
+            // Re-add item with original vector
+            await this.index.addItem({ id: this.id, vector: this.vector });
+        };
+    }
+}
+/**
+ * Remove from TypeAwareHNSW index with rollback support
+ *
+ * Rollback strategy:
+ * - Re-add item to type-specific index with original vector
+ */
+export class RemoveFromTypeAwareHNSWOperation {
+    constructor(index, id, vector, // Required for rollback
+    nounType) {
+        this.index = index;
+        this.id = id;
+        this.vector = vector;
+        this.nounType = nounType;
+        this.name = 'RemoveFromTypeAwareHNSW';
+    }
+    async execute() {
+        // Remove from type-specific index
+        await this.index.removeItem(this.id, this.nounType);
+        // Return rollback action
+        return async () => {
+            // Re-add item with original vector to type-specific index
+            await this.index.addItem({ id: this.id, vector: this.vector }, this.nounType);
+        };
+    }
+}
+/**
+ * Add to metadata index with rollback support
+ *
+ * Rollback strategy:
+ * - Remove item from index
+ */
+export class AddToMetadataIndexOperation {
+    constructor(index, id, entity // Entity or metadata structure
+    ) {
+        this.index = index;
+        this.id = id;
+        this.entity = entity;
+        this.name = 'AddToMetadataIndex';
+    }
+    async execute() {
+        // Add to metadata index (skipFlush=true for transaction atomicity)
+        await this.index.addToIndex(this.id, this.entity, true);
+        // Return rollback action
+        return async () => {
+            // Remove from metadata index
+            await this.index.removeFromIndex(this.id, this.entity);
+        };
+    }
+}
+/**
+ * Remove from metadata index with rollback support
+ *
+ * Rollback strategy:
+ * - Re-add item to index with original metadata
+ */
+export class RemoveFromMetadataIndexOperation {
+    constructor(index, id, entity // Required for rollback
+    ) {
+        this.index = index;
+        this.id = id;
+        this.entity = entity;
+        this.name = 'RemoveFromMetadataIndex';
+    }
+    async execute() {
+        // Remove from metadata index
+        await this.index.removeFromIndex(this.id, this.entity);
+        // Return rollback action
+        return async () => {
+            // Re-add with original metadata (skipFlush=true)
+            await this.index.addToIndex(this.id, this.entity, true);
+        };
+    }
+}
+/**
+ * Add verb to graph index with rollback support
+ *
+ * Rollback strategy:
+ * - Remove verb from graph index
+ */
+export class AddToGraphIndexOperation {
+    constructor(index, verb) {
+        this.index = index;
+        this.verb = verb;
+        this.name = 'AddToGraphIndex';
+    }
+    async execute() {
+        // Add verb to graph index
+        await this.index.addVerb(this.verb);
+        // Return rollback action
+        return async () => {
+            // Remove verb from graph index
+            await this.index.removeVerb(this.verb.id);
+        };
+    }
+}
+/**
+ * Remove verb from graph index with rollback support
+ *
+ * Rollback strategy:
+ * - Re-add verb to graph index
+ */
+export class RemoveFromGraphIndexOperation {
+    constructor(index, verb // Required for rollback
+    ) {
+        this.index = index;
+        this.verb = verb;
+        this.name = 'RemoveFromGraphIndex';
+    }
+    async execute() {
+        // Remove verb from graph index
+        await this.index.removeVerb(this.verb.id);
+        // Return rollback action
+        return async () => {
+            // Re-add verb with original data
+            await this.index.addVerb(this.verb);
+        };
+    }
+}
+/**
+ * Batch operation: Add multiple items to HNSW index
+ *
+ * Useful for bulk imports with transaction support.
+ * Rolls back all items if any fail.
+ */
+export class BatchAddToHNSWOperation {
+    constructor(index, items) {
+        this.name = 'BatchAddToHNSW';
+        this.operations = items.map(item => new AddToHNSWOperation(index, item.id, item.vector));
+    }
+    async execute() {
+        const rollbackActions = [];
+        // Execute all operations
+        for (const op of this.operations) {
+            const rollback = await op.execute();
+            if (rollback) {
+                rollbackActions.push(rollback);
+            }
+        }
+        // Return combined rollback action
+        return async () => {
+            // Execute all rollbacks in reverse order
+            for (let i = rollbackActions.length - 1; i >= 0; i--) {
+                await rollbackActions[i]();
+            }
+        };
+    }
+}
+/**
+ * Batch operation: Add multiple entities to metadata index
+ *
+ * Useful for bulk imports with transaction support.
+ */
+export class BatchAddToMetadataIndexOperation {
+    constructor(index, items) {
+        this.name = 'BatchAddToMetadataIndex';
+        this.operations = items.map(item => new AddToMetadataIndexOperation(index, item.id, item.entity));
+    }
+    async execute() {
+        const rollbackActions = [];
+        // Execute all operations
+        for (const op of this.operations) {
+            const rollback = await op.execute();
+            if (rollback) {
+                rollbackActions.push(rollback);
+            }
+        }
+        // Return combined rollback action
+        return async () => {
+            // Execute all rollbacks in reverse order
+            for (let i = rollbackActions.length - 1; i >= 0; i--) {
+                await rollbackActions[i]();
+            }
+        };
+    }
+}
+//# sourceMappingURL=IndexOperations.js.map