sparda-mcp 0.32.0 → 0.62.0

package/README.md

@@ -10,38 +10,58 @@
 
 ---
 
-**A compiler for backend behavior. The LLVM of web applications.**
+<h1 align="center">AI writes. SPARDA proves.</h1>
 
-For twenty years software communicated through APIs. Then AI agents arrived, and the industry's answer was to expose more endpoints (MCP). But an agent doesn't *understand* an application from a list of disconnected tools — and neither can a linter, a debugger, or a deploy gate reason about a codebase they only read line by line.
+**The trust layer for AI-written backends.** SPARDA compiles your backend — routes, database queries, state mutations, guards, side-effects — into one deterministic behavior graph, then **statically proves what can and can't break before you ship**: no unguarded mutation, no broken invariant, no non-atomic aggregate write.
 
-SPARDA compiles your backend — routes, database queries, state mutations, permissions, side-effects — into one language-agnostic, mathematical graph: the **Unified Behavior Graph (UBG)**, serialized as `.sparda/ubg.json` under the **SBIR** specification ([SPARDA Behavior IR](docs/SBIR_SPEC_V1.1.md)). Compile once; then every tool is a simple pass over that graph.
+[![npm](https://img.shields.io/npm/v/sparda-mcp)](https://www.npmjs.com/package/sparda-mcp)
+[![CI](https://github.com/zyx77550/sparda/actions/workflows/ci.yml/badge.svg)](https://github.com/zyx77550/sparda/actions/workflows/ci.yml)
+![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)
+![runtime deps](https://img.shields.io/badge/runtime%20deps-4%20pinned-4c1)
+[![license](https://img.shields.io/badge/license-BUSL--1.1-blue)](./LICENSE)
+
+100% local · deterministic · zero API key · no cloud account. It fails loudly on a real risk, and when it can only see part of your app it says **PROVEN (PARTIAL)** — never a false green.
+
+## 60-second proof
+
+From your Express, FastAPI, Next.js, NestJS or Medusa app — nothing to configure:
+
+```bash
+npx sparda-mcp apocalypse   # prove the tree is safe to deploy — exit 1 on any real risk
+npx sparda-mcp prove        # the whole verdict: proof + coverage + shareable seal
+npx sparda-mcp badge        # a README badge: proven · coverage% · routes
+```
+
+Under the hood it compiles your backend into one language-agnostic graph — the **Unified Behavior Graph (UBG)**, serialized as `.sparda/ubg.json` under the **SBIR** specification ([SPARDA Behavior IR](docs/SBIR_SPEC_V1.1.md)) — and every command is a pass over that graph.
 
 > [!IMPORTANT]  
-> **The 3700-Route Proof:** In our latest stress-test (v0.26.0), SPARDA successfully compiled and proved **3700+ routes** from elite open-source monsters (Next.js *Dub*, NestJS *Immich*, *MedusaJS*, and GitHub's OpenAPI) in **< 2.2 seconds** per repo, with zero crashes. It natively resolves deep Dependency Injection, external controllers, and Next.js handlers.
+> **The Route-Compilation Proof — reproduce it yourself.** SPARDA compiles real open-source monsters to their behavior graph with **zero crashes**, each in **≈1–2 seconds**: Next.js *Dub* (579 routes), NestJS *Immich* (281), *MedusaJS* (477). It natively resolves deep Dependency Injection, external controllers, and Next.js handlers. One command clones them and re-measures on your machine:
+> ```bash
+> node bench/repro.mjs        # → bench/route-proof.json
+> ```
+> Honesty first: *compiling* a route is a parser result (the number above); *proving* it safe is a separate per-repo verdict — and most real apps come back **NOT_PROVEN**, which is the true state, not a failure. (Our full 25-repo corpus stress compiles **3,565 routes** at ~150 routes/s; that one needs the corpus checked out.)
 
 **What the graph unlocks — 100% local, deterministic, zero runtime dependencies, zero API key:**
 
 | Command | What it does |
 |---|---|
-| **`ubg`** | Compile the codebase to its behavior graph (Express · FastAPI · Next.js natively; **any** stack via OpenAPI) |
+| **`prove`** | *The whole trust verdict in one gesture* — proof + coverage + a shareable seal (`--json` / `--markdown`) |
 | **`apocalypse`** | *Prove the deploy* — no guard, invariant, transaction or aggregate boundary can be broken (SARIF + CI gate) |
+| **`heal`** | *Self-heal, **proven*** — the gate Copilot Autofix doesn't have: a fix ships **only if** replay matches, `verify` still passes, and `apocalypse` finds no new risk / no dropped guard. Whoever wrote the fix, the machine judges it. |
+| **`badge`** | *The shareable artifact* — a self-contained SVG badge + README snippet (verdict · coverage · routes) |
+| **`dossier`** | *The public report* — one self-contained HTML page: verdict, risks, and SPARDA's own blind spots |
+| **`ubg`** | Compile the codebase to its behavior graph (Express · FastAPI · Next.js · NestJS · Medusa natively; **any** stack via OpenAPI) |
 | **`timeless`** | *Time-travel* — record a production request, replay it byte-identically, export the bug as a test |
-| **`heal`** | *Self-heal, proven* — bug → fix → the machine proves the fix is correct and breaks nothing |
 | **`mirror`** | *Execute the graph* — serve the compiled behavior over HTTP with no framework and no source |
-| **`openapi`** | *Emit the standard* — produce an OpenAPI 3.1 spec from the graph |
-| **`verify`** | *Prove the compiler's own laws* (determinism, soundness, round-trip) on your app |
-| **`init` / `dev`** | Expose the graph to AI clients as a live MCP server (+ Twin, Immune, Evolution runtime layer) |
+| **`init` / `dev`** | *Runtime, optional* — expose the graph to AI clients as a live MCP server (+ Twin, Immune, Evolution) |
 
-```bash
-npx sparda-mcp ubg          # compile your backend → .sparda/ubg.json
-npx sparda-mcp apocalypse   # prove the current tree is safe to deploy
-```
-
-No cloud account. No server to host. Exposing raw APIs to AI is the old way — SPARDA compiles the whole system's behavior, then proves, replays, heals, and serves it.
+The prover is the product. The MCP server is one *output* of the graph, not the point — SPARDA compiles the whole system's behavior, then proves, replays, heals, and (optionally) serves it.
 
 **Nomenclature:** **SBIR** is the specification (the format, like "JSON"); **UBG** is the compiled graph itself (the artifact, `ubg.json`). The MCP server is one *output* of the graph, not the product.
 
-## Quickstart
+## Optional: expose the graph to AI clients (MCP runtime)
+
+Beyond proving, SPARDA can turn your running app into a live MCP server — the graph, executable, with write-safety and an immune layer. This is optional and separate from the prover above.
 
 1. **Scan + inject** — run once, from your app's directory:
    ```bash

package/demo-app/.sparda/immunity.json

@@ -0,0 +1 @@
+{"v":"imm1","proven":false,"surfaceOnly":true,"coverage":1,"blindHigh":0,"routes":[{"behaviorHash":"bh1_13969839d8a18d54aa0342618e56db6a","pol":121,"exposed":[]},{"behaviorHash":"bh1_2daf8a2b1b0ed393d443991a2b0700f6","pol":121,"exposed":[]},{"behaviorHash":"bh1_58fbf5ac38b6d71abc7204921de6b957","pol":121,"exposed":[]},{"behaviorHash":"bh1_58fbf5ac38b6d71abc7204921de6b957","pol":121,"exposed":[]},{"behaviorHash":"bh1_cc6788289c612af85b8d215b5bdf9b28","pol":121,"exposed":[]}],"posture":{"auth":{"protected":0,"exposed":0,"na":5},"atomicity":{"protected":0,"exposed":0,"na":5},"reversibility":{"protected":0,"exposed":0,"na":5},"validation":{"protected":0,"exposed":0,"na":5},"aggregate":{"protected":0,"exposed":0,"na":5}},"bytes":5}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.32.0",
+  "version": "0.62.0",
   "mcpName": "io.github.zyx77550/sparda-mcp",
   "description": "Compile backends to behavior graphs. Statically prove security, simulate APIs, and replay bugs.",
   "type": "module",
@@ -17,13 +17,18 @@
   },
   "scripts": {
     "test": "vitest run",
+    "prepublishOnly": "vitest run",
+    "corpus": "node scripts/corpus-oracle.mjs",
+    "corpus:update": "node scripts/corpus-oracle.mjs --update",
     "test:router": "node tests/router-selftest.cjs",
     "test:all": "vitest run && node tests/router-selftest.cjs",
     "coverage": "vitest run --coverage",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write \"**/*.{js,cjs,mjs}\"",
-    "format:check": "prettier --check \"**/*.{js,cjs,mjs}\""
+    "format:check": "prettier --check \"**/*.{js,cjs,mjs}\"",
+    "bench:check": "node bench/check-readme.mjs",
+    "mutation": "node tests/mutation/run.mjs"
   },
   "files": [
     "src",

package/src/commands/apocalypse.js

@@ -43,9 +43,10 @@ export async function runApocalypse(opts) {
   }
 
   const findings = [...staticFindings, ...diffFindings];
-  const verdict = verdictOf(findings, canonical);
   // the honesty companion: where does the proof stop? (see `sparda blindspots`)
   const blind = surveyBlindspots(canonical, report);
+  // coverage feeds the verdict: a clean app that resolved almost nothing is SURFACE, not PROVEN
+  const verdict = verdictOf(findings, canonical, { coverage: blind.coverage.ratio });
 
   if (opts.sarif) {
     const sarifPath = path.join(opts.cwd, '.sparda', 'apocalypse.sarif');

package/src/commands/badge.js

@@ -0,0 +1,111 @@
+// commands/badge.js — the shareable artifact (URGENT-ADOPTION J3-4). The move that converts a
+// download into a star (Codecov/Lighthouse): the result is a badge the user pins proudly in
+// their README. A self-contained SVG (no external fetch — the product's zero-infra ethos) plus
+// a paste-ready markdown block. The verdict word comes from the SAME source as `prove`
+// (verdictState), so the public badge can NEVER over-claim: a 23%-resolved app reads PARTIAL,
+// never a bare PROVEN. `--out <file>` redirects the SVG; `--json` emits the badge data for CI.
+import fs from 'node:fs';
+import path from 'node:path';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { checkGraph, verdictOf, badgeFor } from '../ubg/apocalypse.js';
+import { surveyBlindspots } from '../ubg/blindspots.js';
+
+export async function runBadge(opts) {
+  const { graph, report } = compileUBG(opts.cwd, { write: false });
+  const canonical = canonicalizeGraph(graph);
+  const { findings } = checkGraph(canonical);
+  const blind = surveyBlindspots(canonical, report);
+  const verdict = verdictOf(findings, canonical, { coverage: blind.coverage.ratio });
+  const cov = Math.round(blind.coverage.ratio * 100);
+  const { state, message, color } = badgeFor(verdict, { coverage: blind.coverage.ratio });
+
+  const svg = renderBadge('SPARDA', message, color);
+  const outPath = opts.out
+    ? path.resolve(opts.cwd, opts.out)
+    : path.join(opts.cwd, '.sparda', 'badge.svg');
+
+  const data = {
+    verdict: state,
+    coverage: cov,
+    routes: report.routes,
+    guards: verdict.guards,
+    guardsVerified: verdict.guardsVerified,
+    findings: findings.filter((f) => !f.advisory).length,
+    color,
+    message,
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify({ ...data, svgPath: rel(outPath, opts.cwd) }, null, 2));
+    return { data };
+  }
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, svg);
+
+  const relSvg = rel(outPath, opts.cwd);
+  // shields.io endpoint alternative — same values, for users who prefer a hosted badge
+  const shields = `https://img.shields.io/badge/SPARDA-${encodeURIComponent(message)}-${color.slice(1)}`;
+
+  console.log(
+    `\n✓ Badge written: ${relSvg}  (${state} · ${report.routes} routes · ${cov}% coverage)`,
+  );
+  console.log(`\nPaste into your README:\n`);
+  console.log(`  ![SPARDA](./${relSvg})`);
+  console.log(`\nOr use the shields.io endpoint (no committed file):\n`);
+  console.log(`  ![SPARDA](${shields})`);
+  console.log('');
+  return { data, svgPath: relSvg };
+}
+
+// A shields-style two-part "flat" badge, fully self-contained. Deterministic width from a
+// Verdana-ish per-char estimate — pixel-perfection is not the point, a clean readable badge is.
+function renderBadge(label, message, color) {
+  const lw = textWidth(label);
+  const mw = textWidth(message);
+  const PAD = 6;
+  const lWidth = lw + 2 * PAD;
+  const mWidth = mw + 2 * PAD;
+  const total = lWidth + mWidth;
+  const h = 20;
+  // ×10 coords: shields renders text at a 10× scale then scales down, for crisp positioning
+  const lx = (lWidth / 2) * 10;
+  const mx = (lWidth + mWidth / 2) * 10;
+  const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${total}" height="${h}" role="img" aria-label="${esc(label)}: ${esc(message)}">
+  <title>${esc(label)}: ${esc(message)}</title>
+  <linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient>
+  <clipPath id="r"><rect width="${total}" height="${h}" rx="3" fill="#fff"/></clipPath>
+  <g clip-path="url(#r)">
+    <rect width="${lWidth}" height="${h}" fill="#555"/>
+    <rect x="${lWidth}" width="${mWidth}" height="${h}" fill="${color}"/>
+    <rect width="${total}" height="${h}" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="110" text-rendering="geometricPrecision">
+    <text x="${lx}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="${lw * 10}">${esc(label)}</text>
+    <text x="${lx}" y="140" transform="scale(.1)" textLength="${lw * 10}">${esc(label)}</text>
+    <text x="${mx}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="${mw * 10}">${esc(message)}</text>
+    <text x="${mx}" y="140" transform="scale(.1)" textLength="${mw * 10}">${esc(message)}</text>
+  </g>
+</svg>
+`;
+}
+
+// Verdana 11px approximate advance widths — wide enough to avoid clipping, narrow enough to
+// look tight. Digits/lowercase ~7, uppercase ~8.5, punctuation/space narrower.
+function textWidth(s) {
+  let w = 0;
+  for (const ch of s) {
+    if (/[A-Z]/.test(ch)) w += 8.5;
+    else if (/[a-z0-9]/.test(ch)) w += 7;
+    else if (ch === ' ') w += 4;
+    else if (ch === '·') w += 5;
+    else if (ch === '%') w += 11;
+    else w += 5;
+  }
+  return Math.ceil(w);
+}
+
+const rel = (abs, cwd) =>
+  abs.startsWith(cwd) ? abs.slice(cwd.length + 1).replaceAll('\\', '/') : abs;

package/src/commands/dossier.js

@@ -9,7 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { compileUBG } from '../ubg/compile.js';
 import { canonicalizeGraph } from '../ubg/schema.js';
-import { checkGraph, verdictOf } from '../ubg/apocalypse.js';
+import { checkGraph, verdictOf, verdictState } from '../ubg/apocalypse.js';
 import { surveyBlindspots } from '../ubg/blindspots.js';
 import { buildCapsule } from '../ubg/immunity.js';
 import { AXES, POLARITY_SYMBOL, exposedAxes } from '../ubg/polarity.js';
@@ -19,9 +19,9 @@ export async function runDossier(opts) {
   const compiled = compileUBG(opts.cwd, { write: false, openapi: opts.openapi });
   const canonical = canonicalizeGraph(compiled.graph);
   const { findings, polarity } = checkGraph(canonical);
-  const verdict = verdictOf(findings, canonical);
   const capsule = buildCapsule(canonical);
   const blindspots = surveyBlindspots(canonical, compiled.report);
+  const verdict = verdictOf(findings, canonical, { coverage: blindspots.coverage.ratio });
 
   const data = {
     app: path.basename(path.resolve(opts.cwd)) || 'app',
@@ -32,6 +32,8 @@ export async function runDossier(opts) {
     edges: canonical.edges.length,
     provable: verdict.provable,
     proven: verdict.provable && verdict.clean,
+    state: verdictState(verdict),
+    coverage: Math.round(blindspots.coverage.ratio * 100),
     surfaceOnly: verdict.surfaceOnly,
     guards: verdict.guards,
     guardsVerified: verdict.guardsVerified,
@@ -54,12 +56,23 @@ export async function runDossier(opts) {
   const outPath = path.join(opts.cwd, '.sparda', 'dossier.html');
   fs.mkdirSync(path.dirname(outPath), { recursive: true });
   atomicWrite(outPath, html);
+  const WORD = {
+    PROVEN: '✓ PROVEN',
+    PARTIAL: '◑ PROVEN (PARTIAL)',
+    RISKY: '⚠ RISKY',
+    NOT_PROVEN: '✗ NOT PROVEN',
+    SURFACE: '◐ SURFACE ONLY',
+    NO_PROOF: '✗ NO PROOF',
+  };
   console.log(
-    `DOSSIER — ${data.routes} route(s), verdict ${data.proven ? '✓ PROVEN' : data.provable ? '✗ NOT PROVEN' : '✗ NO PROOF'}`,
+    `DOSSIER — ${data.routes} route(s) · coverage ${data.coverage}% · verdict ${WORD[data.state] ?? data.state}`,
   );
   console.log(
     `  written: .sparda/dossier.html (${html.length} bytes, self-contained) — open it in any browser.`,
   );
+  console.log(
+    `  📸 one screenshotable page — the verdict, the risks, and SPARDA's own blind spots. Share it.`,
+  );
   console.log(
     `  ephemeral: .sparda/ is gitignored, so it vanishes on \`sparda remove\` — save it to keep it.`,
   );
@@ -83,21 +96,43 @@ const SEV_COLOR = {
 };
 
 export function renderDossierHTML(d) {
-  const verdictClass = d.proven ? 'ok' : d.surfaceOnly ? 'warn' : 'bad';
-  const verdictText = d.proven
-    ? 'PROVEN'
-    : d.surfaceOnly
-      ? 'SURFACE ONLY — routes seen, no behavior resolved'
-      : d.provable
-        ? 'NOT PROVEN'
-        : 'NO PROOF — the app’s routes could not be read';
-  const verdictLede = d.proven
-    ? 'No declared guard, invariant, transaction or aggregate boundary can be broken by this code.'
-    : d.surfaceOnly
-      ? 'SPARDA saw the route surface but no state or side-effects behind it — there was nothing to prove. This is NOT a clean bill of health (a spec, or an effect-resolution gap).'
-      : d.provable
-        ? `SPARDA found ${d.counts.critical} critical and ${d.counts.high} high risk(s) that must be fixed before this ships.`
-        : 'SPARDA could not see this app’s route surface — this is not a clean bill of health.';
+  // The verdict word comes from the shared state (single source of truth). Back-compat: derive
+  // it from the older booleans when a caller passes no `state` (e.g. legacy tests). PARTIAL is
+  // honest — a clean proof over only part of the surface never reads as a bare PROVEN.
+  const state =
+    d.state ??
+    (!d.provable
+      ? 'NO_PROOF'
+      : d.surfaceOnly
+        ? 'SURFACE'
+        : d.proven
+          ? 'PROVEN'
+          : 'NOT_PROVEN');
+  const verdictClass =
+    state === 'PROVEN'
+      ? 'ok'
+      : state === 'PARTIAL' || state === 'SURFACE' || state === 'RISKY'
+        ? 'warn'
+        : 'bad';
+  const verdictText = {
+    PROVEN: 'PROVEN',
+    PARTIAL: 'PROVEN (PARTIAL)',
+    RISKY: 'RISKY',
+    SURFACE: 'SURFACE ONLY — routes seen, no behavior resolved',
+    NOT_PROVEN: 'NOT PROVEN',
+    NO_PROOF: 'NO PROOF — the app’s routes could not be read',
+  }[state];
+  const verdictLede = {
+    PROVEN:
+      'No declared guard, invariant, transaction or aggregate boundary can be broken by this code.',
+    PARTIAL: `SPARDA proved the resolved surface (${d.coverage ?? Math.round((d.blindspots?.coverage?.ratio ?? 1) * 100)}%) with 0 violations — but the rest of the app was invisible to static analysis and is UNPROVEN, not safe.`,
+    RISKY: `SPARDA found no critical/high risk, but ${d.counts.medium + d.counts.info} finding(s) to review before this is a clean proof.`,
+    SURFACE:
+      'SPARDA saw the route surface but no state or side-effects behind it — there was nothing to prove. This is NOT a clean bill of health (a spec, or an effect-resolution gap).',
+    NOT_PROVEN: `SPARDA found ${d.counts.critical} critical and ${d.counts.high} high risk(s) that must be fixed before this ships.`,
+    NO_PROOF:
+      'SPARDA could not see this app’s route surface — this is not a clean bill of health.',
+  }[state];
 
   const cell = (v) => {
     const cls = v === -1 ? 'neg' : v === 1 ? 'pos' : 'na';
@@ -164,6 +199,9 @@ export function renderDossierHTML(d) {
   .top{display:flex;justify-content:space-between;align-items:baseline;border-bottom:1px solid var(--line);padding-bottom:16px;font-family:var(--mono);font-size:13px;color:var(--faint)}
   .top b{color:var(--ink);letter-spacing:.12em}
   .hero{padding:48px 0 32px}
+  .verdict-row{display:flex;align-items:center;gap:16px;flex-wrap:wrap}
+  .cov{font-family:var(--mono);font-size:14px;color:var(--faint);padding:10px 18px;border:1px solid var(--line);border-radius:12px;background:var(--panel)}
+  .cov b{color:var(--ink);font-size:18px}
   .stamp{display:inline-flex;align-items:center;gap:12px;font-family:var(--mono);font-weight:700;font-size:16px;padding:12px 24px;border-radius:12px;border:1.5px solid;letter-spacing:.03em;box-shadow:0 4px 12px -4px color-mix(in oklch,currentColor 30%,transparent)}
   .stamp .dot{width:8px;height:8px;border-radius:50%;background:currentColor;box-shadow:0 0 0 4px color-mix(in oklch,currentColor 22%,transparent)}
   .ok{color:var(--green);border-color:var(--green);background:color-mix(in oklch,var(--green) 10%,transparent)}
@@ -198,13 +236,16 @@ export function renderDossierHTML(d) {
   <div class="top"><b>SPARDA</b><span>AI writes. SPARDA proves.</span></div>
 
   <section class="hero">
-    <span class="stamp ${verdictClass}"><span class="dot"></span>${esc(verdictText)}</span>
+    <div class="verdict-row">
+      <span class="stamp ${verdictClass}"><span class="dot"></span>${esc(verdictText)}</span>
+      <span class="cov" title="share of the app's behavior SPARDA resolved and reasoned about">coverage&nbsp;<b>${b.coverage ? (b.coverage.ratio * 100).toFixed(0) : (d.coverage ?? 0)}%</b></span>
+    </div>
     <p>${esc(verdictLede)}</p>
     <div class="stats">
       ${statCard(d.routes, 'routes')}
+      ${statCard((b.coverage.ratio * 100).toFixed(0) + '%', 'behavior resolved')}
       ${statCard(d.nodes, 'graph nodes')}
       ${statCard(d.tables, 'data tables')}
-      ${statCard(d.capsuleBytes + ' B', 'safety capsule')}
       ${statCard(esc(d.framework), 'framework')}
     </div>
     ${

package/src/commands/immunize.js

@@ -50,6 +50,11 @@ export async function runImmunize(opts) {
       ? '✓ PROVEN'
       : '✗ NOT PROVEN';
   console.log(`  verdict: ${verdictText}` + (exposed ? ` — exposed: ${exposed}` : ''));
+  console.log(
+    `  coverage: ${(capsule.coverage * 100).toFixed(0)}% of observed behavior resolved` +
+      (capsule.blindHigh ? ` · ${capsule.blindHigh} high-risk blind spot(s)` : '') +
+      ` — the proof's confidence, frozen with it`,
+  );
   console.log(
     `  written: .sparda/immunity.json (${wire} bytes on the wire) — portable, offline, lookup by behaviorHash`,
   );

package/src/commands/prove.js

@@ -0,0 +1,193 @@
+// commands/prove.js — THE one gesture. The whole trust picture in a single command:
+// the verdict (apocalypse), what SPARDA could NOT see (blindspots coverage), the
+// portable safety seal (immunity capsule), and the behavior fingerprint — assembled,
+// not scattered across six commands. Every piece is an existing organ; prove only
+// composes and presents them, so there is exactly one source of truth per fact.
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { checkGraph, verdictOf, verdictState, badgeFor } from '../ubg/apocalypse.js';
+import { surveyBlindspots } from '../ubg/blindspots.js';
+import { buildCapsule } from '../ubg/immunity.js';
+import { fingerprintGraph } from '../ubg/fingerprint.js';
+import { suggestAppDirs } from '../detect.js';
+
+export async function runProve(opts) {
+  const { graph, report } = compileUBG(opts.cwd, { write: false, openapi: opts.openapi });
+  const canonical = canonicalizeGraph(graph);
+
+  const { findings, obligations } = checkGraph(canonical);
+  const blind = surveyBlindspots(canonical, report);
+  const verdict = verdictOf(findings, canonical, { coverage: blind.coverage.ratio });
+  const capsule = buildCapsule(canonical);
+  const prints = fingerprintGraph(canonical);
+  // one app-level seal: a content address over every route's behavior hash — the same
+  // behavior, in any repo, yields the same seal (the genome's join key, made visible).
+  const seal =
+    'seal_' +
+    crypto
+      .createHash('sha256')
+      .update(prints.map((p) => p.behaviorHash ?? '·').join('\n'))
+      .digest('hex')
+      .slice(0, 16);
+
+  const state = verdictState(verdict);
+
+  const summary = {
+    app: path.basename(path.resolve(opts.cwd)) || 'app',
+    verdict: state,
+    routes: report.routes,
+    guards: verdict.guards,
+    guardsVerified: verdict.guardsVerified,
+    obligations,
+    coverage: blind.coverage.ratio,
+    blindSpots: blind.surface,
+    blindHigh: blind.byRisk.critical + blind.byRisk.high,
+    findings: findings.map((f) => ({
+      rule: f.rule,
+      severity: f.severity,
+      entrypoint: f.entrypoint,
+    })),
+    counts: verdict.counts,
+    capsuleBytes: capsule.bytes,
+    behaviors: new Set(prints.map((p) => p.behaviorHash).filter(Boolean)).size,
+    seal,
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return gate(verdict);
+  }
+
+  // --markdown: a sticky-PR-comment body (used by the GitHub Action's `prove` mode). The
+  // badge renders inline via shields.io — the ONE place a hosted URL is right, because a
+  // GitHub comment can't embed a repo-local SVG. Same verdict word/colour as `badge` and the
+  // CLI (badgeFor), so the PR comment can never over-claim.
+  if (opts.markdown) {
+    console.log(
+      proveMarkdown({ verdict, report, findings, coverage: blind.coverage.ratio, seal }),
+    );
+    return gate(verdict);
+  }
+
+  const ICON = {
+    PROVEN: '✓',
+    PARTIAL: '◑',
+    NOT_PROVEN: '✗',
+    RISKY: '⚠',
+    SURFACE: '◐',
+    NO_PROOF: '✗',
+  };
+  const HEAD = {
+    PROVEN: 'PROVEN',
+    PARTIAL: 'PROVEN (PARTIAL)',
+    NOT_PROVEN: 'NOT PROVEN',
+    RISKY: 'RISKY',
+    SURFACE: 'SURFACE ONLY',
+    NO_PROOF: 'NO PROOF',
+  };
+
+  const cov = `${(blind.coverage.ratio * 100).toFixed(0)}%`;
+  console.log(`\nSPARDA · ${summary.app}`);
+  console.log('─'.repeat(46));
+  console.log(`${ICON[state]} ${HEAD[state]}`);
+
+  if (state === 'PROVEN') {
+    console.log(`  ${obligations} obligations discharged · 0 violations`);
+  } else if (state === 'PARTIAL') {
+    console.log(
+      `  ${obligations} obligations discharged · 0 violations — but only ${cov} of the surface resolved; the rest is UNPROVEN, not safe`,
+    );
+  } else if (state === 'NO_PROOF') {
+    console.log(
+      `  0 routes resolved — nothing to prove (a parser-coverage gap, not a pass)`,
+    );
+    const dirs = suggestAppDirs(opts.cwd);
+    if (dirs.length) {
+      console.log(`  ◐ this looks like a monorepo — the app is in a sub-directory. Try:`);
+      for (const d of dirs.slice(0, 4))
+        console.log(`      cd ${d.dir} && sparda prove   # looks like ${d.framework}`);
+    }
+  } else if (state === 'SURFACE') {
+    console.log(
+      `  ${report.routes} routes seen · coverage ${cov} — not enough state-changing behavior resolved to prove`,
+    );
+  } else {
+    const c = verdict.counts;
+    console.log(
+      `  ${c.critical} critical · ${c.high} high · ${c.medium} medium · ${c.info} info`,
+    );
+    for (const f of findings.slice(0, 5)) {
+      const ep = f.entrypoint.replace(/^entrypoint:/, '');
+      console.log(`    ${sev(f.severity)} ${ep.padEnd(34)} ${labelOf(f.rule)}`);
+    }
+    if (findings.length > 5) console.log(`    … and ${findings.length - 5} more`);
+  }
+
+  console.log(
+    `  ${report.routes} routes · ${verdict.guards} guards (${verdict.guardsVerified} verified) · coverage ${cov}`,
+  );
+  if (blind.surface > 0)
+    console.log(
+      `  ◐ ${blind.surface} blind spots (${summary.blindHigh} high+) — run \`sparda blindspots\``,
+    );
+  console.log(
+    `  ⬡ seal ${seal} · capsule ${capsule.bytes} B · ${summary.behaviors} distinct behaviors`,
+  );
+  console.log('');
+
+  return gate(verdict);
+}
+
+function gate(verdict) {
+  // exit 1 whenever this is not a positive, riskless proof — the CI contract.
+  if (!verdict.safe) process.exitCode = 1;
+}
+
+// The sticky-PR-comment body: the badge (rendered inline via shields.io), the verdict line,
+// the coverage/guards facts, and the top findings. This is the discovery surface — every PR
+// shows the whole team the SPARDA verdict, for free. The badge word/colour comes from
+// badgeFor, so it can never disagree with the CLI or the committed SVG.
+function proveMarkdown({ verdict, report, findings, coverage, seal }) {
+  const { message, color } = badgeFor(verdict, { coverage });
+  const cov = Math.round(coverage * 100);
+  const badge = `https://img.shields.io/badge/SPARDA-${encodeURIComponent(message)}-${color.slice(1)}`;
+  const hard = findings.filter((f) => !f.advisory);
+  const lines = [
+    `### ![SPARDA](${badge})   behavior proof`,
+    '',
+    `\`${report.routes} routes · ${verdict.guards} guards (${verdict.guardsVerified} verified) · coverage ${cov}%\``,
+  ];
+  if (hard.length) {
+    lines.push('', '| severity | route | finding |', '|---|---|---|');
+    for (const f of hard.slice(0, 8))
+      lines.push(
+        `| ${f.severity} | \`${(f.entrypoint ?? '').replace(/^entrypoint:/, '')}\` | ${labelOf(f.rule)} |`,
+      );
+    if (hard.length > 8) lines.push(`| … | | and ${hard.length - 8} more |`);
+  } else {
+    lines.push('', '✅ 0 violations on the resolved surface.');
+  }
+  lines.push(
+    '',
+    `<sub>Proven locally by [SPARDA](https://github.com/zyx77550/sparda) — deterministic, no keys · seal \`${seal}\`</sub>`,
+  );
+  return lines.join('\n');
+}
+
+const sev = (s) => ({ critical: '✗', high: '✗', medium: '⚠', info: '·' })[s] ?? '·';
+
+// human labels for the rule ids, so the seal reads without a decoder ring
+function labelOf(rule) {
+  return (
+    {
+      UNGUARDED_MUTATION: 'unguarded mutation',
+      UNBOUNDED_WRITE_TARGET: 'writes to a request-named table',
+      UNVALIDATED_CONSTRAINED_WRITE: 'unvalidated write to a constrained table',
+      NON_ATOMIC_AGGREGATE_WRITE: 'non-atomic aggregate write',
+      IRREVERSIBLE_OBSERVABLE: 'irreversible external call + state change',
+      AGGREGATE_MEMBER_BYPASS: 'aggregate member touched without its root',
+    }[rule] ?? rule.toLowerCase().replace(/_/g, ' ')
+  );
+}

package/src/commands/review.js

@@ -19,6 +19,7 @@ import { execFileSync } from 'node:child_process';
 import { compileUBG } from '../ubg/compile.js';
 import { canonicalizeGraph, cmp } from '../ubg/schema.js';
 import { checkGraph, diffGraphs, verdictOf } from '../ubg/apocalypse.js';
+import { surveyBlindspots } from '../ubg/blindspots.js';
 
 const ICONS = { critical: '✗', high: '✗', medium: '⚠', info: '·' };
 const err = (message, hint) => Object.assign(new Error(message), { code: 'USER', hint });
@@ -58,11 +59,22 @@ export function reviewGraphs(baseGraph, candidateGraph) {
   const added = [...candEps].filter((e) => !baseEps.has(e)).sort(cmp);
   const removedEps = [...baseEps].filter((e) => !candEps.has(e)).sort(cmp);
 
+  // how much of the changed app SPARDA could actually see — and whether this PR moved
+  // that boundary. A green review over a graph the PR made 20% blinder is not the same
+  // as a green review at full sight; the reviewer must be able to tell them apart.
+  const candCov = surveyBlindspots(candidateGraph).coverage.ratio;
+  const baseCov = surveyBlindspots(baseGraph).coverage.ratio;
+
   return {
-    verdict: verdictOf(findings, candidateGraph),
+    verdict: verdictOf(findings, candidateGraph, { coverage: candCov }),
     obligations,
     findings,
     endpoints: { added, removed: removedEps },
+    coverage: {
+      now: candCov,
+      base: baseCov,
+      delta: Math.round((candCov - baseCov) * 1000) / 1000,
+    },
   };
 }
 
@@ -160,6 +172,18 @@ function renderHuman(r) {
     console.log(`  - removed endpoints: ${endpoints.removed.map(shortEp).join(', ')}`);
   if (!endpoints.added.length && !endpoints.removed.length)
     console.log('  · no endpoints added or removed');
+  if (r.coverage) {
+    const d = r.coverage.delta;
+    const move =
+      d > 0.005
+        ? ` (▲ +${(d * 100).toFixed(0)}%)`
+        : d < -0.005
+          ? ` (▼ ${(d * 100).toFixed(0)}% — harder to see)`
+          : '';
+    console.log(
+      `  · coverage: ${(r.coverage.now * 100).toFixed(0)}% of observed behavior resolved${move}`,
+    );
+  }
 
   if (findings.length) {
     console.log('\n  Behavior risks changed by this diff:');
@@ -191,6 +215,17 @@ function renderMarkdown(r) {
       ? '✓ **PROVEN** — no protection removed, no new risk introduced.'
       : `${v.safe ? '⚠ **RISKY**' : '✗ **NOT PROVEN**'} — ${c.critical} critical, ${c.high} high, ${c.medium} medium, ${c.info} info.`;
   const lines = [`## 🔍 SPARDA semantic review (vs \`${r.base}\`)`, '', head, ''];
+  if (r.coverage) {
+    const pct = (r.coverage.now * 100).toFixed(0);
+    const d = r.coverage.delta;
+    const move =
+      d > 0.005
+        ? ` (▲ +${(d * 100).toFixed(0)}% vs base)`
+        : d < -0.005
+          ? ` (▼ ${(d * 100).toFixed(0)}% vs base — this PR made the app harder to see)`
+          : '';
+    lines.push(`**Coverage:** ${pct}% of observed behavior resolved${move}`, '');
+  }
   if (endpoints.added.length || endpoints.removed.length) {
     lines.push('### Endpoint surface');
     for (const e of endpoints.added) lines.push(`- 🆕 \`${shortEp(e)}\``);