@soulcraft/brainy 5.7.13 → 5.8.0

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

package/dist/transaction/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Transaction System Types
+ *
+ * Provides atomicity for Brainy operations - all succeed or all rollback.
+ * Prevents partial failures that leave system in inconsistent state.
+ */
+/**
+ * Transaction state
+ */
+export type TransactionState = 'pending' | 'executing' | 'committed' | 'rolling_back' | 'rolled_back';
+/**
+ * Rollback action - undoes an operation
+ * Must be idempotent (safe to call multiple times)
+ */
+export type RollbackAction = () => Promise<void>;
+/**
+ * Operation that can be executed and rolled back
+ */
+export interface Operation {
+    /**
+     * Execute the operation
+     * @returns Rollback action to undo this operation (or undefined if no rollback needed)
+     */
+    execute(): Promise<RollbackAction | undefined>;
+    /**
+     * Optional: Name of operation for debugging
+     */
+    readonly name?: string;
+}
+/**
+ * Transaction context passed to user functions
+ */
+export interface TransactionContext {
+    /**
+     * Add an operation to the transaction
+     */
+    addOperation(operation: Operation): void;
+    /**
+     * Get current transaction state
+     */
+    getState(): TransactionState;
+    /**
+     * Get number of operations in transaction
+     */
+    getOperationCount(): number;
+}
+/**
+ * Function that builds a transaction
+ */
+export type TransactionFunction<T> = (ctx: TransactionContext) => Promise<T>;
+/**
+ * Transaction execution result
+ */
+export interface TransactionResult<T> {
+    /**
+     * Result value from user function
+     */
+    value: T;
+    /**
+     * Number of operations executed
+     */
+    operationCount: number;
+    /**
+     * Execution time in milliseconds
+     */
+    executionTimeMs: number;
+}
+/**
+ * Transaction execution options
+ */
+export interface TransactionOptions {
+    /**
+     * Timeout in milliseconds (default: 30000 = 30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Whether to log transaction execution (default: false)
+     */
+    logging?: boolean;
+    /**
+     * Maximum number of rollback retry attempts (default: 3)
+     */
+    maxRollbackRetries?: number;
+}

package/dist/transaction/types.js

@@ -0,0 +1,8 @@
+/**
+ * Transaction System Types
+ *
+ * Provides atomicity for Brainy operations - all succeed or all rollback.
+ * Prevents partial failures that leave system in inconsistent state.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

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