sparda-mcp 0.66.0 → 0.66.2

package/README.md

@@ -25,7 +25,7 @@
 
 ## 60-second proof
 
-From your Express, FastAPI, Next.js, NestJS or Medusa app — nothing to configure:
+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
@@ -53,7 +53,7 @@ Under the hood it compiles your backend into one language-agnostic graph — the
 | **`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)                                                                                                       |
+| **`ubg`**          | Compile the codebase to its behavior graph (Express · FastAPI · Flask · 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                                                                                                                                    |
 | **`mirror`**       | _Execute the graph_ — serve the compiled behavior over HTTP with no framework and no source                                                                                                                                          |
 | **`init` / `dev`** | _Runtime, optional_ — expose the graph to AI clients as a live MCP server (+ Twin, Immune, Evolution)                                                                                                                                |
@@ -213,7 +213,7 @@ The gate is honest in both directions: an unfixed bug, or a "fix" that silently
 
 ## Any Backend On Earth: OpenAPI Lowering
 
-SPARDA parses Express, FastAPI and Next.js natively — and **every other stack through the format the industry already agreed on**. Go, Java, Rails, Laravel, .NET: if it has an OpenAPI spec, it compiles.
+SPARDA parses Express, FastAPI, Flask and Next.js natively — and **every other stack through the format the industry already agreed on**. Go, Java, Rails, Laravel, .NET: if it has an OpenAPI spec, it compiles.
 
 ```bash
 npx sparda-mcp ubg --openapi openapi.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.66.0",
+  "version": "0.66.2",
   "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",
@@ -13,7 +13,7 @@
     "url": "https://github.com/zyx77550/sparda/issues"
   },
   "bin": {
-    "sparda": "./src/index.js"
+    "sparda": "src/index.js"
   },
   "scripts": {
     "test": "vitest run",
@@ -44,6 +44,7 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
     "claude",
     "claude-code",
@@ -60,19 +61,19 @@
   "author": "Residual Labs (residual-labs.fr)",
   "license": "BUSL-1.1",
   "dependencies": {
-    "@babel/parser": "7.26.5",
-    "@babel/traverse": "7.26.5",
-    "@clack/prompts": "0.9.1",
     "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.4",
-    "@vitest/coverage-v8": "^3.2.6",
-    "eslint": "^9.39.4",
-    "eslint-config-prettier": "^9.1.2",
-    "express": "^4.21.0",
-    "globals": "^15.15.0",
+    "@babel/parser": "^8.0.4",
+    "@babel/traverse": "^8.0.4",
+    "@clack/prompts": "^1.7.0",
+    "@eslint/js": "^10.0.1",
+    "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^10.7.0",
+    "eslint-config-prettier": "^10.1.8",
+    "express": "^5.2.1",
+    "globals": "^17.7.0",
     "prettier": "^3.8.4",
-    "vitest": "^3.2.6"
+    "vitest": "^4.1.10"
   }
 }

package/src/commands/evolve.js

@@ -82,7 +82,7 @@ export async function runEvolve(opts) {
       },
     );
   }
