SPARDA

🇫🇷 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.

AI writes. SPARDA proves.

L'IA écrit. SPARDA prouve.

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.

100% local · deterministic · zero API key · no cloud account. It fails loudly on a real risk, and when it can only see part of your app it says PROVEN (PARTIAL) — never a false green. And when it can prove it was not even looking at your whole app, it says PREMISE NOT VERIFIED and claims nothing at all.

60-second proof

From your Express, FastAPI, Flask, Next.js, NestJS or Medusa app — nothing to configure:

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) — and every command is a pass over that graph.

The wedge — catch an AI edit that removes a guard, in the loop

The one thing a text-diff review and a pattern scanner structurally can't do: prove that this specific edit dropped a protection the previous version had. sparda gate diffs the behavior graph before/after an edit and blocks a regression — deterministic, offline, sub-second, exit 2 (the Claude Code PostToolUse contract that stops the agent's edit loop). See it end-to-end in one command, zero setup:

npm run wedge     # (from a clone)  — or drive it on your own app with `sparda gate --arm` then `sparda gate --hook`

  1. baseline armed on the guarded code   (POST /admin/delete-user · requireAdmin)
  2. an AI edit "simplifies" requireAdmin → a pass-through (still compiles, still 200s)
  3. sparda gate on the edit:
       ✗ [critical] GUARD_REMOVED — POST /admin/delete-user was guarded in the baseline
                    and is now reachable without any guard (src/app.js:11)
     ⏱  ~40 ms · deterministic · offline · no API key
     ⛔ exit 2 on --hook — Claude Code PostToolUse blocks the edit

Wire it into Claude Code in one line — the plugin 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

Copy

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:

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:

   Terminal

   Copy

   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:

   Terminal

   Copy

   npx sparda-mcp dev
   

3. Connect your client. init prints a ready-to-paste block for claude_desktop_config.json, pre-filled with your app's name and path:

   config.json

   Copy

   {
     "mcpServers": {
       "your-app": {
         "command": "npx",
         "args": ["sparda-mcp", "dev"],
         "cwd": "/absolute/path/to/your-app"
       }
     }
   }
   

   Claude Code connects to the same bridge. That's it — your running app is now a set of MCP tools your AI can call.

Try the Standalone Demo

To see SPARDA in action instantly without modifying your codebase:

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:

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:

npx sparda-mcp report --html

To output raw JSON for integration:

npx sparda-mcp report --json

Deployment Proof: Apocalypse