sparda-mcp 0.62.0 → 0.64.0

package/README.md

@@ -35,42 +35,47 @@ npx sparda-mcp badge        # a README badge: proven · coverage% · routes
 Under the hood it compiles your backend into one language-agnostic graph — the **Unified Behavior Graph (UBG)**, serialized as `.sparda/ubg.json` under the **SBIR** specification ([SPARDA Behavior IR](docs/SBIR_SPEC_V1.1.md)) — and every command is a pass over that graph.
 
 > [!IMPORTANT]  
-> **The 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:
+> **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.)
+>
+> Honesty first: _compiling_ a route is a parser result (the number above); _proving_ it safe is a separate per-repo verdict — and most real apps come back **NOT_PROVEN**, which is the true state, not a failure. (Our full 25-repo corpus stress compiles **3,565 routes** at ~150 routes/s; that one needs the corpus checked out.)
 
 **What the graph unlocks — 100% local, deterministic, zero runtime dependencies, zero API key:**
 
-| Command | What it does |
-|---|---|
-| **`prove`** | *The whole trust verdict in one gesture* — proof + coverage + a shareable seal (`--json` / `--markdown`) |
-| **`apocalypse`** | *Prove the deploy* — no guard, invariant, transaction or aggregate boundary can be broken (SARIF + CI gate) |
-| **`heal`** | *Self-heal, **proven*** — the gate Copilot Autofix doesn't have: a fix ships **only if** replay matches, `verify` still passes, and `apocalypse` finds no new risk / no dropped guard. Whoever wrote the fix, the machine judges it. |
-| **`badge`** | *The shareable artifact* — a self-contained SVG badge + README snippet (verdict · coverage · routes) |
-| **`dossier`** | *The public report* — one self-contained HTML page: verdict, risks, and SPARDA's own blind spots |
-| **`ubg`** | Compile the codebase to its behavior graph (Express · FastAPI · Next.js · NestJS · Medusa natively; **any** stack via OpenAPI) |
-| **`timeless`** | *Time-travel* — record a production request, replay it byte-identically, export the bug as a test |
-| **`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) |
+| Command            | What it does                                                                                                                                                                                                                         |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **`prove`**        | _The whole trust verdict in one gesture_ — proof + coverage + a shareable seal (`--json` / `--markdown`)                                                                                                                             |
+| **`apocalypse`**   | _Prove the deploy_ — no guard, invariant, transaction or aggregate boundary can be broken (SARIF + CI gate)                                                                                                                          |
+| **`heal`**         | _Self-heal, **proven**_ — the gate Copilot Autofix doesn't have: a fix ships **only if** replay matches, `verify` still passes, and `apocalypse` finds no new risk / no dropped guard. Whoever wrote the fix, the machine judges it. |
+| **`badge`**        | _The shareable artifact_ — a self-contained SVG badge + README snippet (verdict · coverage · routes)                                                                                                                                 |
+| **`dossier`**      | _The public report_ — one self-contained HTML page: verdict, risks, and SPARDA's own blind spots                                                                                                                                     |
+| **`ubg`**          | Compile the codebase to its behavior graph (Express · FastAPI · Next.js · NestJS · Medusa natively; **any** stack via OpenAPI)                                                                                                       |
+| **`timeless`**     | _Time-travel_ — record a production request, replay it byte-identically, export the bug as a test                                                                                                                                    |
+| **`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)                                                                                                                                |
 
-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.
+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.
+**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
    ```
@@ -94,25 +99,31 @@ Beyond proving, SPARDA can turn your running app into a live MCP server — the
 ## 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
 ```
@@ -120,28 +131,35 @@ 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).
+- **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:
@@ -159,11 +177,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).
@@ -180,7 +200,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.
 
@@ -188,7 +208,7 @@ 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
 
@@ -233,7 +253,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
 
@@ -250,34 +270,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
@@ -285,11 +323,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
@@ -307,6 +347,7 @@ runtime, so the guidance never goes stale.
 - **FastAPI** (Python >= 3.9) — AST-based router injection.
 
 ## 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.
@@ -316,18 +357,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,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.62.0",
+  "version": "0.64.0",
   "mcpName": "io.github.zyx77550/sparda-mcp",
   "description": "Compile backends to behavior graphs. Statically prove security, simulate APIs, and replay bugs.",
   "type": "module",

