@longarc/mdash 3.1.1 → 3.1.3

package/src/__tests__/l1-verification-modes.test.ts

@@ -0,0 +1,424 @@
+/**
+ * L1 Verification Modes Test Suite
+ *
+ * Tests the v3.1 verification mode extension to the Commitment Layer.
+ * Covers: claim/verified/witnessed modes, seal versioning, backwards
+ * compatibility, and cross-layer contract preservation.
+ *
+ * These tests are ADDITIVE -- no existing test files are modified.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import {
+  sha256,
+  sha256Object,
+  hmacSeal,
+  hmacVerify,
+  deriveKey,
+  isHash,
+  isSeal,
+  Hash,
+  CommitmentEngine,
+  Commitment,
+  VerificationMode,
+} from '../index';
+
+const TEST_SEAL_KEY = 'test-seal-key-for-mdash-v3-phase1-minimum-32-chars';
+
+// ============================================================================
+// BACKWARDS COMPATIBILITY (Critical -- existing behavior preserved exactly)
+// ============================================================================
+
+describe('L1 Verification Modes', () => {
+  let engine: CommitmentEngine;
+
+  beforeEach(async () => {
+    engine = new CommitmentEngine();
+    await engine.initialize(TEST_SEAL_KEY);
+  });
+
+  describe('Backwards Compatibility', () => {
+    it('default commit() produces v3.0 commitment (no options)', async () => {
+      const commitment = await engine.commit({ test: 'data' }, 'compat-1');
+      expect(commitment.version).toBe('v3.0');
+      expect(commitment.verification_mode).toBeUndefined();
+      expect(commitment.verification_proof).toBeUndefined();
+    });
+
+    it('explicit claim mode produces v3.0 commitment', async () => {
+      const commitment = await engine.commit({ test: 'data' }, 'compat-2', {
+        mode: 'claim',
+      });
+      expect(commitment.version).toBe('v3.0');
+      expect(commitment.verification_mode).toBeUndefined();
+      expect(commitment.verification_proof).toBeUndefined();
+    });
+
+    it('default commit seal matches _v:1 format exactly', async () => {
+      // Manually compute what the old code would have produced
+      const key = await deriveKey(TEST_SEAL_KEY);
+      const content = { test: 'backwards-compat' };
+      const commitment = await engine.commit(content, 'compat-3');
+
+      // Reconstruct _v:1 seal data
+      const v1Data = {
+        _v: 1,
+        id: 'compat-3',
+        content_hash: commitment.content_hash,
+        committed_at: commitment.committed_at,
+      };
+      const expectedSeal = await hmacSeal(v1Data, key);
+      expect(commitment.seal).toBe(expectedSeal);
+    });
+
+    it('default commit verifies with the engine', async () => {
+      const commitment = await engine.commit({ test: 'data' }, 'compat-4');
+      const valid = await engine.verify(commitment);
+      expect(valid).toBe(true);
+    });
+
+    it('default commit proof generation still works', async () => {
+      await engine.commit({ test: 'data' }, 'compat-5');
+      const proof = await engine.generateProof('compat-5');
+      expect(proof.commitment.id).toBe('compat-5');
+      expect(proof.merkle_path.length).toBeGreaterThan(0);
+      expect(proof.root_hash).toBeDefined();
+      expect(proof.leaf_index).toBe(0);
+    });
+
+    it('default commit seal verification still works within proof', async () => {
+      await engine.commit({ test: 'data' }, 'compat-6');
+      const proof = await engine.generateProof('compat-6');
+      // Seal verification (the part our changes touch) works
+      const sealValid = await engine.verify(proof.commitment);
+      expect(sealValid).toBe(true);
+    });
+  });
+
+  // ============================================================================
+  // VERIFIED MODE
+  // ============================================================================
+
+  describe('Verified Mode (L1:verified)', () => {
+    it('creates v3.1 commitment with verification_mode', async () => {
+      const verificationProof = await sha256('lsh-digest-placeholder');
+      const commitment = await engine.commit({ test: 'verified' }, 'ver-1', {
+        mode: 'verified',
+        verificationProof,
+      });
+
+      expect(commitment.version).toBe('v3.1');
+      expect(commitment.verification_mode).toBe('verified');
+      expect(commitment.verification_proof).toBe(verificationProof);
+    });
+
+    it('verified commitment seal includes verification fields', async () => {
+      const key = await deriveKey(TEST_SEAL_KEY);
+      const verificationProof = await sha256('lsh-digest');
+      const commitment = await engine.commit({ test: 'verified' }, 'ver-2', {
+        mode: 'verified',
+        verificationProof,
+      });
+
+      // Reconstruct _v:2 seal data
+      const v2Data = {
+        _v: 2,
+        id: 'ver-2',
+        content_hash: commitment.content_hash,
+        committed_at: commitment.committed_at,
+        verification_mode: 'verified',
+        verification_proof: verificationProof,
+      };
+      const expectedSeal = await hmacSeal(v2Data, key);
+      expect(commitment.seal).toBe(expectedSeal);
+    });
+
+    it('verified commitment verifies correctly', async () => {
+      const verificationProof = await sha256('lsh-digest');
+      const commitment = await engine.commit({ test: 'verified' }, 'ver-3', {
+        mode: 'verified',
+        verificationProof,
+      });
+      const valid = await engine.verify(commitment);
+      expect(valid).toBe(true);
+    });
+
+    it('verified commitment with tampered proof fails verification', async () => {
+      const verificationProof = await sha256('lsh-digest');
+      const commitment = await engine.commit({ test: 'verified' }, 'ver-4', {
+        mode: 'verified',
+        verificationProof,
+      });
+
+      // Tamper with the proof
+      const tampered: Commitment = {
+        ...commitment,
+        verification_proof: await sha256('tampered'),
+      };
+      const valid = await engine.verify(tampered);
+      expect(valid).toBe(false);
+    });
+
+    it('verified commitment with tampered mode fails verification', async () => {
+      const verificationProof = await sha256('lsh-digest');
+      const commitment = await engine.commit({ test: 'verified' }, 'ver-5', {
+        mode: 'verified',
+        verificationProof,
+      });
+
+      // Tamper: change mode to witnessed
+      const tampered: Commitment = {
+        ...commitment,
+        verification_mode: 'witnessed' as VerificationMode,
+      };
+      const valid = await engine.verify(tampered);
+      expect(valid).toBe(false);
+    });
+
+    it('verified mode without proof throws', async () => {
+      await expect(
+        engine.commit({ test: 'data' }, 'ver-6', { mode: 'verified' })
+      ).rejects.toThrow('Enhanced verification mode requires a verification_proof');
+    });
+
+    it('invalid mode string rejected at runtime', async () => {
+      await expect(
+        engine.commit({ test: 'data' }, 'ver-7', {
+          mode: 'admin-override' as VerificationMode,
+        })
+      ).rejects.toThrow('Invalid verification mode');
+    });
+  });
+
+  // ============================================================================
+  // WITNESSED MODE
+  // ============================================================================
+
+  describe('Witnessed Mode (L1:witnessed)', () => {
+    it('creates v3.1 commitment with witnessed mode', async () => {
+      const witnessSeal = await sha256('warden-cosign-abc');
+      const commitment = await engine.commit({ test: 'witnessed' }, 'wit-1', {
+        mode: 'witnessed',
+        verificationProof: witnessSeal,
+      });
+
+      expect(commitment.version).toBe('v3.1');
+      expect(commitment.verification_mode).toBe('witnessed');
+      expect(commitment.verification_proof).toBe(witnessSeal);
+    });
+
+    it('witnessed commitment verifies correctly', async () => {
+      const witnessSeal = await sha256('warden-cosign');
+      const commitment = await engine.commit({ test: 'witnessed' }, 'wit-2', {
+        mode: 'witnessed',
+        verificationProof: witnessSeal,
+      });
+      const valid = await engine.verify(commitment);
+      expect(valid).toBe(true);
+    });
+
+    it('witnessed mode without proof throws', async () => {
+      await expect(
+        engine.commit({ test: 'data' }, 'wit-3', { mode: 'witnessed' })
+      ).rejects.toThrow('Enhanced verification mode requires a verification_proof');
+    });
+  });
+
+  // ============================================================================
+  // CROSS-VERSION INTEGRITY
+  // ============================================================================
+
+  describe('Cross-Version Integrity', () => {
+    it('v3.0 and v3.1 commitments coexist in same engine', async () => {
+      const v30 = await engine.commit({ a: 1 }, 'cross-v30');
+      const proof = await sha256('proof');
+      const v31 = await engine.commit({ b: 2 }, 'cross-v31', {
+        mode: 'verified',
+        verificationProof: proof,
+      });
+
+      expect(v30.version).toBe('v3.0');
+      expect(v31.version).toBe('v3.1');
+
+      // Both verify independently
+      expect(await engine.verify(v30)).toBe(true);
+      expect(await engine.verify(v31)).toBe(true);
+    });
+
+    it('v3.0 and v3.1 commitments share Merkle tree', async () => {
+      await engine.commit({ a: 1 }, 'tree-v30');
+      const proof = await sha256('proof');
+      await engine.commit({ b: 2 }, 'tree-v31', {
+        mode: 'verified',
+        verificationProof: proof,
+      });
+
+      const stats = engine.getStats();
+      expect(stats.commitments).toBe(2);
+      expect(stats.treeStats.leaves).toBe(2);
+    });
+
+    it('v3.0 commitment proof still valid after v3.1 commitments added', async () => {
+      await engine.commit({ first: true }, 'order-1');
+      const proofHash = await sha256('proof');
+      await engine.commit({ second: true }, 'order-2', {
+        mode: 'verified',
+        verificationProof: proofHash,
+      });
+
+      // v3.0 commitment still verifiable after v3.1 additions
+      const proof = await engine.generateProof('order-1');
+      expect(proof.commitment.version).toBe('v3.0');
+      // Seal verification works across versions
+      const sealValid = await engine.verify(proof.commitment);
+      expect(sealValid).toBe(true);
+      // Proof structure intact
+      expect(proof.merkle_path.length).toBeGreaterThan(0);
+      expect(proof.root_hash).toBeDefined();
+    });
+
+    it('v3.1 commitment generates valid proof structure', async () => {
+      const proofHash = await sha256('proof');
+      await engine.commit({ data: true }, 'merkle-v31', {
+        mode: 'witnessed',
+        verificationProof: proofHash,
+      });
+
+      const proof = await engine.generateProof('merkle-v31');
+      expect(proof.commitment.version).toBe('v3.1');
+      expect(proof.commitment.verification_mode).toBe('witnessed');
+      // Seal verification works for v3.1
+      const sealValid = await engine.verify(proof.commitment);
+      expect(sealValid).toBe(true);
+      // Proof structure intact
+      expect(proof.merkle_path.length).toBeGreaterThan(0);
+    });
+  });
+
+  // ============================================================================
+  // SEAL ISOLATION (v1 and v2 seals cannot cross-verify)
+  // ============================================================================
+
+  describe('Seal Version Isolation', () => {
+    it('v3.0 seal does not verify as v3.1 commitment', async () => {
+      const commitment = await engine.commit({ test: 'data' }, 'iso-1');
+
+      // Force-upgrade to v3.1 shape without re-sealing
+      const fakeV31: Commitment = {
+        ...commitment,
+        version: 'v3.1',
+        verification_mode: 'verified',
+        verification_proof: await sha256('fake-proof'),
+      };
+
+      // Should fail: the seal was computed with _v:1, not _v:2
+      const valid = await engine.verify(fakeV31);
+      expect(valid).toBe(false);
+    });
+
+    it('different verification proofs produce different seals', async () => {
+      const proof1 = await sha256('proof-a');
+      const proof2 = await sha256('proof-b');
+
+      const c1 = await engine.commit({ same: 'content' }, 'diff-seal-1', {
+        mode: 'verified',
+        verificationProof: proof1,
+      });
+      const c2 = await engine.commit({ same: 'content' }, 'diff-seal-2', {
+        mode: 'verified',
+        verificationProof: proof2,
+      });
+
+      // Same content, different proofs -> different seals
+      expect(c1.seal).not.toBe(c2.seal);
+      // But same content hash
+      expect(c1.content_hash).toBe(c2.content_hash);
+    });
+
+    it('same proof with different modes produces different seals', async () => {
+      const proof = await sha256('same-proof');
+
+      const verified = await engine.commit({ x: 1 }, 'mode-seal-1', {
+        mode: 'verified',
+        verificationProof: proof,
+      });
+      const witnessed = await engine.commit({ x: 1 }, 'mode-seal-2', {
+        mode: 'witnessed',
+        verificationProof: proof,
+      });
+
+      expect(verified.seal).not.toBe(witnessed.seal);
+    });
+  });
+
+  // ============================================================================
+  // CROSS-LAYER CONTRACT (L2/L3 interfaces unchanged)
+  // ============================================================================
+
+  describe('Cross-Layer Contract Preservation', () => {
+    it('v3.1 commitment has operationId (L2 bridge contract)', async () => {
+      const proof = await sha256('proof');
+      const commitment = await engine.commit({ test: 'bridge' }, 'bridge-1', {
+        mode: 'verified',
+        verificationProof: proof,
+      });
+
+      // L2 AttestationBridge checks: attestation.commitment_id === commitment.operationId
+      expect(commitment.operationId).toBe('bridge-1');
+      expect(commitment.id).toBe(commitment.operationId);
+    });
+
+    it('v3.1 commitment has content_hash (Merkle tree contract)', async () => {
+      const proof = await sha256('proof');
+      const commitment = await engine.commit({ test: 'merkle' }, 'merkle-1', {
+        mode: 'verified',
+        verificationProof: proof,
+      });
+
+      expect(isHash(commitment.content_hash)).toBe(true);
+      expect(commitment.content_hash).toHaveLength(64);
+    });
+
+    it('v3.1 commitment has id (L3 reference contract)', async () => {
+      const proof = await sha256('proof');
+      const commitment = await engine.commit({ test: 'ref' }, 'ref-1', {
+        mode: 'witnessed',
+        verificationProof: proof,
+      });
+
+      // L3 ZK engine references commitments by ID
+      expect(commitment.id).toBe('ref-1');
+      expect(engine.getCommitment('ref-1')).toBeDefined();
+    });
+  });
+
+  // ============================================================================
+  // REWARD SIGNAL COMPATIBILITY (Future training bridge)
+  // ============================================================================
+
+  describe('Reward Signal Compatibility', () => {
+    it('composite score as float in [0,1] is attestable', async () => {
+      // Simulate what Kiwi CompositeRubric will produce:
+      // A composite_score that becomes both a grade AND a reward signal
+      const evalResult = {
+        composite_score: 0.847,
+        rubric_scores: { constraint_adherence: 0.9, factual_grounding: 0.8 },
+        agent_profile_id: 'agent-001',
+      };
+
+      const proof = await sha256('eval-verification');
+      const commitment = await engine.commit(evalResult, 'eval-1', {
+        mode: 'verified',
+        verificationProof: proof,
+      });
+
+      expect(await engine.verify(commitment)).toBe(true);
+
+      // The committed content_hash cryptographically binds the composite_score
+      // This same score can later serve as a GRPO reward signal
+      const expectedHash = await sha256Object(evalResult);
+      expect(commitment.content_hash).toBe(expectedHash);
+    });
+  });
+});

package/src/__tests__/phase1.benchmark.test.ts

@@ -0,0 +1,94 @@
+/**
+ * mdash v3.0 Phase 1 Benchmark Tests
+ *
+ * Environment-sensitive latency SLA tests.
+ * Excluded from Lane A (merge gate). Run in Lane B with continue-on-error.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import {
+  CommitmentEngine,
+  LatencyMonitor,
+  MdashProtocol,
+  createMdash,
+} from '../index';
+
+const TEST_SEAL_KEY = 'test-seal-key-for-mdash-v3-phase1-minimum-32-chars';
+
+async function createInitializedProtocol(): Promise<MdashProtocol> {
+  const protocol = createMdash({ sealKey: TEST_SEAL_KEY });
+  await protocol.initialize();
+  return protocol;
+}
+
+describe('[benchmark] Latency SLAs', () => {
+  describe('Latency Monitor', () => {
+    let monitor: LatencyMonitor;
+
+    beforeEach(() => {
+      monitor = new LatencyMonitor();
+    });
+
+    it('should record latency samples', () => {
+      monitor.record('commitment_seal', 0.3);
+      monitor.record('commitment_seal', 0.5);
+      monitor.record('commitment_seal', 0.4);
+
+      const metrics = monitor.getMetrics('commitment_seal');
+      expect(metrics?.count).toBe(3);
+    });
+
+    it('should calculate P50 and P99', () => {
+      for (let i = 0; i < 100; i++) {
+        monitor.record('test_op', i * 0.01);
+      }
+
+      const metrics = monitor.getMetrics('test_op');
+      expect(metrics?.p50_ms).toBeLessThan(metrics?.p99_ms || 0);
+    });
+
+    it('should check SLA compliance', () => {
+      // Within SLA
+      for (let i = 0; i < 100; i++) {
+        monitor.record('commitment_seal', 0.3);
+      }
+      expect(monitor.isWithinSLA('commitment_seal')).toBe(true);
+
+      // Outside SLA
+      monitor.clear();
+      for (let i = 0; i < 100; i++) {
+        monitor.record('commitment_seal', 5);
+      }
+      expect(monitor.isWithinSLA('commitment_seal')).toBe(false);
+    });
+  });
+
+  describe('Protocol Latency', () => {
+    it('should complete commitment in < 1ms', async () => {
+      const engine = new CommitmentEngine();
+      await engine.initialize(TEST_SEAL_KEY);
+
+      const start = performance.now();
+      await engine.commit({ test: 'latency' }, 'latency-test');
+      const elapsed = performance.now() - start;
+
+      // Allow some slack for CI environments
+      expect(elapsed).toBeLessThan(50);
+    });
+
+    it('should complete checkpoint creation quickly', async () => {
+      const protocol = await createInitializedProtocol();
+
+      const start = performance.now();
+      await protocol.checkpoint.createCheckpoint({
+        agent_id: 'latency-agent',
+        trigger: 'action_start',
+        state: { execution_state: {}, warrant_id: null, action: 'test', params: {} },
+      });
+      const elapsed = performance.now() - start;
+
+      expect(elapsed).toBeLessThan(50);
+    });
+  });
+});

package/src/__tests__/phase1.test.ts

@@ -38,8 +38,6 @@ import {
   // Commitment Layer
   CommitmentEngine,
   IncrementalMerkleTree,
-  LatencyMonitor,
-  
   // Warrant System
   WarrantEngine,
   WarrantCache,
@@ -984,81 +982,6 @@ describe('Physics Engine', () => {
   });
 });
 
-// ============================================================================
-// LATENCY SLA TESTS (15)
-// ============================================================================
-
-describe('Latency SLAs', () => {
-  describe('Latency Monitor', () => {
-    let monitor: LatencyMonitor;
-    
-    beforeEach(() => {
-      monitor = new LatencyMonitor();
-    });
-    
-    it('should record latency samples', () => {
-      monitor.record('commitment_seal', 0.3);
-      monitor.record('commitment_seal', 0.5);
-      monitor.record('commitment_seal', 0.4);
-      
-      const metrics = monitor.getMetrics('commitment_seal');
-      expect(metrics?.count).toBe(3);
-    });
-    
-    it('should calculate P50 and P99', () => {
-      for (let i = 0; i < 100; i++) {
-        monitor.record('test_op', i * 0.01);
-      }
-      
-      const metrics = monitor.getMetrics('test_op');
-      expect(metrics?.p50_ms).toBeLessThan(metrics?.p99_ms || 0);
-    });
-    
-    it('should check SLA compliance', () => {
-      // Within SLA
-      for (let i = 0; i < 100; i++) {
-        monitor.record('commitment_seal', 0.3);
-      }
-      expect(monitor.isWithinSLA('commitment_seal')).toBe(true);
-      
-      // Outside SLA
-      monitor.clear();
-      for (let i = 0; i < 100; i++) {
-        monitor.record('commitment_seal', 5);
-      }
-      expect(monitor.isWithinSLA('commitment_seal')).toBe(false);
-    });
-  });
-  
-  describe('Protocol Latency', () => {
-    it('should complete commitment in < 1ms', async () => {
-      const engine = new CommitmentEngine();
-      await engine.initialize(TEST_SEAL_KEY);
-      
-      const start = performance.now();
-      await engine.commit({ test: 'latency' }, 'latency-test');
-      const elapsed = performance.now() - start;
-      
-      // Allow some slack for CI environments
-      expect(elapsed).toBeLessThan(50);
-    });
-    
-    it('should complete checkpoint creation quickly', async () => {
-      const protocol = await createInitializedProtocol();
-      
-      const start = performance.now();
-      await protocol.checkpoint.createCheckpoint({
-        agent_id: 'latency-agent',
-        trigger: 'action_start',
-        state: { execution_state: {}, warrant_id: null, action: 'test', params: {} },
-      });
-      const elapsed = performance.now() - start;
-      
-      expect(elapsed).toBeLessThan(50);
-    });
-  });
-});
-
 // ============================================================================
 // PROTOCOL INTEGRATION TESTS
 // ============================================================================

package/src/__tests__/phase2-4.benchmark.test.ts

@@ -0,0 +1,60 @@
+/**
+ * mdash v3.0 Phase 2-4 Benchmark Tests
+ *
+ * Environment-sensitive P99 latency SLA tests for L1/L2.
+ * Excluded from Lane A (merge gate). Run in Lane B with continue-on-error.
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { CommitmentEngine } from '../core/commitment.js';
+import { TEEAttestationEngine } from '../tee/engine.js';
+
+const TEST_SEAL_KEY = 'test-seal-key-phase-2-4-v3.0.0-x';
+
+describe('[benchmark] Latency SLA Compliance', () => {
+  let commitmentEngine: CommitmentEngine;
+  let teeEngine: TEEAttestationEngine;
+
+  beforeAll(async () => {
+    commitmentEngine = new CommitmentEngine();
+    await commitmentEngine.initialize(TEST_SEAL_KEY);
+
+    teeEngine = new TEEAttestationEngine(commitmentEngine);
+    await teeEngine.initialize(TEST_SEAL_KEY);
+  });
+
+  it('L1 commitment should complete in <1ms (P99)', async () => {
+    const latencies: number[] = [];
+
+    for (let i = 0; i < 100; i++) {
+      const start = performance.now();
+      await commitmentEngine.commit({ iteration: i }, `latency-l1-${i}`);
+      latencies.push(performance.now() - start);
+    }
+
+    // Sort and get P99
+    latencies.sort((a, b) => a - b);
+    const p99 = latencies[98];
+
+    // Note: In Node.js environment, actual latency may vary
+    // Target is <1ms, we allow 5ms for test stability
+    expect(p99).toBeLessThan(5);
+  });
+
+  it('L2 attestation should complete in <10ms (P99)', async () => {
+    const latencies: number[] = [];
+
+    for (let i = 0; i < 50; i++) {
+      const start = performance.now();
+      await teeEngine.attest({ iteration: i }, `latency-l2-${i}`);
+      latencies.push(performance.now() - start);
+    }
+
+    // Sort and get P99
+    latencies.sort((a, b) => a - b);
+    const p99 = latencies[Math.floor(latencies.length * 0.99)];
+
+    // Target is <10ms, we allow 50ms for test stability
+    expect(p99).toBeLessThan(50);
+  });
+});