@unrdf/kgc-runtime 26.4.2

package/test/crdt.test.mjs

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview Tests for CRDT (Conflict-free Replicated Data Types)
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  createTimestamp,
+  compareTimestamps,
+  createLWWRegister,
+  updateLWWRegister,
+  mergeLWWRegisters,
+  threeWayMergeLWW,
+  createORSet,
+  addToORSet,
+  removeFromORSet,
+  getORSetValues,
+  mergeORSets,
+  threeWayMergeORSet,
+} from '../src/crdt.mjs';
+
+describe('CRDT - Timestamps', () => {
+  it('should create and compare timestamps correctly', () => {
+    const t1 = createTimestamp(1, 'actor1');
+    const t2 = createTimestamp(2, 'actor1');
+    const t3 = createTimestamp(1, 'actor2');
+
+    expect(compareTimestamps(t1, t2)).toBeLessThan(0); // t1 < t2
+    expect(compareTimestamps(t2, t1)).toBeGreaterThan(0); // t2 > t1
+    expect(compareTimestamps(t1, t1)).toBe(0); // t1 == t1
+
+    // Same counter, different actor - lexicographic comparison
+    const cmp = compareTimestamps(t1, t3);
+    expect(cmp).toBe('actor1'.localeCompare('actor2'));
+  });
+});
+
+describe('CRDT - LWW-Register', () => {
+  it('should create and update LWW-Register', () => {
+    const t1 = createTimestamp(1, 'agent1');
+    const reg1 = createLWWRegister('initial value', t1);
+
+    expect(reg1.value).toBe('initial value');
+    expect(reg1.timestamp).toEqual(t1);
+
+    // Update with later timestamp
+    const t2 = createTimestamp(2, 'agent1');
+    const reg2 = updateLWWRegister(reg1, 'updated value', t2);
+
+    expect(reg2.value).toBe('updated value');
+    expect(reg2.timestamp).toEqual(t2);
+
+    // Update with earlier timestamp (should be ignored)
+    const t0 = createTimestamp(0, 'agent1');
+    const reg3 = updateLWWRegister(reg2, 'old value', t0);
+
+    expect(reg3.value).toBe('updated value'); // Not changed
+    expect(reg3.timestamp).toEqual(t2);
+  });
+
+  it('should merge LWW-Registers with last-write-wins semantics', () => {
+    const t1 = createTimestamp(1, 'agent1');
+    const t2 = createTimestamp(2, 'agent2');
+
+    const reg1 = createLWWRegister('value from agent1', t1);
+    const reg2 = createLWWRegister('value from agent2', t2);
+
+    // Merge - later timestamp wins
+    const merged = mergeLWWRegisters(reg1, reg2);
+
+    expect(merged.value).toBe('value from agent2');
+    expect(merged.timestamp).toEqual(t2);
+
+    // Merge in opposite order - result should be same
+    const merged2 = mergeLWWRegisters(reg2, reg1);
+
+    expect(merged2.value).toBe('value from agent2');
+    expect(merged2.timestamp).toEqual(t2);
+  });
+
+  it('should perform three-way merge with common ancestor', () => {
+    const t0 = createTimestamp(0, 'agent0');
+    const t1 = createTimestamp(1, 'agent1');
+    const t2 = createTimestamp(2, 'agent2');
+
+    const ancestor = createLWWRegister('original', t0);
+    const left = createLWWRegister('left edit', t1);
+    const right = createLWWRegister('right edit', t2);
+
+    // Both branches modified - use LWW
+    const merged = threeWayMergeLWW(ancestor, left, right);
+
+    expect(merged.value).toBe('right edit'); // Later timestamp wins
+
+    // Only one branch modified
+    const merged2 = threeWayMergeLWW(ancestor, left, ancestor);
+    expect(merged2.value).toBe('left edit'); // Left branch wins
+
+    const merged3 = threeWayMergeLWW(ancestor, ancestor, right);
+    expect(merged3.value).toBe('right edit'); // Right branch wins
+
+    // No changes
+    const merged4 = threeWayMergeLWW(ancestor, ancestor, ancestor);
+    expect(merged4.value).toBe('original'); // No changes
+  });
+});
+
+describe('CRDT - OR-Set', () => {
+  it('should add and retrieve elements from OR-Set', () => {
+    let set = createORSet();
+    expect(getORSetValues(set)).toHaveLength(0);
+
+    // Add elements
+    const t1 = createTimestamp(1, 'agent1');
+    set = addToORSet(set, 'apple', t1);
+
+    const t2 = createTimestamp(2, 'agent1');
+    set = addToORSet(set, 'banana', t2);
+
+    const values = getORSetValues(set);
+    expect(values).toHaveLength(2);
+    expect(values).toContain('apple');
+    expect(values).toContain('banana');
+  });
+
+  it('should remove elements from OR-Set', () => {
+    let set = createORSet();
+
+    const t1 = createTimestamp(1, 'agent1');
+    set = addToORSet(set, 'item1', t1);
+
+    const t2 = createTimestamp(2, 'agent1');
+    set = addToORSet(set, 'item2', t2);
+
+    expect(getORSetValues(set)).toHaveLength(2);
+
+    // Remove item1
+    const t3 = createTimestamp(3, 'agent1');
+    set = removeFromORSet(set, 'item1', t3);
+
+    const values = getORSetValues(set);
+    expect(values).toHaveLength(1);
+    expect(values).toContain('item2');
+    expect(values).not.toContain('item1');
+  });
+
+  it('should merge OR-Sets correctly', () => {
+    // Agent1's set
+    let set1 = createORSet();
+    const t1 = createTimestamp(1, 'agent1');
+    set1 = addToORSet(set1, 'apple', t1);
+    const t2 = createTimestamp(2, 'agent1');
+    set1 = addToORSet(set1, 'banana', t2);
+
+    // Agent2's set
+    let set2 = createORSet();
+    const t3 = createTimestamp(1, 'agent2');
+    set2 = addToORSet(set2, 'cherry', t3);
+    const t4 = createTimestamp(2, 'agent2');
+    set2 = addToORSet(set2, 'banana', t4); // Also adds banana
+
+    // Merge sets
+    const merged = mergeORSets(set1, set2);
+    const values = getORSetValues(merged);
+
+    expect(values).toHaveLength(3);
+    expect(values).toContain('apple');
+    expect(values).toContain('banana');
+    expect(values).toContain('cherry');
+
+    // Test concurrent add/remove
+    let set3 = createORSet();
+    const t5 = createTimestamp(1, 'agent3');
+    set3 = addToORSet(set3, 'item', t5);
+    const t6 = createTimestamp(2, 'agent3');
+    set3 = removeFromORSet(set3, 'item', t6);
+
+    let set4 = createORSet();
+    const t7 = createTimestamp(3, 'agent4');
+    set4 = addToORSet(set4, 'item', t7); // Re-add after removal
+
+    const merged2 = mergeORSets(set3, set4);
+    const values2 = getORSetValues(merged2);
+
+    // Item should be present (re-added after remove)
+    expect(values2).toContain('item');
+  });
+
+  it('should perform three-way merge for OR-Sets', () => {
+    // Ancestor
+    let ancestor = createORSet();
+    const t0 = createTimestamp(0, 'agent0');
+    ancestor = addToORSet(ancestor, 'original', t0);
+
+    // Left branch - adds 'left'
+    let left = createORSet();
+    left = addToORSet(left, 'original', t0);
+    const t1 = createTimestamp(1, 'agent1');
+    left = addToORSet(left, 'left', t1);
+
+    // Right branch - adds 'right'
+    let right = createORSet();
+    right = addToORSet(right, 'original', t0);
+    const t2 = createTimestamp(1, 'agent2');
+    right = addToORSet(right, 'right', t2);
+
+    // Three-way merge
+    const merged = threeWayMergeORSet(ancestor, left, right);
+    const values = getORSetValues(merged);
+
+    expect(values).toHaveLength(3);
+    expect(values).toContain('original');
+    expect(values).toContain('left');
+    expect(values).toContain('right');
+  });
+});

