sparda-mcp 0.13.1 → 0.13.3

package/README.md

@@ -10,27 +10,33 @@
 
 ---
 
-**Compile your backend into a deterministic behavior runtime.**
+**A compiler for backend behavior. The LLVM of web applications.**
 
-For twenty years, software communicated via APIs. Then AI agents arrived. The industry's response was simply to expose more endpoints (MCP). But an agent doesn't understand your application; it only sees a list of disconnected tools. That is enough for a human, but not for an autonomous machine.
+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.
 
-SPARDA analyzes your Express, FastAPI, or Next.js application, extracts its behavior, and compiles it into a **SPARDA Behavior Graph (SBG)**. 
+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.
 
-This graph acts as a local, deterministic runtime that powers:
-* **MCP Server Integration**: Exposing your endpoints to AI clients dynamically.
-* **SPARDA Twin**: An executable, offline simulation clone of your backend for safe agent testing.
-* **SPARDA Immune**: Real-time graph-based anomaly defense, latency alerts, and auto-quarantine.
-* **SPARDA Evolution**: Statically inferred grammar mapping and in-memory workflow optimization.
+**What the graph unlocks — 100% local, deterministic, zero runtime dependencies, zero API key:**
 
-All executed 100% locally, with zero runtime dependencies and zero cloud connection.
+| 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) |
 
 ```bash
-npx sparda-mcp init   # Scan your app, compile the UBG, inject the SPARDA Runtime
-npx sparda-mcp dev    # Connect Claude Desktop / Cursor over stdio
+npx sparda-mcp ubg          # compile your backend → .sparda/ubg.json
+npx sparda-mcp apocalypse   # prove the current tree is safe to deploy
 ```
 
-No OpenAPI spec to write. No cloud account. No API key. No server to host.
-Exposing raw APIs to AI is the old way. SPARDA compiles the whole system's behavior.
+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.
+
+**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.
 
 ## Quickstart
 
@@ -68,7 +74,7 @@ To see SPARDA in action instantly without modifying your codebase:
 ```bash
 npx sparda-mcp demo
 ```
-This runs the entire lifecycle (detect → parse → generate → inject → remove) on a bundled demo app in a temporary folder, illustrating all six guarantees in 10 seconds.
+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
 
@@ -139,6 +145,28 @@ 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).
 
+## Self-Healing, Proven: `sparda heal`
+
+The loop above, as **one gesture** — and the machine judges the fix, whoever wrote it:
+
+```bash
+npx sparda-mcp heal <flightId>                       # diagnose + write the fix brief
+# ...apply the fix (a human, or --agent "your-ai-cli")...
+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.
+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.
+
+```
+✓ 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.
+
 ## 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.

package/SKILL.md

@@ -2,8 +2,8 @@
 name: sparda-mcp
 description: >-
   Drive a SPARDA compiled Behavior Runtime to its full potential. Use this whenever
-  you are connected to a backend running the SPARDA Runtime (compiled into a SPARDA
-  Behavior Graph - SBG) — recognizable by the tools `sparda_get_context`, `sparda_info`,
+  you are connected to a backend running the SPARDA Runtime (compiled into a Unified
+  Behavior Graph - UBG) — recognizable by the tools `sparda_get_context`, `sparda_info`,
   `sparda_confirm`, or composite tools. It teaches the graph-context-first workflow,
   how to exploit the response-recycling flywheel, the circuit-breaker, crystallized
   circuits, offline Twin simulations, and the two-phase confirm protocol for writes.
@@ -11,7 +11,9 @@ description: >-
 
 # Driving a SPARDA Behavior Runtime
 
-A SPARDA server is driven by a compiled **SPARDA Behavior Graph (SBG)**. Instead of exposing raw, disconnected endpoints, SPARDA has compiled the host application's states, transitions, permissions, and side-effects 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.
+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 same graph also powers dev-time compiler commands you run in the app's repo — `sparda ubg` (compile), `apocalypse` (prove the deploy), `timeless` (record/replay a request), `heal` (prove a fix), `mirror` (serve the graph), `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
 
