@soulcraft/brainy 5.7.13 → 5.9.0

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

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

@@ -0,0 +1,128 @@
+/**
+ * Storage Operations with Rollback Support
+ *
+ * Provides transactional operations for all storage adapters.
+ * Each operation can be executed and rolled back atomically.
+ *
+ * Supports:
+ * - All 8 storage adapters (FileSystem, S3, Memory, OPFS, GCS, Azure, R2, TypeAware)
+ * - Nouns (entities) and Verbs (relationships)
+ * - Metadata and vector data
+ * - COW (Copy-on-Write) storage
+ */
+import type { StorageAdapter, HNSWNoun, HNSWVerb, NounMetadata, VerbMetadata } from '../../coreTypes.js';
+import type { Operation, RollbackAction } from '../types.js';
+/**
+ * Save noun metadata with rollback support
+ *
+ * Rollback strategy:
+ * - If metadata existed: Restore previous metadata
+ * - If metadata was new: Delete metadata
+ */
+export declare class SaveNounMetadataOperation implements Operation {
+    private readonly storage;
+    private readonly id;
+    private readonly metadata;
+    readonly name = "SaveNounMetadata";
+    constructor(storage: StorageAdapter, id: string, metadata: NounMetadata);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Save noun (vector data) with rollback support
+ *
+ * Rollback strategy:
+ * - If noun existed: Restore previous noun
+ * - If noun was new: Delete noun (if deleteNoun exists on adapter)
+ *
+ * Note: Not all adapters implement deleteNoun - this is acceptable
+ * because orphaned vector data without metadata is invisible to queries
+ */
+export declare class SaveNounOperation implements Operation {
+    private readonly storage;
+    private readonly noun;
+    readonly name = "SaveNoun";
+    constructor(storage: StorageAdapter, noun: HNSWNoun);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Delete noun metadata with rollback support
+ *
+ * Rollback strategy:
+ * - Restore deleted metadata
+ */
+export declare class DeleteNounMetadataOperation implements Operation {
+    private readonly storage;
+    private readonly id;
+    readonly name = "DeleteNounMetadata";
+    constructor(storage: StorageAdapter, id: string);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Save verb metadata with rollback support
+ *
+ * Rollback strategy:
+ * - If metadata existed: Restore previous metadata
+ * - If metadata was new: Delete metadata
+ */
+export declare class SaveVerbMetadataOperation implements Operation {
+    private readonly storage;
+    private readonly id;
+    private readonly metadata;
+    readonly name = "SaveVerbMetadata";
+    constructor(storage: StorageAdapter, id: string, metadata: VerbMetadata);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Save verb (vector data) with rollback support
+ *
+ * Rollback strategy:
+ * - If verb existed: Restore previous verb
+ * - If verb was new: Delete verb (if deleteVerb exists on adapter)
+ */
+export declare class SaveVerbOperation implements Operation {
+    private readonly storage;
+    private readonly verb;
+    readonly name = "SaveVerb";
+    constructor(storage: StorageAdapter, verb: HNSWVerb);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Delete verb metadata with rollback support
+ *
+ * Rollback strategy:
+ * - Restore deleted metadata
+ */
+export declare class DeleteVerbMetadataOperation implements Operation {
+    private readonly storage;
+    private readonly id;
+    readonly name = "DeleteVerbMetadata";
+    constructor(storage: StorageAdapter, id: string);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Update noun metadata with rollback support
+ *
+ * Rollback strategy:
+ * - Restore previous metadata
+ *
+ * Note: This is a convenience operation that wraps SaveNounMetadataOperation
+ * with explicit "update" semantics
+ */
+export declare class UpdateNounMetadataOperation implements Operation {
+    readonly name = "UpdateNounMetadata";
+    private saveOperation;
+    constructor(storage: StorageAdapter, id: string, metadata: NounMetadata);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Update verb metadata with rollback support
+ *
+ * Rollback strategy:
+ * - Restore previous metadata
+ */
+export declare class UpdateVerbMetadataOperation implements Operation {
+    readonly name = "UpdateVerbMetadata";
+    private saveOperation;
+    constructor(storage: StorageAdapter, id: string, metadata: VerbMetadata);
+    execute(): Promise<RollbackAction>;
+}

package/dist/transaction/operations/StorageOperations.js

@@ -0,0 +1,253 @@
+/**
+ * Storage Operations with Rollback Support
+ *
+ * Provides transactional operations for all storage adapters.
+ * Each operation can be executed and rolled back atomically.
+ *
+ * Supports:
+ * - All 8 storage adapters (FileSystem, S3, Memory, OPFS, GCS, Azure, R2, TypeAware)
+ * - Nouns (entities) and Verbs (relationships)
+ * - Metadata and vector data
+ * - COW (Copy-on-Write) storage
+ */
+/**
+ * Save noun metadata with rollback support
+ *
+ * Rollback strategy:
+ * - If metadata existed: Restore previous metadata
+ * - If metadata was new: Delete metadata
+ */
+export class SaveNounMetadataOperation {
+    constructor(storage, id, metadata) {
+        this.storage = storage;
+        this.id = id;
+        this.metadata = metadata;
+        this.name = 'SaveNounMetadata';
+    }
+    async execute() {
+        // Get existing metadata (for rollback)
+        const previousMetadata = await this.storage.getNounMetadata(this.id);
+        // Save new metadata
+        await this.storage.saveNounMetadata(this.id, this.metadata);
+        // Return rollback action
+        return async () => {
+            if (previousMetadata) {
+                // Restore previous metadata
+                await this.storage.saveNounMetadata(this.id, previousMetadata);
+            }
+            else {
+                // Delete newly created metadata
+                await this.storage.deleteNounMetadata(this.id);
+            }
+        };
+    }
+}
+/**
+ * Save noun (vector data) with rollback support
+ *
+ * Rollback strategy:
+ * - If noun existed: Restore previous noun
+ * - If noun was new: Delete noun (if deleteNoun exists on adapter)
+ *
+ * Note: Not all adapters implement deleteNoun - this is acceptable
+ * because orphaned vector data without metadata is invisible to queries
+ */
+export class SaveNounOperation {
+    constructor(storage, noun) {
+        this.storage = storage;
+        this.noun = noun;
+        this.name = 'SaveNoun';
+    }
+    async execute() {
+        // Get existing noun (for rollback)
+        const previousNoun = await this.storage.getNoun(this.noun.id);
+        // Save new noun
+        await this.storage.saveNoun(this.noun);
+        // Return rollback action
+        return async () => {
+            if (previousNoun) {
+                // Restore previous noun (extract just vector data)
+                const nounData = {
+                    id: previousNoun.id,
+                    vector: previousNoun.vector,
+                    connections: previousNoun.connections || new Map(),
+                    level: previousNoun.level || 0
+                };
+                await this.storage.saveNoun(nounData);
+            }
+            else {
+                // Delete newly created noun (if adapter supports it)
+                // Note: Not all adapters implement deleteNoun
+                // This is acceptable - metadata deletion makes entity invisible
+                if ('deleteNoun' in this.storage && typeof this.storage.deleteNoun === 'function') {
+                    await this.storage.deleteNoun(this.noun.id);
+                }
+            }
+        };
+    }
+}
+/**
+ * Delete noun metadata with rollback support
+ *
+ * Rollback strategy:
+ * - Restore deleted metadata
+ */
+export class DeleteNounMetadataOperation {
+    constructor(storage, id) {
+        this.storage = storage;
+        this.id = id;
+        this.name = 'DeleteNounMetadata';
+    }
+    async execute() {
+        // Get metadata before deletion (for rollback)
+        const previousMetadata = await this.storage.getNounMetadata(this.id);
+        if (!previousMetadata) {
+            // Nothing to delete - no rollback needed
+            return async () => { };
+        }
+        // Delete metadata
+        await this.storage.deleteNounMetadata(this.id);
+        // Return rollback action
+        return async () => {
+            // Restore deleted metadata
+            await this.storage.saveNounMetadata(this.id, previousMetadata);
+        };
+    }
+}
+/**
+ * Save verb metadata with rollback support
+ *
+ * Rollback strategy:
+ * - If metadata existed: Restore previous metadata
+ * - If metadata was new: Delete metadata
+ */
+export class SaveVerbMetadataOperation {
+    constructor(storage, id, metadata) {
+        this.storage = storage;
+        this.id = id;
+        this.metadata = metadata;
+        this.name = 'SaveVerbMetadata';
+    }
+    async execute() {
+        // Get existing metadata (for rollback)
+        const previousMetadata = await this.storage.getVerbMetadata(this.id);
+        // Save new metadata
+        await this.storage.saveVerbMetadata(this.id, this.metadata);
+        // Return rollback action
+        return async () => {
+            if (previousMetadata) {
+                // Restore previous metadata
+                await this.storage.saveVerbMetadata(this.id, previousMetadata);
+            }
+            else {
+                // Delete newly created verb (metadata + vector)
+                // Note: StorageAdapter has deleteVerb but not deleteVerbMetadata
+                await this.storage.deleteVerb(this.id);
+            }
+        };
+    }
+}
+/**
+ * Save verb (vector data) with rollback support
+ *
+ * Rollback strategy:
+ * - If verb existed: Restore previous verb
+ * - If verb was new: Delete verb (if deleteVerb exists on adapter)
+ */
+export class SaveVerbOperation {
+    constructor(storage, verb) {
+        this.storage = storage;
+        this.verb = verb;
+        this.name = 'SaveVerb';
+    }
+    async execute() {
+        // Get existing verb (for rollback)
+        const previousVerb = await this.storage.getVerb(this.verb.id);
+        // Save new verb
+        await this.storage.saveVerb(this.verb);
+        // Return rollback action
+        return async () => {
+            if (previousVerb) {
+                // Restore previous verb (extract just vector data)
+                const verbData = {
+                    id: previousVerb.id,
+                    sourceId: previousVerb.sourceId,
+                    targetId: previousVerb.targetId,
+                    verb: previousVerb.verb,
+                    vector: previousVerb.vector,
+                    connections: previousVerb.connections || new Map()
+                };
+                await this.storage.saveVerb(verbData);
+            }
+            else {
+                // Delete newly created verb (if adapter supports it)
+                if ('deleteVerb' in this.storage && typeof this.storage.deleteVerb === 'function') {
+                    await this.storage.deleteVerb(this.verb.id);
+                }
+            }
+        };
+    }
+}
+/**
+ * Delete verb metadata with rollback support
+ *
+ * Rollback strategy:
+ * - Restore deleted metadata
+ */
+export class DeleteVerbMetadataOperation {
+    constructor(storage, id) {
+        this.storage = storage;
+        this.id = id;
+        this.name = 'DeleteVerbMetadata';
+    }
+    async execute() {
+        // Get metadata before deletion (for rollback)
+        const previousMetadata = await this.storage.getVerbMetadata(this.id);
+        if (!previousMetadata) {
+            // Nothing to delete - no rollback needed
+            return async () => { };
+        }
+        // Delete verb (metadata + vector)
+        // Note: StorageAdapter has deleteVerb but not deleteVerbMetadata
+        await this.storage.deleteVerb(this.id);
+        // Return rollback action
+        return async () => {
+            // Restore deleted metadata
+            await this.storage.saveVerbMetadata(this.id, previousMetadata);
+        };
+    }
+}
+/**
+ * Update noun metadata with rollback support
+ *
+ * Rollback strategy:
+ * - Restore previous metadata
+ *
+ * Note: This is a convenience operation that wraps SaveNounMetadataOperation
+ * with explicit "update" semantics
+ */
+export class UpdateNounMetadataOperation {
+    constructor(storage, id, metadata) {
+        this.name = 'UpdateNounMetadata';
+        this.saveOperation = new SaveNounMetadataOperation(storage, id, metadata);
+    }
+    async execute() {
+        return await this.saveOperation.execute();
+    }
+}
+/**
+ * Update verb metadata with rollback support
+ *
+ * Rollback strategy:
+ * - Restore previous metadata
+ */
+export class UpdateVerbMetadataOperation {
+    constructor(storage, id, metadata) {
+        this.name = 'UpdateVerbMetadata';
+        this.saveOperation = new SaveVerbMetadataOperation(storage, id, metadata);
+    }
+    async execute() {
+        return await this.saveOperation.execute();
+    }
+}
+//# sourceMappingURL=StorageOperations.js.map

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

@@ -0,0 +1,10 @@
+/**
+ * Transaction Operations
+ *
+ * Re-exports all transactional operations for storage and indexes.
+ * These operations provide atomicity with rollback support.
+ *
+ * @module transaction/operations
+ */
+export { SaveNounMetadataOperation, SaveNounOperation, DeleteNounMetadataOperation, SaveVerbMetadataOperation, SaveVerbOperation, DeleteVerbMetadataOperation, UpdateNounMetadataOperation, UpdateVerbMetadataOperation } from './StorageOperations.js';
+export { AddToHNSWOperation, AddToTypeAwareHNSWOperation, RemoveFromHNSWOperation, RemoveFromTypeAwareHNSWOperation, AddToMetadataIndexOperation, RemoveFromMetadataIndexOperation, AddToGraphIndexOperation, RemoveFromGraphIndexOperation, BatchAddToHNSWOperation, BatchAddToMetadataIndexOperation } from './IndexOperations.js';

package/dist/transaction/operations/index.js

@@ -0,0 +1,13 @@
+/**
+ * Transaction Operations
+ *
+ * Re-exports all transactional operations for storage and indexes.
+ * These operations provide atomicity with rollback support.
+ *
+ * @module transaction/operations
+ */
+// Storage Operations
+export { SaveNounMetadataOperation, SaveNounOperation, DeleteNounMetadataOperation, SaveVerbMetadataOperation, SaveVerbOperation, DeleteVerbMetadataOperation, UpdateNounMetadataOperation, UpdateVerbMetadataOperation } from './StorageOperations.js';
+// Index Operations
+export { AddToHNSWOperation, AddToTypeAwareHNSWOperation, RemoveFromHNSWOperation, RemoveFromTypeAwareHNSWOperation, AddToMetadataIndexOperation, RemoveFromMetadataIndexOperation, AddToGraphIndexOperation, RemoveFromGraphIndexOperation, BatchAddToHNSWOperation, BatchAddToMetadataIndexOperation } from './IndexOperations.js';
+//# sourceMappingURL=index.js.map