@longarc/mdash 3.0.0

package/src/checkpoint/engine.ts

@@ -0,0 +1,532 @@
+/**
+ * mdash v3.0 - Checkpoint Surety
+ * 
+ * Event-driven checkpoints replace time-driven intervals.
+ * "State transition triggers seal, not time intervals."
+ * 
+ * Target Latency:
+ * - Checkpoint creation: <0.5ms P50, <1ms P99
+ * 
+ * Key Property:
+ * - Single action blast radius: if an action fails, only that action is affected
+ */
+
+import {
+  Hash,
+  Seal,
+  Timestamp,
+  CheckpointId,
+  WarrantId,
+  generateCheckpointId,
+  generateTimestamp,
+  sha256Object,
+  hmacSeal,
+  hmacVerify,
+  deriveKey,
+} from '../core/crypto';
+
+import { CommitmentEngine } from '../core/commitment';
+
+// ============================================================================
+// CHECKPOINT TYPES
+// ============================================================================
+
+export type CheckpointTrigger =
+  | 'action_start'
+  | 'action_complete'
+  | 'state_change'
+  | 'constraint_check'
+  | 'error'
+  | 'recovery'
+  | 'manual';
+
+export type CheckpointStatus = 'pending' | 'sealed' | 'verified' | 'failed';
+
+export interface CheckpointState {
+  /** Current execution state */
+  execution_state: Record<string, unknown>;
+  /** Active warrant at checkpoint */
+  warrant_id: WarrantId | null;
+  /** Action being performed */
+  action: string;
+  /** Action parameters */
+  params: Record<string, unknown>;
+  /** Result (if action complete) */
+  result?: unknown;
+  /** Error (if failed) */
+  error?: string;
+}
+
+export interface Checkpoint {
+  /** Unique checkpoint identifier */
+  id: CheckpointId;
+  /** Agent this checkpoint belongs to */
+  agent_id: string;
+  /** Trigger that created this checkpoint */
+  trigger: CheckpointTrigger;
+  /** Current status */
+  status: CheckpointStatus;
+  /** State at checkpoint */
+  state: CheckpointState;
+  /** Parent checkpoint (for happens-before) */
+  parent_id: CheckpointId | null;
+  /** Physics validation score */
+  physics_score: number;
+  /** Timestamp of creation */
+  created_at: Timestamp;
+  /** Content hash */
+  hash: Hash;
+  /** HMAC seal */
+  seal: Seal;
+  /** L1 commitment reference */
+  commitment_id: string | null;
+  /** Protocol version */
+  version: 'v3.0';
+}
+
+export interface CheckpointChain {
+  /** Head of the chain */
+  head: Checkpoint;
+  /** Previous checkpoints */
+  predecessors: CheckpointId[];
+  /** Chain length */
+  length: number;
+  /** Chain hash (rolling) */
+  chain_hash: Hash;
+}
+
+// ============================================================================
+// HAPPENS-BEFORE LATTICE
+// ============================================================================
+
+/**
+ * Lamport-style happens-before ordering for checkpoints
+ * Ensures causal consistency in distributed execution
+ */
+export class HappensBeforeLattice {
+  private checkpoints: Map<CheckpointId, Checkpoint> = new Map();
+  private children: Map<CheckpointId, CheckpointId[]> = new Map();
+  private roots: CheckpointId[] = [];
+  
+  /**
+   * Add a checkpoint to the lattice
+   */
+  add(checkpoint: Checkpoint): void {
+    this.checkpoints.set(checkpoint.id, checkpoint);
+    
+    if (checkpoint.parent_id) {
+      const siblings = this.children.get(checkpoint.parent_id) || [];
+      siblings.push(checkpoint.id);
+      this.children.set(checkpoint.parent_id, siblings);
+    } else {
+      this.roots.push(checkpoint.id);
+    }
+  }
+  
+  /**
+   * Check if a happens-before b
+   */
+  happensBefore(a: CheckpointId, b: CheckpointId): boolean {
+    const cpB = this.checkpoints.get(b);
+    if (!cpB) return false;
+    
+    // Walk up from b to see if we reach a
+    let current: CheckpointId | null = b;
+    while (current) {
+      if (current === a) return true;
+      const cp = this.checkpoints.get(current);
+      current = cp?.parent_id || null;
+    }
+    
+    return false;
+  }
+  
+  /**
+   * Check if two checkpoints are concurrent (neither happens-before the other)
+   */
+  areConcurrent(a: CheckpointId, b: CheckpointId): boolean {
+    return !this.happensBefore(a, b) && !this.happensBefore(b, a);
+  }
+  
+  /**
+   * Get the causal history of a checkpoint
+   */
+  getCausalHistory(id: CheckpointId): Checkpoint[] {
+    const history: Checkpoint[] = [];
+    let current: CheckpointId | null = id;
+    
+    while (current) {
+      const cp = this.checkpoints.get(current);
+      if (!cp) break;
+      history.push(cp);
+      current = cp.parent_id;
+    }
+    
+    return history;
+  }
+  
+  /**
+   * Get all checkpoints after a given one
+   */
+  getSuccessors(id: CheckpointId): Checkpoint[] {
+    const successors: Checkpoint[] = [];
+    const queue = this.children.get(id) || [];
+    
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      const cp = this.checkpoints.get(current);
+      if (cp) {
+        successors.push(cp);
+        queue.push(...(this.children.get(current) || []));
+      }
+    }
+    
+    return successors;
+  }
+  
+  /**
+   * Find the latest common ancestor of two checkpoints
+   */
+  findLCA(a: CheckpointId, b: CheckpointId): CheckpointId | null {
+    const ancestorsA = new Set<CheckpointId>();
+    let current: CheckpointId | null = a;
+    
+    while (current) {
+      ancestorsA.add(current);
+      const cp = this.checkpoints.get(current);
+      current = cp?.parent_id || null;
+    }
+    
+    current = b;
+    while (current) {
+      if (ancestorsA.has(current)) {
+        return current;
+      }
+      const cp = this.checkpoints.get(current);
+      current = cp?.parent_id || null;
+    }
+    
+    return null;
+  }
+  
+  /**
+   * Get statistics
+   */
+  getStats(): { total: number; roots: number; maxDepth: number } {
+    let maxDepth = 0;
+    
+    for (const id of this.checkpoints.keys()) {
+      const history = this.getCausalHistory(id);
+      maxDepth = Math.max(maxDepth, history.length);
+    }
+    
+    return {
+      total: this.checkpoints.size,
+      roots: this.roots.length,
+      maxDepth,
+    };
+  }
+}
+
+// ============================================================================
+// CHECKPOINT ENGINE
+// ============================================================================
+
+export class CheckpointEngine {
+  private key: CryptoKey | null = null;
+  private commitmentEngine: CommitmentEngine;
+  private lattice: HappensBeforeLattice;
+  private checkpoints: Map<CheckpointId, Checkpoint> = new Map();
+  private agentHeads: Map<string, CheckpointId> = new Map(); // Latest checkpoint per agent
+  
+  constructor(commitmentEngine: CommitmentEngine) {
+    this.commitmentEngine = commitmentEngine;
+    this.lattice = new HappensBeforeLattice();
+  }
+  
+  /**
+   * Initialize the engine with a seal key
+   */
+  async initialize(sealKey: string): Promise<void> {
+    this.key = await deriveKey(sealKey);
+  }
+  
+  /**
+   * Create a checkpoint
+   * Target: <0.5ms P50, <1ms P99
+   */
+  async createCheckpoint(params: {
+    agent_id: string;
+    trigger: CheckpointTrigger;
+    state: CheckpointState;
+    physics_score?: number;
+  }): Promise<Checkpoint> {
+    if (!this.key) {
+      throw new Error('Engine not initialized. Call initialize() first.');
+    }
+    
+    const startTime = performance.now();
+    
+    const id = generateCheckpointId();
+    const now = generateTimestamp();
+    const parentId = this.agentHeads.get(params.agent_id) || null;
+    
+    // Compute state hash
+    const hash = await sha256Object({
+      id,
+      agent_id: params.agent_id,
+      trigger: params.trigger,
+      state: params.state,
+      parent_id: parentId,
+      created_at: now,
+    });
+    
+    // Create checkpoint data for sealing
+    const checkpointData = {
+      _v: 1,
+      id,
+      agent_id: params.agent_id,
+      trigger: params.trigger,
+      hash,
+      parent_id: parentId,
+      created_at: now,
+    };
+    
+    // Seal the checkpoint
+    const seal = await hmacSeal(checkpointData, this.key);
+    
+    const checkpoint: Checkpoint = {
+      id,
+      agent_id: params.agent_id,
+      trigger: params.trigger,
+      status: 'pending',
+      state: params.state,
+      parent_id: parentId,
+      physics_score: params.physics_score ?? 1.0,
+      created_at: now,
+      hash,
+      seal,
+      commitment_id: null,
+      version: 'v3.0',
+    };
+    
+    // Commit to L1 (async, don't wait)
+    const commitmentId = `checkpoint:${id}`;
+    this.commitmentEngine.commit(checkpoint, commitmentId).then(() => {
+      checkpoint.commitment_id = commitmentId;
+      checkpoint.status = 'sealed';
+    });
+    
+    // Store and index
+    this.checkpoints.set(id, checkpoint);
+    this.agentHeads.set(params.agent_id, id);
+    this.lattice.add(checkpoint);
+    
+    const elapsed = performance.now() - startTime;
+    if (elapsed > 1) {
+      console.warn(`Checkpoint creation exceeded P99: ${elapsed.toFixed(2)}ms`);
+    }
+    
+    return checkpoint;
+  }
+  
+  /**
+   * Create checkpoint for action start
+   */
+  async onActionStart(params: {
+    agent_id: string;
+    warrant_id: WarrantId;
+    action: string;
+    params: Record<string, unknown>;
+  }): Promise<Checkpoint> {
+    return this.createCheckpoint({
+      agent_id: params.agent_id,
+      trigger: 'action_start',
+      state: {
+        execution_state: { status: 'starting' },
+        warrant_id: params.warrant_id,
+        action: params.action,
+        params: params.params,
+      },
+    });
+  }
+  
+  /**
+   * Create checkpoint for action completion
+   */
+  async onActionComplete(params: {
+    agent_id: string;
+    warrant_id: WarrantId;
+    action: string;
+    params: Record<string, unknown>;
+    result: unknown;
+    physics_score: number;
+  }): Promise<Checkpoint> {
+    return this.createCheckpoint({
+      agent_id: params.agent_id,
+      trigger: 'action_complete',
+      state: {
+        execution_state: { status: 'complete' },
+        warrant_id: params.warrant_id,
+        action: params.action,
+        params: params.params,
+        result: params.result,
+      },
+      physics_score: params.physics_score,
+    });
+  }
+  
+  /**
+   * Create checkpoint for error
+   */
+  async onError(params: {
+    agent_id: string;
+    warrant_id: WarrantId | null;
+    action: string;
+    error: string;
+  }): Promise<Checkpoint> {
+    return this.createCheckpoint({
+      agent_id: params.agent_id,
+      trigger: 'error',
+      state: {
+        execution_state: { status: 'error' },
+        warrant_id: params.warrant_id,
+        action: params.action,
+        params: {},
+        error: params.error,
+      },
+      physics_score: 0,
+    });
+  }
+  
+  /**
+   * Verify a checkpoint
+   */
+  async verify(checkpoint: Checkpoint): Promise<boolean> {
+    if (!this.key) {
+      throw new Error('Engine not initialized. Call initialize() first.');
+    }
+    
+    // Verify hash
+    const expectedHash = await sha256Object({
+      id: checkpoint.id,
+      agent_id: checkpoint.agent_id,
+      trigger: checkpoint.trigger,
+      state: checkpoint.state,
+      parent_id: checkpoint.parent_id,
+      created_at: checkpoint.created_at,
+    });
+    
+    if (expectedHash !== checkpoint.hash) {
+      return false;
+    }
+    
+    // Verify seal
+    const checkpointData = {
+      _v: 1,
+      id: checkpoint.id,
+      agent_id: checkpoint.agent_id,
+      trigger: checkpoint.trigger,
+      hash: checkpoint.hash,
+      parent_id: checkpoint.parent_id,
+      created_at: checkpoint.created_at,
+    };
+    
+    return hmacVerify(checkpointData, checkpoint.seal, this.key);
+  }
+  
+  /**
+   * Get checkpoint by ID
+   */
+  get(id: CheckpointId): Checkpoint | null {
+    return this.checkpoints.get(id) || null;
+  }
+  
+  /**
+   * Get the latest checkpoint for an agent
+   */
+  getHead(agentId: string): Checkpoint | null {
+    const headId = this.agentHeads.get(agentId);
+    if (!headId) return null;
+    return this.checkpoints.get(headId) || null;
+  }
+  
+  /**
+   * Get checkpoint chain for an agent
+   */
+  getChain(agentId: string, limit: number = 100): Checkpoint[] {
+    const headId = this.agentHeads.get(agentId);
+    if (!headId) return [];
+    
+    return this.lattice.getCausalHistory(headId).slice(0, limit);
+  }
+  
+  /**
+   * Check if checkpoint a happened before checkpoint b
+   */
+  happensBefore(a: CheckpointId, b: CheckpointId): boolean {
+    return this.lattice.happensBefore(a, b);
+  }
+  
+  /**
+   * Get statistics
+   */
+  getStats(): {
+    total: number;
+    agents: number;
+    latticeStats: ReturnType<HappensBeforeLattice['getStats']>;
+  } {
+    return {
+      total: this.checkpoints.size,
+      agents: this.agentHeads.size,
+      latticeStats: this.lattice.getStats(),
+    };
+  }
+}
+
+// ============================================================================
+// BLAST RADIUS ANALYZER
+// ============================================================================
+
+/**
+ * Analyzes the impact scope of a failed action
+ * "Single action blast radius" means failures are isolated
+ */
+export class BlastRadiusAnalyzer {
+  private lattice: HappensBeforeLattice;
+  
+  constructor(lattice: HappensBeforeLattice) {
+    this.lattice = lattice;
+  }
+  
+  /**
+   * Analyze the blast radius of a failed checkpoint
+   * Returns affected checkpoints that depend on the failed one
+   */
+  analyze(failedId: CheckpointId): {
+    affected: Checkpoint[];
+    isolated: boolean;
+    recoveryPoint: CheckpointId | null;
+  } {
+    const successors = this.lattice.getSuccessors(failedId);
+    const history = this.lattice.getCausalHistory(failedId);
+    
+    // Find the last good checkpoint (recovery point)
+    const failedCheckpoint = history[0];
+    const recoveryPoint = failedCheckpoint?.parent_id ?? null;
+    
+    return {
+      affected: successors,
+      isolated: successors.length === 0,
+      recoveryPoint,
+    };
+  }
+  
+  /**
+   * Check if an action can be safely retried
+   */
+  canRetry(checkpointId: CheckpointId): boolean {
+    const { isolated } = this.analyze(checkpointId);
+    return isolated;
+  }
+}