@unrdf/kgc-runtime 26.4.2

package/test/receipt.test.mjs

@@ -0,0 +1,295 @@
+/**
+ * @fileoverview Tests for Receipt generation, validation, and storage
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  generateReceipt,
+  verifyReceiptHash,
+  verifyReceiptChain,
+  ReceiptStore,
+} from '../src/receipt.mjs';
+
+const TEST_RECEIPT_DIR = './var/kgc/receipts-test';
+
+describe('Receipt Generation and Validation', () => {
+  describe('generateReceipt', () => {
+    it('should generate valid receipt with hash', async () => {
+      const receipt = await generateReceipt(
+        'test_operation',
+        { input1: 'value1' },
+        { output1: 'result1' }
+      );
+
+      expect(receipt).toHaveProperty('id');
+      expect(receipt).toHaveProperty('hash');
+      expect(receipt).toHaveProperty('timestamp');
+      expect(receipt.operation).toBe('test_operation');
+      expect(receipt.inputs).toEqual({ input1: 'value1' });
+      expect(receipt.outputs).toEqual({ output1: 'result1' });
+      expect(receipt.hash).toMatch(/^[a-f0-9]{64}$/);
+    });
+
+    it('should generate receipt with parent hash for chaining', async () => {
+      const parentReceipt = await generateReceipt(
+        'parent_op',
+        { a: 1 },
+        { b: 2 }
+      );
+
+      const childReceipt = await generateReceipt(
+        'child_op',
+        { c: 3 },
+        { d: 4 },
+        parentReceipt.hash
+      );
+
+      expect(childReceipt.parentHash).toBe(parentReceipt.hash);
+    });
+
+    it('should produce deterministic hash for same inputs', async () => {
+      const receipt1 = await generateReceipt(
+        'op',
+        { x: 1 },
+        { y: 2 }
+      );
+
+      const receipt2 = await generateReceipt(
+        'op',
+        { x: 1 },
+        { y: 2 }
+      );
+
+      // Different IDs and timestamps, but operation data is same
+      expect(receipt1.id).not.toBe(receipt2.id);
+    });
+  });
+
+  describe('verifyReceiptHash', () => {
+    it('should verify valid receipt hash', async () => {
+      const receipt = await generateReceipt(
+        'verify_test',
+        { test: 'data' },
+        { result: 'success' }
+      );
+
+      const isValid = await verifyReceiptHash(receipt);
+      expect(isValid).toBe(true);
+    });
+
+    it('should reject tampered receipt', async () => {
+      const receipt = await generateReceipt(
+        'tamper_test',
+        { data: 'original' },
+        { result: 'ok' }
+      );
+
+      // Tamper with output
+      receipt.outputs.result = 'tampered';
+
+      const isValid = await verifyReceiptHash(receipt);
+      expect(isValid).toBe(false);
+    });
+  });
+
+  describe('verifyReceiptChain', () => {
+    it('should verify valid chain of receipts', async () => {
+      const receipt1 = await generateReceipt('op1', { a: 1 }, { b: 2 });
+      const receipt2 = await generateReceipt('op2', { c: 3 }, { d: 4 }, receipt1.hash);
+      const receipt3 = await generateReceipt('op3', { e: 5 }, { f: 6 }, receipt2.hash);
+
+      const { valid, errors } = await verifyReceiptChain([receipt1, receipt2, receipt3]);
+
+      expect(valid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should detect broken chain linkage', async () => {
+      const receipt1 = await generateReceipt('op1', { a: 1 }, { b: 2 });
+      const receipt2 = await generateReceipt('op2', { c: 3 }, { d: 4 }, 'wrong_hash');
+
+      const { valid, errors } = await verifyReceiptChain([receipt1, receipt2]);
+
+      expect(valid).toBe(false);
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors[0]).toContain('invalid parent hash');
+    });
+  });
+});
+
+describe('ReceiptStore', () => {
+  let store;
+
+  beforeEach(() => {
+    // Clean up test directory
+    if (existsSync(TEST_RECEIPT_DIR)) {
+      rmSync(TEST_RECEIPT_DIR, { recursive: true, force: true });
+    }
+    mkdirSync(TEST_RECEIPT_DIR, { recursive: true });
+    store = new ReceiptStore(TEST_RECEIPT_DIR);
+  });
+
+  afterEach(() => {
+    // Clean up after tests
+    if (existsSync(TEST_RECEIPT_DIR)) {
+      rmSync(TEST_RECEIPT_DIR, { recursive: true, force: true });
+    }
+  });
+
+  describe('save and load', () => {
+    it('should save and load receipt', async () => {
+      const receipt = await generateReceipt(
+        'save_test',
+        { input: 'test' },
+        { output: 'result' }
+      );
+
+      const savedPath = await store.save(receipt);
+      expect(existsSync(savedPath)).toBe(true);
+
+      const loaded = await store.load(receipt.id);
+      expect(loaded).toEqual(receipt);
+    });
+
+    it('should return null for non-existent receipt', async () => {
+      const loaded = await store.load('non_existent_id');
+      expect(loaded).toBeNull();
+    });
+
+    it('should update manifest on save', async () => {
+      const receipt = await generateReceipt(
+        'manifest_test',
+        { a: 1 },
+        { b: 2 }
+      );
+
+      await store.save(receipt);
+
+      const manifestPath = join(TEST_RECEIPT_DIR, 'manifest.json');
+      expect(existsSync(manifestPath)).toBe(true);
+
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+      expect(manifest.receipts).toHaveLength(1);
+      expect(manifest.receipts[0].id).toBe(receipt.id);
+      expect(manifest.receipts[0].hash).toBe(receipt.hash);
+    });
+  });
+
+  describe('list', () => {
+    it('should list all stored receipts', async () => {
+      const receipts = [
+        await generateReceipt('op1', { a: 1 }, { b: 2 }),
+        await generateReceipt('op2', { c: 3 }, { d: 4 }),
+        await generateReceipt('op3', { e: 5 }, { f: 6 }),
+      ];
+
+      for (const receipt of receipts) {
+        await store.save(receipt);
+      }
+
+      const listed = await store.list();
+      expect(listed).toHaveLength(3);
+
+      const ids = listed.map((r) => r.id);
+      expect(ids).toContain(receipts[0].id);
+      expect(ids).toContain(receipts[1].id);
+      expect(ids).toContain(receipts[2].id);
+    });
+
+    it('should return empty array when no receipts exist', async () => {
+      const listed = await store.list();
+      expect(listed).toEqual([]);
+    });
+  });
+
+  describe('loadChain', () => {
+    it('should load full receipt chain', async () => {
+      const r1 = await generateReceipt('op1', { a: 1 }, { b: 2 });
+      await store.save(r1);
+
+      const r2 = await generateReceipt('op2', { c: 3 }, { d: 4 }, r1.hash);
+      await store.save(r2);
+
+      const r3 = await generateReceipt('op3', { e: 5 }, { f: 6 }, r2.hash);
+      await store.save(r3);
+
+      const chain = await store.loadChain(r3.id);
+
+      expect(chain).toHaveLength(3);
+      expect(chain[0].id).toBe(r1.id);
+      expect(chain[1].id).toBe(r2.id);
+      expect(chain[2].id).toBe(r3.id);
+    });
+
+    it('should handle single receipt (no chain)', async () => {
+      const receipt = await generateReceipt('single', { x: 1 }, { y: 2 });
+      await store.save(receipt);
+
+      const chain = await store.loadChain(receipt.id);
+
+      expect(chain).toHaveLength(1);
+      expect(chain[0].id).toBe(receipt.id);
+    });
+  });
+
+  describe('delete', () => {
+    it('should delete receipt and update manifest', async () => {
+      const receipt = await generateReceipt('delete_test', { a: 1 }, { b: 2 });
+      await store.save(receipt);
+
+      const deleted = await store.delete(receipt.id);
+      expect(deleted).toBe(true);
+
+      const loaded = await store.load(receipt.id);
+      expect(loaded).toBeNull();
+
+      // Check manifest
+      const manifestPath = join(TEST_RECEIPT_DIR, 'manifest.json');
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+      expect(manifest.receipts).toHaveLength(0);
+    });
+
+    it('should return false when deleting non-existent receipt', async () => {
+      const deleted = await store.delete('non_existent');
+      expect(deleted).toBe(false);
+    });
+  });
+
+  describe('integration', () => {
+    it('should handle multiple receipts with chains', async () => {
+      // Create chain 1
+      const c1r1 = await generateReceipt('chain1_op1', { a: 1 }, { b: 2 });
+      await store.save(c1r1);
+
+      const c1r2 = await generateReceipt('chain1_op2', { c: 3 }, { d: 4 }, c1r1.hash);
+      await store.save(c1r2);
+
+      // Create chain 2
+      const c2r1 = await generateReceipt('chain2_op1', { e: 5 }, { f: 6 });
+      await store.save(c2r1);
+
+      const c2r2 = await generateReceipt('chain2_op2', { g: 7 }, { h: 8 }, c2r1.hash);
+      await store.save(c2r2);
+
+      // List all
+      const all = await store.list();
+      expect(all).toHaveLength(4);
+
+      // Load chains
+      const chain1 = await store.loadChain(c1r2.id);
+      const chain2 = await store.loadChain(c2r2.id);
+
+      expect(chain1).toHaveLength(2);
+      expect(chain2).toHaveLength(2);
+
+      // Verify chains
+      const verify1 = await verifyReceiptChain(chain1);
+      const verify2 = await verifyReceiptChain(chain2);
+
+      expect(verify1.valid).toBe(true);
+      expect(verify2.valid).toBe(true);
+    });
+  });
+});

package/test/rollback.test.mjs

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview Tests for Rollback Event Log System
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { RollbackLog } from '../src/rollback.mjs';
+import { promises as fs } from 'fs';
+import path from 'path';
+
+const TEST_LOG_PATH = './var/kgc/test-undo-log.json';
+
+describe('RollbackLog', () => {
+  let rollbackLog;
+
+  beforeEach(async () => {
+    rollbackLog = new RollbackLog(TEST_LOG_PATH);
+    // Clear any existing log
+    try {
+      await fs.unlink(TEST_LOG_PATH);
+    } catch (error) {
+      // File doesn't exist - that's fine
+    }
+  });
+
+  afterEach(async () => {
+    // Cleanup
+    try {
+      await fs.unlink(TEST_LOG_PATH);
+    } catch (error) {
+      // Ignore cleanup errors
+    }
+  });
+
+  it('should append and retrieve undo log entries', async () => {
+    const txId = 'tx_test_001';
+    const operations = [
+      { id: 'op1', type: 'add_capsule', data: { id: 'c1' } },
+      { id: 'op2', type: 'add_capsule', data: { id: 'c2' } },
+    ];
+
+    // Append entry
+    const entry = await rollbackLog.append(txId, operations, 'hash123');
+
+    expect(entry.transaction_id).toBe(txId);
+    expect(entry.operations).toHaveLength(2);
+    expect(entry.hash).toBe('hash123');
+    expect(entry.timestamp).toBeDefined();
+
+    // Retrieve entry
+    const retrieved = await rollbackLog.getByTransactionId(txId);
+
+    expect(retrieved).toBeDefined();
+    expect(retrieved.transaction_id).toBe(txId);
+    expect(retrieved.operations).toHaveLength(2);
+
+    // Verify persistence
+    const newLog = new RollbackLog(TEST_LOG_PATH);
+    const persistedEntry = await newLog.getByTransactionId(txId);
+
+    expect(persistedEntry).toBeDefined();
+    expect(persistedEntry.transaction_id).toBe(txId);
+  });
+
+  it('should replay undo operations in correct order', async () => {
+    const txId = 'tx_replay_001';
+    const operations = [
+      { id: 'op1', type: 'remove_capsule', data: { capsule_id: 'c1' } },
+      { id: 'op2', type: 'remove_capsule', data: { capsule_id: 'c2' } },
+      { id: 'op3', type: 'remove_capsule', data: { capsule_id: 'c3' } },
+    ];
+
+    await rollbackLog.append(txId, operations);
+
+    // Track applied operations
+    const applied = [];
+    const applyOp = async (op) => {
+      applied.push(op.id);
+    };
+
+    // Replay
+    const result = await rollbackLog.replay(txId, applyOp);
+
+    expect(result.success).toBe(true);
+    expect(result.operations_applied).toBe(3);
+    expect(result.errors).toHaveLength(0);
+
+    // Verify operations applied in reverse order
+    expect(applied).toEqual(['op3', 'op2', 'op1']);
+  });
+
+  it('should manage multiple log entries and provide statistics', async () => {
+    // Add multiple entries
+    await rollbackLog.append('tx_001', [{ id: 'op1', type: 'add_capsule', data: {} }]);
+
+    // Wait a bit to ensure different timestamps
+    await new Promise(resolve => setTimeout(resolve, 10));
+
+    await rollbackLog.append('tx_002', [{ id: 'op2', type: 'add_capsule', data: {} }]);
+
+    await new Promise(resolve => setTimeout(resolve, 10));
+
+    await rollbackLog.append('tx_003', [
+      { id: 'op3', type: 'add_capsule', data: {} },
+      { id: 'op4', type: 'add_capsule', data: {} },
+    ]);
+
+    // Get all entries
+    const allEntries = await rollbackLog.getAll();
+    expect(allEntries).toHaveLength(3);
+
+    // Get statistics
+    const stats = await rollbackLog.getStats();
+    expect(stats.total).toBe(3);
+    expect(stats.oldest).toBeDefined();
+    expect(stats.newest).toBeDefined();
+    expect(new Date(stats.newest).getTime()).toBeGreaterThanOrEqual(
+      new Date(stats.oldest).getTime()
+    );
+
+    // Get by time range
+    const start = new Date(stats.oldest);
+    const end = new Date(stats.newest);
+
+    const rangeEntries = await rollbackLog.getByTimeRange(start, end);
+    expect(rangeEntries).toHaveLength(3);
+
+    // Clear log
+    await rollbackLog.clear();
+    const clearedStats = await rollbackLog.getStats();
+    expect(clearedStats.total).toBe(0);
+  });
+});

package/test/saga-orchestrator.test.mjs

@@ -0,0 +1,279 @@
+/**
+ * Tests for Saga Pattern - Distributed Transactions
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  SagaOrchestrator,
+  createSagaStep,
+  createSagaBuilder,
+} from '../src/saga-orchestrator.mjs';
+
+describe('Saga Pattern - Distributed Transactions', () => {
+  describe('SagaOrchestrator', () => {
+    it('should execute saga steps sequentially', async () => {
+      const executionOrder = [];
+
+      const step1 = createSagaStep(
+        'step1',
+        'first',
+        async (ctx) => {
+          executionOrder.push('step1-execute');
+          return { ...ctx, step1: 'done' };
+        },
+        async () => {
+          executionOrder.push('step1-compensate');
+        }
+      );
+
+      const step2 = createSagaStep(
+        'step2',
+        'second',
+        async (ctx) => {
+          executionOrder.push('step2-execute');
+          return { ...ctx, step2: 'done' };
+        },
+        async () => {
+          executionOrder.push('step2-compensate');
+        }
+      );
+
+      const saga = new SagaOrchestrator({
+        id: 'test-saga',
+        name: 'Test Saga',
+        steps: [step1, step2],
+      });
+
+      const result = await saga.execute({ initial: 'data' });
+
+      expect(result.success).toBe(true);
+      expect(result.result.step1).toBe('done');
+      expect(result.result.step2).toBe('done');
+      expect(executionOrder).toEqual(['step1-execute', 'step2-execute']);
+    });
+
+    it('should execute saga steps in parallel', async () => {
+      const executionTimes = {};
+
+      const step1 = createSagaStep(
+        'step1',
+        'parallel1',
+        async () => {
+          const start = Date.now();
+          await new Promise(resolve => setTimeout(resolve, 50));
+          executionTimes.step1 = Date.now() - start;
+          return 'step1-result';
+        },
+        async () => {}
+      );
+
+      const step2 = createSagaStep(
+        'step2',
+        'parallel2',
+        async () => {
+          const start = Date.now();
+          await new Promise(resolve => setTimeout(resolve, 50));
+          executionTimes.step2 = Date.now() - start;
+          return 'step2-result';
+        },
+        async () => {}
+      );
+
+      const saga = new SagaOrchestrator({
+        id: 'parallel-saga',
+        name: 'Parallel Saga',
+        steps: [step1, step2],
+        parallel: true,
+      });
+
+      const startTime = Date.now();
+      const result = await saga.execute();
+      const totalTime = Date.now() - startTime;
+
+      expect(result.success).toBe(true);
+      expect(result.result.parallel1).toBe('step1-result');
+      expect(result.result.parallel2).toBe('step2-result');
+      // Total time should be ~50ms (parallel) not ~100ms (sequential)
+      expect(totalTime).toBeLessThan(100);
+    });
+
+    it('should compensate on failure (sequential)', async () => {
+      const compensated = [];
+
+      const step1 = createSagaStep(
+        'step1',
+        'first',
+        async () => 'step1-done',
+        async () => {
+          compensated.push('step1');
+        }
+      );
+
+      const step2 = createSagaStep(
+        'step2',
+        'second',
+        async () => {
+          throw new Error('Step 2 failed');
+        },
+        async () => {
+          compensated.push('step2');
+        }
+      );
+
+      const step3 = createSagaStep(
+        'step3',
+        'third',
+        async () => 'step3-done',
+        async () => {
+          compensated.push('step3');
+        }
+      );
+
+      const saga = new SagaOrchestrator({
+        id: 'compensate-saga',
+        name: 'Compensate Saga',
+        steps: [step1, step2, step3],
+      });
+
+      const result = await saga.execute();
+
+      expect(result.success).toBe(false);
+      expect(result.state.status).toBe('compensated');
+      expect(result.state.completedSteps).toHaveLength(1); // Only step1 completed
+      expect(compensated).toEqual(['step1']); // Compensate in reverse
+    });
+
+    it('should retry failed steps', async () => {
+      let attempts = 0;
+
+      const step = createSagaStep(
+        'retry-step',
+        'retry',
+        async () => {
+          attempts++;
+          if (attempts < 3) {
+            throw new Error('Not yet');
+          }
+          return 'success';
+        },
+        async () => {},
+        { retryable: true, maxRetries: 3 }
+      );
+
+      const saga = new SagaOrchestrator({
+        id: 'retry-saga',
+        name: 'Retry Saga',
+        steps: [step],
+      });
+
+      const result = await saga.execute();
+
+      expect(result.success).toBe(true);
+      expect(attempts).toBe(3);
+    });
+
+    it('should not retry non-retryable steps', async () => {
+      let attempts = 0;
+
+      const step = createSagaStep(
+        'no-retry-step',
+        'noretry',
+        async () => {
+          attempts++;
+          throw new Error('Fail immediately');
+        },
+        async () => {},
+        { retryable: false }
+      );
+
+      const saga = new SagaOrchestrator({
+        id: 'no-retry-saga',
+        name: 'No Retry Saga',
+        steps: [step],
+      });
+
+      const result = await saga.execute();
+
+      expect(result.success).toBe(false);
+      expect(attempts).toBe(1);
+    });
+
+    it('should track saga execution state', async () => {
+      const step = createSagaStep(
+        'step1',
+        'track',
+        async () => 'result',
+        async () => {}
+      );
+
+      const saga = new SagaOrchestrator({
+        id: 'track-saga',
+        name: 'Track Saga',
+        steps: [step],
+      });
+
+      const result = await saga.execute();
+      const states = saga.getAllStates();
+
+      expect(states).toHaveLength(1);
+      expect(states[0].status).toBe('completed');
+      expect(states[0].completedSteps).toHaveLength(1);
+      expect(states[0].startTime).toBeDefined();
+      expect(states[0].endTime).toBeDefined();
+    });
+
+    it('should generate receipt for saga execution', async () => {
+      const step = createSagaStep(
+        'step1',
+        'receipt',
+        async () => 'done',
+        async () => {}
+      );
+
+      const saga = new SagaOrchestrator({
+        id: 'receipt-saga',
+        name: 'Receipt Saga',
+        steps: [step],
+      });
+
+      const result = await saga.execute();
+      const states = saga.getAllStates();
+      const receipt = await saga.generateReceipt(states[0].sagaId);
+
+      expect(receipt.operation).toContain('saga:Receipt Saga');
+      expect(receipt.outputs.success).toBe(true);
+      expect(receipt.outputs.completedSteps).toBe(1);
+    });
+  });
+
+  describe('createSagaBuilder', () => {
+    it('should build saga with fluent API', () => {
+      const saga = createSagaBuilder('builder-saga', 'Builder Saga')
+        .step(createSagaStep('s1', 'step1', async () => 1, async () => {}))
+        .step(createSagaStep('s2', 'step2', async () => 2, async () => {}))
+        .build();
+
+      expect(saga).toBeInstanceOf(SagaOrchestrator);
+      expect(saga.config.id).toBe('builder-saga');
+      expect(saga.config.steps).toHaveLength(2);
+    });
+
+    it('should support parallel execution flag', () => {
+      const saga = createSagaBuilder('parallel-builder', 'Parallel')
+        .step(createSagaStep('s1', 'step1', async () => 1, async () => {}))
+        .inParallel()
+        .build();
+
+      expect(saga.config.parallel).toBe(true);
+    });
+
+    it('should support continueOnError flag', () => {
+      const saga = createSagaBuilder('continue-builder', 'Continue')
+        .step(createSagaStep('s1', 'step1', async () => 1, async () => {}))
+        .continueOnError()
+        .build();
+
+      expect(saga.config.continueOnError).toBe(true);
+    });
+  });
+});