sparda-mcp 0.68.0 → 0.69.0

package/README.md

@@ -21,14 +21,14 @@
 ![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
 ```
@@ -68,7 +68,7 @@ npm run wedge     # (from a clone)  — or drive it on your own app with `sparda
 
 | 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)                                                                                                                                 |
@@ -163,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:
@@ -361,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.68.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",

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/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>

package/src/commands/enforce.js

@@ -0,0 +1,344 @@
+// commands/enforce.js — the third leg (ADR-076): SAST observes, RASP imposes, SPARDA does
+// both AND proves what it imposed. `sparda enforce` closes the type-lock gap (ADR-070) by
+// SYNTHESIS: a clean mutation route whose only protection is an ASSERTED guard (an opaque
+// middleware SPARDA cannot read) gets a minimal boundary check SPARDA CAN read — inserted
+// into the route's middleware chain, where domination is syntactically guaranteed (every
+// chain step dominates the handler; no dominator-tree computation needed, the chain IS the
+// dominance spine the guard scanner already trusts). PARTIAL → PROVEN, by construction.
+//
+// The three rails that keep this honest:
+//   1. THE COURT — after writing, the app is recompiled and must prove PROVEN with zero new
+//      findings; otherwise every edit is rolled back and the command fails. Enforcement that
+//      cannot prove itself does not persist. (A non-denying check can never buy green: the
+//      gate re-runs the same verifier that demanded the proof in the first place.)
+//   2. REVERSIBILITY (hard rule #4) — the injected block is marker-fenced, the chain
+//      insertion is a single unique identifier, and the pre-enforce content hash is recorded:
+//      `sparda enforce --revert` restores the file byte-for-byte (verified by hash).
+//   3. DISCLOSURE — the manifest (.sparda/enforce.json) makes an enforced proof auditable
+//      and distinguishable from a native static proof; `prove` reads it and reports
+//      PROVEN (ENFORCED), never a silent bare PROVEN. Soundness never depends on the
+//      manifest: delete the injected check and the verdict falls back to PARTIAL on its own.
+//
+// V1 scope (honest): Express route registrations `<app|router>.<verb>('/path', mw…, handler)`
+// with ≥1 middleware already in the chain (the asserted guard), JS/TS, same-file. The check
+// denies when the authenticated principal is ABSENT (`req.user` by convention, configurable
+// via --principal): legitimate traffic through a working auth middleware is untouched; a
+// removed/broken auth middleware now fails closed instead of open.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from '@babel/parser';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import {
+  checkGraph,
+  verdictOf,
+  verdictState,
+  assertedOnlyMutationRoutes,
+} from '../ubg/apocalypse.js';
+
+export const ENFORCE_IDENT = 'spardaProvenAuth';
+const MARK_START = '// >>> sparda-enforce (do not edit this block) >>>';
+const MARK_END = '// <<< sparda-enforce <<<';
+const HTTP_VERBS = new Set(['get', 'post', 'put', 'patch', 'delete', 'all']);
+const MANIFEST_REL = path.join('.sparda', 'enforce.json');
+
+const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');
+
+// The synthesized boundary check. Deny-first, provable by the same scanner that verifies any
+// guard (a 401 status response = deniesWithStatus): nothing about this is trusted by name.
+// `body` is overridable ONLY so the adversarial tests can prove the court below rejects a
+// non-denying counterfeit — production callers never pass it.
+function shimBlock(principal, body) {
+  return [
+    '',
+    MARK_START,
+    '// SPARDA-synthesized boundary proof (ADR-076): denies when no authenticated principal is',
+    "// present. Inserted because this file's guarded mutation route(s) rest on a guard SPARDA",
+    '// could not verify. Behavior for authenticated traffic is unchanged. Revert with',
+    '// `sparda enforce --revert`.',
+    `const ${ENFORCE_IDENT} = (req, res, next) => {`,
+    body ??
+      `  if (!${principal}) return res.status(401).json({ error: 'unauthorized' });`,
+    '  return next();',
+    '};',
+    MARK_END,
+    '',
+  ].join('\n');
+}
+
+// Find the route-registration CallExpression at (or spanning from) the entrypoint's recorded
+// line: `<obj>.<verb>('/path', …)`. Returns the babel node or null.
+function routeCallAt(ast, line) {
+  let hit = null;
+  const walk = (node) => {
+    if (!node || typeof node !== 'object' || hit) return;
+    if (Array.isArray(node)) {
+      for (const n of node) walk(n);
+      return;
+    }
+    if (
+      node.type === 'CallExpression' &&
+      node.loc?.start.line === line &&
+      node.callee?.type === 'MemberExpression' &&
+      node.callee.property?.type === 'Identifier' &&
+      HTTP_VERBS.has(node.callee.property.name) &&
+      node.arguments?.length >= 2
+    ) {
+      hit = node;
+      return;
+    }
+    for (const k of Object.keys(node)) {
+      if (k === 'loc' || k === 'range') continue;
+      const v = node[k];
+      if (v && typeof v === 'object') walk(v);
+    }
+  };
+  walk(ast.program);
+  return hit;
+}
+
+// Compute the per-file edit plan for the given target routes. Pure: returns
+// { insertions: [offset], needsBlock, blockOffset } or an error string.
+function planFile(src, lines) {
+  const ast = parse(src, {
+    sourceType: 'unambiguous',
+    plugins: ['typescript', 'jsx', 'decorators-legacy'],
+  });
+  const insertions = [];
+  for (const line of lines) {
+    const call = routeCallAt(ast, line);
+    if (!call) return { error: `no route registration found at line ${line}` };
+    const args = call.arguments;
+    if (args.some((a) => a?.type === 'Identifier' && a.name === ENFORCE_IDENT)) continue; // idempotent
+    if (args.length < 3)
+      return {
+        error: `route at line ${line} has no middleware chain to anchor to (path + handler only)`,
+      };
+    // insertion point: before the LAST argument (the handler) — after every existing
+    // middleware, so the asserted guard still runs first and the proof shim dominates
+    // only the handler, never the app's own middleware.
+    insertions.push(args[args.length - 1].start);
+  }
+  const needsBlock = !src.includes(MARK_START);
+  // the block goes after the last top-level import (or at the top for CJS)
+  let blockOffset = 0;
+  for (const stmt of ast.program.body)
+    if (stmt.type === 'ImportDeclaration') blockOffset = stmt.end;
+  return { insertions, needsBlock, blockOffset };
+}
+
+function applyEdits(src, plan, principal, shimBody) {
+  const edits = plan.insertions
+    .map((offset) => ({ offset, text: `${ENFORCE_IDENT}, ` }))
+    .sort((a, b) => b.offset - a.offset);
+  let out = src;
+  for (const e of edits) out = out.slice(0, e.offset) + e.text + out.slice(e.offset);
+  if (plan.needsBlock) {
+    const at = plan.blockOffset;
+    out = out.slice(0, at) + shimBlock(principal, shimBody) + out.slice(at);
+  }
+  return out;
+}
+
+function compileVerdict(cwd) {
+  const canonical = canonicalizeGraph(compileUBG(cwd, { write: false }).graph);
+  const { findings } = checkGraph(canonical);
+  const verdict = verdictOf(findings, canonical, {});
+  return { canonical, findings, verdict, state: verdictState(verdict) };
+}
+
+export function readEnforceManifest(cwd) {
+  try {
+    const m = JSON.parse(fs.readFileSync(path.join(cwd, MANIFEST_REL), 'utf8'));
+    // the manifest is a claim like any other — it counts only while the injected checks are
+    // still in place (a hand-stripped shim must not read as ENFORCED)
+    for (const [rel, rec] of Object.entries(m.files ?? {})) {
+      const cur = fs.readFileSync(path.join(cwd, rel), 'utf8');
+      if (sha(cur) !== rec.enforcedSha256 || !cur.includes(MARK_START)) return null;
+    }
+    return m;
+  } catch {
+    return null;
+  }
+}
+
+export async function runEnforce(opts) {
+  const cwd = opts.cwd;
+  const principal = opts.principal ?? 'req.user';
+  const log = (s) => console.error(s);
+
+  if (opts.revert) return revertEnforce(cwd, { json: opts.json });
+
+  // `req.user` / `req.auth` shapes only — the principal lands in a `!(...)` test inside the
+  // generated code, so it must be a plain member path (defense against option injection).
+  if (!/^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)+$/.test(principal))
+    throw Object.assign(new Error(`invalid --principal: ${principal}`), {
+      code: 'USER',
+      hint: 'Use a plain member path like req.user or req.auth.',
+    });
+
+  const before = compileVerdict(cwd);
+  const targets = assertedOnlyMutationRoutes(before.canonical).filter((t) => t.loc?.file);
+  if (targets.length === 0) {
+    const msg =
+      before.state === 'PROVEN'
+        ? 'Nothing to enforce — the app is already PROVEN.'
+        : `Nothing to enforce — no clean mutation route rests on an asserted-only guard (verdict: ${before.state}). Enforce closes exactly that gap; other findings need real fixes, not synthesis.`;
+    if (opts.json) console.log(JSON.stringify({ enforced: [], note: msg }, null, 2));
+    else log(msg);
+    return;
+  }
+
+  // group targets per file, plan all edits
+  const byFile = new Map();
+  for (const t of targets) {
+    if (!byFile.has(t.loc.file)) byFile.set(t.loc.file, []);
+    byFile.get(t.loc.file).push(t);
+  }
+  const plans = new Map(); // rel -> { src, out }
+  for (const [rel, list] of byFile) {
+    const abs = path.join(cwd, rel);
+    const src = fs.readFileSync(abs, 'utf8');
+    const plan = planFile(
+      src,
+      list.map((t) => t.loc.line),
+    );
+    if (plan.error)
+      throw Object.assign(new Error(`${rel}: ${plan.error}`), {
+        code: 'USER',
+        hint: 'This route shape is outside enforce V1 (Express chain form). File an issue with the route.',
+      });
+    plans.set(rel, { src, out: applyEdits(src, plan, principal, opts._shimBody) });
+  }
+
+  if (!opts.apply) {
+    // dry-run is the default — enforcement writes code, so the plan is shown first
+    log(`sparda enforce — plan (dry run; pass --apply to write):\n`);
+    for (const t of targets)
+      log(`  ⚙ ${t.label} — insert ${ENFORCE_IDENT} before the handler`);
+    for (const rel of plans.keys())
+      log(
+        `  ⚙ ${rel} — add the marker-fenced ${ENFORCE_IDENT} block (denies without ${principal})`,
+      );
+    log(
+      `\n  The check denies only when ${principal} is ABSENT. Verify your auth middleware sets it.\n  After --apply, SPARDA recompiles and keeps the edit ONLY if the app proves PROVEN.`,
+    );
+    if (opts.json)
+      console.log(
+        JSON.stringify(
+          { plan: targets.map((t) => t.label), files: [...plans.keys()], applied: false },
+          null,
+          2,
+        ),
+      );
+    return;
+  }
+
+  // write, then THE COURT: recompile — the edit persists only if it proves itself
+  for (const [rel, p] of plans) fs.writeFileSync(path.join(cwd, rel), p.out);
+  const after = compileVerdict(cwd);
+  const stillAsserted = assertedOnlyMutationRoutes(after.canonical).length;
+  const grewFindings = after.findings.length > before.findings.length;
+  if (after.state !== 'PROVEN' || stillAsserted > 0 || grewFindings) {
+    for (const [rel, p] of plans) fs.writeFileSync(path.join(cwd, rel), p.src); // roll back, byte-for-byte
+    throw Object.assign(
+      new Error(
+        `enforcement did not prove itself (verdict ${after.state}, asserted-only left ${stillAsserted}${grewFindings ? ', new findings appeared' : ''}) — every edit rolled back`,
+      ),
+      {
+        code: 'USER',
+        hint: 'The synthesized check could not be verified on the recompiled graph. Nothing was changed.',
+      },
+    );
+  }
+
+  // record the manifest — the auditable provenance of the ENFORCED tier
+  const manifest = {
+    version: 1,
+    at: new Date().toISOString(),
+    principal,
+    routes: targets.map((t) => t.label),
+    files: Object.fromEntries(
+      [...plans].map(([rel, p]) => [
+        rel,
+        { originalSha256: sha(p.src), enforcedSha256: sha(p.out) },
+      ]),
+    ),
+  };
+  fs.mkdirSync(path.join(cwd, '.sparda'), { recursive: true });
+  fs.writeFileSync(
+    path.join(cwd, MANIFEST_REL),
+    JSON.stringify(manifest, null, 2) + '\n',
+  );
+
+  if (opts.json)
+    console.log(
+      JSON.stringify(
+        {
+          enforced: manifest.routes,
+          files: Object.keys(manifest.files),
+          verdict: 'PROVEN (ENFORCED)',
+        },
+        null,
+        2,
+      ),
+    );
+  else {
+    for (const t of targets) log(`  ✓ enforced ${t.label}`);
+    log(
+      `\n✓ PROVEN (ENFORCED) — ${targets.length} route(s) now carry a boundary check SPARDA verified on the recompiled graph.\n  Revert any time: sparda enforce --revert (byte-for-byte).`,
+    );
+  }
+}
+
+export function revertEnforce(cwd, { json } = {}) {
+  const log = (s) => console.error(s);
+  const manifestPath = path.join(cwd, MANIFEST_REL);
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    log('Nothing to revert — no enforcement manifest found.');
+    return;
+  }
+  const results = [];
+  for (const [rel, rec] of Object.entries(manifest.files ?? {})) {
+    const abs = path.join(cwd, rel);
+    let cur;
+    try {
+      cur = fs.readFileSync(abs, 'utf8');
+    } catch {
+      results.push({ file: rel, restored: false, reason: 'missing' });
+      continue;
+    }
+    // strip the fenced block (with the exact newlines shimBlock added around it), then the
+    // chain identifiers — the two edits enforce made, undone in reverse
+    let out = cur.replace(
+      new RegExp(
+        `\\n${MARK_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${MARK_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n`,
+        'g',
+      ),
+      '',
+    );
+    out = out.split(`${ENFORCE_IDENT}, `).join('');
+    fs.writeFileSync(abs, out);
+    results.push({ file: rel, restored: sha(out) === rec.originalSha256 });
+  }
+  fs.rmSync(manifestPath, { force: true });
+  const clean = results.every((r) => r.restored);
+  if (json) console.log(JSON.stringify({ reverted: results, byteClean: clean }, null, 2));
+  else {
+    for (const r of results)
+      log(
+        r.restored
+          ? `  ✓ ${r.file} restored byte-for-byte`
+          : `  ⚠ ${r.file} reverted, but differs from the pre-enforce bytes (edited since?)`,
+      );
+    log(
+      clean
+        ? '✓ enforcement fully reverted.'
+        : '⚠ reverted with differences — review the files above.',
+    );
+  }
+}