package/src/commands/apocalypse.js

@@ -45,8 +45,12 @@ export async function runApocalypse(opts) {
   const findings = [...staticFindings, ...diffFindings];
   // the honesty companion: where does the proof stop? (see `sparda blindspots`)
   const blind = surveyBlindspots(canonical, report);
-  // coverage feeds the verdict: a clean app that resolved almost nothing is SURFACE, not PROVEN
-  const verdict = verdictOf(findings, canonical, { coverage: blind.coverage.ratio });
+  // coverage feeds the verdict: a clean app that resolved almost nothing is SURFACE, not PROVEN;
+  // and any high-risk blind spot pulls a bare PROVEN down to PARTIAL (E-047, the giant-test rung)
+  const verdict = verdictOf(findings, canonical, {
+    coverage: blind.coverage.ratio,
+    blindHigh: blind.byRisk.critical + blind.byRisk.high,
+  });
 
   if (opts.sarif) {
     const sarifPath = path.join(opts.cwd, '.sparda', 'apocalypse.sarif');

package/src/commands/badge.js

@@ -16,7 +16,10 @@ export async function runBadge(opts) {
   const canonical = canonicalizeGraph(graph);
   const { findings } = checkGraph(canonical);
   const blind = surveyBlindspots(canonical, report);
-  const verdict = verdictOf(findings, canonical, { coverage: blind.coverage.ratio });
+  const verdict = verdictOf(findings, canonical, {
+    coverage: blind.coverage.ratio,
+    blindHigh: blind.byRisk.critical + blind.byRisk.high,
+  });
   const cov = Math.round(blind.coverage.ratio * 100);
   const { state, message, color } = badgeFor(verdict, { coverage: blind.coverage.ratio });
 

package/src/commands/dossier.js

@@ -21,7 +21,10 @@ export async function runDossier(opts) {
   const { findings, polarity } = checkGraph(canonical);
   const capsule = buildCapsule(canonical);
   const blindspots = surveyBlindspots(canonical, compiled.report);
-  const verdict = verdictOf(findings, canonical, { coverage: blindspots.coverage.ratio });
+  const verdict = verdictOf(findings, canonical, {
+    coverage: blindspots.coverage.ratio,
+    blindHigh: blindspots.byRisk.critical + blindspots.byRisk.high,
+  });
 
   const data = {
     app: path.basename(path.resolve(opts.cwd)) || 'app',

package/src/commands/init.js

@@ -48,6 +48,17 @@ export async function runInit(opts) {
     s.stop(
       `Stack detected: ${c.cyan('Next.js (App Router)')} — app dir: ${stack.entryFile}/, port: ${stack.port}`,
     );
+  } else {
+    s.stop(
+      `Stack detected: ${c.cyan(stack.framework)} — but AST parsing is not supported yet.`,
+    );
+    throw Object.assign(
+      new Error(`AST extraction for ${stack.framework} is not yet supported.`),
+      {
+        code: 'USER',
+        hint: `SPARDA detected ${stack.framework}, but currently only supports Express, FastAPI, and Next.js for AST parsing. NestJS and others are on the roadmap!`,
+      },
+    );
   }
 
   // Opt-in runtime probe (Brief #3): static is the floor, probe only ADDS routes

package/src/commands/prove.js

@@ -19,7 +19,10 @@ export async function runProve(opts) {
 
   const { findings, obligations } = checkGraph(canonical);
   const blind = surveyBlindspots(canonical, report);
-  const verdict = verdictOf(findings, canonical, { coverage: blind.coverage.ratio });
+  const verdict = verdictOf(findings, canonical, {
+    coverage: blind.coverage.ratio,
+    blindHigh: blind.byRisk.critical + blind.byRisk.high,
+  });
   const capsule = buildCapsule(canonical);
   const prints = fingerprintGraph(canonical);
   // one app-level seal: a content address over every route's behavior hash — the same

package/src/commands/review.js

@@ -62,11 +62,15 @@ export function reviewGraphs(baseGraph, candidateGraph) {
   // how much of the changed app SPARDA could actually see — and whether this PR moved
   // that boundary. A green review over a graph the PR made 20% blinder is not the same
   // as a green review at full sight; the reviewer must be able to tell them apart.
-  const candCov = surveyBlindspots(candidateGraph).coverage.ratio;
+  const candBlind = surveyBlindspots(candidateGraph);
+  const candCov = candBlind.coverage.ratio;
   const baseCov = surveyBlindspots(baseGraph).coverage.ratio;
 
   return {
-    verdict: verdictOf(findings, candidateGraph, { coverage: candCov }),
+    verdict: verdictOf(findings, candidateGraph, {
+      coverage: candCov,
+      blindHigh: candBlind.byRisk.critical + candBlind.byRisk.high,
+    }),
     obligations,
     findings,
     endpoints: { added, removed: removedEps },

package/src/server/stdio.js

@@ -26,8 +26,39 @@ import { createSpardaEngine } from './engine.js';
 import { initiateWrite, preapproveWrite, confirmWrite } from './confirmation.js';
 import { resolveContext, injectContext, fingerprintContext } from './context-carrier.js';
 import { resolveSpardaKey } from '../generator/manifest.js';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { checkGraph, diffGraphs, verdictOf, verdictState } from '../ubg/apocalypse.js';
+import { surveyBlindspots } from '../ubg/blindspots.js';
 
 const EVENT_POLL_MS = Number(process.env.SPARDA_EVENT_POLL_MS ?? 5000);
+
+// Built-in MCP prompts (workflows) served by every SPARDA server, regardless of the app's own
+// inferred workflows. `prove-my-edit` is the discoverability surface for `sparda_prove`: the
+// workflow an editing agent lists and follows to check its OWN change before committing — the
+// one check an LLM cannot do to itself by re-reading its code.
+export const BUILTIN_WORKFLOWS = [
+  {
+    name: 'prove-my-edit',
+    description:
+      "Prove an edit didn't break a guard before you commit — the check an LLM can't do to itself by re-reading its own code.",
+    steps: [
+      'Call sparda_prove. If you just edited one route, pass route with its method+path (e.g. "DELETE /orders") to focus the finding list — the verdict still reflects the whole app.',
+      'Read the verdict: PROVEN / PARTIAL are safe to commit. SURFACE / NO_PROOF mean SPARDA could not resolve enough to prove it — treat that as "unknown", never as a pass.',
+      'Fix every finding with regression:true first — that edit removed a guard, dropped a route, or grew the blast radius vs the last proven baseline.',
+      'If baselined is false, run `sparda apocalypse --save-baseline` once on a known-good state so future sparda_prove calls can catch regressions.',
+    ],
+  },
+];
+
+// App-inferred workflows (carry-over, sacred) win on a name clash; built-ins fill the rest.
+export function mergeWorkflows(appWorkflows) {
+  const out = [...(appWorkflows ?? [])];
+  for (const b of BUILTIN_WORKFLOWS) {
+    if (!out.some((w) => w.name === b.name)) out.push(b);
+  }
+  return out;
+}
 // Advertised MCP server version — read from package.json so it can never drift from the
 // published package (it was pinned at a stale '0.5.2' for many releases).
 const SPARDA_VERSION = (() => {
@@ -340,6 +371,21 @@ export async function startStdioBridge({ cwd, portOverride }) {
           'Call this FIRST. Returns the full living context of this app: every tool with its description, known workflows, runtime telemetry (per-tool calls/errors/latency), quarantined tools, and the immune memory of past diagnosed failures. Lets any AI session resume exactly where the previous one stopped.',
         inputSchema: { type: 'object', properties: {} },
       },
+      {
+        name: 'sparda_prove',
+        description:
+          'Prove this app is safe to deploy — NOW, before you commit. Compiles the current source to its behavior graph and discharges the static proof obligations (unguarded mutation, non-atomic aggregate write, unvalidated constrained write). If a baseline was saved (`sparda apocalypse --save-baseline`), it ALSO diffs against it: any finding flagged `regression:true` means your edit removed a guard, dropped a route, or grew the blast radius vs the last proven state — the check an LLM cannot do to itself by re-reading code. Returns a deterministic verdict (PROVEN / PARTIAL / SURFACE / NO_PROOF / RISKY / NOT_PROVEN), the coverage % it resolved, and every finding with its route. The verdict is the exact word `sparda apocalypse` and the badge emit; it never over-claims (a low-coverage clean app reads SURFACE/PARTIAL, never a bare PROVEN). Pass `route` (e.g. "DELETE /orders") to focus the finding list on the route you just edited — the verdict still reflects the whole app.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            route: {
+              type: 'string',
+              description:
+                'Optional. Substring of a route label (method + path, e.g. "POST /invoices") to filter the findings to the route you just edited. Omit to see the whole app.',
+            },
+          },
+        },
+      },
       {
         name: 'sparda_confirm',
         description:
@@ -360,14 +406,14 @@ export async function startStdioBridge({ cwd, portOverride }) {
   }));
 
   server.setRequestHandler(ListPromptsRequestSchema, async () => ({
-    prompts: (manifest.semantic?.workflows ?? []).map((w) => ({
+    prompts: mergeWorkflows(manifest.semantic?.workflows).map((w) => ({
       name: w.name,
       description: w.description,
     })),
   }));
 
   server.setRequestHandler(GetPromptRequestSchema, async (req) => {
-    const w = (manifest.semantic?.workflows ?? []).find(
+    const w = mergeWorkflows(manifest.semantic?.workflows).find(
       (x) => x.name === req.params.name,
     );
     if (!w) throw new Error(`unknown prompt: ${req.params.name}`);
@@ -411,6 +457,9 @@ export async function startStdioBridge({ cwd, portOverride }) {
         ),
       );
     }
+    if (name === 'sparda_prove') {
+      return text(JSON.stringify(proveApp(cwd, { route: args.route }), null, 2));
+    }
     if (name === 'sparda_get_context') {
       const headers = hostHeaders(key, ctx);
       const [stats, events] = await Promise.all([
@@ -1081,6 +1130,79 @@ function text(t) {
   return { content: [{ type: 'text', text: t }] };
 }
 
+// The proof layer, served live over MCP — same compile + obligations as `sparda apocalypse`,
+// so an AI can prove its own edit structurally the moment it writes it, not a CI run later.
+// Reuses `verdictState` verbatim: this tool physically cannot show a word the CLI/badge won't
+// (the no-false-PROVEN invariant is one function, shared). Read-only (write:false); an
+// AI-initiated call, never on the host's request path, so Law 1 holds.
+//   opts.route  — substring; keep only findings on routes whose label matches (focus the
+//                 answer on the route the AI just edited, e.g. "DELETE /orders").
+export function proveApp(cwd, { route } = {}) {
+  let canonical, report;
+  try {
+    const compiled = compileUBG(cwd, { write: false });
+    canonical = canonicalizeGraph(compiled.graph);
+    report = compiled.report;
+  } catch (err) {
+    // A parser gap is NOT a pass — say so honestly, never a silent green.
+    return {
+      verdict: 'NO_PROOF',
+      provable: false,
+      note: `SPARDA could not compile this app's surface (${err.message}). An uncompiled app proves nothing — this is NOT a pass.`,
+    };
+  }
+  const { findings: staticFindings, obligations } = checkGraph(canonical);
+
+  // Baseline diff — the regression check that IS apocalypse's edge over a plain linter: did
+  // this edit REMOVE a guard, drop a route, or grow the blast radius vs the last saved proof?
+  // Only if a baseline was recorded (`sparda apocalypse --save-baseline`); absent → static only.
+  let diffFindings = [];
+  let baselined = false;
+  const baselinePath = path.join(cwd, '.sparda', 'ubg.baseline.json');
+  if (fs.existsSync(baselinePath)) {
+    try {
+      const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+      diffFindings = diffGraphs(baseline, canonical).findings;
+      baselined = true;
+    } catch {
+      // unreadable baseline → degrade to static-only, never crash the AI's call
+    }
+  }
+
+  const all = [...staticFindings, ...diffFindings];
+  const label = (id) => canonical.nodes.find((n) => n.id === id)?.label ?? id;
+  let findings = all.map((f) => ({
+    severity: f.severity,
+    rule: f.rule,
+    route: label(f.entrypoint),
+    regression: diffFindings.includes(f),
+    message: f.message,
+  }));
+  if (route) {
+    const needle = route.toLowerCase();
+    findings = findings.filter((f) => f.route.toLowerCase().includes(needle));
+  }
+
+  const blind = surveyBlindspots(canonical, report);
+  // The verdict word always reflects the WHOLE app (a route filter narrows the finding list,
+  // never the safety claim — an AI must never read "PROVEN" because it hid the rest).
+  const verdict = verdictOf(all, canonical, {
+    coverage: blind.coverage.ratio,
+    blindHigh: blind.byRisk.critical + blind.byRisk.high,
+  });
+  return {
+    verdict: verdictState(verdict),
+    provable: verdict.provable,
+    coverage: Math.round(blind.coverage.ratio * 100) / 100,
+    baselined,
+    obligations,
+    counts: verdict.counts,
+    findings,
+    blindspots: { surface: blind.surface, coverage: blind.coverage.ratio },
+    ...(route ? { scopedTo: route } : {}),
+  };
+}
+
 // AI-facing message when the Signal-2 gate (Brief #1) refuses a `sparda_confirm`. Each reason
 // tells the model what to do next without implying it can approve the write itself.
 function signal2Denial(reason) {

package/src/ubg/apocalypse.js

@@ -488,7 +488,7 @@ const COVERAGE_FLOOR = 0.05;
 // finding, never changes the CI gate; a PARTIAL app is still clean, just qualified.
 const COVERAGE_COMPLETE = 0.6;
 
-export function verdictOf(findings, graph, { coverage } = {}) {
+export function verdictOf(findings, graph, { coverage, blindHigh = 0 } = {}) {
   const counts = { critical: 0, high: 0, medium: 0, info: 0 };
   for (const f of findings) counts[f.severity]++;
   // Advisory findings (BOLA/IDOR, ADR-058) are absence-based and FP-prone: they point a
@@ -528,9 +528,20 @@ export function verdictOf(findings, graph, { coverage } = {}) {
   // A clean whole-app proof below the completeness bar is PARTIAL — proved, but not over
   // the whole surface. Only meaningful when coverage was measured (whole-app run); a partial
   // graph (heal delta, coverage undefined) is never labelled partial.
+  //
+  // E-047 (the blind-spot rung, from the cal.com giant test): coverage is a RATIO, so on a
+  // huge app it can clear the bar (cal.com/api/v2: 71%) while the ABSOLUTE count of high-risk
+  // blind spots is large (46 guarded mutations whose writes never resolved). A bare "PROVEN"
+  // over 46 unproven high-risk mutations over-claims. So a clean app is also PARTIAL when any
+  // high-severity blind spot remains — the label carries the uncertainty (metrology's error
+  // bars), independent of the ratio. Sound: only ever SOFTENS PROVEN→PARTIAL, never masks a
+  // finding, never touches the CI gate (`safe`). blindHigh defaults to 0, so a caller that
+  // did not survey blind spots (heal delta) is unaffected.
   const clean = provable && !surfaceOnly && hardCount === 0;
   const partial =
-    clean && coverage != null && entrypoints > 0 && coverage < COVERAGE_COMPLETE;
+    clean &&
+    entrypoints > 0 &&
+    ((coverage != null && coverage < COVERAGE_COMPLETE) || blindHigh > 0);
   // `safe` is the CI gate (block a risky deploy): a surface-only app has no
   // critical/high findings and is NOT risky, so it does not fail the gate — it just
   // isn't a positive proof. `clean` is the strong claim (PROVEN) and DOES require

package/src/ubg/extract.js

@@ -140,6 +140,8 @@ const moduleCache = new Map(); // absFile -> module facts (parse once per compil
 export function clearModuleCache() {
   moduleCache.clear();
   tsconfigCache.clear();
+  workspaceCache.clear();
+  workspaceRootOf.clear();
 }
 
 // absFile → { ast, functions: Map<name,{node,line,exported}>, imports: Map<local,abs>, error }
@@ -357,7 +359,159 @@ export function resolveRelImport(fromFile, spec) {
   // cross-module hop (controller → service → repository) dead-ends and effects behind
   // DI are invisible. A bare npm package (`kysely`, `@nestjs/common`) simply resolves
   // to nothing here (no matching file under the project), which is correct.
-  return resolveAliasedImport(fromFile, clean(spec));
+  //
+  // The WORKSPACE fallback (the mycorrhizal network): a monorepo app's real mutation
+  // logic lives in shared workspace packages it imports by NAME, not by path — cal.com's
+  // `this.svc.updateEventType()` delegates to `@calcom/platform-libraries` → `@calcom/trpc`
+  // → `prisma.update()`, three packages away and entirely outside the analyzed app dir. A
+  // tsconfig alias can't reach them (they're resolved via the workspace, not `paths`). So
+  // when the alias miss, map the `@scope/pkg[/subpath]` specifier to the package's real
+  // directory under the workspace and resolve into it. Trees share nutrients across the
+  // fungal network, not just their own root ball — the schema/effect code is a shared
+  // nutrient drawn from the workspace, not the app's own folder.
+  return (
+    resolveAliasedImport(fromFile, clean(spec)) ??
+    resolveWorkspaceImport(fromFile, clean(spec))
+  );
+}
+
+// name -> absolute package dir, for every package in the workspace that owns `fromFile`.
+// Cached per workspace root (built once, ~100 package.json reads on a giant monorepo).
+const workspaceCache = new Map(); // rootDir -> Map(name -> dir)
+const workspaceRootOf = new Map(); // dir -> rootDir | null
+
+// walk up to the monorepo root: the nearest ancestor whose package.json declares
+// `workspaces`, or that carries a pnpm-workspace.yaml. `null` = not a workspace.
+function findWorkspaceRoot(fromFile) {
+  let dir = path.dirname(fromFile);
+  const chain = [];
+  for (let i = 0; i < 40; i++) {
+    if (workspaceRootOf.has(dir)) {
+      const v = workspaceRootOf.get(dir);
+      for (const d of chain) workspaceRootOf.set(d, v);
+      return v;
+    }
+    chain.push(dir);
+    let root = null;
+    try {
+      const pj = path.join(dir, 'package.json');
+      if (fs.existsSync(pj)) {
+        const pkg = JSON.parse(fs.readFileSync(pj, 'utf8'));
+        if (pkg.workspaces) root = dir;
+      }
+      if (!root && fs.existsSync(path.join(dir, 'pnpm-workspace.yaml'))) root = dir;
+    } catch {
+      // unreadable manifest — keep walking up
+    }
+    if (root) {
+      for (const d of chain) workspaceRootOf.set(d, root);
+      return root;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  for (const d of chain) workspaceRootOf.set(d, null);
+  return null;
+}
+
+// the workspace's package globs, from package.json `workspaces` (array or {packages})
+// or a minimal pnpm-workspace.yaml parse (the `- '...'` list under `packages:`).
+function workspaceGlobs(root) {
+  const globs = [];
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    const ws = pkg.workspaces;
+    if (Array.isArray(ws)) globs.push(...ws);
+    else if (ws && Array.isArray(ws.packages)) globs.push(...ws.packages);
+  } catch {
+    // no/invalid root package.json — fall through to pnpm
+  }
+  try {
+    const yml = fs.readFileSync(path.join(root, 'pnpm-workspace.yaml'), 'utf8');
+    for (const m of yml.matchAll(/^\s*-\s*['"]?([^'"\n]+?)['"]?\s*$/gm)) globs.push(m[1]);
+  } catch {
+    // no pnpm-workspace.yaml
+  }
+  return globs;
+}
+
+// expand one workspace glob to concrete package dirs. Supports the two forms real
+// workspaces use: an exact path (`packages/app-store`) and a trailing `/*` (one level of
+// subdirs, e.g. `packages/*`, `packages/platform/*`). `**` is treated as a single level —
+// good enough for every workspace layout in the wild, and never unbounded.
+function expandGlob(root, glob) {
+  const g = glob.replace(/\/\*\*$/, '/*');
+  const star = g.indexOf('*');
+  if (star === -1) return [path.resolve(root, g)];
+  const baseRel = g.slice(0, star).replace(/\/$/, '');
+  const baseDir = path.resolve(root, baseRel);
+  try {
+    return fs
+      .readdirSync(baseDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => path.join(baseDir, e.name));
+  } catch {
+    return [];
+  }
+}
+
+export function workspacePackages(fromFile) {
+  const root = findWorkspaceRoot(fromFile);
+  if (!root) return null;
+  if (workspaceCache.has(root)) return workspaceCache.get(root);
+  const map = new Map();
+  for (const glob of workspaceGlobs(root)) {
+    for (const dir of expandGlob(root, glob)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+        if (typeof pkg.name === 'string' && !map.has(pkg.name)) map.set(pkg.name, dir);
+      } catch {
+        // not a package (no/invalid package.json) — skip
+      }
+    }
+  }
+  workspaceCache.set(root, map);
+  return map;
+}
+
+// the entry file of a package with no subpath import (`@calcom/trpc`): its declared
+// source/main/module, else the conventional src/index or index.
+function packageEntry(dir) {
+  const fields = [];
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    for (const f of [pkg.source, pkg.module, pkg.main])
+      if (typeof f === 'string') fields.push(f);
+  } catch {
+    // no package.json fields — conventions below still apply
+  }
+  for (const f of [...fields, 'src/index', 'index']) {
+    const hit = firstModuleFile(path.resolve(dir, f.replace(/\.(m?[jt]s|cjs)$/, '')));
+    if (hit) return hit;
+  }
+  return null;
+}
+
+// resolve `@scope/pkg/subpath` (or `pkg/subpath`) to a real source file under the
+// workspace. Longest package-name match wins (`@calcom/platform-libraries` beats a
+// hypothetical `@calcom/platform`), then the subpath resolves against the package dir.
+function resolveWorkspaceImport(fromFile, spec) {
+  if (spec.startsWith('.') || spec.startsWith('/')) return null;
+  const map = workspacePackages(fromFile);
+  if (!map) return null;
+  let best = null;
+  for (const name of map.keys()) {
+    if (
+      (spec === name || spec.startsWith(name + '/')) &&
+      name.length > (best?.length ?? -1)
+    )
+      best = name;
+  }
+  if (!best) return null;
+  const dir = map.get(best);
+  const sub = spec.length > best.length ? spec.slice(best.length + 1) : '';
+  return sub ? firstModuleFile(path.resolve(dir, sub)) : packageEntry(dir);
 }
 
 // probe the standard TS/JS extensions + index files for a resolved base path.

package/src/ubg/prisma.js

@@ -10,6 +10,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { cmp } from './schema.js';
+import { workspacePackages } from './extract.js';
 
 const SCHEMA_CANDIDATES = ['prisma/schema.prisma', 'schema.prisma', 'db/schema.prisma'];
 // Prisma's `prismaSchemaFolder` layout (stable since 6.x): the schema is SPLIT across many
@@ -55,6 +56,35 @@ function collectSchemaFiles(cwd, fileCandidates, dirCandidates) {
   return [];
 }
 
+// P4 (E-048, the mycorrhizal network for STATE): a monorepo app usually declares NO schema of
+// its own — it depends on a shared `@scope/prisma`-style workspace package that owns the whole
+// schema (cal.com: apps/web has 0 tables locally; `@calcom/prisma` has 100 models). Without
+// this the app's entire state layer is invisible and every mutation reasons against nothing.
+// When the app dir yields no schema, look through its workspace DEPENDENCIES for the package
+// that owns one — the same name→dir map the module resolver already builds. Schema-ish deps are
+// tried first (a `prisma`/`db` package is the DB package), then any remaining workspace dep.
+function workspaceSchemaFiles(cwd, fileCandidates, dirCandidates) {
+  let deps;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  } catch {
+    return [];
+  }
+  const map = workspacePackages(path.join(cwd, 'package.json'));
+  if (!map) return [];
+  const inWorkspace = Object.keys(deps).filter((n) => map.has(n));
+  const ordered = [
+    ...inWorkspace.filter((n) => /prisma|schema|(^|[-/])db($|[-/])|database/i.test(n)),
+    ...inWorkspace.filter((n) => !/prisma|schema|(^|[-/])db($|[-/])|database/i.test(n)),
+  ];
+  for (const name of ordered) {
+    const files = collectSchemaFiles(map.get(name), fileCandidates, dirCandidates);
+    if (files.length) return files;
+  }
+  return [];
+}
+
 const TYPE_MAP = {
   string: 'string',
   int: 'number',
@@ -78,7 +108,11 @@ export function parsePrismaSchemas(cwd) {
   } catch {
     // no package.json / unparsable — the default candidates stand
   }
-  const files = collectSchemaFiles(cwd, candidates, SCHEMA_DIR_CANDIDATES);
+  // local first; then the workspace dependency that owns the shared schema (P4)
+  const local = collectSchemaFiles(cwd, candidates, SCHEMA_DIR_CANDIDATES);
+  const files = local.length
+    ? local
+    : workspaceSchemaFiles(cwd, candidates, SCHEMA_DIR_CANDIDATES);
   if (!files.length) return { tables: [], skipped, sourceFile: null };
 
   // Read + strip comments once per file; keep the relative path for correct per-table locs.