sparda-mcp 0.67.0 → 0.69.0

package/README.md

@@ -21,20 +21,40 @@
 ![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.
+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. And when it can prove it was not even looking at your whole app, it says **PREMISE NOT VERIFIED** and claims nothing at all.
 
 ## 60-second proof
 
 From your Express, FastAPI, Flask, 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 apocalypse   # prove the tree is safe to deploy — exit 1 on any real risk, or on an unverified premise
 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.
 
+## The wedge — catch an AI edit that removes a guard, in the loop
+
+The one thing a text-diff review and a pattern scanner structurally can't do: prove that **this specific edit** dropped a protection the previous version had. `sparda gate` diffs the behavior graph before/after an edit and blocks a regression — deterministic, offline, sub-second, exit 2 (the Claude Code `PostToolUse` contract that stops the agent's edit loop). See it end-to-end in one command, zero setup:
+
+```bash
+npm run wedge     # (from a clone)  — or drive it on your own app with `sparda gate --arm` then `sparda gate --hook`
+```
+
+```
+  1. baseline armed on the guarded code   (POST /admin/delete-user · requireAdmin)
+  2. an AI edit "simplifies" requireAdmin → a pass-through (still compiles, still 200s)
+  3. sparda gate on the edit:
+       ✗ [critical] GUARD_REMOVED — POST /admin/delete-user was guarded in the baseline
+                    and is now reachable without any guard (src/app.js:11)
+     ⏱  ~40 ms · deterministic · offline · no API key
+     ⛔ exit 2 on --hook — Claude Code PostToolUse blocks the edit
+```
+
+**Wire it into Claude Code in one line** — the [plugin](integrations/claude-code-plugin) registers a `PostToolUse` hook that runs `npx -y sparda-mcp gate --hook` after every `Edit`/`Write`, so a guard-removing edit is caught before it lands.
+
 > [!IMPORTANT]  
 > **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:
 >
@@ -48,7 +68,7 @@ Under the hood it compiles your backend into one language-agnostic graph — the
 
 | Command            | What it does                                                                                                                                                                                                                         |
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **`prove`**        | _The whole trust verdict in one gesture_ — proof + coverage + a shareable seal (`--json` / `--markdown`)                                                                                                                             |
+| **`prove`**        | _The whole trust verdict in one gesture_ — proof + coverage + premise check + 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)                                                                                                                                 |
@@ -143,6 +163,8 @@ This command reads the compiled `.sparda/ubg.json` (with zero source code parsin
 - **Non-Atomic Aggregate Write (High)**: Flags when an API writes to multiple tables of the same Consistency Domain (Aggregate) outside a single transaction scope.
 - **Unvalidated Constrained Write (Medium)**: Flags writes into columns with declared invariants (CHECK, NOT NULL, UNIQUE — parsed from your `.sql` DDL **or `schema.prisma`**, Prisma enums included) without prior validation (Zod/Pydantic).
 - **Irreversible Observable Effect (High)**: Flags out-of-process actions (like Stripe charges) that happen alongside state writes without a structural compensation path (like a catch-refund).
+- **Taint Flow Analysis (High)**: Tracks untrusted input variables through the AST to ensure they do not corrupt critical sinks.
+- **Guard Dominance (Medium)**: Proves that top-level security guards cannot be bypassed by nested or overlapping sibling routes.
 - **Aggregate Member Bypass (Info)**: Flags mutating a member table directly without routing through the aggregate root.
 
 To save your current graph as a safe baseline:
@@ -341,7 +363,8 @@ runtime, so the guidance never goes stale.
 ## Supported frameworks
 
 - **Next.js App Router (13/14/15)** — file-based injection. SPARDA creates a catch-all route handler. It natively resolves wrapped handlers (`export const POST = withAuth(h)`) and deep effect chains.
-- **NestJS** — AST-based router injection. Deeply resolves Multi-hop Dependency Injection (Controller → Service → Repository), inherited DI, and `baseUrl`/`paths` imports. Resolves ORM writes: Prisma, Kysely, and TypeORM injected repositories (`@InjectRepository(Entity)` → `this.repo.save()`).
+- **NestJS** — AST-based router injection. Deeply resolves Multi-hop Dependency Injection (Controller → Service → Repository), inherited DI, and `baseUrl`/`paths` imports. Fully supports composite decorators (`applyDecorators`). Resolves ORM writes: Prisma, Kysely, and TypeORM injected repositories (`@InjectRepository(Entity)` → `this.repo.save()`).
+- **Strapi** — Native AST ingestion of Strapi content-types, core controllers, and custom routes.
 - **Express 4/5** (JS/TS, ESM/CJS) — AST-based router injection. Deeply resolves external controllers, Mongoose schemas, barrel re-exports, and inline handlers. Uses dynamic tree-scanning to find non-standard entry points (`bootstrap.ts`, etc).
 - **MedusaJS** — Native AST ingestion of complex e-commerce routing.
 - **Any Backend On Earth (Go, Java, Rails, Laravel)** — Compiles flawlessly from OpenAPI 3.x specs.

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

@@ -1 +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}
+{"v":"imm1","proven":false,"surfaceOnly":true,"coverage":null,"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.67.0",
+  "version": "0.69.0",
   "mcpName": "io.github.zyx77550/sparda-mcp",
   "description": "AI writes. SPARDA proves. A deterministic, offline gate that catches when an AI edit removes a guard, exposes a route, or breaks an invariant — no API key, right in the agent edit loop.",
   "type": "module",
@@ -28,7 +28,8 @@
     "format": "prettier --write \"**/*.{js,cjs,mjs}\"",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs}\"",
     "bench:check": "node bench/check-readme.mjs",