@@ -137,10 +139,12 @@ Writes are **disabled by default**. The protocol is not optional:
   manifest validity, the semantic/immune cache, host reachability, and quarantine;
   it exits non-zero so it can gate CI.
 - **Formal Deployment Proof** → `sparda apocalypse` reads the compiled graph (`ubg.json`) and proves five correctness obligations: catches unguarded mutations, non-atomic aggregate writes, unvalidated writes to constrained tables, uncompensated observable effects, and aggregate root bypasses. Run `sparda apocalypse --save-baseline` to store the reference graph; subsequent runs diff against the baseline to catch dropped guards, dropped SQL invariants, or grown blast radiuses.
-- **OpenAPI Ingestion** → Run `sparda ubg --openapi <openapi_spec.json_or_yaml>` to compile any non-JS/Python backend (Go, Java, Rails, Laravel, .NET) into a SPARDA Behavior Graph by mapping security schemes into guards and request/response structures.
+- **OpenAPI Ingestion** → Run `sparda ubg --openapi <openapi_spec.json>` to compile any non-JS/Python backend (Go, Java, Rails, Laravel, .NET) into a Unified Behavior Graph by mapping security schemes into guards and request/response structures. (JSON specs only — convert YAML once with `npx -y js-yaml spec.yaml > spec.json`.)
 - **Executing the Graph (No code mock)** → Run `sparda mirror` to host a mock HTTP simulation server directly from `ubg.json` without any backend code. Enforces authentication guards, returns typed responses, and acts as a contract sandbox.
 - **Exporting OpenAPI 3.1 Spec** → Run `sparda openapi` to generate a valid, deterministic OpenAPI 3.1 spec dynamically from the compiled behavior graph.
 - **Self-Verification** → Run `sparda verify` to test the compiler's own invariants (byte-determinism, soundness, and spec round-trip) to guarantee trust.
+- **Time-Travel Debugging** → `sparda timeless` records a production request's nondeterminism (db, http, clock, random, uuid) and replays it byte-identically against current code. `sparda timeless replay <id>` re-flies it; `sparda timeless export <id>` turns the bug into a vitest test. Recording is opt-in in the app (deterministic sampling + GDPR redaction built in).
+- **Self-Healing, Proven** → `sparda heal <id>` builds a fix brief from the graph, then `--check --expect '{"status":200}'` gates a candidate fix on three axes at once: the recorded flight now returns the expected response (not the bug), `verify` still passes, and `apocalypse` finds no new critical/high and no removed guard. The gate is honest both ways — an unfixed bug keeps it closed (exit 1).
 - **Clone learning / Transfer sémantique** → Use `sparda seed export` to package your app's descriptions, workflows, and antibodies. Then `sparda seed import --germinate` in another clone to import the structure and germinate simulated twin instances.
 - **Learn exemplars** → Start your live app and run `sparda twin --learn` to fetch actual response data and construct `.sparda/twin.json` locally.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "mcpName": "io.github.zyx77550/sparda-mcp",
   "description": "Compile backends to behavior graphs. Statically prove security, simulate APIs, and replay bugs.",
   "type": "module",

package/src/flight/box.js

