sparda-mcp 0.69.1 → 0.70.1

package/README.md

@@ -6,53 +6,97 @@
 
 <br/>
 
-> 🇫🇷 **Français** : Pour comprendre SPARDA en 10 minutes (douleur, architecture, vision), lisez le document du fondateur : [SPARDA-EXPLIQUE.md](docs/SPARDA-EXPLIQUE.md).
+> 🇫🇷 **Français** — _L'IA écrit. SPARDA prouve._ Un gate déterministe et hors-ligne qui détecte quand une modif d'IA retire une garde, expose une route ou casse un invariant — sans clé API, directement dans la boucle d'édition de l'agent. Pour tout comprendre en 10 minutes (douleur, architecture, vision) : [SPARDA-EXPLIQUE.md](docs/SPARDA-EXPLIQUE.md).
 
 ---
 
-**The trust layer for AI-written code. AI writes. SPARDA proves.**
+<h1 align="center">AI writes. SPARDA proves.</h1>
+<p align="center"><em>L'IA écrit. SPARDA prouve.</em></p>
 
-Under the hood: a compiler for backend behavior — the LLVM of web applications.
+**The trust layer for AI-written backends.** SPARDA compiles your backend — routes, database queries, state mutations, guards, side-effects — into one deterministic behavior graph, then **statically proves what can and can't break before you ship**: no unguarded mutation, no broken invariant, no non-atomic aggregate write.
 