-    "mutation": "node tests/mutation/run.mjs"
+    "mutation": "node tests/mutation/run.mjs",
+    "wedge": "node bench/wedge.mjs"
   },
   "files": [
     "src",

package/src/commands/apocalypse.js

@@ -18,7 +18,8 @@ import {
   verdictState,
   buildProofObjects,
 } from '../ubg/apocalypse.js';
-import { surveyBlindspots } from '../ubg/blindspots.js';
+import { surveyBlindspots, coveragePct } from '../ubg/blindspots.js';
+import { premiseFor, withPremiseGaps } from '../ubg/premise.js';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 
 // version travels with the proof so an audit knows which prover produced it
@@ -69,13 +70,22 @@ export async function runApocalypse(opts) {
   }
 
   const findings = [...staticFindings, ...diffFindings];
+  // THE PREMISE, before the proof. This is the CI gate — the command whose exit code
+  // decides whether a tree ships — so it is the last place that may certify an app whose
+  // route table nobody checked. `premiseFor` keeps the opt-in boundary: the runtime
+  // oracle needs `--probe`, the boot-free convention oracle always runs.
+  const premise = await premiseFor(canonical, report, {
+    cwd: opts.cwd,
+    probe: opts.probe,
+  });
   // the honesty companion: where does the proof stop? (see `sparda blindspots`)
-  const blind = surveyBlindspots(canonical, report);
+  const blind = surveyBlindspots(canonical, withPremiseGaps(report, premise));
   // coverage feeds the verdict: a clean app that resolved almost nothing is SURFACE, not PROVEN;
   // and any high-risk blind spot pulls a bare PROVEN down to PARTIAL (E-047, the giant-test rung)
   const verdict = verdictOf(findings, canonical, {
     coverage: blind.coverage.ratio,
     blindHigh: blind.byRisk.critical + blind.byRisk.high,
+    premiseGaps: premise.available ? premise.gaps.length : 0,
   });
 
   if (opts.sarif) {
@@ -136,6 +146,21 @@ export async function runApocalypse(opts) {
       if (opts.verbose && report.skipped?.length)
         for (const s of report.skipped)
           console.log(`      skipped: ${s.reason}${s.file ? ` (${s.file})` : ''}`);
+    } else if (verdict.premiseUnverified) {
+      // The one negative backed by a source outside SPARDA. It is stated BEFORE the
+      // clean/risky branches on purpose: findings about a subject we did not have are
+      // not the headline, the missing subject is.
+      const witness =
+        premise.oracle === 'convention'
+          ? "the framework's own file conventions"
+          : 'the running app';
+      console.log(
+        `✗ PREMISE NOT VERIFIED — ${premise.gaps.length} route(s) ${witness} serve were NEVER seen by the compiler. Nothing below is a claim about this tree: the proof's subject is incomplete, so no verdict is issued.`,
+      );
+      for (const g of premise.gaps.slice(0, 8))
+        console.log(`      ✗ ${g.method} ${g.path}`);
+      if (premise.gaps.length > 8)
+        console.log(`      … and ${premise.gaps.length - 8} more`);
     } else if (verdict.clean) {
       console.log(
         `✓ PROVEN — ${obligations} obligation(s) discharged, zero violations. No declared guard, invariant, transaction or aggregate boundary can be broken by this tree.`,
@@ -148,16 +173,22 @@ export async function runApocalypse(opts) {
     }
     // Honesty companion: where the proof stops. A green verdict over a graph riddled
     // with blind spots is not omniscience — say so, on the same screen as the verdict.
+    if (premise.available)
+      console.log(
+        premise.oracle === 'convention'
+          ? `  ⚖ premise checked against the framework's file conventions: ${premise.probed} route(s) implied, ${premise.gaps.length} gap(s)`
+          : `  ⚖ premise checked against the running app: ${premise.probed} route(s) probed, ${premise.gaps.length} gap(s)`,
+      );
     if (blind.surface > 0) {
       const hi = blind.byRisk.critical + blind.byRisk.high;
       console.log(
-        `  ◐ blind spots: ${blind.surface} (${hi} high+, ${blind.byRisk.medium} medium, ${blind.byRisk.low} low) · coverage ${(blind.coverage.ratio * 100).toFixed(0)}% — run \`sparda blindspots\` for the map`,
+        `  ◐ blind spots: ${blind.surface} (${hi} high+, ${blind.byRisk.medium} medium, ${blind.byRisk.low} low) · coverage ${coveragePct(blind.coverage.ratio)} — run \`sparda blindspots\` for the map`,
       );
     }
   }
 
   if (!verdict.safe) process.exitCode = 1; // CI gates on this
-  return { verdict, findings, obligations, blindspots: blind };
+  return { verdict, findings, obligations, blindspots: blind, premise };
 }
 
 // SARIF 2.1.0 — GitHub code scanning eats this directly

package/src/commands/badge.js

@@ -9,18 +9,29 @@ 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';
+import { surveyBlindspots, coveragePct } from '../ubg/blindspots.js';
+import { premiseFor, withPremiseGaps } from '../ubg/premise.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);
+  // A badge is the artifact that leaves the repo. It may not read green over an app
+  // whose route table was never checked — that is the one place a false claim travels
+  // furthest and is hardest to retract.
+  const premise = await premiseFor(canonical, report, {
+    cwd: opts.cwd,
+    probe: opts.probe,
+  });
+  const blind = surveyBlindspots(canonical, withPremiseGaps(report, premise));
   const verdict = verdictOf(findings, canonical, {
     coverage: blind.coverage.ratio,
     blindHigh: blind.byRisk.critical + blind.byRisk.high,
+    premiseGaps: premise.available ? premise.gaps.length : 0,
   });
-  const cov = Math.round(blind.coverage.ratio * 100);
+  // null = measured-but-unknown (0/0): the JSON keeps the null, the console says the word
+  const cov =
+    blind.coverage.ratio == null ? null : Math.round(blind.coverage.ratio * 100);
   const { state, message, color } = badgeFor(verdict, { coverage: blind.coverage.ratio });
 
   const svg = renderBadge('SPARDA', message, color);
@@ -52,7 +63,7 @@ export async function runBadge(opts) {
   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)`,
+    `\n✓ Badge written: ${relSvg}  (${state} · ${report.routes} routes · ${coveragePct(blind.coverage.ratio)} coverage)`,
   );
   console.log(`\nPaste into your README:\n`);
   console.log(`  ![SPARDA](./${relSvg})`);

package/src/commands/blindspots.js

@@ -10,7 +10,7 @@
 //   sparda blindspots --json     the raw survey for tooling
 import { compileUBG } from '../ubg/compile.js';
 import { canonicalizeGraph } from '../ubg/schema.js';
-import { surveyBlindspots } from '../ubg/blindspots.js';
+import { surveyBlindspots, coveragePct } from '../ubg/blindspots.js';
 
 const ICON = { critical: '✗', high: '✗', medium: '⚠', low: '·' };
 
@@ -30,7 +30,7 @@ export async function runBlindspots(opts) {
       `  ${surface} blind spot(s): ${byRisk.high + byRisk.critical} high+, ${byRisk.medium} medium, ${byRisk.low} low`,
     );
     console.log(
-      `  coverage ${(coverage.ratio * 100).toFixed(1)}% — ${coverage.resolved} behaviors resolved, ${coverage.blind} left unseen`,
+      `  coverage ${coveragePct(coverage.ratio, 1)} — ${coverage.resolved} behaviors resolved, ${coverage.blind} left unseen`,
     );
     if (surface === 0) {
       console.log(

package/src/commands/claude-hook.js

@@ -0,0 +1,105 @@
+// commands/claude-hook.js — one-command install of the SPARDA gate into Claude Code's
+// PostToolUse hook, so every AI edit is proven in the loop with zero manual wiring. This is
+// the DX that makes the gate irreproachable: the agent edits, the gate fires, a regression
+// comes back on stderr with a fix (see gate.js). Writes to the PROJECT's .claude/settings.json
+// so the whole team inherits it via the repo.
+//
+// Two hard constraints, both honored by the pure functions below:
+//   • idempotent — installing twice never duplicates the hook;
+//   • cleanly removable (hard rule #4) — uninstall strips EXACTLY our entry and prunes the
+//     containers it emptied, leaving any other hooks/settings byte-for-byte untouched.
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+// the exact command the hook runs; also the marker that identifies OUR entry on removal.
+export const GATE_HOOK_CMD = 'npx --no-install sparda-mcp gate --hook';
+const MATCHER = 'Edit|Write';
+
+const isOurHook = (h) => h?.type === 'command' && h?.command === GATE_HOOK_CMD;
+
+// Ensure our PostToolUse hook is present. Pure: takes a settings object, returns
+// { settings, changed }. Idempotent — if any PostToolUse block already runs our command,
+// nothing changes. Never touches unrelated hooks or matchers.
+export function applyClaudeHook(settings) {
+  const next = structuredClone(settings ?? {});
+  next.hooks ??= {};
+  const post = Array.isArray(next.hooks.PostToolUse) ? next.hooks.PostToolUse : [];
+  const already = post.some((block) => (block?.hooks ?? []).some(isOurHook));
+  if (already) return { settings: next, changed: false };
+  post.push({ matcher: MATCHER, hooks: [{ type: 'command', command: GATE_HOOK_CMD }] });
+  next.hooks.PostToolUse = post;
+  return { settings: next, changed: true };
+}
+
+// Strip EXACTLY our hook and prune what that emptied: our command out of each block's hooks,
+// then blocks left with no hooks, then PostToolUse if empty, then hooks if empty. Any other
+// hook a user added is preserved. Pure: returns { settings, changed }.
+export function removeClaudeHook(settings) {
+  const next = structuredClone(settings ?? {});
+  const post = next.hooks?.PostToolUse;
+  if (!Array.isArray(post)) return { settings: next, changed: false };
+
+  let changed = false;
+  const kept = [];
+  for (const block of post) {
+    const hooks = block?.hooks ?? [];
+    const remaining = hooks.filter((h) => !isOurHook(h));
+    if (remaining.length !== hooks.length) changed = true;
+    if (remaining.length) kept.push({ ...block, hooks: remaining });
+    // a block whose only hook was ours is dropped entirely (never leave a matcher orphaned)
+  }
+  if (!changed) return { settings: next, changed: false };
+
+  if (kept.length) next.hooks.PostToolUse = kept;
+  else delete next.hooks.PostToolUse;
+  if (next.hooks && Object.keys(next.hooks).length === 0) delete next.hooks;
+  return { settings: next, changed: true };
+}
+
+function settingsPath(cwd) {
+  return path.join(cwd, '.claude', 'settings.json');
+}
+
+// read .claude/settings.json into an object. `{}` when absent; throws a USER error (never a
+// silent overwrite) when present-but-unparseable — we will not clobber a file we can't read.
+function readSettings(file) {
+  if (!fs.existsSync(file)) return {};
+  const raw = fs.readFileSync(file, 'utf8');
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw Object.assign(
+      new Error(`${file} is not valid JSON — refusing to overwrite it.`),
+      { code: 'USER', hint: 'Fix the JSON by hand, then re-run.' },
+    );
+  }
+}
+
+export function installClaudeHook(cwd) {
+  const file = settingsPath(cwd);
+  const { settings, changed } = applyClaudeHook(readSettings(file));
+  if (!changed) return { changed: false, file };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  atomicWrite(file, JSON.stringify(settings, null, 2) + '\n');
+  return { changed: true, file };
+}
+
+// Uninstall for the CLI and for `sparda remove` (rule #4). Returns whether anything was
+// removed. Never errors when the file/hook is absent — removal is best-effort cleanup.
+export function uninstallClaudeHook(cwd) {
+  const file = settingsPath(cwd);
+  if (!fs.existsSync(file)) return { changed: false, file };
+  let current;
+  try {
+    current = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return { changed: false, file }; // unreadable — leave it exactly as-is
+  }
+  const { settings, changed } = removeClaudeHook(current);
+  if (!changed) return { changed: false, file };
+  // if we emptied the file to `{}` AND it holds nothing else, remove it; else write it back
+  if (Object.keys(settings).length === 0) fs.rmSync(file);
+  else atomicWrite(file, JSON.stringify(settings, null, 2) + '\n');
+  return { changed: true, file };
+}

package/src/commands/dossier.js

@@ -10,7 +10,8 @@ import path from 'node:path';
 import { compileUBG } from '../ubg/compile.js';
 import { canonicalizeGraph } from '../ubg/schema.js';
 import { checkGraph, verdictOf, verdictState } from '../ubg/apocalypse.js';
-import { surveyBlindspots } from '../ubg/blindspots.js';
+import { premiseFor, withPremiseGaps } from '../ubg/premise.js';
+import { surveyBlindspots, coveragePct } from '../ubg/blindspots.js';
 import { buildCapsule } from '../ubg/immunity.js';
 import { AXES, POLARITY_SYMBOL, exposedAxes } from '../ubg/polarity.js';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
@@ -20,10 +21,20 @@ export async function runDossier(opts) {
   const canonical = canonicalizeGraph(compiled.graph);
   const { findings, polarity } = checkGraph(canonical);
   const capsule = buildCapsule(canonical);
-  const blindspots = surveyBlindspots(canonical, compiled.report);
+  // the public report — same rule as the badge: it must not describe an app SPARDA
+  // never fully had
+  const premise = await premiseFor(canonical, compiled.report, {
+    cwd: opts.cwd,
+    probe: opts.probe,
+  });
+  const blindspots = surveyBlindspots(
+    canonical,
+    withPremiseGaps(compiled.report, premise),
+  );
   const verdict = verdictOf(findings, canonical, {
     coverage: blindspots.coverage.ratio,
     blindHigh: blindspots.byRisk.critical + blindspots.byRisk.high,
+    premiseGaps: premise.available ? premise.gaps.length : 0,
   });
 
   const data = {
@@ -36,7 +47,10 @@ export async function runDossier(opts) {
     provable: verdict.provable,
     proven: verdict.provable && verdict.clean,
     state: verdictState(verdict),
-    coverage: Math.round(blindspots.coverage.ratio * 100),
+    coverage:
+      blindspots.coverage.ratio == null
+        ? null // 0/0 — a measurement that does not exist, never "100"
+        : Math.round(blindspots.coverage.ratio * 100),
     surfaceOnly: verdict.surfaceOnly,
     guards: verdict.guards,
     guardsVerified: verdict.guardsVerified,
@@ -241,12 +255,12 @@ export function renderDossierHTML(d) {
   <section class="hero">
     <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>
+      <span class="cov" title="share of the app's behavior SPARDA resolved and reasoned about">coverage&nbsp;<b>${b.coverage ? coveragePct(b.coverage.ratio) : `${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(coveragePct(b.coverage.ratio), 'behavior resolved')}
       ${statCard(d.nodes, 'graph nodes')}
       ${statCard(d.tables, 'data tables')}
       ${statCard(esc(d.framework), 'framework')}
@@ -266,7 +280,7 @@ export function renderDossierHTML(d) {
   <h2>What SPARDA found</h2>
   ${findingCards}
 
-  <h2>Where the proof stops <small>SPARDA's own blind spots · coverage ${(b.coverage.ratio * 100).toFixed(0)}% · ${b.surface} unseen, ranked by what each could hide</small></h2>
+  <h2>Where the proof stops <small>SPARDA's own blind spots · coverage ${coveragePct(b.coverage.ratio)} · ${b.surface} unseen, ranked by what each could hide</small></h2>
   ${blindRows}
 
   <footer>