@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/lib/extractors/proof-graph.js

@@ -1,431 +1,431 @@
-/**
- * Proof Graph v2
- * 
- * Builds the Reality Proof Graph that connects:
- * UI_ACTION → NETWORK_REQUEST → CLIENT_CALL → SERVER_ROUTE → HANDLER
- * 
- * This is the evidence chain that makes verdicts defensible.
- */
-
-"use strict";
-
-const crypto = require("crypto");
-const { normalizeUrl, matchRoute, RouteIndex } = require("./route-matcher");
-
-/**
- * Build the Reality Proof Graph from static + runtime data
- */
-function buildProofGraph(options = {}) {
-  const {
-    serverRoutes = [],
-    clientCalls = [],
-    uiBindings = [],
-    runtimeRequests = [],
-    runtimeActions = [],
-  } = options;
-
-  const nodes = [];
-  const edges = [];
-  const nodeMap = new Map();
-
-  // 1. Add server route nodes
-  for (const route of serverRoutes) {
-    const node = {
-      id: route.id,
-      type: "SERVER_ROUTE",
-      label: `${route.methods.join("/")} ${route.canonicalPath}`,
-      data: {
-        methods: route.methods,
-        path: route.canonicalPath,
-        confidence: route.confidence,
-        handler: route.handler,
-      },
-    };
-    nodes.push(node);
-    nodeMap.set(route.id, node);
-    
-    // Index by canonical path for matching
-    nodeMap.set(`route:${route.canonicalPath}`, node);
-  }
-
-  // 2. Add client call nodes
-  const routeIndex = new RouteIndex(serverRoutes);
-  
-  for (const call of clientCalls) {
-    const node = {
-      id: call.id,
-      type: "CLIENT_CALL",
-      label: `${call.method} ${call.canonicalPath || call.urlTemplate}`,
-      data: {
-        kind: call.kind,
-        method: call.method,
-        path: call.canonicalPath,
-        urlTemplate: call.urlTemplate,
-        confidence: call.confidence,
-        runtime: call.runtime,
-      },
-    };
-    nodes.push(node);
-    nodeMap.set(call.id, node);
-
-    // Link to server route if matched
-    if (call.canonicalPath) {
-      const match = routeIndex.match(call.canonicalPath, call.method);
-      if (match.matched && match.route) {
-        edges.push({
-          id: `E_${hashShort(call.id + match.route.id)}`,
-          source: call.id,
-          target: match.route.id,
-          type: "CALLS",
-          data: {
-            matchType: match.matchType,
-            confidence: match.confidence,
-          },
-        });
-      } else {
-        // No match - this is a gap
-        node.data.gap = true;
-        node.data.gapReason = "No matching server route";
-      }
-    }
-  }
-
-  // 3. Add UI binding nodes
-  for (const binding of uiBindings) {
-    const node = {
-      id: binding.bindingId,
-      type: "UI_BINDING",
-      label: `${binding.event}: ${binding.labelHint || "unknown"}`,
-      data: {
-        file: binding.file,
-        lines: binding.lines,
-        event: binding.event,
-        labelHint: binding.labelHint,
-      },
-    };
-    nodes.push(node);
-    nodeMap.set(binding.bindingId, node);
-
-    // Link to client calls
-    for (const callId of binding.calls || []) {
-      if (nodeMap.has(callId)) {
-        edges.push({
-          id: `E_${hashShort(binding.bindingId + callId)}`,
-          source: binding.bindingId,
-          target: callId,
-          type: "TRIGGERS",
-          data: {},
-        });
-      }
-    }
-  }
-
-  // 4. Add runtime action nodes and correlate with requests
-  for (const action of runtimeActions) {
-    const node = {
-      id: action.id || `RA_${hashShort(action.selector + action.timestamp)}`,
-      type: "RUNTIME_ACTION",
-      label: `${action.type}: ${action.selector || action.url || "unknown"}`,
-      data: {
-        type: action.type,
-        selector: action.selector,
-        url: action.url,
-        timestamp: action.timestamp,
-        screenshot: action.screenshot,
-      },
-    };
-    nodes.push(node);
-    nodeMap.set(node.id, node);
-
-    // Link action to triggered requests
-    for (const reqId of action.requestIds || []) {
-      edges.push({
-        id: `E_${hashShort(node.id + reqId)}`,
-        source: node.id,
-        target: reqId,
-        type: "TRIGGERED",
-        data: {},
-      });
-    }
-  }
-
-  // 5. Add runtime request nodes and correlate with client calls
-  for (const req of runtimeRequests) {
-    const nodeId = req.id || `RR_${hashShort(req.url + req.method + req.timestamp)}`;
-    const normalizedPath = normalizeUrl(req.url);
-
-    const node = {
-      id: nodeId,
-      type: "RUNTIME_REQUEST",
-      label: `${req.method} ${normalizedPath} → ${req.status}`,
-      data: {
-        method: req.method,
-        url: req.url,
-        normalizedPath,
-        status: req.status,
-        timestamp: req.timestamp,
-        duration: req.duration,
-        failed: req.status >= 400,
-      },
-    };
-    nodes.push(node);
-    nodeMap.set(nodeId, node);
-
-    // Link to matching client call
-    const matchingCall = clientCalls.find(c => {
-      if (!c.canonicalPath) return false;
-      const callPath = c.canonicalPath;
-      const reqPath = normalizedPath;
-      
-      // Exact match or dynamic match
-      if (callPath === reqPath) return true;
-      
-      // Check if call has params that could match
-      if (callPath.includes("{")) {
-        const regex = new RegExp(
-          "^" + callPath.replace(/\{[^}]+\}/g, "[^/]+") + "$"
-        );
-        return regex.test(reqPath);
-      }
-      return false;
-    });
-
-    if (matchingCall) {
-      edges.push({
-        id: `E_${hashShort(matchingCall.id + nodeId)}`,
-        source: matchingCall.id,
-        target: nodeId,
-        type: "RUNTIME_PROOF",
-        data: {
-          status: req.status,
-          proved: req.status < 400 ? "exists" : "failed",
-        },
-      });
-
-      // Also link to server route
-      const routeMatch = routeIndex.match(normalizedPath, req.method);
-      if (routeMatch.matched && routeMatch.route) {
-        edges.push({
-          id: `E_${hashShort(nodeId + routeMatch.route.id)}`,
-          source: nodeId,
-          target: routeMatch.route.id,
-          type: "SERVED_BY",
-          data: {
-            status: req.status,
-          },
-        });
-      }
-    } else {
-      // Unmapped request - didn't come from static extraction
-      node.data.unmapped = true;
-    }
-  }
-
-  return {
-    nodes,
-    edges,
-    stats: {
-      serverRoutes: serverRoutes.length,
-      clientCalls: clientCalls.length,
-      uiBindings: uiBindings.length,
-      runtimeRequests: runtimeRequests.length,
-      runtimeActions: runtimeActions.length,
-      totalNodes: nodes.length,
-      totalEdges: edges.length,
-      gaps: nodes.filter(n => n.data?.gap).length,
-      unmapped: nodes.filter(n => n.data?.unmapped).length,
-    },
-  };
-}
-
-/**
- * Find gaps in the proof graph (missing links)
- */
-function findProofGaps(graph) {
-  const gaps = [];
-
-  for (const node of graph.nodes) {
-    // Client calls with no server route match
-    if (node.type === "CLIENT_CALL" && node.data?.gap) {
-      gaps.push({
-        type: "MISSING_ROUTE",
-        severity: node.data.confidence === "high" ? "BLOCK" : "WARN",
-        node,
-        reason: node.data.gapReason,
-      });
-    }
-
-    // Runtime requests that 404'd
-    if (node.type === "RUNTIME_REQUEST" && node.data?.status === 404) {
-      gaps.push({
-        type: "RUNTIME_404",
-        severity: "BLOCK",
-        node,
-        reason: `Runtime request to ${node.data.normalizedPath} returned 404`,
-      });
-    }
-
-    // Runtime requests that are unmapped (not from static extraction)
-    if (node.type === "RUNTIME_REQUEST" && node.data?.unmapped && node.data?.status < 400) {
-      gaps.push({
-        type: "UNMAPPED_REQUEST",
-        severity: "INFO",
-        node,
-        reason: `Runtime saw ${node.data.method} ${node.data.normalizedPath} not found in static extraction`,
-      });
-    }
-  }
-
-  // UI bindings that don't trigger any network activity
-  const uiBindingNodes = graph.nodes.filter(n => n.type === "UI_BINDING");
-  for (const binding of uiBindingNodes) {
-    const outEdges = graph.edges.filter(e => e.source === binding.id);
-    if (outEdges.length === 0) {
-      gaps.push({
-        type: "DEAD_UI_CANDIDATE",
-        severity: "WARN",
-        node: binding,
-        reason: `UI binding ${binding.data.event} on "${binding.data.labelHint || "unknown"}" has no detected network calls`,
-      });
-    }
-  }
-
-  return gaps;
-}
-
-/**
- * Generate findings from proof graph gaps
- */
-function generateProofFindings(graph, gaps) {
-  const findings = [];
-
-  for (const gap of gaps) {
-    if (gap.type === "MISSING_ROUTE") {
-      findings.push({
-        id: `F_ROUTE_MISSING_${hashShort(gap.node.id)}`,
-        detectorId: "D_ROUTE_MISSING",
-        severity: gap.severity,
-        category: "Routes",
-        scope: gap.node.data?.runtime || "client",
-        title: `Client calls ${gap.node.data?.method} ${gap.node.data?.path} but no server route exists`,
-        why: "AI frequently invents endpoints. This will cause errors in production.",
-        confidence: gap.node.data?.confidence || "medium",
-        evidence: [{
-          id: `E_${hashShort(gap.node.id)}`,
-          kind: "file",
-          reason: gap.reason,
-        }],
-        proofNode: gap.node.id,
-      });
-    }
-
-    if (gap.type === "RUNTIME_404") {
-      findings.push({
-        id: `F_RUNTIME_404_${hashShort(gap.node.id)}`,
-        detectorId: "D_ROUTE_MISSING",
-        severity: "BLOCK",
-        category: "Routes",
-        scope: "runtime",
-        title: `Runtime 404: ${gap.node.data?.method} ${gap.node.data?.normalizedPath}`,
-        why: "Runtime proof shows this endpoint does not exist.",
-        confidence: "high",
-        evidence: [{
-          id: `E_${hashShort(gap.node.id)}`,
-          kind: "request",
-          url: gap.node.data?.url,
-          httpStatus: gap.node.data?.status,
-          reason: gap.reason,
-        }],
-        proofNode: gap.node.id,
-      });
-    }
-
-    if (gap.type === "DEAD_UI_CANDIDATE") {
-      findings.push({
-        id: `F_DEAD_UI_${hashShort(gap.node.id)}`,
-        detectorId: "D_DEAD_CLICK_NO_EFFECT",
-        severity: gap.severity,
-        category: "DeadUI",
-        scope: "client",
-        title: `Potential dead UI: ${gap.node.data?.event} on "${gap.node.data?.labelHint || "button"}"`,
-        why: "UI element has a handler but no detected network call. May be dead code.",
-        confidence: "low",
-        evidence: [{
-          id: `E_${hashShort(gap.node.id)}`,
-          kind: "file",
-          file: gap.node.data?.file,
-          lines: gap.node.data?.lines,
-          reason: gap.reason,
-        }],
-        proofNode: gap.node.id,
-      });
-    }
-  }
-
-  return findings;
-}
-
-/**
- * Serialize proof graph for output
- */
-function serializeProofGraph(graph) {
-  return {
-    schemaVersion: "2.0.0",
-    timestamp: new Date().toISOString(),
-    nodes: graph.nodes,
-    edges: graph.edges,
-    stats: graph.stats,
-  };
-}
-
-/**
- * Merge runtime data into existing proof graph
- */
-function mergeRuntimeProof(graph, runtimeReport) {
-  const { requests = [], actions = [], auth = {} } = runtimeReport;
-
-  // Add runtime nodes and edges
-  const runtimeGraph = buildProofGraph({
-    serverRoutes: [],
-    clientCalls: [],
-    uiBindings: [],
-    runtimeRequests: requests,
-    runtimeActions: actions,
-  });
-
-  // Merge nodes (avoid duplicates)
-  const existingIds = new Set(graph.nodes.map(n => n.id));
-  for (const node of runtimeGraph.nodes) {
-    if (!existingIds.has(node.id)) {
-      graph.nodes.push(node);
-    }
-  }
-
-  // Merge edges
-  const existingEdgeIds = new Set(graph.edges.map(e => e.id));
-  for (const edge of runtimeGraph.edges) {
-    if (!existingEdgeIds.has(edge.id)) {
-      graph.edges.push(edge);
-    }
-  }
-
-  // Update stats
-  graph.stats.runtimeRequests = requests.length;
-  graph.stats.runtimeActions = actions.length;
-  graph.stats.totalNodes = graph.nodes.length;
-  graph.stats.totalEdges = graph.edges.length;
-
-  return graph;
-}
-
-function hashShort(text) {
-  return crypto.createHash("sha256").update(text).digest("hex").slice(0, 12).toUpperCase();
-}
-
-module.exports = {
-  buildProofGraph,
-  findProofGaps,
-  generateProofFindings,
-  serializeProofGraph,
-  mergeRuntimeProof,
-};
+/**
+ * Proof Graph v2
+ * 
+ * Builds the Reality Proof Graph that connects:
+ * UI_ACTION → NETWORK_REQUEST → CLIENT_CALL → SERVER_ROUTE → HANDLER
+ * 
+ * This is the evidence chain that makes verdicts defensible.
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+const { normalizeUrl, matchRoute, RouteIndex } = require("./route-matcher");
+
+/**
+ * Build the Reality Proof Graph from static + runtime data
+ */
+function buildProofGraph(options = {}) {
+  const {
+    serverRoutes = [],
+    clientCalls = [],
+    uiBindings = [],
+    runtimeRequests = [],
+    runtimeActions = [],
+  } = options;
+
+  const nodes = [];
+  const edges = [];
+  const nodeMap = new Map();
+
+  // 1. Add server route nodes
+  for (const route of serverRoutes) {
+    const node = {
+      id: route.id,
+      type: "SERVER_ROUTE",
+      label: `${route.methods.join("/")} ${route.canonicalPath}`,
+      data: {
+        methods: route.methods,
+        path: route.canonicalPath,
+        confidence: route.confidence,
+        handler: route.handler,
+      },
+    };
+    nodes.push(node);
+    nodeMap.set(route.id, node);
+    
+    // Index by canonical path for matching
+    nodeMap.set(`route:${route.canonicalPath}`, node);
+  }
+
+  // 2. Add client call nodes
+  const routeIndex = new RouteIndex(serverRoutes);
+  
+  for (const call of clientCalls) {
+    const node = {
+      id: call.id,
+      type: "CLIENT_CALL",
+      label: `${call.method} ${call.canonicalPath || call.urlTemplate}`,
+      data: {
+        kind: call.kind,
+        method: call.method,
+        path: call.canonicalPath,
+        urlTemplate: call.urlTemplate,
+        confidence: call.confidence,
+        runtime: call.runtime,
+      },
+    };
+    nodes.push(node);
+    nodeMap.set(call.id, node);
+
+    // Link to server route if matched
+    if (call.canonicalPath) {
+      const match = routeIndex.match(call.canonicalPath, call.method);
+      if (match.matched && match.route) {
+        edges.push({
+          id: `E_${hashShort(call.id + match.route.id)}`,
+          source: call.id,
+          target: match.route.id,
+          type: "CALLS",
+          data: {
+            matchType: match.matchType,
+            confidence: match.confidence,
+          },
+        });
+      } else {
+        // No match - this is a gap
+        node.data.gap = true;
+        node.data.gapReason = "No matching server route";
+      }
+    }
+  }
+
+  // 3. Add UI binding nodes
+  for (const binding of uiBindings) {
+    const node = {
+      id: binding.bindingId,
+      type: "UI_BINDING",
+      label: `${binding.event}: ${binding.labelHint || "unknown"}`,
+      data: {
+        file: binding.file,
+        lines: binding.lines,
+        event: binding.event,
+        labelHint: binding.labelHint,
+      },
+    };
+    nodes.push(node);
+    nodeMap.set(binding.bindingId, node);
+
+    // Link to client calls
+    for (const callId of binding.calls || []) {
+      if (nodeMap.has(callId)) {
+        edges.push({
+          id: `E_${hashShort(binding.bindingId + callId)}`,
+          source: binding.bindingId,
+          target: callId,
+          type: "TRIGGERS",
+          data: {},
+        });
+      }
+    }
+  }
+
+  // 4. Add runtime action nodes and correlate with requests
+  for (const action of runtimeActions) {
+    const node = {
+      id: action.id || `RA_${hashShort(action.selector + action.timestamp)}`,
+      type: "RUNTIME_ACTION",
+      label: `${action.type}: ${action.selector || action.url || "unknown"}`,
+      data: {
+        type: action.type,
+        selector: action.selector,
+        url: action.url,
+        timestamp: action.timestamp,
+        screenshot: action.screenshot,
+      },
+    };
+    nodes.push(node);
+    nodeMap.set(node.id, node);
+
+    // Link action to triggered requests
+    for (const reqId of action.requestIds || []) {
+      edges.push({
+        id: `E_${hashShort(node.id + reqId)}`,
+        source: node.id,
+        target: reqId,
+        type: "TRIGGERED",
+        data: {},
+      });
+    }
+  }
+
+  // 5. Add runtime request nodes and correlate with client calls
+  for (const req of runtimeRequests) {
+    const nodeId = req.id || `RR_${hashShort(req.url + req.method + req.timestamp)}`;
+    const normalizedPath = normalizeUrl(req.url);
+
+    const node = {
+      id: nodeId,
+      type: "RUNTIME_REQUEST",
+      label: `${req.method} ${normalizedPath} → ${req.status}`,
+      data: {
+        method: req.method,
+        url: req.url,
+        normalizedPath,
+        status: req.status,
+        timestamp: req.timestamp,
+        duration: req.duration,
+        failed: req.status >= 400,
+      },
+    };
+    nodes.push(node);
+    nodeMap.set(nodeId, node);
+
+    // Link to matching client call
+    const matchingCall = clientCalls.find(c => {
+      if (!c.canonicalPath) return false;
+      const callPath = c.canonicalPath;
+      const reqPath = normalizedPath;
+      
+      // Exact match or dynamic match
+      if (callPath === reqPath) return true;
+      
+      // Check if call has params that could match
+      if (callPath.includes("{")) {
+        const regex = new RegExp(
+          "^" + callPath.replace(/\{[^}]+\}/g, "[^/]+") + "$"
+        );
+        return regex.test(reqPath);
+      }
+      return false;
+    });
+
+    if (matchingCall) {
+      edges.push({
+        id: `E_${hashShort(matchingCall.id + nodeId)}`,
+        source: matchingCall.id,
+        target: nodeId,
+        type: "RUNTIME_PROOF",
+        data: {
+          status: req.status,
+          proved: req.status < 400 ? "exists" : "failed",
+        },
+      });
+
+      // Also link to server route
+      const routeMatch = routeIndex.match(normalizedPath, req.method);
+      if (routeMatch.matched && routeMatch.route) {
+        edges.push({
+          id: `E_${hashShort(nodeId + routeMatch.route.id)}`,
+          source: nodeId,
+          target: routeMatch.route.id,
+          type: "SERVED_BY",
+          data: {
+            status: req.status,
+          },
+        });
+      }
+    } else {
+      // Unmapped request - didn't come from static extraction
+      node.data.unmapped = true;
+    }
+  }
+
+  return {
+    nodes,
+    edges,
+    stats: {
+      serverRoutes: serverRoutes.length,
+      clientCalls: clientCalls.length,
+      uiBindings: uiBindings.length,
+      runtimeRequests: runtimeRequests.length,
+      runtimeActions: runtimeActions.length,
+      totalNodes: nodes.length,
+      totalEdges: edges.length,
+      gaps: nodes.filter(n => n.data?.gap).length,
+      unmapped: nodes.filter(n => n.data?.unmapped).length,
+    },
+  };
+}
+
+/**
+ * Find gaps in the proof graph (missing links)
+ */
+function findProofGaps(graph) {
+  const gaps = [];
+
+  for (const node of graph.nodes) {
+    // Client calls with no server route match
+    if (node.type === "CLIENT_CALL" && node.data?.gap) {
+      gaps.push({
+        type: "MISSING_ROUTE",
+        severity: node.data.confidence === "high" ? "BLOCK" : "WARN",
+        node,
+        reason: node.data.gapReason,
+      });
+    }
+
+    // Runtime requests that 404'd
+    if (node.type === "RUNTIME_REQUEST" && node.data?.status === 404) {
+      gaps.push({
+        type: "RUNTIME_404",
+        severity: "BLOCK",
+        node,
+        reason: `Runtime request to ${node.data.normalizedPath} returned 404`,
+      });
+    }
+
+    // Runtime requests that are unmapped (not from static extraction)
+    if (node.type === "RUNTIME_REQUEST" && node.data?.unmapped && node.data?.status < 400) {
+      gaps.push({
+        type: "UNMAPPED_REQUEST",
+        severity: "INFO",
+        node,
+        reason: `Runtime saw ${node.data.method} ${node.data.normalizedPath} not found in static extraction`,
+      });
+    }
+  }
+
+  // UI bindings that don't trigger any network activity
+  const uiBindingNodes = graph.nodes.filter(n => n.type === "UI_BINDING");
+  for (const binding of uiBindingNodes) {
+    const outEdges = graph.edges.filter(e => e.source === binding.id);
+    if (outEdges.length === 0) {
+      gaps.push({
+        type: "DEAD_UI_CANDIDATE",
+        severity: "WARN",
+        node: binding,
+        reason: `UI binding ${binding.data.event} on "${binding.data.labelHint || "unknown"}" has no detected network calls`,
+      });
+    }
+  }
+
+  return gaps;
+}
+
+/**
+ * Generate findings from proof graph gaps
+ */
+function generateProofFindings(graph, gaps) {
+  const findings = [];
+
+  for (const gap of gaps) {
+    if (gap.type === "MISSING_ROUTE") {
+      findings.push({
+        id: `F_ROUTE_MISSING_${hashShort(gap.node.id)}`,
+        detectorId: "D_ROUTE_MISSING",
+        severity: gap.severity,
+        category: "Routes",
+        scope: gap.node.data?.runtime || "client",
+        title: `Client calls ${gap.node.data?.method} ${gap.node.data?.path} but no server route exists`,
+        why: "AI frequently invents endpoints. This will cause errors in production.",
+        confidence: gap.node.data?.confidence || "medium",
+        evidence: [{
+          id: `E_${hashShort(gap.node.id)}`,
+          kind: "file",
+          reason: gap.reason,
+        }],
+        proofNode: gap.node.id,
+      });
+    }
+
+    if (gap.type === "RUNTIME_404") {
+      findings.push({
+        id: `F_RUNTIME_404_${hashShort(gap.node.id)}`,
+        detectorId: "D_ROUTE_MISSING",
+        severity: "BLOCK",
+        category: "Routes",
+        scope: "runtime",
+        title: `Runtime 404: ${gap.node.data?.method} ${gap.node.data?.normalizedPath}`,
+        why: "Runtime proof shows this endpoint does not exist.",
+        confidence: "high",
+        evidence: [{
+          id: `E_${hashShort(gap.node.id)}`,
+          kind: "request",
+          url: gap.node.data?.url,
+          httpStatus: gap.node.data?.status,
+          reason: gap.reason,
+        }],
+        proofNode: gap.node.id,
+      });
+    }
+
+    if (gap.type === "DEAD_UI_CANDIDATE") {
+      findings.push({
+        id: `F_DEAD_UI_${hashShort(gap.node.id)}`,
+        detectorId: "D_DEAD_CLICK_NO_EFFECT",
+        severity: gap.severity,
+        category: "DeadUI",
+        scope: "client",
+        title: `Potential dead UI: ${gap.node.data?.event} on "${gap.node.data?.labelHint || "button"}"`,
+        why: "UI element has a handler but no detected network call. May be dead code.",
+        confidence: "low",
+        evidence: [{
+          id: `E_${hashShort(gap.node.id)}`,
+          kind: "file",
+          file: gap.node.data?.file,
+          lines: gap.node.data?.lines,
+          reason: gap.reason,
+        }],
+        proofNode: gap.node.id,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Serialize proof graph for output
+ */
+function serializeProofGraph(graph) {
+  return {
+    schemaVersion: "2.0.0",
+    timestamp: new Date().toISOString(),
+    nodes: graph.nodes,
+    edges: graph.edges,
+    stats: graph.stats,
+  };
+}
+
+/**
+ * Merge runtime data into existing proof graph
+ */
+function mergeRuntimeProof(graph, runtimeReport) {
+  const { requests = [], actions = [], auth = {} } = runtimeReport;
+
+  // Add runtime nodes and edges
+  const runtimeGraph = buildProofGraph({
+    serverRoutes: [],
+    clientCalls: [],
+    uiBindings: [],
+    runtimeRequests: requests,
+    runtimeActions: actions,
+  });
+
+  // Merge nodes (avoid duplicates)
+  const existingIds = new Set(graph.nodes.map(n => n.id));
+  for (const node of runtimeGraph.nodes) {
+    if (!existingIds.has(node.id)) {
+      graph.nodes.push(node);
+    }
+  }
+
+  // Merge edges
+  const existingEdgeIds = new Set(graph.edges.map(e => e.id));
+  for (const edge of runtimeGraph.edges) {
+    if (!existingEdgeIds.has(edge.id)) {
+      graph.edges.push(edge);
+    }
+  }
+
+  // Update stats
+  graph.stats.runtimeRequests = requests.length;
+  graph.stats.runtimeActions = actions.length;
+  graph.stats.totalNodes = graph.nodes.length;
+  graph.stats.totalEdges = graph.edges.length;
+
+  return graph;
+}
+
+function hashShort(text) {
+  return crypto.createHash("sha256").update(text).digest("hex").slice(0, 12).toUpperCase();
+}
+
+module.exports = {
+  buildProofGraph,
+  findProofGaps,
+  generateProofFindings,
+  serializeProofGraph,
+  mergeRuntimeProof,
+};