@@ -29,8 +29,11 @@ export function createFlightBox() {
   const als = new AsyncLocalStorage();
   const originals = {};
   let armed = false;
-  let insideUUID = false;
-  let insideFetch = false;
+  // Node 18: fetch (undici) and crypto.randomUUID call Date.now()/Math.random()
+  // internally — those must NOT be recorded as entropy taps. The suppression
+  // flag lives ON THE STORE (per-request), not on the box: a global flag would
+  // let one request's fetch window swallow a concurrent request's entropy taps
+  // and silently corrupt its flight.
 
   function arm() {
     if (armed) return;
@@ -42,7 +45,7 @@ export function createFlightBox() {
 
     Date.now = function spardaDateNow() {
       const store = als.getStore();
-      if (!store || insideUUID || insideFetch) return originals.dateNow();
+      if (!store || store.suppressEntropy) return originals.dateNow();
       if (store.mode === 'record') {
         const v = originals.dateNow();
         tapOut(store, 'time', 'Date.now', v);
@@ -53,7 +56,7 @@ export function createFlightBox() {
 
     Math.random = function spardaRandom() {
       const store = als.getStore();
-      if (!store || insideUUID || insideFetch) return originals.random();
+      if (!store || store.suppressEntropy) return originals.random();
       if (store.mode === 'record') {
         const v = originals.random();
         tapOut(store, 'random', 'Math.random', v);
@@ -69,13 +72,13 @@ export function createFlightBox() {
           const store = als.getStore();
           if (!store) return originals.randomUUID();
           if (store.mode === 'record') {
-            insideUUID = true;
+            store.suppressEntropy = true;
             try {
               const v = originals.randomUUID();
               tapOut(store, 'uuid', 'crypto.randomUUID', v);
               return v;
             } finally {
-              insideUUID = false;
+              store.suppressEntropy = false;
             }
           }
           return takeTap(store, 'uuid', 'crypto.randomUUID');
@@ -90,7 +93,7 @@ export function createFlightBox() {
       const method = (init?.method ?? 'GET').toUpperCase();
       const label = `${method} ${url}`;
       if (store.mode === 'record') {
-        insideFetch = true;
+        store.suppressEntropy = true;
         try {
           const res = await originals.fetch(input, init);
           const text = (await res.text()).slice(0, MAX_BODY_BYTES);
@@ -98,7 +101,7 @@ export function createFlightBox() {
           tapOut(store, 'http', label, { status: res.status, headers, body: text });
           return new Response(text, { status: res.status, headers });
         } finally {
-          insideFetch = false;
+          store.suppressEntropy = false;
         }
       }
       const rec = takeTap(store, 'http', label);

package/src/ubg/openapi.js

@@ -102,7 +102,12 @@ export function extractOpenAPI(cwd, specPath) {
 function opSecurity(op, globalSecurity, known) {
   const local = op.security ? op.security.flatMap((s) => Object.keys(s)) : null;
   const active = local ?? globalSecurity;
-  return [...new Set(active.filter((s) => known.includes(s) || active.length))].sort();
+  // keep referenced schemes that are actually declared in components; if a
+  // spec references a scheme it never defined it is malformed, but the intent
+  // to protect the endpoint is clear — fall back to the raw references then.
+  // (The previous `|| active.length` made the filter a no-op — a real bug.)
+  const declared = active.filter((s) => known.includes(s));
+  return [...new Set(declared.length ? declared : active)].sort();
 }
 
 function paramsOf(op, item, rawPath) {

package/src/ubg/verify.js

@@ -36,10 +36,17 @@ export function verifyProject(cwd, { openapi = null } = {}) {
     /^[0-9a-f]{64}$/.test(a.graph.meta.sourceHash),
   );
 
-  // Canonical form is idempotent: canonicalize(canonicalize(g)) == canonicalize(g)
-  const canon1 = a.json;
-  const canon2 = JSON.stringify(canonicalizeGraph(reviveGraph(a.graph)), null, 2) + '\n';
-  record('Determinism (§3.3)', 'canonical form is a fixed point', canon1 === canon2);
+  // Canonical form is a fixed point: re-canonicalizing an ALREADY-canonical
+  // graph must be a no-op. This is a real idempotence check — the previous
+  // version compared canonicalize(g) with canonicalize(g) (trivially equal)
+  // and proved nothing.
+  const once = canonicalizeGraph(a.graph);
+  const twice = canonicalizeGraph(once);
+  record(
+    'Determinism (§3.3)',
+    'canonical form is a fixed point',
+    JSON.stringify(once) === JSON.stringify(twice),
+  );
 
   // Structural integrity — every edge lands on a real node, every kind known.
   let structural = true;
@@ -144,9 +151,3 @@ function openApiRoundTrip(graph, cwd) {
     return { pass: false, detail: err.message.split('\n')[0] };
   }
 }
-
-// canonicalizeGraph wants a live graph (Map nodes); rebuild one from the
-// canonical arrays so we can re-canonicalize and check the fixed point
-function reviveGraph(liveGraph) {
-  return liveGraph; // compileUBG returns the live graph; canonicalize accepts it
-}