sparda

SPARDA is a local trust-layer tool for AI-written backends, with the core proposition "AI writes, SPARDA proves." It compiles backend code into a deterministic behavior graph (Unified Behavior Graph, UBG), then uses that graph for static proofs, regression detection, replay, and self-healing, all 100% local, deterministic, with no API keys and no cloud account required.

Purpose and Positioning SPARDA targets the problem that AI may silently remove security protections, expose routes, or break invariants when editing code. Text diff review and pattern scanners are structurally unable to prove that "this edit removed a protection the previous version had," whereas SPARDA does so by comparing the behavior graphs before and after the edit. It is described as "the trust layer for AI-written backends."

Main Capabilities

1. Behavior graph compilation: compiles a language-agnostic unified behavior graph from applications such as Express, FastAPI, Flask, Next.js, NestJS, and Medusa, serialized to .sparda/ubg.json, following the SBIR (SPARDA Behavior IR) specification. It is officially said to compile Next.js Dub (579 routes), NestJS Immich (281 routes), and MedusaJS (477 routes) with zero crashes, at about 1-2 seconds per route, and can natively resolve deep dependency injection, external controllers, and Next.js handlers.
2. Edit gate: sparda gate compares the behavior graphs before and after an edit, blocks regressions, is deterministic, offline, and sub-second, and exit code 2 conforms to the Claude Code PostToolUse contract, which can stop an agent's edit loop. A PostToolUse hook can be registered via a plugin to run npx -y sparda-mcp gate --hook after every Edit/Write.
3. Deployment proof (Apocalypse): reads the compiled .sparda/ubg.json and statically discharges five correctness obligations—unguarded mutations (Critical), non-atomic aggregate writes (High), unvalidated constrained writes (Medium), irreversible observable side effects (High), and aggregate membership bypass (Info). It can save a baseline and compare candidate graphs to detect regression vectors such as security protection removal, SQL invariant removal, and API impact scope expansion; finding Critical or High, block CI with a non-zero exit code.
4. Time Travel (Timeless): Record the nondeterministic points in production requests (db, http, clock, random, uuid), only a few KB per request, then replay byte-for-byte against the current code, with the database, webhooks, and clock all virtualized. Recording requires only two lines of code, with built-in deterministic sampling and GDPR redaction.
5. Self-healing (sparda heal): Generate a repair brief from the behavior graph, hand it to a fixer (human or AI), then prove the fix across three dimensions: behavior, compiler laws, and no regressions. Unfixed bugs or "fixes" that quietly remove protections remain closed (exit code 1).
6. OpenAPI fallback: In addition to natively parsing Express, FastAPI, and Next.js, any backend with an OpenAPI spec (Go, Java, Rails, Laravel, .NET, etc.) can be compiled. Security schemes become gate guard nodes, response schemas become typed returns, and declared request bodies are treated as validated input. v1 supports JSON specs only.
7. Mirror VM: The behavior graph is executable, requiring no Express, FastAPI, or source code—it can respond to HTTP using only ubg.json. Guards actually reject (401), responses render the compiled return schemas, and unknown paths return 404 with the full routing table. Every response carries x-sparda-mirror: true, and the mirror only serves declared behavior, never inventing business values.

MCP runtime (optional) SPARDA can turn a running application into a live MCP server. Run once from the application directory using npx sparda-mcp init: parse routes (AST), generate a marked /mcp router, inject into the application (with backup), write sparda.json—every step is reversible. After starting the application, run npx sparda-mcp dev to start the bridge; init prints a config block that can be pasted directly into claude_desktop_config.json. Claude Code connects to the same bridge.

Write safety mechanism Write tools (POST/PUT/DELETE) are disabled by default and must be enabled per tool in sparda.json; the selection persists after each rerun. The first call to an enabled write operation is not executed, but instead returns awaiting_confirmation envelope (one-time token plus action preview), submitted only after explicit confirmation; when the client supports MCP elicitation, the confirmation prompt appears in the AI's own UI. After every successful write, the same resource is read back, i.e., "proof-after-write."

Other commands

• npx sparda-mcp doctor --app: audits codebase drift, detects stale tools, unsynchronized routes, schema drift, zombie configuration; high-severity issues trigger a non-zero exit code.
• npx sparda-mcp seed export/import: packages and shares the app's "genome" (semantic memory, workflows, antibodies).
• npx sparda-mcp twin: starts a safe simulated mock server on the original port; GET is served from learned samples, write operations return a simulated 202, and it never touches the real database or production API; use twin --learn to learn samples.
• npx sparda-mcp grammar: maps the graph of valid tool call sequences to prevent LLM hallucinated routing.
• npx sparda-mcp evolve: mutates candidate chains and tests them in twin memory, promoting successful chains into evolution workflow suggestions.
• npx sparda-mcp remove: restores code byte for byte (tested on JS, TS, Python, and even Windows CRLF files).

Applicable scenarios Suitable for backend teams using frameworks such as Express, FastAPI, Flask, Next.js, NestJS, and Medusa, especially in scenarios where AI agents are connected into the edit loop and there is a need to prevent AI edits from introducing security regressions; also suitable for engineering workflows requiring offline, deterministic proof, CI gating, production bug replay, and self-healing.

Limitations and honest boundaries Officially stated: compiled routes are the parser's result; proving their safety is a separate per-repository determination, and most real applications return NOT_PROVEN, which is a true state rather than a failure; when only part of the application is visible, it outputs PROVEN (PARTIAL), never giving a false green; when it can prove that the entire application was not seen, it outputs PREMISE NOT VERIFIED and makes no claims. Replay is per-request, and concurrent race capture is not within the scope of v1. v1 supports only the JSON specification and rejects zero-dependency half-parsed YAML. For more honest limitations, see docs/SECURITY.md.

Installation and usage No configuration is required; run npx sparda-mcp init from the application directory. A standalone demo can run the full MCP lifecycle (detect→parse→generate→inject→remove) in about 10 seconds in a temporary folder. The compiler itself can be run with npx sparda-mcp ubg followed by apocalypse. The black-box report can print a terminal dashboard, output .sparda/report.html with --html, or output raw JSON.