-For twenty years software communicated through APIs. Then AI agents arrived, and the industry's answer was to expose more endpoints (MCP). But an agent doesn't *understand* an application from a list of disconnected tools — and neither can a linter, a debugger, or a deploy gate reason about a codebase they only read line by line.
+[![npm](https://img.shields.io/npm/v/sparda-mcp)](https://www.npmjs.com/package/sparda-mcp)
+[![CI](https://github.com/zyx77550/sparda/actions/workflows/ci.yml/badge.svg)](https://github.com/zyx77550/sparda/actions/workflows/ci.yml)
+![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)
+![runtime deps](https://img.shields.io/badge/runtime%20deps-4%20pinned-4c1)
+[![license](https://img.shields.io/badge/license-BUSL--1.1-blue)](./LICENSE)
 
-SPARDA compiles your backend — routes, database queries, state mutations, permissions, side-effects — into one language-agnostic, mathematical graph: the **Unified Behavior Graph (UBG)**, serialized as `.sparda/ubg.json` under the **SBIR** specification ([SPARDA Behavior IR](docs/SBIR_SPEC_V1.1.md)). Compile once; then every tool is a simple pass over that graph.
+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.
 
-> [!IMPORTANT]  
-> **The 3700-Route Proof:** In our latest stress-test (v0.26.0), SPARDA successfully compiled and proved **3700+ routes** from elite open-source monsters (Next.js *Dub*, NestJS *Immich*, *MedusaJS*, and GitHub's OpenAPI) in **< 2.2 seconds** per repo, with zero crashes. It natively resolves deep Dependency Injection, external controllers, and Next.js handlers.
+## 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, or on an unverified premise
+npx sparda-mcp prove        # the whole verdict: proof + coverage + shareable seal
+npx sparda-mcp badge        # a README badge: proven · coverage% · routes
+```
+
+Under the hood it compiles your backend into one language-agnostic graph — the **Unified Behavior Graph (UBG)**, serialized as `.sparda/ubg.json` under the **SBIR** specification ([SPARDA Behavior IR](docs/SBIR_SPEC_V1.1.md)) — and every command is a pass over that graph.
 
-**What the graph unlocks — 100% local, deterministic, zero runtime dependencies, zero API key:**
+## The wedge — catch an AI edit that removes a guard, in the loop
 
-| Command | What it does |
-|---|---|
-| **`ubg`** | Compile the codebase to its behavior graph (Express · FastAPI · Next.js natively; **any** stack via OpenAPI) |
-| **`apocalypse`** | *Prove the deploy* — no guard, invariant, transaction or aggregate boundary can be broken (SARIF + CI gate) |
-| **`timeless`** | *Time-travel* — record a production request, replay it byte-identically, export the bug as a test |
-| **`heal`** | *Self-heal, proven* — bug → fix → the machine proves the fix is correct and breaks nothing |
-| **`mirror`** | *Execute the graph* — serve the compiled behavior over HTTP with no framework and no source |
-| **`openapi`** | *Emit the standard* — produce an OpenAPI 3.1 spec from the graph |
-| **`verify`** | *Prove the compiler's own laws* (determinism, soundness, round-trip) on your app |
-| **`init` / `dev`** | Expose the graph to AI clients as a live MCP server (+ Twin, Immune, Evolution runtime layer) |
+The one thing a text-diff review and a pattern scanner structurally can't do: prove that **this specific edit** dropped a protection the previous version had. `sparda gate` diffs the behavior graph before/after an edit and blocks a regression — deterministic, offline, sub-second, exit 2 (the Claude Code `PostToolUse` contract that stops the agent's edit loop). See it end-to-end in one command, zero setup:
 
 ```bash
-npx sparda-mcp ubg          # compile your backend → .sparda/ubg.json
-npx sparda-mcp apocalypse   # prove the current tree is safe to deploy
+npm run wedge     # (from a clone)  — or drive it on your own app with `sparda gate --arm` then `sparda gate --hook`
 ```
 
-No cloud account. No server to host. Exposing raw APIs to AI is the old way — SPARDA compiles the whole system's behavior, then proves, replays, heals, and serves it.
+```
+  1. baseline armed on the guarded code   (POST /admin/delete-user · requireAdmin)
+  2. an AI edit "simplifies" requireAdmin → a pass-through (still compiles, still 200s)
+  3. sparda gate on the edit:
+       ✗ [critical] GUARD_REMOVED — POST /admin/delete-user was guarded in the baseline
+                    and is now reachable without any guard (src/app.js:11)
+     ⏱  ~40 ms · deterministic · offline · no API key
+     ⛔ exit 2 on --hook — Claude Code PostToolUse blocks the edit
+```
+
+**Wire it into Claude Code in one line** — the [plugin](integrations/claude-code-plugin) registers a `PostToolUse` hook that runs `npx -y sparda-mcp gate --hook` after every `Edit`/`Write`, so a guard-removing edit is caught before it lands.
+
+> [!IMPORTANT]  
+> **The Route-Compilation Proof — reproduce it yourself.** SPARDA compiles real open-source monsters to their behavior graph with **zero crashes**, each in **≈1–2 seconds**: Next.js _Dub_ (579 routes), NestJS _Immich_ (281), _MedusaJS_ (477). It natively resolves deep Dependency Injection, external controllers, and Next.js handlers. One command clones them and re-measures on your machine:
+>
+> ```bash
+> node bench/repro.mjs        # → bench/route-proof.json
+> ```
+>
+> Honesty first: _compiling_ a route is a parser result (the number above); _proving_ it safe is a separate per-repo verdict — and most real apps come back **NOT_PROVEN**, which is the true state, not a failure. (Our full 25-repo corpus stress compiles **3,565 routes** at ~150 routes/s; that one needs the corpus checked out.)
+
+**What the graph unlocks — 100% local, deterministic, 4 exact-pinned dependencies, zero API key:**
 
-**Nomenclature:** **SBIR** is the specification (the format, like "JSON"); **UBG** is the compiled graph itself (the artifact, `ubg.json`). The MCP server is one *output* of the graph, not the product.
+| Command            | What it does                                                                                                                                                                                                                         |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **`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)                                                                                                                                 |
+| **`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 · 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)                                                                                                                                |
 
-## Quickstart
+The prover is the product. The MCP server is one _output_ of the graph, not the point — SPARDA compiles the whole system's behavior, then proves, replays, heals, and (optionally) serves it.
+
+**Nomenclature:** **SBIR** is the specification (the format, like "JSON"); **UBG** is the compiled graph itself (the artifact, `ubg.json`). The MCP server is one _output_ of the graph, not the product.
+
+## Optional: expose the graph to AI clients (MCP runtime)
+
+Beyond proving, SPARDA can turn your running app into a live MCP server — the graph, executable, with write-safety and an immune layer. This is optional and separate from the prover above.
 
 1. **Scan + inject** — run once, from your app's directory:
+
    ```bash
    npx sparda-mcp init
    ```
+
    SPARDA parses your routes (AST), generates a marked `/mcp` router, injects it into
    your app (with a backup), and writes `sparda.json`. Every step is reversible.
 
 2. **Start your app, then start the bridge:**
+
    ```bash
    npx sparda-mcp dev
    ```
@@ -76,25 +120,31 @@ No cloud account. No server to host. Exposing raw APIs to AI is the old way —
 ## Try the Standalone Demo
 
 To see SPARDA in action instantly without modifying your codebase:
+
 ```bash
 npx sparda-mcp demo
 ```
+
 This runs the entire MCP lifecycle (detect → parse → generate → inject → remove) on a bundled demo app in a temporary folder, in about 10 seconds. For the compiler itself, run `npx sparda-mcp ubg` then `apocalypse` on any Express/FastAPI app.
 
 ## Black Box Report
 
 SPARDA is designed as a local organism. To see what it remembers and how much compute it has recycled:
+
 ```bash
 npx sparda-mcp report
 ```
+
 This prints a terminal dashboard aggregating your exposed tools, write opt-ins, proof journal decisions, and crystallized composite tools.
 
 To write a self-contained, offline HTML dashboard at `.sparda/report.html`, append the `--html` flag:
+
 ```bash
 npx sparda-mcp report --html
 ```
 
 To output raw JSON for integration:
+
 ```bash
 npx sparda-mcp report --json
 ```
@@ -102,28 +152,37 @@ npx sparda-mcp report --json
 ## Deployment Proof: Apocalypse
 
 SPARDA's Behavior Graph is a formal model of your system. Instead of waiting for runtime failures or relying on static analysis vibes, you can statically prove the safety of your backend before any deployment:
+
 ```bash
 npx sparda-mcp apocalypse
 ```
+
 This command reads the compiled `.sparda/ubg.json` (with zero source code parsing at runtime) and discharges five static correctness obligations:
-* **Unguarded Mutation (Critical)**: Flags any mutation path that does not cross a security `guard`.
-* **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).
-* **Aggregate Member Bypass (Info)**: Flags mutating a member table directly without routing through the aggregate root.
+
+- **Unguarded Mutation (Critical)**: Flags any mutation path that does not cross a security `guard`.
+- **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:
+
 ```bash
 npx sparda-mcp apocalypse --save-baseline
 ```
+
 Subsequent runs will diff the candidate graph against this baseline to detect regression vectors:
-* Deletion of any security `guard` (Critical).
-* Deletion of a database SQL invariant (High).
-* API blast radius expansion (Medium).
+
+- Deletion of any security `guard` (Critical).
+- Deletion of a database SQL invariant (High).
+- API blast radius expansion (Medium).
 
 If any Critical or High finding is found, `apocalypse` exits with a non-zero code to block your CI pipeline.
 
 **One step in your workflow — findings land in the GitHub Security tab (SARIF):**
+
 ```yaml
 - uses: zyx77550/sparda@main
   with:
@@ -141,11 +200,13 @@ npx sparda-mcp timeless export <id>    # the production bug is now a vitest test
 ```
 
 Recording is two lines in your app (ESM), with deterministic sampling and GDPR redaction built in:
+
 ```js
 import { getFlightBox } from 'sparda-mcp/src/flight/box.js';
-const box = getFlightBox(); box.arm();
-app.use(box.middleware({ sample: 100 }));   // 1 request in 100; passwords/tokens redacted by default
-const db = box.wrapClient(pgPool);           // your query client, tapped
+const box = getFlightBox();
+box.arm();
+app.use(box.middleware({ sample: 100 })); // 1 request in 100; passwords/tokens redacted by default
+const db = box.wrapClient(pgPool); // your query client, tapped
 ```
 
 The closed loop nobody else has: **production bug → recorded flight → failing test → AI writes the fix → `apocalypse` proves the fix breaks no guard, invariant or transaction → deploy.** Replay is per-request (concurrent-race capture is out of scope for v1 — stated, not hidden).
@@ -162,7 +223,7 @@ npx sparda-mcp heal <flightId> --check --expect '{"status":404}'
 
 The brief is built from the graph itself — it hands the fixer the handler's `file:line`, the capabilities the fix must not grow, and the guards it must not remove. Then the **gate** — the actual product — proves the fix on three axes at once:
 
-1. **Behavior** — lenient replay of the recorded flight (same deterministic inputs) now produces the *expected* response, not the recorded bug. The fix may reformulate a query (the tap is relabeled, allowed); it may **not** change the effect order or kinds.
+1. **Behavior** — lenient replay of the recorded flight (same deterministic inputs) now produces the _expected_ response, not the recorded bug. The fix may reformulate a query (the tap is relabeled, allowed); it may **not** change the effect order or kinds.
 2. **Compiler laws** — `verify` still passes: the graph is still sound and deterministic.
 3. **No regression** — `apocalypse` diff against the frozen pre-fix graph: zero new critical/high findings, no guard removed, no blast radius grown.
 
@@ -170,11 +231,11 @@ The brief is built from the graph itself — it hands the fixer the handler's `f
 ✓ HEALED & PROVEN — same recorded inputs, correct output, zero law broken, zero protection lost. Ship it.
 ```
 
-The gate is honest in both directions: an unfixed bug, or a "fix" that silently drops a guard, keeps it **closed** (exit 1). This is the difference between an AI that writes plausible code and a system that *proves* the code is correct — the trust layer the agent era is missing.
+The gate is honest in both directions: an unfixed bug, or a "fix" that silently drops a guard, keeps it **closed** (exit 1). This is the difference between an AI that writes plausible code and a system that _proves_ the code is correct — the trust layer the agent era is missing.
 
 ## 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
@@ -215,7 +276,7 @@ To undo everything: **`npx sparda-mcp remove`** restores your code byte-for-byte
 5. **Nothing leaves your machine.** No telemetry to us, no cloud, local key auth, 4 exact-pinned dependencies.
 6. **What it learns is never lost.** Diagnoses, descriptions, settings — versioned with your git, surviving every re-init.
 
-What we *don't* promise: the honest limits in [docs/SECURITY.md](./docs/SECURITY.md).
+What we _don't_ promise: the honest limits in [docs/SECURITY.md](./docs/SECURITY.md).
 
 ## How it works
 
@@ -232,34 +293,52 @@ What we *don't* promise: the honest limits in [docs/SECURITY.md](./docs/SECURITY
 ## What SPARDA gives your AI
 
 ### Operate, not just read
+
 Every route becomes a tool that runs against your live process — real auth, real data,
 warm connections. One call to **`sparda_get_context`** hands the AI the whole living
 picture: enabled tools, suggested workflows, runtime telemetry, quarantine state, and
 immune memory — so every session resumes where the last one stopped.
 
+### Prove the edit before you commit — the one check an LLM can't do to itself
+
+The AI just edited a route. Did it quietly drop a guard? It calls **`sparda_prove`** and
+finds out **now**, not in a CI run later. The tool recompiles the app to its behavior graph,
+discharges the same static obligations as `sparda apocalypse`, and returns a deterministic
+verdict — the exact word the CLI and badge emit, so it can never over-claim (a low-coverage
+clean app reads `SURFACE`, never a bare `PROVEN`). Save a baseline once
+(`sparda apocalypse --save-baseline`) and every later `sparda_prove` flags any finding with
+`regression: true` — the guard your edit removed, the route it dropped, the blast radius it
+grew. That's _"AI writes. SPARDA proves."_ inside the edit loop. Clients that list MCP prompts
+also get the **`prove-my-edit`** workflow.
+
 ### Write-safety: the AI can't write until you say so
+
 - Writes (POST/PUT/DELETE) ship **disabled**. Enable them per tool in `sparda.json`; your choice survives every re-init.
 - An enabled write is **never executed on the first call**. SPARDA returns an `awaiting_confirmation` envelope — a single-use token plus a preview of the action — and commits only after an explicit confirm step.
 - When your client supports MCP elicitation, that confirmation prompt appears **in the AI's own UI**.
 - **Proof-after-write**: every successful write is followed by a read-back of the same resource, so the AI — and you — see the real effect, not a hopeful guess.
 
 ### Your app defends itself — zero LLM on the hot path
+
 - **Quarantine.** A tool that returns 3 consecutive 5xx is quarantined: further calls get a `503` with a reason and a retry delay instead of hammering your broken route. After a cooldown it half-opens for a single probe.
 - **Latency & anomaly flags.** The router learns each route's baseline and flags deviations locally, in a few lines of math.
 - **Adaptive diagnosis, only on surprise.** A genuinely new failure wakes your AI client's own model to diagnose it once; the diagnosis is cached as an "antibody" in `sparda.json`, so the same failure later costs zero tokens. Cloning your code doesn't clone its immune memory.
 
 ### A free intelligence layer, zero API key
+
 On first connection your AI client's own model (via MCP sampling) rewrites raw routes
 into business-language tool descriptions and proposes multi-step workflows — cached in
 `sparda.json` and exposed as MCP prompts. Nothing to configure, nothing to pay.
 
 ### It gets cheaper the more you use it
+
 - **Response recycling.** When a read keeps returning the same answer, SPARDA serves the next identical call straight from memory — without touching your host app. Reads only; writes always hit the host.
 - **A recycling gauge.** `GET /mcp/stats` counts how many calls were answered from SPARDA's own knowledge vs. how many paid the host route. It reads 0% on day one and fills with usage — a measure, never a promise.
 
 ### Tools nobody wrote — Labs, opt-in, default OFF
+
 Turn it on with `"labs": { "recordSequences": true }` in `sparda.json`. SPARDA then
-notices when one tool's output feeds the next tool's input and records the *circuit* —
+notices when one tool's output feeds the next tool's input and records the _circuit_ —
 structure only (tool names, argument names, counts), never your data. A read-only
 circuit seen enough times **crystallizes into a composite tool**, announced
 mid-session: one call runs the whole chain, auto-feeding each step from the previous
@@ -267,11 +346,13 @@ step's real response. Write routes are never absorbed — their per-call confirm
 always stands.
 
 ### Living context & telemetry
+
 `GET /mcp/stats` (per-tool calls/errors, tool "purity", quarantine state) and
 `GET /mcp/events` (errors, latency anomalies, cached diagnoses) expose exactly what
 your app is doing — surfaced to the AI as live notifications.
 
 ## Built for AI clients: the bundled Skill
+
 SPARDA ships with an Agent Skill ([`SKILL.md`](./SKILL.md)) that teaches any compatible
 AI client how to drive a SPARDA server to its **full potential** — call
 `sparda_get_context` first, exploit response recycling, honor quarantine, prefer
@@ -282,13 +363,20 @@ 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. Supports Prisma, TypeORM, and Kysely.
-- **Express 4/5** (JS/TS, ESM/CJS) — AST-based router injection. Deeply resolves external controllers, Mongoose schemas, and barrel re-exports. Uses dynamic tree-scanning to find non-standard entry points (`bootstrap.ts`, etc).
+- **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.
 - **FastAPI** (Python >= 3.9) — AST-based router injection.
 
+### Effects it resolves (what makes the irreversibility & atomicity proofs bite)
+
+- **Databases** — Prisma (incl. named/multiline relations and interactive `$transaction(tx ⇒ …)`), TypeORM, Kysely, Drizzle, Knex, Sequelize, Mongoose, and raw SQL. Foreign keys become aggregate/consistency domains, so a multi-table write outside a transaction is caught.
+- **External side-effects** — recognized by call shape and by import origin, so an irreversible outbound effect next to a DB write is proven compensable-or-not: `fetch`/axios/got, Stripe, Twilio, SendGrid/Resend/nodemailer, AWS SDK v3 (`send(new PutObjectCommand())`), and other payment/mail/cloud/queue clients. A read on such a client stays a non-observable GET — no false alarms.
+
 ## Security posture (honest)
+
 - 4 runtime dependencies, exact-pinned.
 - **Dynamic Local Key Resolution.** The generated router contains no baked secrets. It resolves authorization keys at runtime from the `SPARDA_LOCAL_KEY` environment variable or the local gitignored `.sparda/key` file, and fails closed (503) when neither is found. For custom production or staging setups, you can override this behavior by exposing `SPARDA_LOCAL_KEY` in your environment.
 - Local key on every router call; self-reference loop protection; 30s timeouts; 8 KB output truncation.
@@ -298,18 +386,21 @@ runtime, so the guidance never goes stale.
 Full threat model and known gaps: [docs/SECURITY.md](./docs/SECURITY.md).
 
 ## Documentation
+
 - [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — how `init`, the injected router, and the bridge fit together, plus the `sparda.json` schema.
 - [docs/SECURITY.md](./docs/SECURITY.md) — threat model, defenses, and honest known gaps.
 - [docs/TESTING.md](./docs/TESTING.md) — how the promises above are kept honest in CI.
 - [docs/ERRORS.md](./docs/ERRORS.md) — the error knowledge base.
 
 ## Beyond the open core
+
 SPARDA is free, including in production (see License). Team-scale capabilities —
 fine-grained per-person access policies and a signed, tamper-evident audit log — are
 planned for a future paid tier. The open core stands on its own; nothing here is
 crippled to upsell you.
 
 ## License
+
 [Business Source License 1.1](./LICENSE) — free to use, including in production.
 You may not resell SPARDA or offer it as a competing commercial service.
 Each version converts to Apache 2.0 four years after its release.

package/SKILL.md

@@ -13,11 +13,11 @@ description: >-
 
 A SPARDA server is driven by a compiled **Unified Behavior Graph (UBG)** — the graph SPARDA's compiler produces from the host application's states, transitions, permissions, and side-effects, serialized under the **SBIR** specification. Instead of exposing raw, disconnected endpoints, SPARDA compiles the app into a deterministic behavioral model. The local **SPARDA Runtime** dynamically executes this graph inside the live host process, powering the MCP interface, the Twin simulation clone, and the Immune system offline.
 
-> This skill covers the **runtime** (driving a live MCP server) — the live half of SPARDA's trust layer: *"AI writes. SPARDA proves."* The same graph also powers dev-time proof commands you run in the app's repo — `sparda review` (the behavior diff of a PR), `apocalypse` (prove the deploy), `timeless` (record/replay a request), `heal` (prove a fix), `mirror` (serve the graph), `ubg` (compile), `verify` (prove the compiler's laws). Those are CLI, not MCP tools; see the project README.
+> This skill covers the **runtime** (driving a live MCP server) — the live half of SPARDA's trust layer: _"AI writes. SPARDA proves."_ The same graph also powers dev-time proof commands you run in the app's repo — `sparda review` (the behavior diff of a PR), `apocalypse` (prove the deploy), `timeless` (record/replay a request), `heal` (prove a fix), `mirror` (serve the graph), `ubg` (compile), `verify` (prove the compiler's laws). Those are CLI, not MCP tools; see the project README.
 
 ## Rule 0 — call `sparda_get_context` first, every session
 
-Before anything else, call **`sparda_get_context`** (no params). It returns the *live* state of the SPARDA Behavior Graph:
+Before anything else, call **`sparda_get_context`** (no params). It returns the _live_ state of the SPARDA Behavior Graph:
 
 - the active routes/tools, workflows, and type-propagated schemas;
 - `runtime` — current stats (calls, errors, quarantine states, Twin mode active);
@@ -35,19 +35,45 @@ Read it to orient yourself inside the graph. `sparda_info` gives a lighter summa
   parameter schema was only partially inferred — pass arguments carefully.
 - **Meta-tools** — `sparda_get_context`, `sparda_info`,
   `sparda_list_disabled_tools`, `sparda_confirm`.
+- **The proof tool** — `sparda_prove`. Call it **after you edit a route, before you
+  commit** — see _Prove your own edit_ below. It's the one check you can't do to
+  yourself by re-reading your code.
 - **Composite tools** — labelled `[Labs circuit ×N]`, `readOnly`. One call runs a
-  whole proven multi-step chain (see *Crystallized circuits* below).
+  whole proven multi-step chain (see _Crystallized circuits_ below).
 
 Only **enabled** tools appear. Write tools are hidden until the user opts in, so a
-missing write is a config state, not an error — see *Writing safely*.
+missing write is a config state, not an error — see _Writing safely_.
+
+## Prove your own edit — call `sparda_prove` before you commit
+
+This is the tool an LLM needs most and can least fake. After you edit a route,
+**call `sparda_prove`** — it recompiles the app to its behavior graph and discharges
+the same static obligations as `sparda apocalypse` (unguarded mutation, non-atomic
+aggregate write, unvalidated constrained write), then returns a deterministic verdict.
+
+- **Focus it.** Pass `route` with the method+path you just touched (e.g.
+  `{ "route": "DELETE /orders" }`) to narrow the finding list. The **verdict still
+  reflects the whole app** — a filter never buys you a greener light.
+- **Read the verdict honestly.** `PROVEN` / `PARTIAL` are safe to commit. `SURFACE`
+  and `NO_PROOF` mean SPARDA _couldn't resolve enough to prove it_ — that is
+  "unknown", **never** a pass. The word is the exact one the CLI and badge emit; it
+  physically cannot over-claim.
+- **The regression check is the point.** If a baseline was saved
+  (`sparda apocalypse --save-baseline` on a known-good state), any finding with
+  `regression: true` means _your edit_ removed a guard, dropped a route, or grew the
+  blast radius vs the last proven state. Fix those before committing — this is the
+  check you cannot perform by re-reading your own diff.
+- Clients that list MCP prompts also see **`prove-my-edit`**, the built-in workflow
+  that walks these steps.
 
 ## Exploit the intelligence layer (this is the "full potential")
 
 **1. Response-recycling flywheel — make repeated reads free.**
-When the *same* read tool returns a byte-identical result for the *same* arguments
+When the _same_ read tool returns a byte-identical result for the _same_ arguments
 **3 times within 30 seconds**, SPARDA serves the next identical call straight from
 RAM (`servedByFlywheel: true`) **without touching the host app**. So:
-- Don't fear repeating stable GETs — repetition is what *activates* the cache.
+
+- Don't fear repeating stable GETs — repetition is what _activates_ the cache.
 - Don't bolt your own client-side cache on top; you'd hide the signal that lets
   SPARDA recycle, and you'd lose freshness control.
 - Watch `recycling.flywheel.servedFromMemory` climb in context — that's free work.
@@ -55,7 +81,7 @@ RAM (`servedByFlywheel: true`) **without touching the host app**. So:
 
 **2. Circuit-breaker / quarantine — stop hammering a sick backend.**
 After **3 consecutive 5xx** on a tool, SPARDA quarantines it: subsequent calls
-return **HTTP 503** with `reason` and `retryInMs` *instead of* hitting the failing
+return **HTTP 503** with `reason` and `retryInMs` _instead of_ hitting the failing
 host. Honor `retryInMs` — do not retry-loop. Check `runtime.quarantine` in context
 before depending on a tool. After a cooldown (~60s) the tool half-opens for one
 probe; one more 5xx re-quarantines it.
@@ -68,7 +94,7 @@ single **composite tool** for that chain and announces it mid-session via
 call and it's marked read-only. (Writes are never absorbed into a circuit.)
 
 **4. Adaptive immunity — read the diagnosis before retrying.**
-Repeated, unfamiliar failures trigger a *one-shot* LLM diagnosis that SPARDA caches
+Repeated, unfamiliar failures trigger a _one-shot_ LLM diagnosis that SPARDA caches
 as an "antibody" (keyed by `source|tool|status`). Recurrences reuse the cached
 diagnosis at zero cost. When an error event carries a diagnosis, **read it** and
 adapt — don't blindly retry the same call.
@@ -78,11 +104,13 @@ an `immune` event in `/mcp/events`. Treat it as a hint to back off or warn the u
 
 **6. Twin Simulation Mode — practice safely on a clone.**
 When `/mcp/stats` or `sparda_get_context.runtime` contains `"twin": true`, you are connected to a safe, in-memory mock clone of the application.
+
 - All GET reads return learned exemplars (observed response shapes and mock values).
 - All write tools return simulated `202` echoes but do not write to database or external APIs.
 - Use this twin mode to practice multi-step workflows, debug tool sequences, and test your plans without touching the live production backend.
 
 **7. Grammar & Evolution — discover optimal workflows.**
+
 - You can query or contribute to the app's grammar (`.sparda/grammar.json`). The grammar maps valid sequences of tool calls (edges).
 - Running `sparda evolve` mutates and runs candidate chains against the twin. The successful evolved sequences are suggested as mid-session workflows.
 
@@ -151,7 +179,8 @@ Writes are **disabled by default**. The protocol is not optional:
 - **Learn exemplars** → Start your live app and run `sparda twin --learn` to fetch actual response data and construct `.sparda/twin.json` locally.
 
 ---
-*This skill ships with `sparda-mcp` and is regenerated from SPARDA's capability
+
+_This skill ships with `sparda-mcp` and is regenerated from SPARDA's capability
 surface each release, so it tracks new tools and behaviors. The **live, per-project**
 tool list, stats, and workflows always come from `sparda_get_context` at runtime —
-trust it over any static list.*
+trust it over any static list._

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "sparda-mcp",
-  "version": "0.69.1",
+  "version": "0.70.1",
   "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.",
+  "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 \u2014 no API key, right in the agent edit loop.",
   "type": "module",
   "repository": {
     "type": "git",
@@ -17,7 +17,7 @@
   },
   "scripts": {
     "test": "vitest run",
-    "prepublishOnly": "vitest run",
+    "prepublishOnly": "node scripts/release-gate.mjs",
     "corpus": "node scripts/corpus-oracle.mjs",
     "corpus:update": "node scripts/corpus-oracle.mjs --update",
     "test:router": "node tests/router-selftest.cjs",
@@ -29,7 +29,9 @@
     "format:check": "prettier --check \"**/*.{js,cjs,mjs}\"",
     "bench:check": "node bench/check-readme.mjs",
     "mutation": "node tests/mutation/run.mjs",
-    "wedge": "node bench/wedge.mjs"
+    "wedge": "node bench/wedge.mjs",
+    "release:check": "node scripts/release-gate.mjs",
+    "publish:vscode": "cd extensions/vscode && vsce publish"
   },
   "files": [
     "src",

package/src/ubg/extract.js

@@ -799,6 +799,36 @@ export function resolveExportedFunction(mod, name, seen = new Set()) {
   return null;
 }
 
+// The CLASS twin of `resolveExportedFunction`, and it exists for the same reason one
+// level up. A monorepo package (`@novu/dal`, `@novu/application-generic`) resolves to its
+// entry file, and that entry file is a BARREL — sixty `export * from './repositories/…'`
+// lines and not one class declaration. `classInModule` looks for a class DECLARED in the
+// module it was handed, so every DI hop into a workspace package died on the barrel:
+// measured on novu, 1479 of 2039 constructor-DI hops resolved to nothing, `PinoLogger`
+// and the repository classes at the top of the list. The route's real behavior — every
+// db_write the repository performs — was simply absent from the graph.
+//
+// Bounded by `seen` (a barrel cycle terminates) and memoized by the caller, because a
+// wide barrel is walked once per hop otherwise.
+export function resolveExportedClass(mod, name, seen = new Set()) {
+  if (!mod || mod.error) return null;
+  const direct = classInModule(mod, name);
+  if (direct) return { cls: direct, mod };
+  const named = mod.reexports.get(name); // export { X } from './x'
+  if (named && !seen.has(named)) {
+    seen.add(named);
+    const hit = resolveExportedClass(parseModule(named), name, seen);
+    if (hit) return hit;
+  }
+  for (const file of mod.starReexports ?? []) {
+    if (seen.has(file)) continue;
+    seen.add(file);
+    const hit = resolveExportedClass(parseModule(file), name, seen);
+    if (hit) return hit;
+  }
+  return null;
+}
+
 function collectTopLevel(node, facts, absFile, exported) {
   if (node.type === 'ExportNamedDeclaration' && node.declaration) {
     collectTopLevel(node.declaration, facts, absFile, true);

package/src/ubg/nestjs.js

@@ -96,6 +96,12 @@ export function extractNest(cwd, entryDir) {
   // verified (immich: 253 guards, 0 verified). Prove it ONCE here — resolve its canActivate
   // through DI to a real deny — and every auth-named guard on the app earns `verified`.
   const globalGuardDenies = detectGlobalDenyGuard(root, engine);
+  // Middleware bound in a module's `configure()` via `consumer.apply(X).forRoutes(...)`
+  // (ADR-089) — the auth a per-controller decorator scan cannot see. Detected once; matched
+  // per concrete route below. Unreadable bindings are declared, never guessed.
+  const { bindings: consumerBindings, blindspots: consumerBlindspots } =
+    detectConsumerMiddleware(root, engine);
+  for (const b of consumerBlindspots) skipped.push(b);
   // one resolution per decorator DEFINITION, not per use — novu applies the same four
   // composites across 451 routes
   const compositeCache = new Map();
@@ -245,7 +251,7 @@ export function extractNest(cwd, entryDir) {
           // method it delegates to through DI (this.<prop>.<call>())
           const scan = engine.handlerScan(m, di, mod, cls);
 
-          const chain = [
+          const baseChain = [
             ...guards.map(({ name, mod: srcMod }) => {
               const scan = guardStepScan(name, srcMod, false);
               return {
@@ -306,13 +312,24 @@ export function extractNest(cwd, entryDir) {
             : [fullPath];
           for (const verb of verbs)
             for (const routePath of paths) {
+              // Middleware this concrete (verb, path) earns from module forRoutes bindings,
+              // computed per route because a binding matches on method + path, which vary
+              // across the @All / multi-path expansion. Prepended: middleware runs first.
+              const mwSteps = consumerGuardSteps(
+                consumerBindings,
+                verb,
+                routePath,
+                cls.id?.name ?? null,
+                rel,
+                m.loc?.start.line ?? 0,
+              ).filter((s) => !baseChain.some((c) => c.name === s.name));
               routes.push({
                 method: verb,
                 path: routePath,
                 sourceFile: rel,
                 sourceLine: m.loc?.start.line ?? 0,
                 params: pathParamsOf(routePath),
-                chain,
+                chain: mwSteps.length ? [...mwSteps, ...baseChain] : baseChain,
                 description: '',
                 authOptOut: http.optOut === true, // temp — consumed by the posture pass
               });
@@ -666,6 +683,266 @@ function returnsFalse(fnNode) {
   return found;
 }
 
+// --- MiddlewareConsumer.forRoutes() (ADR-089) ------------------------------------------
+//
+// The auth that decorator scans miss. A Nest module can gate routes NOT with `@UseGuards`
+// on the controller, but by registering middleware in its own `configure()` method:
+//
+//   export class ArticleModule implements NestModule {
+//     configure(consumer: MiddlewareConsumer) {
+//       consumer.apply(AuthMiddleware).forRoutes(
+//         { path: 'articles/:slug', method: RequestMethod.DELETE }, …);
+//     }
+//   }
+//
+// The controller carries no guard decorator, so a per-method scan reads the mutation as
+// UNGUARDED — a false CRITICAL on a route the framework actually authenticates (measured
+// on nestjs-realworld: 7 hard findings, 4 of them false because AuthMiddleware guards the
+// route from the module, not the controller). This is the middleware twin of the global
+// APP_GUARD detection above: read the binding once, in the module, and attach the guard to
+// every route it PROVABLY targets.
+//
+// SOUNDNESS. Attaching a guard DOWNGRADES a finding, so a binding matched to a route it does
+// not cover would HIDE a hole (Direction 2). Two disciplines keep it honest:
+//   1. the matcher never OVER-covers — a target `:param` covers a route segment (literal or
+//      param), but a target literal never covers a route `:param` (the route serves URLs the
+//      literal target does not), and a shorter target never covers a deeper route. Anything
+//      unreadable (computed path, spread, an `exclude()` we cannot parse) matches NOTHING and
+//      is DECLARED, never guessed — an under-match is a surfaceable false positive, the safe
+//      direction.
+//   2. only an AUTH-NAMED middleware attaches (here as an ASSERTED guard, ADR-063 — trusted
+//      by name, never `verified`); a `LoggerMiddleware` registered via forRoutes gates
+//      nothing and must not soften a critical. Proving the middleware's `use()` actually
+//      denies (→ verified) is the separate, stricter upgrade in `middlewareUseScan`.
+const ASSERTED_MIDDLEWARE_SCAN = {
+  effects: [],
+  returnShapes: [],
+  calls: [],
+  async: false,
+  validatesInput: false,
+  guardSignals: {},
+  assertedGuard: true,
+};
+
+// The deny-proven twin (ADR-089): when a forRoutes middleware's `use()` resolves through DI
+// to a real deny (a 4xx throw / `res.status(401)`), its guard reads VERIFIED — the mutation
+// reaches PROVEN, exactly like a proven APP_GUARD. Behaviour over names: a middleware PROVEN
+// to deny is a guard even if its name reads nothing like one; a `LoggerMiddleware` that only
+// calls next() proves no deny and stays out of the chain.
+const VERIFIED_MIDDLEWARE_SCAN = {
+  effects: [],
+  returnShapes: [],
+  calls: [],
+  async: true,
+  validatesInput: false,
+  guardSignals: { deniesWithStatus: true },
+};
+
+// A verb from a `RequestMethod.X` member expression: `RequestMethod.DELETE` → 'delete',
+// `RequestMethod.ALL` → 'all'. undefined = a method we cannot read (a variable / computed).
+function requestMethodOf(node) {
+  if (node?.type !== 'MemberExpression' || node.property?.type !== 'Identifier')
+    return undefined;
+  const v = node.property.name.toLowerCase();
+  return v === 'all' || NEST_ALL_EXPANSION.includes(v) || v === 'options' || v === 'head'
+    ? v
+    : undefined;
+}
+
+// segments of a path, leading/trailing slashes stripped: '/articles/:slug/' → ['articles',':slug']
+const segsOf = (p) =>
+  String(p ?? '')
+    .replace(/^\/+|\/+$/g, '')
+    .split('/')
+    .filter(Boolean);
+
+// Does a forRoutes target PATH cover a route PATH, in Nest's path-to-regexp sense, WITHOUT
+// ever over-covering? A target param covers any route segment; a target literal covers only
+// the identical literal (a route param at that position serves URLs the literal misses); a
+// trailing `*` covers the remainder; unmatched depth on either side is no cover.
+function pathCovers(targetPath, routePath) {
+  const t = segsOf(targetPath);
+  const r = segsOf(routePath);
+  for (let i = 0; i < t.length; i++) {
+    const ts = t[i];
+    if (ts === '*' || ts === '(.*)' || ts === '**') return true; // wildcard → covers the rest
+    const rs = r[i];
+    if (rs === undefined) return false; // target reaches deeper than the route
+    if (ts.startsWith(':')) continue; // param target covers any segment (literal or param)
+    if (rs.startsWith(':')) return false; // literal target cannot cover a route param
+    if (ts !== rs) return false; // literal vs literal
+  }
+  return t.length === r.length; // no leftover route segments the target fails to cover
+}
+
+// One forRoutes / exclude argument → a normalized target. `unread` is DECLARED, never treated
+// as covering anything (soundness: an unreadable binding is a blind spot, not a wildcard).
+function parseConsumerTarget(arg) {
+  if (arg.type === 'StringLiteral')
+    return { kind: 'path', path: arg.value, method: 'all' };
+  if (arg.type === 'Identifier') return { kind: 'controller', name: arg.name };
+  if (arg.type === 'ObjectExpression') {
+    let p = null;
+    let method = 'all'; // Nest default when `method` is omitted is RequestMethod.ALL
+    let unread = false;
+    for (const pr of arg.properties) {
+      if (pr.type !== 'ObjectProperty' || pr.key?.type !== 'Identifier') continue;
+      if (pr.key.name === 'path') {
+        if (pr.value.type === 'StringLiteral') p = pr.value.value;
+        else unread = true;
+      } else if (pr.key.name === 'method') {
+        const m = requestMethodOf(pr.value);
+        if (m === undefined) unread = true;
+        else method = m;
+      }
+    }
+    if (unread || p === null) return { kind: 'unread', src: 'route-object' };
+    return { kind: 'path', path: p, method };
+  }
+  return { kind: 'unread', src: arg.type };
+}
+
+// The `.apply(...).forRoutes(...)` (optionally `.exclude(...)`) chain rooted at a forRoutes
+// call: the applied middleware NAMES, the forRoutes TARGETS, and the exclude targets.
+function consumerChainOf(forRoutesCall) {
+  const targets = forRoutesCall.arguments.map(parseConsumerTarget);
+  const applied = [];
+  const excludes = [];
+  let node =
+    forRoutesCall.callee.type === 'MemberExpression' ? forRoutesCall.callee.object : null;
+  while (
+    node &&
+    node.type === 'CallExpression' &&
+    node.callee?.type === 'MemberExpression'
+  ) {
+    const prop = node.callee.property?.name;
+    if (prop === 'apply')
+      for (const a of node.arguments) {
+        const n = idName(a);
+        if (n) applied.push(n);
+        else excludes.push({ kind: 'unread', src: 'apply-arg' }); // unreadable middleware ref
+      }
+    else if (prop === 'exclude')
+      excludes.push(...node.arguments.map(parseConsumerTarget));
+    node = node.callee.object;
+  }
+  return { applied, targets, excludes };
+}
+
+// → { bindings, blindspots }. Each binding: { middlewares:[name], mod, targets, excludes,
+// hasUnread }. Scans module files (textual pre-filter) for every forRoutes chain. The mod is
+// carried so a later deny-proof can resolve the middleware class through its imports.
+function detectConsumerMiddleware(root, engine) {
+  const bindings = [];
+  const blindspots = [];
+  for (const file of walk(root)) {
+    let head;
+    try {
+      head = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    if (!/forRoutes/.test(head)) continue;
+    const mod = parseModule(file);
+    if (mod.error) continue;
+    const rel = relOf(root, file);
+    walkAst(mod.ast.program, (n) => {
+      if (
+        n.type !== 'CallExpression' ||
+        n.callee?.type !== 'MemberExpression' ||
+        n.callee.property?.name !== 'forRoutes'
+      )
+        return;
+      const { applied, targets, excludes } = consumerChainOf(n);
+      if (!applied.length) return; // a forRoutes with no readable middleware — nothing to attach
+      const hasUnread =
+        targets.some((t) => t.kind === 'unread') ||
+        excludes.some((t) => t.kind === 'unread');
+      if (hasUnread)
+        blindspots.push({
+          reason: `a MiddlewareConsumer binding in ${rel} applies ${applied.join(', ')} through a route/exclude target SPARDA could not read — routes it may cover are left flagged rather than silently credited`,
+          file: rel,
+          risk: 'high',
+        });
+      // Prove the deny ONCE per binding (ADR-089): a middleware whose `use()` resolves to a
+      // real deny reads VERIFIED wherever it is bound; one whose deny we cannot prove stays
+      // asserted-by-name. Resolution follows the middleware's own imports from this module.
+      const denies = new Set();
+      for (const name of applied)
+        if (middlewareDenies(name, mod, engine)) denies.add(name);
+      bindings.push({ middlewares: applied, denies, mod, targets, excludes });
+    });
+  }
+  return { bindings, blindspots };
+}
+
+// Resolve a forRoutes middleware class → its `use()` → prove it can deny (a 4xx throw /
+// `res.status(401)` / `next(err)`), following DI so a delegated deny is seen. The middleware
+// twin of `guardClassDenies`. A functional middleware (a bare function, not a class) has no
+// class to resolve → false, and the caller falls back to the asserted-by-name reading.
+function middlewareDenies(name, mod, engine) {
+  const file = mod.imports.get(name);
+  const gmod = file ? parseModule(file) : mod;
+  if (gmod.error) return false;
+  const cls = classInModule(gmod, name);
+  if (!cls) return false;
+  const hit = methodInClassChain(cls, gmod, 'use');
+  if (!hit) return false;
+  const di = diMapWithMod(cls, hit.mod);
+  const scan = engine.handlerScan(hit.fn, di, hit.mod, cls);
+  return Boolean(scan.guardSignals?.deniesWithStatus);
+}
+
+// The middleware guard steps a route earns from the app's forRoutes bindings. A binding
+// applies to the route iff some target covers it AND no exclude does; an unreadable exclude
+// makes the binding abstain on that route (never attach — the route might be the excluded
+// one). A middleware PROVEN to deny attaches VERIFIED (→ PROVEN); one only auth-NAMED attaches
+// asserted (name-trusted, unverified); anything else — a LoggerMiddleware that proves no deny
+// and reads nothing like a guard — attaches nothing and never softens the critical.
+function consumerGuardSteps(bindings, verb, routePath, controllerName, sourceFile, line) {
+  const steps = [];
+  const seen = new Set();
+  for (const b of bindings) {
+    const excluded = b.excludes.some((t) =>
+      targetCovers(t, verb, routePath, controllerName),
+    );
+    const excludeUnreadable = b.excludes.some((t) => t.kind === 'unread');
+    if (excluded || excludeUnreadable) continue;
+    if (!b.targets.some((t) => targetCovers(t, verb, routePath, controllerName)))
+      continue;
+    for (const name of b.middlewares) {
+      if (seen.has(name)) continue;
+      const proven = b.denies?.has(name);
+      // proof beats name (behaviour over names): a proven denier is a guard whatever its
+      // name; an unproven middleware must be auth-named to attach even asserted.
+      if (!proven && !(GUARD_DECORATOR.test(name) || nameLooksLikePrincipal(name)))
+        continue;
+      seen.add(name);
+      steps.push({
+        name,
+        sourceFile,
+        sourceLine: line ?? 0,
+        fn: null,
+        scan: proven ? VERIFIED_MIDDLEWARE_SCAN : ASSERTED_MIDDLEWARE_SCAN,
+        role: 'middleware',
+      });
+    }
+  }
+  return steps;
+}
+
+// Does a normalized target cover (verb, routePath, controllerName)? Unreadable targets cover
+// nothing — the whole point of declaring them.
+function targetCovers(target, verb, routePath, controllerName) {
+  if (target.kind === 'controller') return target.name === controllerName;
+  if (target.kind === 'path')
+    return (
+      (target.method === 'all' || target.method === verb) &&
+      pathCovers(target.path, routePath)
+    );
+  return false;
+}
+
 // --- composite decorators: `applyDecorators(UseGuards(X), …)` (ADR-084) ---------------
 //
 // NestJS's OFFICIAL composition API. A house decorator is declared once and used

package/src/ubg/resolve.js

@@ -26,6 +26,7 @@ import {
   methodInClassChain,
   computeThisSymbols,
   resolveExportedFunction,
+  resolveExportedClass,
   collectRepoFields,
   collectReqDerived,
   reqParamName,
@@ -156,6 +157,7 @@ function seedTaint(fn, args, callerReq) {
 // live here, scoped to the run.
 export function createResolver({ cwd, scannedFiles, helpers }) {
   const classBundles = new Map(); // memo: per (class file, class.method[, symbols])
+  const classLookups = new Map(); // memo: per (module, class name) — barrel walks
   const rel = (abs) => relOf(cwd, abs);
 
   // ---- member-call following (imports, instantiated services, this/super) ----
@@ -411,9 +413,22 @@ export function createResolver({ cwd, scannedFiles, helpers }) {
     const file = mod.imports.get(className);
     const clsMod = file ? parseModule(file) : mod;
     if (clsMod.error) return null;
-    const cls = classInModule(clsMod, className);
-    if (!cls) return null;
-    return classMethodBundle(cls, clsMod, methodName, depth, stack, thisSymbols);
+    const hit = classThroughBarrels(clsMod, className);
+    if (!hit) return null;
+    return classMethodBundle(hit.cls, hit.mod, methodName, depth, stack, thisSymbols);
+  }
+
+  // A class is looked up THROUGH barrels: declared here, or re-exported from a module
+  // this one re-exports. A monorepo package entry point is a barrel and nothing else, so
+  // without this every DI hop into a workspace package resolves to nothing at all —
+  // silently, since an unresolved hop leaves no trace of its own. Memoized per (module,
+  // class): a sixty-line barrel is otherwise re-walked once per hop.
+  function classThroughBarrels(clsMod, className) {
+    const key = `cls:${clsMod._file ?? ''}#${className}`;
+    if (classLookups.has(key)) return classLookups.get(key);
+    const hit = resolveExportedClass(clsMod, className);
+    classLookups.set(key, hit);
+    return hit;
   }
 
   // The fully-resolved scan of `<topCls>.<methodName>` — its body plus everything