-  let exemplars = {};
+  let exemplars;
   try {
     exemplars = JSON.parse(fs.readFileSync(twinPath, 'utf8')).exemplars ?? {};
   } catch {

package/src/commands/gate.js

@@ -3,11 +3,29 @@
 // edit gate must never scream about pre-existing state (that noise is fatal to
 // adoption — see docs/TWO-FALSE-POSITIVE-CLASSES-2026-07-19.md), so everything
 // already true at arm time is silent and only the regression speaks.
-//   sparda gate            report the edit's behavior delta vs baseline (exit 1 on critical/high)
+//
+// The load-bearing subtlety (E-GATE-1): a PostToolUse hook fires after EVERY
+// edit, including the mid-sequence ones that leave a file temporarily
+// unparseable. When a file fails to parse its routes vanish from the graph, so a
+// naive diff reads that as ENTRYPOINT_REMOVED / GUARD_REMOVED and cries a false
+// regression on the agent's own in-progress work. That false alarm, fired
+// constantly, is what gets the gate uninstalled in five minutes. So: a regression
+// whose baseline entrypoint lives in a now-unparseable file is NOT a regression —
+// it is "unproven, come back when it parses". The gate ABSTAINS, never claims
+// clean (it proved nothing) and never claims safe. An unparseable tree has no
+// defined behavior to regress against — abstention is the sound call.
+//
+// Note on PostToolUse semantics: the edit has already landed, so exit 2 does not
+// *prevent* it — it feeds the regression back to the agent as stderr, which the
+// agent reads and corrects in the same session (self-heal in the loop). That is
+// the honest claim: immediate feedback, not a hard block. (A hard pre-commit
+// block is the pre-commit hook / CI Action's job — same command, `apocalypse`.)
+//   sparda gate            report the edit's behavior delta vs baseline
 //   sparda gate --arm      freeze the current graph as the accepted baseline
 //   sparda gate --hook     Claude Code PostToolUse contract: silent when clean,
-//                          report on stderr + exit 2 (blocking feedback) on regression;
-//                          arms itself on first run so there is nothing to configure.
+//                          report on stderr + exit 2 (feedback to the agent) on a
+//                          real regression; abstains (exit 0) while a file is
+//                          mid-edit; arms itself on first run — zero config.
 import fs from 'node:fs';
 import path from 'node:path';
 import { compileUBG } from '../ubg/compile.js';
@@ -18,22 +36,49 @@ import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 // severities that block the edit; medium/info regressions are reported, never fatal
 const BLOCKING = new Set(['critical', 'high']);
 const findingKey = (f) => `${f.rule}|${f.entrypoint}`;
+// diff rules that mean "this route/protection disappeared" — the ones a vanished
+// (unparseable) file can forge. Introduced-risk rules can never be forged by a
+// missing file, so they are never suppressed.
+const REMOVAL_RULES = new Set(['ENTRYPOINT_REMOVED', 'GUARD_REMOVED']);
+
+// files the compiler could not read/parse this run — reason is prefixed by the
+// module error (`parse error: …` / `unreadable: …`) in every extractor's skipped list.
+function unparsedFiles(report) {
+  const out = new Set();
+  for (const s of report?.skipped ?? []) {
+    if (s.file && /(^|\b)(parse error|unreadable|Unexpected|SyntaxError)/i.test(s.reason))
+      out.add(s.file);
+  }
+  return out;
+}
 
 // The gate's whole judgment, pure over two canonical graphs (testable without a repo):
 // diff regressions (guard/route/invariant lost, blast radius grown) + static findings
 // the candidate has that the baseline did not — the same composition `review` proved
-// out (ADR-030), pointed at the baseline instead of a git ref.
-export function gateDelta(baseline, candidate) {
+// out (ADR-030), pointed at the baseline instead of a git ref. `unparsed` (the set of
+// files that failed to parse in the candidate) splits the diff removals into real
+// regressions vs in-progress edits whose baseline route lives in a now-broken file.
+export function gateDelta(baseline, candidate, unparsed = new Set()) {
+  const baseLoc = new Map((baseline.nodes ?? []).map((n) => [n.id, n.loc?.file]));
   const diff = diffGraphs(baseline, candidate).findings;
   const before = new Set(checkGraph(baseline).findings.map(findingKey));
   const introduced = checkGraph(candidate).findings.filter(
     (f) => !before.has(findingKey(f)),
   );
   const seen = new Set(diff.map(findingKey));
-  const findings = [...diff, ...introduced.filter((f) => !seen.has(findingKey(f)))];
+  const all = [...diff, ...introduced.filter((f) => !seen.has(findingKey(f)))];
+
+  const findings = [];
+  const abstained = [];
+  for (const f of all) {
+    if (REMOVAL_RULES.has(f.rule) && unparsed.has(baseLoc.get(f.entrypoint)))
+      abstained.push(f);
+    else findings.push(f);
+  }
   return {
     findings,
     blocking: findings.filter((f) => BLOCKING.has(f.severity)),
+    abstained,
   };
 }
 
@@ -48,10 +93,25 @@ export async function runGate(opts) {
   // in hook mode stdout belongs to nobody and stderr is what the agent reads
   const say = hook ? (s) => console.error(s) : (s) => console.log(s);
 
-  const { graph } = compileUBG(opts.cwd, { write: false });
-  const candidate = canonicalizeGraph(graph);
   const baselinePath = path.join(opts.cwd, '.sparda', 'ubg.baseline.json');
 
+  // A tree that does not compile at all (broken entry / detection throw) has no
+  // behavior to judge. Abstain instead of crashing the hook — the agent is mid-edit.
+  let graph, report;
+  try {
+    ({ graph, report } = compileUBG(opts.cwd, { write: false }));
+  } catch (err) {
+    if (opts.json)
+      console.log(JSON.stringify({ ok: true, abstained: err.message }, null, 2));
+    else if (!hook)
+      say(
+        `⏳ GATE ABSTAINED — the tree does not compile yet (${err.message}). Fix it, then re-check.`,
+      );
+    return { armed: false, findings: [], abstained: true };
+  }
+  const candidate = canonicalizeGraph(graph);
+  const unparsed = unparsedFiles(report);
+
   const arm = () => {
     fs.mkdirSync(path.dirname(baselinePath), { recursive: true });
     atomicWrite(baselinePath, JSON.stringify(candidate, null, 2) + '\n');
@@ -75,13 +135,18 @@ export async function runGate(opts) {
   }
 
   const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
-  const { findings, blocking } = gateDelta(baseline, candidate);
+  const { findings, blocking, abstained } = gateDelta(baseline, candidate, unparsed);
   const ms = Number(process.hrtime.bigint() - t0) / 1e6;
 
   if (opts.json) {
     console.log(
       JSON.stringify(
-        { ok: blocking.length === 0, ms: Math.round(ms), findings },
+        {
+          ok: blocking.length === 0,
+          ms: Math.round(ms),
+          findings,
+          abstained: abstained.map((f) => f.entrypoint),
+        },
         null,
         2,
       ),
@@ -90,8 +155,17 @@ export async function runGate(opts) {
     return { armed: false, findings };
   }
 
+  // Abstention notice: a route vanished only because its file doesn't parse yet.
+  // Never blocking — this is the normal mid-edit state, not a regression.
+  if (abstained.length) {
+    const files = [...new Set([...unparsed])].join(', ');
+    say(
+      `⏳ GATE HELD — ${abstained.length} route(s) can't be proven while ${files} doesn't parse (mid-edit?). Not a regression; I'll re-check once it parses.`,
+    );
+  }
+
   if (findings.length === 0) {
-    if (!hook)
+    if (!hook && !abstained.length)
       say(
         `✓ GATE CLEAN — this edit lost no guard, dropped no route, grew no blast radius (proven vs baseline in ${Math.round(ms)} ms).`,
       );

package/src/commands/heal.js

@@ -100,7 +100,7 @@ async function gate(opts, id, flight, healDir) {
   // 3. apocalypse: no new critical/high, nothing protected got removed
   const fixedGraph = canonicalizeGraph(compileUBG(opts.cwd, { write: false }).graph);
   const staticFindings = checkGraph(fixedGraph).findings;
-  let regressions = [];
+  let regressions;
   const baselinePath = path.join(healDir, 'baseline.json');
   if (fs.existsSync(baselinePath)) {
     const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));

package/src/commands/seed.js

@@ -277,7 +277,7 @@ export async function runSeed(opts, args) {
     if (opts.germinate) {
       const { buildGrammar } = await import('./grammar.js');
       const { twinFilePath } = await import('./twin.js');
-      let exemplars = null;
+      let exemplars;
       try {
         exemplars =
           JSON.parse(fs.readFileSync(twinFilePath(opts.cwd), 'utf8')).exemplars ?? null;

package/src/detect.js

@@ -92,7 +92,7 @@ export function detectStack(cwd) {
     const known = ['fastify', 'koa'].find((d) => deps[d]);
     if (known)
       throw err(
-        `${known} detected — not supported yet. Express, NestJS & FastAPI in v0.`,
+        `${known} detected — not supported yet. Express, NestJS, FastAPI & Flask in v0.`,
         '+1 the framework vote: github.com/zyx77550/sparda/issues/1',
       );
   }
@@ -108,6 +108,18 @@ export function detectStack(cwd) {
       return { framework: 'fastapi', entryFile, port, pythonCmd };
     }
   }
+  // Flask — checked AFTER FastAPI (a FastAPI project may pull flask transitively; FastAPI
+  // wins). The same Python extractor handles it; only the entry-file marker differs.
+  for (const f of ['requirements.txt', 'pyproject.toml']) {
+    const p = path.join(cwd, f);
+    if (
+      fs.existsSync(p) &&
+      /(^|[^a-z])flask([^a-z]|$)/i.test(fs.readFileSync(p, 'utf8'))
+    ) {
+      const entryFile = findFlaskEntry(cwd);
+      return { framework: 'flask', entryFile, port: 5000, pythonCmd: detectPython() };
+    }
+  }
 
   // Last resort before giving up — monorepo app dirs whose framework config lives
   // ELSEWHERE than the pointed dir. Purely structural, so it never mis-fires on a
@@ -130,7 +142,7 @@ export function detectStack(cwd) {
 
   const suggestions = suggestAppDirs(cwd);
   throw err(
-    'No supported framework found (Express, Next.js, NestJS, Medusa, FastAPI).',
+    'No supported framework found (Express, Next.js, NestJS, Medusa, FastAPI, Flask).',
     suggestions.length
       ? `This looks like a monorepo — the analyzable app is in a sub-directory. Try:\n` +
           suggestions
@@ -401,7 +413,28 @@ function findFastAPIEntry(cwd) {
   );
 }
 
-function searchPyFiles(dir, root, countRef = { val: 0 }) {
+// Flask's entry is the file that calls `Flask(__name__)` — conventionally app.py /
+// wsgi.py / run.py / main.py, else the first .py declaring it. Same shape as the
+// FastAPI finder; the Python extractor handles both frameworks from that entry.
+function findFlaskEntry(cwd) {
+  const candidates = ['app.py', 'wsgi.py', 'run.py', 'main.py', 'src/app.py'];
+  for (const rel of candidates) {
+    const abs = path.resolve(cwd, rel);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+      if (fs.readFileSync(abs, 'utf8').includes('Flask(')) {
+        return path.relative(cwd, abs).split(path.sep).join('/');
+      }
+    }
+  }
+  const entry = searchPyFiles(cwd, cwd, { val: 0 }, 'Flask(');
+  if (entry) return path.relative(cwd, entry).split(path.sep).join('/');
+  throw err(
+    'Could not locate your Flask entry file (the one calling Flask()).',
+    'Specify it manually, or make sure Flask() is declared in one of your python files.',
+  );
+}
+
+function searchPyFiles(dir, root, countRef = { val: 0 }, marker = 'FastAPI(') {
   const EXCLUDE = new Set([
     'node_modules',
     '.git',
@@ -434,7 +467,7 @@ function searchPyFiles(dir, root, countRef = { val: 0 }) {
       countRef.val++;
       if (countRef.val > 200) return null;
       const src = fs.readFileSync(abs, 'utf8');
-      if (src.includes('FastAPI(')) {
+      if (src.includes(marker)) {
         return abs;
       }
     }

package/src/flight/heal.js

@@ -27,7 +27,7 @@ export function evaluateHealing(flight, replay, expectation = null) {
     reasons.push('response is byte-identical to the recorded bug — nothing changed');
   }
 
-  let expectationMet = null;
+  let expectationMet;
   if (expectation) {
     expectationMet = true;
     if (expectation.status !== undefined && replay.actual.status !== expectation.status) {

package/src/generator/express.js

@@ -80,7 +80,7 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
   const isESM = moduleType === 'esm';
   const isTS = ext === '.ts';
 
-  let importLine = '';
+  let importLine;
   let reqType = '';
   let resType = '';
   let nextType = '';

package/src/generator/manifest.js

@@ -42,7 +42,7 @@ export function ensureSpardaKey(cwd, prevManifest = null) {
 // state (opt-in flags + observed circuits), and the `sparding` security
 // memory survive as long as the tool's method+path are unchanged.
 export function carryOverManifest(cwd, tools) {
-  let prev = null;
+  let prev;
   try {
     prev = JSON.parse(fs.readFileSync(path.join(cwd, 'sparda.json'), 'utf8'));
   } catch {

package/src/parser/fastapi.js

@@ -30,6 +30,7 @@ export function parseFastAPIProject(cwd, entryFile, pythonCmd = 'python') {
   } catch (err) {
     throw new Error(
       `Failed to parse Python extractor output: ${err.message}. Raw output: ${res.stdout}`,
+      { cause: err },
     );
   }
 }

package/src/ubg/apocalypse.js

@@ -58,11 +58,14 @@ export function buildProofObjects(graph) {
       .map((id) => g.nodes.get(id))
       .filter(Boolean);
     const guards = reached.filter((n) => n.kind === 'guard');
-    const writes = [];
+    const allWrites = [];
     for (const n of reached)
       if (n.kind === 'effect')
         for (const e of g.mutOut.get(n.id) ?? [])
-          writes.push({ effect: n, stateId: e.to });
+          allWrites.push({ effect: n, stateId: e.to });
+    // guard-dominance (C2): a write that runs BEFORE the route's guard is NOT discharged by it —
+    // never claim it in a proof (scan-level truth, authoritative over the graph's hoisted gate edge).
+    const writes = allWrites.filter((w) => !w.effect.meta?.bypassesGuard);
     // a proof object is emitted ONLY for a genuinely DISCHARGED obligation: a mutating route
     // (O1 applies) that actually reaches a guard. A guardless mutation is a FINDING, not a proof.
     if (!writes.length || !guards.length) continue;
@@ -153,7 +156,28 @@ export function checkGraph(graph) {
 
     // O1 — every mutation path must pass a guard
     obligations++;
-    if (writes.length) vec.auth = guards.length ? 1 : -1;
+    // Guard-DOMINANCE (kills the C2 false PROVEN): a guard on the route does NOT cover a mutation
+    // that runs BEFORE it — an early-return branch that mutates then checks auth after, or a write in
+    // a branch a sibling guards. `bypassesGuard` is the SCAN-LEVEL truth (set only when a guard
+    // demonstrably follows the write in the SAME body), and it is authoritative: the graph hoists an
+    // in-body guard into a chain node with a gate edge, so a gate edge cannot be trusted to mean
+    // "runs before the whole body". Under-approximated by construction, so it can only ever turn a
+    // PROVEN into NOT_PROVEN — never fabricate a guard, never a false PROVEN.
+    const bypassWrites =
+      guards.length > 0 ? writes.filter((w) => w.effect.meta.bypassesGuard) : [];
+    if (writes.length) vec.auth = guards.length === 0 || bypassWrites.length ? -1 : 1;
+    if (bypassWrites.length) {
+      // A bypassed guard is worse than no guard (it reads as protected but isn't) — a hard critical,
+      // never softened by the credential/public-by-design taxonomy below.
+      findings.push({
+        rule: 'UNGUARDED_MUTATION',
+        severity: 'critical',
+        guardBypass: true,
+        entrypoint: ep.id,
+        message: `${ep.label} mutates ${fmtStates(bypassWrites)} BEFORE its guard runs — an early-return / pre-check branch reaches the write without passing the route's auth check, so the guard does not cover it`,
+        evidence: bypassWrites.map((w) => `${w.effect.id} (${locOf(w.effect)})`),
+      });
+    }
     if (writes.length && guards.length === 0) {
       // taint enrichment (ADR-P1): does request data provably flow into one of these
       // writes? A tag on an ALREADY-emitted finding — never a finding of its own — so it

package/src/ubg/compile.js

@@ -34,6 +34,9 @@ export function compileUBG(
     medusa: () => extractMedusa(cwd, stack.entryFile),
     nextjs: () => extractNext(cwd, stack.entryFile),
     fastapi: () => extractFastAPI(cwd, stack.entryFile, stack.pythonCmd),
+    // Flask reuses the FastAPI (Python) extractor — same stdlib-ast walk, Flask route
+    // discovery folded in (Flask()/Blueprint/@app.route/register_blueprint/@login_required).
+    flask: () => extractFastAPI(cwd, stack.entryFile, stack.pythonCmd),
     openapi: () => extractOpenAPI(cwd, stack.entryFile),
   };
   if (!extractors[stack.framework]) {

package/src/ubg/extract.js

@@ -839,6 +839,8 @@ export function scanFunction(fnNode, env = {}) {
     // an advisory (never prove a guard, never silence a finding), so widening them can
     // never fabricate a gate (E-042) or a false PROVEN.
     credentialSignals: { verifyCall: false, denies4xxOrThrows: false, redirects: false },
+    // guard-dominance (C2): set true once any in-body guard barrier is seen while walking the body.
+    hasInBodyGuard: false,
     async: Boolean(fnNode?.async),
   };
   if (!fnNode) return result;
@@ -853,6 +855,14 @@ export function scanFunction(fnNode, env = {}) {
     // `this.knex(this.collection)` inside a service resolve to `:collection`.
     thisSymbols: env.thisSymbols ?? null,
   });
+  // guard-dominance: a mutation on an unguarded path is a real bypass ONLY when THIS body also holds
+  // a guard (so a guard is genuinely being circumvented). A body with no guard of its own is guarded
+  // elsewhere (positional middleware / a caller) — leave it to the route model, untouched. Strip the
+  // temporary marker either way so it never leaks into the graph.
+  for (const e of result.effects) {
+    if (result.hasInBodyGuard && e._unguardedPath) e.bypassesGuard = true;
+    delete e._unguardedPath;
+  }
   return result;
 }
 
@@ -1080,6 +1090,91 @@ function collectReqDerived(fnNode) {
 // SBIR §2.2 — transaction wrappers whose function arguments open a scope
 const TX_WRAPPERS = new Set(['transaction', '$transaction', 'withTransaction']);
 
+// Mutating effect kinds — the ones a guard is supposed to dominate (O1). A read is never a bypass.
+const MUTATING_EFFECTS = new Set(['db_write', 'http_call', 'fs_write']);
+
+// Guard-DOMINANCE (kills the C2 false PROVEN): a guard on a route's chain does not make EVERY
+// write on the route safe — the guard must run BEFORE the write. A handler that mutates in an
+// early-return branch and only checks auth afterwards (`if (preview) { charge.create(); return }
+// … await requireAuth(req)`) bypasses its own guard. We compute, per body, which mutations
+// execute on a path that has not yet passed a guard, AND where a guard follows on the same spine
+// (so there genuinely IS a guard being bypassed — a body whose guard lives cross-procedurally is
+// left to the route-level model, unchanged). This can only ever SUBTRACT guard credit — it never
+// invents a guard — so a heuristic barrier is sound: at worst it misses a bypass, never fabricates.
+//
+// A spine statement sets the barrier when everything sequentially after it has passed the check:
+//   (a) an early-deny gate — `if (test) throw | return <4xx>` (fall-through ⇒ the check passed), or
+//   (b) a guard CALL on the spine — `await requireAuth(req)` / `const s = await getSession()`.
+function spineCall(stmt) {
+  let e = null;
+  if (stmt.type === 'ExpressionStatement') e = stmt.expression;
+  else if (stmt.type === 'VariableDeclaration' && stmt.declarations[0])
+    e = stmt.declarations[0].init;
+  if (e?.type === 'AwaitExpression') e = e.argument;
+  return e?.type === 'CallExpression' ? e : null;
+}
+
+// An AUTHORIZATION gate, tightly — NOT the broad GUARD_NAME (which matches business calls like
+// `hasAdmin`/`getRole`/`verifyEmail` and would flood false bypasses). Only names that unambiguously
+// gate access: `require/ensure/assert{Auth,Session,User,Owner,Permission,Role,Admin,Login,Access}`,
+// `authenticate`/`authorize`, `canActivate`, `get(Server)Session`, `check/verify{Auth,Session,…}`.
+const AUTH_GATE_CALL =
+  /(^|[^a-z])(require|ensure|assert)[_]?(auth|session|user|owner|permission|role|admin|login|access)|authenticate|authoriz(e|ation)|can[_]?activate|get[_]?server[_]?session|get[_]?session|check[_]?(auth|permission|access|session)|verify[_]?(auth|session|permission)|protect[_]?route/i;
+
+function isGuardCall(call) {
+  const callee = call.callee;
+  const name =
+    callee?.type === 'Identifier'
+      ? callee.name
+      : callee?.type === 'MemberExpression' && callee.property?.type === 'Identifier'
+        ? callee.property.name
+        : '';
+  return AUTH_GATE_CALL.test(name);
+}
+
+// Does this subtree AUTH-deny — refuse with 401/403 or an auth exception? (Deliberately NOT any
+// throw or any 4xx: a validation `throw new BadRequestException()` inside a service is not an auth
+// gate, and treating it as one is what produced false bypasses.)
+function subtreeAuthDenies(node) {
+  let found = false;
+  const walk = (n) => {
+    if (found || !n || typeof n !== 'object') return;
+    if (Array.isArray(n)) {
+      for (const x of n) walk(x);
+      return;
+    }
+    if (n.type === 'CallExpression' && deniedStatusOf(n)) return void (found = true);
+    if (n.type === 'NewExpression') {
+      const nm = n.callee?.name;
+      if (
+        /^(Unauthorized|Forbidden)(Exception|Error)$/.test(nm ?? '') ||
+        (Array.isArray(n.arguments) && n.arguments.some(isDenyOptions))
+      )
+        return void (found = true);
+    }
+    for (const k of Object.keys(n)) {
+      if (
+        k === 'loc' ||
+        k === 'range' ||
+        k === 'leadingComments' ||
+        k === 'trailingComments'
+      )
+        continue;
+      const v = n[k];
+      if (v && typeof v === 'object') walk(v);
+    }
+  };
+  walk(node);
+  return found;
+}
+
+function statementSetsBarrier(stmt) {
+  if (!stmt) return false;
+  if (stmt.type === 'IfStatement') return subtreeAuthDenies(stmt.consequent);
+  const call = spineCall(stmt);
+  return call ? isGuardCall(call) : false;
+}
+
 function visit(node, out, ctx) {
   if (!node || typeof node !== 'object') return;
   if (Array.isArray(node)) {
@@ -1087,6 +1182,24 @@ function visit(node, out, ctx) {
     return;
   }
 
+  // Ordered spine walk of a block, tracking whether a guard has executed ON THE CURRENT PATH. A
+  // spine guard covers everything sequentially after it AND everything nested inside those later
+  // statements; a guard INSIDE a branch covers only that branch, never a sibling. Each mutation
+  // visited while the path is still unguarded is tagged `_unguardedPath` — a write reachable without
+  // passing a guard. (scanFunction promotes those to `bypassesGuard` only when THIS body actually
+  // has an in-body guard, so a body guarded cross-procedurally is left to the route model, unchanged.)
+  if (node.type === 'BlockStatement') {
+    let guarded = ctx.guarded === true;
+    for (const stmt of node.body) {
+      visit(stmt, out, { ...ctx, guarded });
+      if (statementSetsBarrier(stmt)) {
+        guarded = true;
+        out.hasInBodyGuard = true;
+      }
+    }
+    return;
+  }
+
   // G2 credential signal (advisory-only): the body can refuse — any throw, or any 4xx
   // response. Deliberately BROADER than guardSignals.deniesWithStatus (401/403) because it
   // can only ever downgrade a critical to an advisory, never verify a guard.
@@ -1491,6 +1604,10 @@ function pushEffect(out, ctx, effect) {
   }
   if (ctx?.tryId != null) effect.tryId = ctx.tryId;
   if (ctx?.catchOf != null) effect.catchOf = ctx.catchOf;
+  // guard-dominance (C2): a mutation reached while no guard has run on this path. Temporary — promoted
+  // to `bypassesGuard` in scanFunction only if this body also HAS a guard (else it is left unchanged).
+  if (ctx?.guarded !== true && MUTATING_EFFECTS.has(effect.effectType))
+    effect._unguardedPath = true;
   out.effects.push(effect);
 }
 

package/src/ubg/fastapi.js

@@ -38,6 +38,7 @@ export function extractFastAPI(cwd, entryFile, pythonCmd = 'python') {
   } catch (err) {
     throw new Error(
       `FastAPI UBG extractor returned invalid JSON: ${err.message}. Raw: ${res.stdout.slice(0, 200)}`,
+      { cause: err },
     );
   }
   if (payload.error) throw new Error(payload.error);

package/src/ubg/fastapi_extract.py

@@ -305,12 +305,42 @@ def scan_function(fn):
         "validatesInput": False,
         "async": isinstance(fn, ast.AsyncFunctionDef),
     }
-    ctx = {"tx": None, "iso": "default", "tryId": None, "catchOf": None}
+    # var -> model table, from `u = User(...)` — so `db.session.add(u)` (the dominant
+    # Flask-SQLAlchemy write) resolves to a real table instead of an untable-able blind write.
+    var_models = {}
+    for n in ast.walk(fn):
+        if (isinstance(n, ast.Assign) and len(n.targets) == 1
+                and isinstance(n.targets[0], ast.Name)
+                and isinstance(n.value, ast.Call)
+                and isinstance(n.value.func, ast.Name)
+                and n.value.func.id[:1].isupper()):
+            var_models[n.targets[0].id] = n.value.func.id.lower()
+    ctx = {"tx": None, "iso": "default", "tryId": None, "catchOf": None,
+           "var_models": var_models}
     for stmt in fn.body:
         _visit(stmt, out, ctx)
     return out
 
 
+def query_model_of(node):
+    """Flask-SQLAlchemy Query API: `Model.query.filter_by(...).delete()` /
+    `User.query.get(id)` → 'model' — the capitalized Name that `.query` hangs off,
+    however deep the chain (filter/filter_by/order_by/… are all calls)."""
+    cur = node
+    while cur is not None:
+        if (isinstance(cur, ast.Attribute) and cur.attr == "query"
+                and isinstance(cur.value, ast.Name)
+                and cur.value.id[:1].isupper()):
+            return cur.value.id.lower()
+        if isinstance(cur, ast.Attribute):
+            cur = cur.value
+        elif isinstance(cur, ast.Call):
+            cur = cur.func.value if isinstance(cur.func, ast.Attribute) else None
+        else:
+            cur = None
+    return None
+
+
 def _visit(node, out, ctx):
     if isinstance(node, ast.Try):
         try_line = node.lineno
@@ -434,6 +464,16 @@ def inspect_call(node, out, ctx):
     # The receiver is matched on the full dotted chain, so `self.db.add(…)`
     # inside a service class reads like `db.add(…)` at module level.
     recv = dotted_name(func.value)
+    # Flask-SQLAlchemy Query API: Model.query.filter_by(...).delete() / .update() — a write on
+    # the model the chain roots at. (A bare Model.query.get()/all() is a read, handled as select.)
+    if method in ("delete", "update"):
+        qm = query_model_of(func.value)
+        if qm:
+            push_effect(out, ctx, {
+                "effectType": "db_write", "op": method, "table": qm,
+                "line": line, "driver": root or "unknown",
+            })
+            return
     if method == "query" and node.args and isinstance(node.args[0], ast.Name):
         push_effect(out, ctx, {
             "effectType": "db_read", "op": "select",
@@ -443,8 +483,18 @@ def inspect_call(node, out, ctx):
         return
     if (method in ("add", "add_all", "merge") and recv
             and re.search(r"session|db", recv, re.I)):
+        # resolve the model: db.session.add(u) where `u = User(...)`, or the inline
+        # db.session.add(User(...)). An unresolved add stays table-less (still a write).
+        table = None
+        if node.args:
+            a = node.args[0]
+            if isinstance(a, ast.Name):
+                table = ctx.get("var_models", {}).get(a.id)
+            elif (isinstance(a, ast.Call) and isinstance(a.func, ast.Name)
+                    and a.func.id[:1].isupper()):
+                table = a.func.id.lower()
         push_effect(out, ctx, {
-            "effectType": "db_write", "op": "insert", "table": None,
+            "effectType": "db_write", "op": "insert", "table": table,
             "line": line, "driver": root,
         })
         return
@@ -873,6 +923,10 @@ class UbgExtractor:
                             for t in self.dep_targets_of(kw.value):
                                 self.global_middlewares.append(
                                     {"target": t, "file": abs_file})
+                elif cname == "Flask":
+                    # Flask app: `app = Flask(__name__)`. Routes hang off @app.route /
+                    # @app.get/@app.post — same decorator-on-function shape as FastAPI.
+                    app_vars.add(var)
                 elif cname == "APIRouter":
                     router_vars.add(var)
                     router_prefixes[var] = ""
@@ -882,6 +936,16 @@ class UbgExtractor:
                             router_prefixes[var] = lit(kw.value)
                         if kw.arg == "dependencies":
                             router_deps[var] = self.dep_targets_of(kw.value)
+                elif cname == "Blueprint":
+                    # Flask Blueprint: `bp = Blueprint('x', __name__, url_prefix='/y')`.
+                    # A blueprint is FastAPI's APIRouter by another name — the same
+                    # prefix + register-later model, so it reuses the router machinery.
+                    router_vars.add(var)
+                    router_prefixes[var] = ""
+                    router_deps[var] = []
+                    for kw in call.keywords:
+                        if kw.arg == "url_prefix" and isinstance(lit(kw.value), str):
+                            router_prefixes[var] = lit(kw.value)
             elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                 functions[node.name] = node
 
@@ -926,18 +990,20 @@ class UbgExtractor:
             if isinstance(node, ast.Expr) and isinstance(node.value, ast.Call):
                 self.collect_mount(node.value, abs_file, prefix, import_map,
                                    router_vars, router_prefixes, depth)
+                self.collect_cbv(node.value, abs_file, prefix, modctx, rel_file,
+                                 router_vars, router_prefixes)
                 continue
             if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                 continue
             found = self.route_decorator_of(node, app_vars, router_vars)
             if not found:
                 continue
-            dec, obj_name, method = found
+            dec, obj_name, methods = found
             raw_path = lit(dec.args[0]) if dec.args else None
             if not isinstance(raw_path, str):
                 self.skipped.append({
                     "reason": "dynamic path on %s (non-literal first arg)"
-                              % method.upper(),
+                              % "/".join(m.upper() for m in methods),
                     "file": rel_file, "line": node.lineno,
                 })
                 continue
@@ -954,6 +1020,28 @@ class UbgExtractor:
                 continue
 
             chain = []
+            # Flask auth decorators — @login_required / @jwt_required() / @requires_auth —
+            # gate the handler exactly like a resolved FastAPI dependency that denies. A
+            # decorator whose NAME is an auth gate is a VERIFIED guard (the framework enforces
+            # the 401), so a mutation behind it is not a false UNGUARDED_MUTATION.
+            for d in node.decorator_list:
+                dname = (d.func.attr if isinstance(d, ast.Call)
+                         and isinstance(d.func, ast.Attribute)
+                         else d.func.id if isinstance(d, ast.Call)
+                         and isinstance(d.func, ast.Name)
+                         else d.attr if isinstance(d, ast.Attribute)
+                         else d.id if isinstance(d, ast.Name) else "")
+                if re.search(r'login_required|jwt_required|requires?_auth'
+                             r'|auth_required|require_login|token_required'
+                             r'|permission_required', dname or "", re.I):
+                    chain.append({
+                        "name": dname, "role": "middleware", "sourceFile": rel_file,
+                        "sourceLine": node.lineno,
+                        "scan": {"effects": [], "returnShapes": [], "calls": [],
+                                 "async": False, "validatesInput": False,
+                                 "guardSignals": {"deniesWithStatus": True}},
+                    })
+                    break
             dep_names = list(router_deps.get(obj_name, []))
             for kw in dec.keywords:
                 if kw.arg == "dependencies":
@@ -971,7 +1059,9 @@ class UbgExtractor:
                 else:
                     self.skipped.append({
                         "reason": "dependency '%s' not resolved on %s %s"
-                                  % (dep_name, method.upper(), full_path),
+                                  % (dep_name,
+                                     "/".join(m.upper() for m in methods),
+                                     full_path),
                         "file": rel_file, "line": node.lineno,
                     })
             # DI bindings: `svc: UserService = Depends(get_user_service)` /
@@ -1003,31 +1093,172 @@ class UbgExtractor:
                 "sourceLine": node.lineno, "scan": handler_scan,
             })
 
-            self.routes.append({
-                "method": method,
-                "path": full_path,
-                "sourceFile": rel_file,
-                "sourceLine": node.lineno,
-                "params": params,
-                "chain": chain,
-                "description": (ast.get_docstring(node) or "")[:400],
-            })
+            # one entrypoint per HTTP method (a Flask `@app.route(methods=[…])` can
+            # declare several; FastAPI/@app.get yields exactly one)
+            for method in methods:
+                self.routes.append({
+                    "method": method,
+                    "path": full_path,
+                    "sourceFile": rel_file,
+                    "sourceLine": node.lineno,
+                    "params": params,
+                    "chain": chain,
+                    "description": (ast.get_docstring(node) or "")[:400],
+                })
 
     def route_decorator_of(self, fn, app_vars, router_vars):
+        # Returns (decorator, owner_var, [methods]). Matches BOTH:
+        #   @app.get / @router.post / @app.delete   (FastAPI + Flask 2.0 shorthand)
+        #   @app.route("/x", methods=["GET","POST"]) (Flask — methods in a kwarg, default GET)
         for dec in fn.decorator_list:
-            if isinstance(dec, ast.Call) and isinstance(dec.func, ast.Attribute) \
-                    and dec.func.attr in HTTP_VERBS \
-                    and isinstance(dec.func.value, ast.Name) \
+            if not (isinstance(dec, ast.Call)
+                    and isinstance(dec.func, ast.Attribute)
+                    and isinstance(dec.func.value, ast.Name)
                     and (dec.func.value.id in app_vars
-                         or dec.func.value.id in router_vars):
-                return dec, dec.func.value.id, dec.func.attr
+                         or dec.func.value.id in router_vars)):
+                continue
+            attr = dec.func.attr
+            if attr in HTTP_VERBS:
+                return dec, dec.func.value.id, [attr]
+            if attr == "route":
+                methods = ["get"]
+                for kw in dec.keywords:
+                    if kw.arg == "methods" and isinstance(kw.value, (ast.List, ast.Tuple)):
+                        got = [lit(e).lower() for e in kw.value.elts
+                               if isinstance(lit(e), str)
+                               and lit(e).lower() in HTTP_VERBS]
+                        if got:
+                            methods = got
+                return dec, dec.func.value.id, methods
         return None
 
+    def collect_cbv(self, call, abs_file, prefix, modctx, rel_file,
+                    router_vars, router_prefixes):
+        """Flask class-based views: a MethodView registered via
+        `app.add_url_rule('/x', view_func=Cls.as_view('n'), methods=[…])`, or a
+        Flask-RESTful `api.add_resource(Cls, '/x')`. Each HTTP-verb method on the
+        class (or up its bases) becomes a route, scanned like any handler — so the
+        DELETE/POST inside a MethodView is no longer an invisible mutation surface."""
+        if not (isinstance(call.func, ast.Attribute) and call.args):
+            return
+        attr = call.func.attr
+        if attr not in ("add_url_rule", "add_resource"):
+            return
+        owner = call.func.value
+        owner_name = owner.id if isinstance(owner, ast.Name) else None
+        local_prefix = (router_prefixes.get(owner_name, "")
+                        if owner_name in router_vars else "")
+        cbv_name, raw_path, restrict = None, None, None
+        if attr == "add_url_rule":
+            raw_path = lit(call.args[0]) if call.args else None
+            for kw in call.keywords:
+                if (kw.arg == "view_func" and isinstance(kw.value, ast.Call)
+                        and isinstance(kw.value.func, ast.Attribute)
+                        and kw.value.func.attr == "as_view"
+                        and isinstance(kw.value.func.value, ast.Name)):
+                    cbv_name = kw.value.func.value.id
+                elif kw.arg == "methods" and isinstance(kw.value, (ast.List, ast.Tuple)):
+                    restrict = {lit(e).lower() for e in kw.value.elts
+                                if isinstance(lit(e), str)}
+        else:  # add_resource(Cls, "/path")
+            if isinstance(call.args[0], ast.Name):
+                cbv_name = call.args[0].id
+            raw_path = lit(call.args[1]) if len(call.args) > 1 else None
+        if not cbv_name or not isinstance(raw_path, str):
+            return
+        hit = self.resolve_class(modctx, cbv_name)
+        if not hit:
+            return
+        cls, cmod = hit
+        full_path = (prefix + local_prefix + raw_path).replace("//", "/")
+        if not full_path.startswith("/"):
+            full_path = "/" + full_path
+        # class-level guards: MethodView `decorators = [...]` / Flask-RESTful
+        # `method_decorators = [...]` apply to every verb method.
+        class_guard = self.cbv_class_guard(cls, rel_file)
+        for verb in HTTP_VERBS:
+            if restrict is not None and verb not in restrict:
+                continue
+            m = self.method_in_class_chain(cls, cmod, verb)
+            if not m:
+                continue
+            fn, fmod = m
+            mrel = self.rel(fmod["file"])
+            chain = []
+            for g in (class_guard + self.auth_guard_steps(fn, mrel)):
+                chain.append(g)
+            chain.append({
+                "name": "%s.%s" % (cbv_name, verb), "role": "handler",
+                "sourceFile": mrel, "sourceLine": fn.lineno,
+                "scan": self.deep_scan(fn, fmod),
+            })
+            self.routes.append({
+                "method": verb, "path": full_path,
+                "sourceFile": mrel, "sourceLine": fn.lineno,
+                "params": self.params_of(fn, full_path),
+                "chain": chain,
+                "description": (ast.get_docstring(fn) or "")[:400],
+            })
+
+    def auth_guard_steps(self, fn, rel_file):
+        """@login_required / @jwt_required / @requires_auth on a handler → a verified guard step."""
+        steps = []
+        for d in getattr(fn, "decorator_list", []):
+            dname = (d.func.attr if isinstance(d, ast.Call)
+                     and isinstance(d.func, ast.Attribute)
+                     else d.func.id if isinstance(d, ast.Call)
+                     and isinstance(d.func, ast.Name)
+                     else d.attr if isinstance(d, ast.Attribute)
+                     else d.id if isinstance(d, ast.Name) else "")
+            if re.search(r'login_required|jwt_required|requires?_auth|auth_required'
+                         r'|require_login|token_required|permission_required',
+                         dname or "", re.I):
+                steps.append(self._guard_step(dname, rel_file, fn.lineno))
+                break
+        return steps
+
+    def cbv_class_guard(self, cls, rel_file):
+        """MethodView `decorators = [login_required]` / Flask-RESTful
+        `method_decorators = [jwt_required]` — a class-level guard over every method."""
+        for stmt in cls.body:
+            if (isinstance(stmt, ast.Assign) and len(stmt.targets) == 1
+                    and isinstance(stmt.targets[0], ast.Name)
+                    and stmt.targets[0].id in ("decorators", "method_decorators")
+                    and isinstance(stmt.value, (ast.List, ast.Tuple))):
+                for e in stmt.value.elts:
+                    nm = (e.func.id if isinstance(e, ast.Call)
+                          and isinstance(e.func, ast.Name)
+                          else e.func.attr if isinstance(e, ast.Call)
+                          and isinstance(e.func, ast.Attribute)
+                          else e.id if isinstance(e, ast.Name)
+                          else e.attr if isinstance(e, ast.Attribute) else "")
+                    if re.search(r'login_required|jwt_required|requires?_auth'
+                                 r'|auth_required|require_login|token_required'
+                                 r'|permission_required', nm or "", re.I):
+                        return [self._guard_step(nm, rel_file, cls.lineno)]
+        return []
+
+    @staticmethod
+    def _guard_step(name, rel_file, line):
+        return {
+            "name": name, "role": "middleware", "sourceFile": rel_file,
+            "sourceLine": line,
+            "scan": {"effects": [], "returnShapes": [], "calls": [],
+                     "async": False, "validatesInput": False,
+                     "guardSignals": {"deniesWithStatus": True}},
+        }
+
     def collect_mount(self, call, abs_file, prefix, import_map, router_vars,
                       router_prefixes, depth=0):
+        # FastAPI `app.include_router(r, prefix=…)` and Flask
+        # `app.register_blueprint(bp, url_prefix=…)` are the same act — mount a
+        # sub-router under a prefix. `register_blueprint` names its prefix `url_prefix`.
         if not (isinstance(call.func, ast.Attribute)
-                and call.func.attr == "include_router" and call.args):
+                and call.func.attr in ("include_router", "register_blueprint")
+                and call.args):
             return
+        prefix_kw = "url_prefix" if call.func.attr == "register_blueprint" \
+            else "prefix"
         arg0 = call.args[0]
         router_name = None
         if isinstance(arg0, ast.Name):
@@ -1038,7 +1269,7 @@ class UbgExtractor:
             return
         mount_prefix = ""
         for kw in call.keywords:
-            if kw.arg == "prefix" and isinstance(lit(kw.value), str):
+            if kw.arg == prefix_kw and isinstance(lit(kw.value), str):
                 mount_prefix = lit(kw.value)
         resolved = import_map.get(router_name)
         cum = (prefix + mount_prefix).replace("//", "/")

package/src/ubg/genome.js

@@ -134,7 +134,7 @@ export function verifyAntibody(ab) {
   const id = `${ANTIBODY_VERSION}_${sha256(body).slice(0, 32)}`;
   if (id !== ab.id) return { ok: false, reason: 'content-address' };
   // signature: Ed25519 over the same claim bytes the id commits to.
-  let sigOk = false;
+  let sigOk;
   try {
     sigOk = crypto.verify(
       null,

package/src/ubg/nextjs.js

@@ -9,6 +9,77 @@ import { parseModule, resolveExportedFunction, scanFunction } from './extract.js
 import { walkCalls } from './resolve.js';
 
 const VERBS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+
+// Read `export const config = { matcher: "…" | ["…", …] }` from a middleware module.
+// Returns { patterns: string[]|null, unresolved: boolean }. patterns=null means no
+// matcher (Next runs the middleware on every path). unresolved=true means a matcher
+// exists but isn't a static string/array we can evaluate — the SOUND response is to
+// NOT credit the guard (never a false PROVEN), handled in middlewareCovers().
+export function readMatcher(mod) {
+  if (!mod?.ast) return { patterns: null, unresolved: false };
+  for (const node of mod.ast.program.body) {
+    const decl = node.type === 'ExportNamedDeclaration' ? node.declaration : node;
+    if (decl?.type !== 'VariableDeclaration') continue;
+    for (const d of decl.declarations) {
+      if (d.id?.name !== 'config' || d.init?.type !== 'ObjectExpression') continue;
+      const m = d.init.properties.find(
+        (p) => (p.key?.name ?? p.key?.value) === 'matcher',
+      );
+      if (!m) return { patterns: null, unresolved: false }; // config without matcher = all paths
+      const lit = (n) => (n?.type === 'StringLiteral' ? n.value : null);
+      if (lit(m.value) !== null) return { patterns: [lit(m.value)], unresolved: false };
+      if (m.value?.type === 'ArrayExpression') {
+        const out = m.value.elements.map(lit);
+        return out.every((s) => s !== null)
+          ? { patterns: out, unresolved: false }
+          : { patterns: null, unresolved: true };
+      }
+      return { patterns: null, unresolved: true }; // computed matcher — can't decide
+    }
+  }
+  return { patterns: null, unresolved: false };
+}
+
+// Does a middleware with these matcher patterns run on `routePath`? Returns
+// true | false | null(=unknown). Handles the two dominant vibe-coded forms:
+// positive path globs (`/dashboard/:path*`) and the negative-lookahead exclude
+// (`/((?!api/|_next/).*)`). Anything else → null, and the caller treats unknown
+// as "do not attribute the guard" so an unresolved matcher never fabricates a proof.
+export function matcherCovers(patterns, routePath) {
+  let anyUnknown = false;
+  for (const p of patterns) {
+    const r = onePattern(p, routePath);
+    if (r === true) return true;
+    if (r === null) anyUnknown = true;
+  }
+  return anyUnknown ? null : false;
+}
+
+function onePattern(pattern, routePath) {
+  if (typeof pattern !== 'string' || pattern[0] !== '/') return null;
+  // negative lookahead: "/((?!api/|_next/|favicon.ico).*)" → covers everything but the excludes
+  const neg = pattern.match(/^\/\(\(\?!(.+?)\)\.\*\)\/?$/);
+  if (neg) {
+    const excludes = neg[1].split('|').map((s) => '/' + s.replace(/\/$/, ''));
+    return !excludes.some((ex) => routePath === ex || routePath.startsWith(ex + '/'));
+  }
+  // any other regex-ish pattern → not statically decidable here
+  if (/[()?!+^$|\\]/.test(pattern)) return null;
+  // positive path glob: `:seg` and `*` are wildcards, everything else literal.
+  // `/:path*` (slash + star modifier) matches zero-or-more trailing segments, so
+  // `/dashboard/:path*` covers `/dashboard` itself as well as `/dashboard/x`.
+  const rx = new RegExp(
+    '^' +
+      pattern
+        .replace(/[.]/g, '\\$&')
+        .replace(/\/:[A-Za-z0-9_]+\*/g, '(?:/.*)?')
+        .replace(/:[A-Za-z0-9_]+\*/g, '.*')
+        .replace(/:[A-Za-z0-9_]+/g, '[^/]+')
+        .replace(/\*/g, '.*') +
+      '$',
+  );
+  return rx.test(routePath);
+}
 const ROUTE_FILES = new Set([
   'route.js',
   'route.ts',
@@ -34,12 +105,19 @@ export function extractNext(cwd, appDir) {
     if (mod.error) continue;
     const fn = mod.functions.get('middleware') ?? mod.functions.get('default');
     if (fn) {
+      // `export const config = { matcher: [...] }` scopes which paths the middleware
+      // runs on. Ignoring it is a FALSE-PROVEN generator: a middleware that denies
+      // for /dashboard would otherwise be credited as a guard on /api too. Carry the
+      // matcher so the translator only attributes the guard to paths it truly covers.
+      const { patterns, unresolved } = readMatcher(mod);
       globalMiddlewares.push({
         name: 'middleware',
         role: 'middleware',
         sourceFile: rel(abs),
         sourceLine: fn.line,
         fn: fn.node,
+        matcherPatterns: patterns, // null = no matcher = runs on every path (Next default)
+        matcherUnresolved: unresolved, // matcher present but not statically decidable
       });
       scannedFiles.push(rel(abs));
     }
@@ -91,10 +169,74 @@ export function extractNext(cwd, appDir) {
         walk(abs, [...segments, m ? `:${m[1]}` : name]);
       } else if (item.isFile() && ROUTE_FILES.has(item.name)) {
         parseRouteFile(abs, '/' + segments.join('/') || '/');
+      } else if (item.isFile() && /\.(t|j)sx?$/.test(item.name)) {
+        // C3: a Next server action (`'use server'`) is a remotely-invocable entrypoint just like a
+        // route — a client form can call it with any args. An unguarded mutating action is a real
+        // hole, but SPARDA saw only `route.ts` files, so it was INVISIBLE and coverage read a false
+        // 100%. Extract exported server actions so they get the same O1 guard analysis as routes.
+        parseServerActions(abs);
       }
     }
   }
 
+  // A server action = an exported async function in a `'use server'` MODULE, or any async function
+  // with a function-level `'use server'` directive. Registered as a POST entrypoint (actions mutate
+  // via a POST-like RPC); its body scan gets the normal in-body guard + guard-dominance treatment.
+  function parseServerActions(absFile) {
+    let src;
+    try {
+      src = fs.readFileSync(absFile, 'utf8');
+    } catch {
+      return;
+    }
+    if (!src.includes('use server')) return; // cheap pre-filter — never parse an ordinary component
+    const mod = parseModule(absFile);
+    if (mod.error || !mod.ast) return;
+    const relFile = rel(absFile);
+    const relNoExt = relFile.replace(/\.(t|j)sx?$/, '');
+    const moduleLevel = (mod.ast.program.directives ?? []).some(
+      (d) => d.value?.value === 'use server',
+    );
+    let found = false;
+    for (const { name, fn, line } of exportedAsyncFns(mod.ast)) {
+      if (!moduleLevel && !fnDeclaresUseServer(fn)) continue;
+      found = true;
+      // in-body auth verifier → a guard step, exactly as a plain route handler gets (nextjs.js's
+      // bodyGuardScan is tight: a verifier-shaped NAME that PROVABLY denies). No wrapper on actions.
+      const guardSteps = [];
+      const bg = bodyGuardScan(fn, mod);
+      if (bg)
+        guardSteps.push({
+          name: bg,
+          role: 'middleware',
+          sourceFile: relFile,
+          sourceLine: line,
+          fn: null,
+          scan: {
+            effects: [],
+            returnShapes: [],
+            calls: [],
+            async: true,
+            validatesInput: false,
+            guardSignals: { deniesWithStatus: true },
+          },
+        });
+      routes.push({
+        method: 'post',
+        path: `(action) ${relNoExt}#${name}`,
+        sourceFile: relFile,
+        sourceLine: line,
+        params: [],
+        chain: [
+          ...guardSteps,
+          { name, role: 'handler', sourceFile: relFile, sourceLine: line, fn },
+        ],
+        description: 'server action',
+      });
+    }
+    if (found && !scannedFiles.includes(relFile)) scannedFiles.push(relFile);
+  }
+
   function parseRouteFile(absFile, urlPath) {
     const mod = parseModule(absFile);
     const relFile = rel(absFile);
@@ -239,6 +381,53 @@ function verbHandlers(mod) {
   return out;
 }
 
+// Exported async functions of a module — `export async function f(){}`,
+// `export const f = async () => {}`, `export default async function(){}`. Server actions are
+// always async; a non-async export in a `'use server'` file is a re-exported constant, not an action.
+function exportedAsyncFns(ast) {
+  const out = [];
+  const consider = (name, fn, line) => {
+    if (fn && fn.async) out.push({ name, fn, line: line ?? fn.loc?.start.line ?? 0 });
+  };
+  for (const node of ast.program.body) {
+    if (node.type === 'ExportNamedDeclaration' && node.declaration) {
+      const d = node.declaration;
+      if (d.type === 'FunctionDeclaration' && d.id)
+        consider(d.id.name, d, d.loc?.start.line);
+      else if (d.type === 'VariableDeclaration')
+        for (const decl of d.declarations)
+          if (
+            decl.id?.type === 'Identifier' &&
+            (decl.init?.type === 'ArrowFunctionExpression' ||
+              decl.init?.type === 'FunctionExpression')
+          )
+            consider(decl.id.name, decl.init, decl.loc?.start.line);
+    } else if (node.type === 'ExportDefaultDeclaration') {
+      const d = node.declaration;
+      if (
+        d?.type === 'FunctionDeclaration' ||
+        d?.type === 'ArrowFunctionExpression' ||
+        d?.type === 'FunctionExpression'
+      )
+        consider(d.id?.name ?? 'default', d, d.loc?.start.line);
+    }
+  }
+  return out;
+}
+
+// A function-level `'use server'` directive — `async function f(){ 'use server'; … }`.
+function fnDeclaresUseServer(fn) {
+  const b = fn?.body;
+  if (b?.type !== 'BlockStatement') return false;
+  if ((b.directives ?? []).some((d) => d.value?.value === 'use server')) return true;
+  const first = b.body?.[0];
+  return (
+    first?.type === 'ExpressionStatement' &&
+    first.expression?.type === 'StringLiteral' &&
+    first.expression.value === 'use server'
+  );
+}
+
 // resolve an `export const VERB = <init>` right-hand side to a scannable function node
 // (or null — route still registered, body blind) PLUS the names of any HOC wrappers the
 // handler is nested inside. Handles inline fns, local aliases, and wrapper calls whose

package/src/ubg/resolve.js

@@ -33,6 +33,13 @@ export const MAX_RESOLVE_DEPTH = 6;
 // merge one scan's findings into another — the single copy of the contract
 // every follower shares.
 export function mergeScan(into, add) {
+  // Guard-dominance (C2) is a property of the ROUTE HANDLER's own body: a mutation that runs before
+  // the handler's auth check. A `bypassesGuard` computed inside a delegated/transitively-called body
+  // is that body's INTERNAL ordering (a service that mutates then runs a permission check) — not the
+  // route's auth gate, exactly as "effects merge; guards do not" (below). Strip it at the merge so a
+  // service's internal shape never flags the route. The handler's own effects live in `into` from
+  // the start and are never merged, so they keep their flag.
+  for (const e of add.effects) if (e.bypassesGuard) delete e.bypassesGuard;
   into.effects.push(...add.effects);
   into.returnShapes = [...(into.returnShapes ?? []), ...(add.returnShapes ?? [])];
   into.calls = [...(into.calls ?? []), ...(add.calls ?? [])];

package/src/ubg/translate.js

@@ -24,6 +24,18 @@ import {
   stateId,
 } from './schema.js';
 import { isGuardLike, isNoOpGuard, scanFunction } from './extract.js';
+import { matcherCovers } from './nextjs.js';
+
+// A global middleware only guards a route whose path its Next `config.matcher`
+// actually covers. No matcher → every path (Next default). A matcher present but
+// unresolved, or one that resolves to "not covered", → do NOT attribute (an
+// unproven guard is never fabricated — SOUNDNESS.md, no false PROVEN).
+function middlewareAppliesTo(mw, routePath) {
+  if (mw.role !== 'middleware' || mw.matcherPatterns == null) {
+    return !mw.matcherUnresolved; // no matcher = all paths; unresolved matcher = abstain
+  }
+  return matcherCovers(mw.matcherPatterns, routePath) === true;
+}
 
 // Is this chain step / helper a REAL guard? Named or deny-bodied like a guard, and
 // NOT a visible no-op pass-through (a disabled `(req,res,next)=>next()` guards nothing).
@@ -149,8 +161,12 @@ function translateRoute(
     ),
   );
 
-  // global middlewares run before route-level ones — same chain, lower order
-  const fullChain = [...globalMiddlewares, ...route.chain];
+  // global middlewares run before route-level ones — same chain, lower order —
+  // but only those whose matcher actually covers this route's path (E-NEXT-MW)
+  const applicable = globalMiddlewares.filter((mw) =>
+    middlewareAppliesTo(mw, route.path),
+  );
+  const fullChain = [...applicable, ...route.chain];
   let prevId = epId;
   let order = 0;
   const chainNodes = [];
@@ -325,6 +341,9 @@ function attachBody(graph, ownerId, scan, helperByName, scanCache, expanded) {
           // Advisory provenance — it enriches an UNGUARDED_MUTATION, never a finding of
           // its own (a per-function under-approximation can't see service-layer validation).
           ...(eff.tainted ? { tainted: true } : {}),
+          // guard-dominance (kills the C2 false PROVEN): this mutation runs BEFORE a guard that
+          // follows it on the same body spine — i.e. it executes without having passed that check.
+          ...(eff.bypassesGuard ? { bypassesGuard: true } : {}),
           // object-scope provenance (ADR-058 B): the query targets a bare `id`, and whether
           // it is scoped to the caller. A route with an idScoped access and NO ownerScoped
           // access anywhere on its resolved path is a BOLA candidate (advisory).