package/test/enhanced-bounds.test.mjs

@@ -0,0 +1,487 @@
+/**
+ * @file Enhanced bounds tests - Soft limits, quotas, rate limiting
+ */
+
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { EnhancedBoundsChecker } from '../src/enhanced-bounds.mjs';
+
+// =============================================================================
+// Soft Limits Tests
+// =============================================================================
+
+describe('Enhanced Bounds - Soft Limits', () => {
+  /** @type {EnhancedBoundsChecker} */
+  let checker;
+
+  beforeEach(() => {
+    checker = new EnhancedBoundsChecker({
+      max_files_touched: 100,
+      max_bytes_changed: 10000,
+      max_tool_ops: 1000,
+      warnings: {
+        filesThreshold: 0.8,
+        bytesThreshold: 0.9,
+        opsThreshold: 0.75,
+      },
+    });
+  });
+
+  it('should emit warning receipt at 80% threshold', async () => {
+    // Use 80 files (80% of 100)
+    const receipt = await checker.checkAndRecord({
+      type: 'file_touch',
+      files: 80,
+    });
+
+    assert.equal(receipt.admit, true);
+    assert.equal(receipt.warnings.length, 1);
+    assert.equal(receipt.warnings[0].type, 'warning');
+    assert.match(receipt.warnings[0].message, /80%/);
+  });
+
+  it('should emit error receipt at 100% threshold', async () => {
+    // Use 100 files (100% of 100)
+    const receipt = await checker.checkAndRecord({
+      type: 'file_touch',
+      files: 100,
+    });
+
+    assert.equal(receipt.admit, true); // First time should admit
+    assert.equal(receipt.warnings.length, 0);
+    assert.equal(receipt.errors.length, 0);
+
+    // Next operation should fail
+    const receipt2 = await checker.checkAndRecord({
+      type: 'file_touch',
+      files: 1,
+    });
+
+    assert.equal(receipt2.admit, false);
+    assert.equal(receipt2.errors.length, 1);
+    assert.equal(receipt2.errors[0].type, 'error');
+  });
+
+  it('should emit warning for bytes at 90% threshold', async () => {
+    // Use 9000 bytes (90% of 10000)
+    const receipt = await checker.checkAndRecord({
+      type: 'bytes_change',
+      bytes: 9000,
+    });
+
+    assert.equal(receipt.admit, true);
+    assert.equal(receipt.warnings.length, 1);
+    assert.equal(receipt.warnings[0].metric, 'bytes');
+    assert.equal(receipt.warnings[0].percentage, 90);
+  });
+
+  it('should emit warning for ops at 75% threshold', async () => {
+    // Use 750 ops (75% of 1000)
+    const receipt = await checker.checkAndRecord({
+      type: 'tool_op',
+      ops: 750,
+    });
+
+    assert.equal(receipt.admit, true);
+    assert.equal(receipt.warnings.length, 1);
+    assert.equal(receipt.warnings[0].metric, 'ops');
+    assert.match(receipt.warnings[0].message, /75%/);
+  });
+});
+
+// =============================================================================
+// Per-Agent Quota Tests
+// =============================================================================
+
+describe('Enhanced Bounds - Per-Agent Quotas', () => {
+  /** @type {EnhancedBoundsChecker} */
+  let checker;
+
+  beforeEach(() => {
+    checker = new EnhancedBoundsChecker({
+      max_files_touched: 1000,
+      max_bytes_changed: 100000,
+    });
+  });
+
+  it('should enforce per-agent file quota', async () => {
+    checker.setAgentQuota('agent:backend-dev', {
+      max_files: 10,
+      max_bytes: 5000,
+    });
+
+    // Agent can use up to 10 files
+    const receipt1 = await checker.checkAndRecord(
+      {
+        type: 'file_touch',
+        files: 5,
+      },
+      'agent:backend-dev'
+    );
+    assert.equal(receipt1.admit, true);
+
+    const receipt2 = await checker.checkAndRecord(
+      {
+        type: 'file_touch',
+        files: 4,
+      },
+      'agent:backend-dev'
+    );
+    assert.equal(receipt2.admit, true);
+
+    // Should reject when quota exceeded
+    const receipt3 = await checker.checkAndRecord(
+      {
+        type: 'file_touch',
+        files: 2,
+      },
+      'agent:backend-dev'
+    );
+    assert.equal(receipt3.admit, false);
+    assert.equal(receipt3.errors.length, 1);
+    assert.match(receipt3.errors[0].message, /quota/i);
+  });
+
+  it('should enforce per-agent byte quota', async () => {
+    checker.setAgentQuota('agent:tester', {
+      max_bytes: 1000,
+    });
+
+    const receipt1 = await checker.checkAndRecord(
+      {
+        type: 'bytes_change',
+        bytes: 800,
+      },
+      'agent:tester'
+    );
+    assert.equal(receipt1.admit, true);
+
+    const receipt2 = await checker.checkAndRecord(
+      {
+        type: 'bytes_change',
+        bytes: 300,
+      },
+      'agent:tester'
+    );
+    assert.equal(receipt2.admit, false);
+  });
+
+  it('should track separate quotas for different agents', async () => {
+    checker.setAgentQuota('agent:A', { max_files: 5 });
+    checker.setAgentQuota('agent:B', { max_files: 10 });
+
+    // Agent A uses 5 files
+    await checker.checkAndRecord({ type: 'file_touch', files: 5 }, 'agent:A');
+
+    // Agent B can still use 10 files
+    const receipt = await checker.checkAndRecord(
+      { type: 'file_touch', files: 8 },
+      'agent:B'
+    );
+    assert.equal(receipt.admit, true);
+
+    // Agent A cannot use more
+    const receipt2 = await checker.checkAndRecord(
+      { type: 'file_touch', files: 1 },
+      'agent:A'
+    );
+    assert.equal(receipt2.admit, false);
+  });
+});
+
+// =============================================================================
+// Rate Limiting Tests
+// =============================================================================
+
+describe('Enhanced Bounds - Rate Limiting', () => {
+  /** @type {EnhancedBoundsChecker} */
+  let checker;
+
+  beforeEach(() => {
+    checker = new EnhancedBoundsChecker({
+      max_files_touched: 1000,
+    });
+  });
+
+  it('should enforce rate limit per agent', async () => {
+    checker.setRateLimit({
+      maxOpsPerSecond: 5,
+      windowSizeMs: 1000,
+    });
+
+    // First 5 operations should succeed
+    for (let i = 0; i < 5; i++) {
+      const receipt = await checker.checkAndRecord(
+        { type: 'op', files: 1 },
+        'agent:worker'
+      );
+      assert.equal(receipt.admit, true);
+    }
+
+    // 6th operation should be rate limited
+    const receipt = await checker.checkAndRecord(
+      { type: 'op', files: 1 },
+      'agent:worker'
+    );
+    assert.equal(receipt.admit, false);
+    assert.ok(receipt.errors.some((e) => e.metric === 'rate_limit'));
+  });
+
+  it('should allow operations after window expires', async () => {
+    checker.setRateLimit({
+      maxOpsPerSecond: 3,
+      windowSizeMs: 100, // Short window for testing
+    });
+
+    // Fill the window
+    for (let i = 0; i < 3; i++) {
+      await checker.checkAndRecord({ type: 'op', files: 1 }, 'agent:test');
+    }
+
+    // Should be rate limited
+    const receipt1 = await checker.checkAndRecord(
+      { type: 'op', files: 1 },
+      'agent:test'
+    );
+    assert.equal(receipt1.admit, false);
+
+    // Wait for window to expire
+    await new Promise((resolve) => setTimeout(resolve, 150));
+
+    // Should now succeed
+    const receipt2 = await checker.checkAndRecord(
+      { type: 'op', files: 1 },
+      'agent:test'
+    );
+    assert.equal(receipt2.admit, true);
+  });
+});
+
+// =============================================================================
+// Integration Tests
+// =============================================================================
+
+describe('Enhanced Bounds - Integration', () => {
+  /** @type {EnhancedBoundsChecker} */
+  let checker;
+
+  beforeEach(() => {
+    checker = new EnhancedBoundsChecker({
+      max_files_touched: 100,
+      max_bytes_changed: 10000,
+      max_tool_ops: 1000,
+      warnings: {
+        filesThreshold: 0.8,
+        bytesThreshold: 0.9,
+      },
+    });
+
+    checker.setAgentQuota('agent:backend-dev', {
+      max_files: 50,
+      max_bytes: 5000,
+    });
+
+    checker.setRateLimit({
+      maxOpsPerSecond: 10,
+      windowSizeMs: 1000,
+    });
+  });
+
+  it('should enforce all limits simultaneously', async () => {
+    // This should pass (within all limits)
+    const receipt1 = await checker.checkAndRecord(
+      {
+        type: 'composite',
+        files: 40,
+        bytes: 4000,
+        ops: 1,
+      },
+      'agent:backend-dev'
+    );
+    assert.equal(receipt1.admit, true);
+    assert.equal(receipt1.warnings.length, 0);
+
+    // This should trigger soft limit warning (80% of 50 files = 40 files already used)
+    const receipt2 = await checker.checkAndRecord(
+      {
+        type: 'composite',
+        files: 5,
+        bytes: 500,
+        ops: 1,
+      },
+      'agent:backend-dev'
+    );
+    assert.equal(receipt2.admit, true);
+    // May have warnings for global or agent limits
+
+    // This should fail agent quota
+    const receipt3 = await checker.checkAndRecord(
+      {
+        type: 'composite',
+        files: 10,
+        bytes: 100,
+        ops: 1,
+      },
+      'agent:backend-dev'
+    );
+    assert.equal(receipt3.admit, false);
+  });
+
+  it('should provide detailed receipt with all checks', async () => {
+    const receipt = await checker.checkAndRecord(
+      {
+        type: 'file_write',
+        files: 1,
+        bytes: 100,
+        ops: 1,
+      },
+      'agent:backend-dev'
+    );
+
+    assert.ok(receipt.receipt_id);
+    assert.ok(receipt.timestamp);
+    assert.equal(receipt.agentId, 'agent:backend-dev');
+    assert.equal(receipt.operation, 'file_write');
+    assert.ok(Array.isArray(receipt.warnings));
+    assert.ok(Array.isArray(receipt.errors));
+    assert.equal(typeof receipt.admit, 'boolean');
+  });
+
+  it('should track usage correctly', async () => {
+    await checker.checkAndRecord(
+      {
+        type: 'op1',
+        files: 10,
+        bytes: 1000,
+        ops: 5,
+      },
+      'agent:backend-dev'
+    );
+
+    const globalUsage = checker.getUsage();
+    assert.equal(globalUsage.files_touched, 10);
+    assert.equal(globalUsage.bytes_changed, 1000);
+    assert.equal(globalUsage.tool_ops, 5);
+
+    const agentUsage = checker.getAgentUsage('agent:backend-dev');
+    assert.equal(agentUsage.files_touched, 10);
+    assert.equal(agentUsage.bytes_changed, 1000);
+    assert.equal(agentUsage.tool_ops, 5);
+  });
+
+  it('should filter receipts by type', async () => {
+    // Create warning
+    await checker.checkAndRecord({ type: 'op', files: 80 });
+
+    // Create error
+    checker.setAgentQuota('agent:test', { max_files: 1 });
+    await checker.checkAndRecord({ type: 'op', files: 10 }, 'agent:test');
+
+    const warnings = checker.getReceiptsByType('warning');
+    const errors = checker.getReceiptsByType('error');
+
+    assert.ok(warnings.length > 0);
+    assert.ok(errors.length > 0);
+  });
+});
+
+// =============================================================================
+// Usage Tracking Tests
+// =============================================================================
+
+describe('Enhanced Bounds - Usage Tracking', () => {
+  it('should track global usage across all agents', async () => {
+    const checker = new EnhancedBoundsChecker({
+      max_files_touched: 1000,
+      max_bytes_changed: 100000,
+    });
+
+    await checker.checkAndRecord({ type: 'op', files: 10 }, 'agent:A');
+    await checker.checkAndRecord({ type: 'op', files: 20 }, 'agent:B');
+    await checker.checkAndRecord({ type: 'op', bytes: 1000 }, 'agent:A');
+
+    const usage = checker.getUsage();
+    assert.equal(usage.files_touched, 30);
+    assert.equal(usage.bytes_changed, 1000);
+  });
+
+  it('should track per-agent usage separately', async () => {
+    const checker = new EnhancedBoundsChecker({
+      max_files_touched: 1000,
+    });
+
+    await checker.checkAndRecord({ type: 'op', files: 10 }, 'agent:A');
+    await checker.checkAndRecord({ type: 'op', files: 20 }, 'agent:B');
+
+    const usageA = checker.getAgentUsage('agent:A');
+    const usageB = checker.getAgentUsage('agent:B');
+
+    assert.equal(usageA.files_touched, 10);
+    assert.equal(usageB.files_touched, 20);
+  });
+
+  it('should reset usage correctly', async () => {
+    const checker = new EnhancedBoundsChecker({
+      max_files_touched: 100,
+    });
+
+    await checker.checkAndRecord({ type: 'op', files: 50 }, 'agent:test');
+
+    checker.reset();
+
+    const usage = checker.getUsage();
+    assert.equal(usage.files_touched, 0);
+    assert.equal(checker.getReceipts().length, 0);
+  });
+});
+
+// =============================================================================
+// Custom Warning Thresholds Tests
+// =============================================================================
+
+describe('Enhanced Bounds - Custom Warning Thresholds', () => {
+  it('should use custom warning thresholds', async () => {
+    const checker = new EnhancedBoundsChecker({
+      max_files_touched: 100,
+      warnings: {
+        filesThreshold: 0.5, // Warn at 50%
+      },
+    });
+
+    // At 50%, should warn
+    const receipt1 = await checker.checkAndRecord({
+      type: 'op',
+      files: 50,
+    });
+    assert.equal(receipt1.warnings.length, 1);
+    assert.equal(receipt1.warnings[0].percentage, 50);
+
+    // Below 50%, should not warn
+    checker.reset();
+    const receipt2 = await checker.checkAndRecord({
+      type: 'op',
+      files: 40,
+    });
+    assert.equal(receipt2.warnings.length, 0);
+  });
+
+  it('should support different thresholds for different metrics', async () => {
+    const checker = new EnhancedBoundsChecker({
+      max_files_touched: 100,
+      max_bytes_changed: 10000,
+      warnings: {
+        filesThreshold: 0.5,
+        bytesThreshold: 0.9,
+      },
+    });
+
+    const receipt = await checker.checkAndRecord({
+      type: 'op',
+      files: 50, // 50% - should warn
+      bytes: 8000, // 80% - should not warn
+    });
+
+    assert.equal(receipt.warnings.length, 1);
+    assert.equal(receipt.warnings[0].metric, 'files');
+  });
+});