sparda-mcp 0.14.1 → 0.15.0

package/README.md

@@ -6,115 +6,39 @@
 
 <br/>
 
-<div align="center">
-
-## **AI writes. SPARDA proves.**
-
-</div>
-
-AI made writing code free. It made *trusting* code the bottleneck. Your agents open
-pull requests faster than any human can truly review them, and the industry's answer
-is to have another LLM skim the diff — an opinion grading an opinion.
-
-SPARDA is not an opinion. It's a **behavior compiler**: it compiles your backend
-(code + schema) into a deterministic behavior graph, and *proves* things against it —
-which guard a PR removed, which invariant a deploy dropped, whether a fix broke
-nothing else. Every finding is a **counterexample**, never a vibe. Zero spec to
-write, zero config, zero API key, nothing leaves your machine.
-
-One engine, four moves:
-
-| | Command | What it proves |
-|---|---|---|
-| 🔍 | `sparda review` | the **behavior diff** of a PR — guards dropped, blast radius grown, new endpoints |
-| 🛡️ | `sparda apocalypse` | a deploy can't break any declared guard, invariant, transaction or aggregate |
-| 🪞 | `sparda mirror` | a live mock **derived from the code** — enforces the real state machine, can never drift |
-| ⏪ | `sparda timeless` / `heal` | replay a production bug deterministically; gate the fix with proof, not hope |
-
-And because trust must extend to *runtime*, the same engine turns your app into a
-safe set of MCP tools for Claude & friends — writes gated, failures quarantined
-(see [Give your AI safe hands](#give-your-ai-safe-hands-the-mcp-layer)).
-
-## Review every PR's *behavior* — one file, zero config
+> 🇫🇷 **Français** : Pour comprendre SPARDA en 10 minutes (douleur, architecture, vision), lisez le document du fondateur : [SPARDA-EXPLIQUE.md](docs/SPARDA-EXPLIQUE.md).
 
-Every code-review tool diffs your **text**. None diff your **behavior**. SPARDA
-compiles the PR's base branch and your changes to the behavior graph and comments the
-difference — as one sticky comment that updates on every push:
+---
 
-<div align="center">
-  <img src="assets/pr-review-demo.svg" alt="SPARDA review bot commenting the behavior diff on a pull request: NOT PROVEN — GUARD_REMOVED on POST /pay, BLAST_RADIUS_GREW on POST /transfer, new endpoint POST /refund" width="740" />
-</div>
+**A compiler for backend behavior. The LLVM of web applications.**
 
-<br/>
+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.
 
-Drop this one file into `.github/workflows/sparda-review.yml` — no key, no account,
-no spec to write:
-
-```yaml
-name: SPARDA behavior review
-on: pull_request
-permissions:
-  contents: read
-  pull-requests: write
-jobs:
-  review:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
-      - uses: zyx77550/sparda@main
-        with:
-          mode: review          # comment-only by default — never blocks a merge
-          # fail-on-severity: high   # uncomment to also gate the check
-```
+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.
 
-Every finding is a **counterexample from the code + schema**, not a pattern-match — so
-no false-positive noise to train your team to ignore. Same engine, as a hard CI gate:
-`mode: apocalypse` (the default) fails the job on any critical/high and can upload
-SARIF to the Security tab.
+**What the graph unlocks — 100% local, deterministic, zero runtime dependencies, zero API key:**
 
-## Prove the deploy
+| 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 apocalypse            # PROVEN, RISKY, or NOT PROVEN — with counterexamples
-npx sparda-mcp apocalypse --sarif    # findings land in GitHub's Security tab
+npx sparda-mcp ubg          # compile your backend → .sparda/ubg.json
+npx sparda-mcp apocalypse   # prove the current tree is safe to deploy
 ```
 
-Five proof obligations discharged over the compiled graph — unguarded mutations,
-unvalidated constrained writes, non-atomic aggregate writes, irreversible external
-calls, aggregate bypasses — plus a diff against your saved baseline: no entrypoint
-silently removed, no guard dropped, no blast radius grown. Exit 1 gates the pipeline.
-
-## A mock that can never lie
-
-```bash
-npx sparda-mcp mirror                # the graph IS the server — no framework, no source
-```
+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.
 
-The mirror serves your compiled behavior over HTTP: guards actually deny (401),
-responses come out typed, and the **inferred state machine is enforced** — `POST
-/orders` seeds `pending`, paying it moves it to `paid`, paying it *again* is refused
-`409`. Hand-written mocks drift; this one is derived from your code + schema, so it's
-synchronized by construction. Front-ends develop against backends that aren't
-deployed — or written — yet.
+**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.
 
-## Give your AI safe hands (the MCP layer)
-
-Your AI can write code. It still can't *operate* your app — and giving it raw access
-usually means days of glue code and one prayer per `DELETE`. SPARDA deletes that work:
-
-```bash
-npx sparda-mcp init   # scan your Express/FastAPI/Next.js app, inject the MCP router — 3 minutes
-npx sparda-mcp dev    # connect Claude Desktop / Claude Code. Done.
-```
-
-No OpenAPI spec. No account. No API key. No server to host. And the same trust rules
-apply at runtime: **writes are disabled by default**, an enabled write needs an
-explicit human confirmation (two-phase, single-use token), and every write is followed
-by a proof-after-write read-back.
-
-<details>
-<summary><b>Quickstart — three steps</b></summary>
+## Quickstart
 
 1. **Scan + inject** — run once, from your app's directory:
    ```bash
@@ -144,24 +68,130 @@ by a proof-after-write read-back.
    Claude Code connects to the same bridge. That's it — your running app is now a set
    of MCP tools your AI can call.
 
-</details>
-
 ## Try the Standalone Demo
 
 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
 
 SPARDA is designed as a local organism. To see what it remembers and how much compute it has recycled:
 ```bash
-npx sparda-mcp report          # terminal dashboard
-npx sparda-mcp report --html   # self-contained offline dashboard at .sparda/report.html
-npx sparda-mcp report --json   # raw JSON for integration
+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
+```
+
+## 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.
+
+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).
+
+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:
+    sarif: 'true'
+```
+
+## Time Travel: Timeless
+
+Every production request is deterministic between its effects — the compiler knows exactly where the nondeterminism lives (db, http, clock, random, uuid: the effect nodes of the graph). Timeless records only those points (a few KB per request) and replays the request **byte-identically** against your current code, with the database, webhooks and clock virtualized from the recording:
+
+```bash
+npx sparda-mcp timeless                # list recorded flights
+npx sparda-mcp timeless replay <id>    # re-fly it — byte-identical or loud divergence
+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
+```
+
+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.
+
+```bash
+npx sparda-mcp ubg --openapi openapi.json
+```
+
+Security schemes become gating `guard` nodes, response schemas become typed returns, declared request bodies count as validated input. Pair the spec with your `.sql` or `schema.prisma` files and the full state layer — invariants, aggregates, state machines — fills in from declared truth. (JSON specs in v1; we refuse to half-parse YAML with zero dependencies.)
+
+## The Mirror VM: delete the framework, the app still answers
+
+The graph is not a diagram — it executes:
+
+```bash
+npx sparda-mcp mirror
+```
+
+```
+MIRROR — the graph is serving. 3 entrypoint(s) on http://127.0.0.1:4477
+  GET    /orders/{orderId}  → {amount, id, status}
+  POST   /orders  🔒 bearerAuth  → {amount, id, status}
+```
+
+No Express. No FastAPI. No source code — just `ubg.json` answering HTTP: guards actually deny (401), responses render the compiled return schemas, unknown paths 404 with the full route table. Front-end teams develop against backends that aren't deployed yet — or aren't written yet (point `mirror` at an OpenAPI spec). Every response carries `x-sparda-mirror: true`; the mirror serves declared behavior, it never invents business values.
 
 To undo everything: **`npx sparda-mcp remove`** restores your code byte-for-byte.
 
@@ -173,10 +203,10 @@ To undo everything: **`npx sparda-mcp remove`** restores your code byte-for-byte
 
 <br/>
 
-1. **Proof, not opinion.** Every review/apocalypse finding is a counterexample derived from your code + schema — deterministic, byte-identical run after run, machine after machine.
-2. **Three minutes, one command.** AST scan, router generation, reversible injection — no config.
-3. **Try it for free, leave for free.** `npx sparda-mcp remove` restores your code **byte-for-byte** (tested on JS, TS, Python, even Windows CRLF files). No trace, no lock-in.
-4. **The AI cannot write until you say so.** Every POST/PUT/DELETE is disabled by default; you enable per tool, and your choice survives every re-run.
+1. **Three minutes, one command.** AST scan, router generation, reversible injection — no config.
+2. **Try it for free, leave for free.** `npx sparda-mcp remove` restores your code **byte-for-byte** (tested on JS, TS, Python, even Windows CRLF files). No trace, no lock-in.
+3. **The AI cannot write until you say so.** Every POST/PUT/DELETE is disabled by default; you enable per tool, and your choice survives every re-run.
+4. **Your app defends itself.** A route failing 3 times in a row is quarantined — the AI can't hammer your broken production. Latency anomalies are flagged. Zero LLM needed.
 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.
 
@@ -184,14 +214,23 @@ What we *don't* promise: the honest limits in [docs/SECURITY.md](./docs/SECURITY
 
 ## How it works
 
-1. **The compiler.** `sparda ubg` (run implicitly by `review`/`apocalypse`/`mirror`) parses your codebase and SQL/Prisma schema (AST — 100% local, zero LLM) into a deterministic behavior graph: entrypoints, guards, effects, state, invariants, state machines. `sparda verify` proves the compiler's own laws (determinism, soundness, round-trip) on your input.
-2. **The proofs.** `review` and `apocalypse` discharge proof obligations over that graph; `mirror` executes it; `timeless` records/replays real requests against it.
-3. **The MCP layer.** `init` injects a tiny marked router (`/mcp`) into your app — fully reversible with `remove`. Tool calls run **inside your live app process** — warm DB pools, real auth chain, real data. Zero infrastructure: compute from your host process, intelligence from your AI client's own model (MCP sampling), storage from `sparda.json` + git.
+1. `npx sparda-mcp init` parses your codebase (AST), extracts every route, and injects a tiny marked router (`/mcp`) into your app — fully reversible with `npx sparda-mcp remove`.
+2. Tool calls run **inside your live app process** — warm DB pools, real auth chain, real data. SPARDA adds no infrastructure: compute comes from your host process, intelligence from your AI client's own model (MCP sampling), storage from `sparda.json` + git.
+3. Write tools (POST/PUT/DELETE) are **disabled by default**. You opt in per tool in `sparda.json` — your choices survive re-runs.
 4. Suspicious docstrings are sanitized before they ever reach the AI (prompt-injection defense).
+5. `npx sparda-mcp doctor --app` audits your codebase for drift: it detects stale tools (IA seeing ghosts), unsynced routes, schema drift via fingerprints, and zombie configurations. High severity issues trigger a non-zero exit code for your CI pipeline.
+6. `npx sparda-mcp seed export/import` lets you package and share your app's "genome" (semantic memory, workflows, antibodies) securely, transferring immune memory between environments or across similar stacks with zero data leak.
+7. `npx sparda-mcp twin` starts a safe, simulated mock server of your backend on the original port. It serves GET calls from learned exemplars (observed response shapes & mock data) and returns simulated 202 writes without ever touching your real database or production APIs. Learn exemplars by running `npx sparda-mcp twin --learn`.
+8. `npx sparda-mcp grammar` maps the graph of valid sequences of tool calls (observed circuits and candidate hypotheses) to prevent LLM hallucination of routes.
+9. `npx sparda-mcp evolve` mutates candidate chains and tests them against the twin in-memory, promoting successful chains to evolved workflow suggestions.
 
-## The living organism — what runtime trust looks like
+## What SPARDA gives your AI
 
-The proof gate covers what AI *writes*. These organs cover what AI *does*, live:
+### 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.
 
 ### 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.
@@ -223,10 +262,9 @@ step's real response. Write routes are never absorbed — their per-call confirm
 always stands.
 
 ### Living context & telemetry
-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. `GET /mcp/stats` and
-`GET /mcp/events` expose the same live picture over HTTP.
+`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
@@ -241,10 +279,10 @@ runtime, so the guidance never goes stale.
 - **Next.js App Router (13/14/15)** — file-based injection. Since Next.js uses file-system routing, SPARDA simply creates a catch-all route handler under `app/mcp/[...sparda]/route.js`. **Nothing in your existing codebase's code is touched**; running `remove` simply deletes the generated file.
 - **Express 4/5** (JS/TS, ESM/CJS) — AST-based router injection.
 - **FastAPI** (Python >= 3.9) — AST-based router injection.
-- **Any backend with an OpenAPI spec** — `--openapi api.json` lowers the spec into the same behavior graph, so `review`, `apocalypse`, `mirror` and `openapi` work on Go, Rails, Java, .NET… without a parser.
 
 ## 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.
 - AST-positioned injection with backup and post-injection re-parse; `npx sparda-mcp remove` leaves a clean git diff.
 - Persistence is **value-free**: SPARDA records structure (tool names, field names, fingerprints), never your payloads.

package/SKILL.md

@@ -1,42 +1,32 @@
 ---
 name: sparda-mcp
 description: >-
-  Drive a SPARDA-generated MCP server to its full potential. Use this whenever
-  you are connected to an MCP server built by SPARDA (sparda-mcp) — recognizable
-  by the tools `sparda_get_context`, `sparda_info`, `sparda_confirm`, or composite
-  tools labelled "[Labs circuit]". It teaches the call-context-first workflow, how
-  to exploit the response-recycling flywheel, the circuit-breaker, crystallized
-  circuits and adaptive immunity, and the mandatory two-phase confirm protocol for
-  write tools. Reach for it before calling raw endpoints, before any write, or when
-  a tool returns 202 (awaiting confirmation) or 503 (quarantined).
+  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 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.
 ---
 
-# Driving a SPARDA MCP server
+# Driving a SPARDA Behavior Runtime
 
-A SPARDA server is **not** a flat list of HTTP endpoints. SPARDA injected a live
-`/mcp` router *inside a real running app*, so its tools are that app's actual
-routes — wrapped in an intelligence layer that makes repeated use **cheaper** (it
-recycles stable answers from memory) and **safer** (it quarantines failing tools
-and gates writes behind human confirmation). This is the runtime half of SPARDA's
-trust layer — "AI writes. SPARDA proves." — the same engine that proves PRs and
-deploys (`sparda review` / `apocalypse`) also guards what you *do* to the live app.
-Used naively it's just an API. Used well, it gets faster and safer the more you
-call it. This skill is how to use it well.
+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.
 
 ## Rule 0 — call `sparda_get_context` first, every session
 
-Before anything else, call **`sparda_get_context`** (no params). It returns the
-*live* picture, so you never guess the surface:
+Before anything else, call **`sparda_get_context`** (no params). It returns the *live* state of the SPARDA Behavior Graph:
 
-- the enabled tools + their descriptions, and SPARDA's suggested **workflows**;
-- `runtime` — current `/mcp/stats` (per-tool call/error counts, tool "purity",
-  quarantine state);
-- the last ~20 **events** (errors, latency anomalies, immune diagnoses);
-- **immune memory** (known failure signatures + cached fixes);
-- **recycling** stats (how many calls were served from memory);
-- a `behavior` snapshot (which response fields are stable).
+- the active routes/tools, workflows, and type-propagated schemas;
+- `runtime` — current stats (calls, errors, quarantine states, Twin mode active);
+- the last ~20 **events** (errors, latency anomalies, immune alerts);
+- **immune memory** (cached antibodies and error diagnoses);
+- **recycling** metrics (flywheel memory hit rates);
+- a `behavior` snapshot of stable variables.
 
-Read it before acting. `sparda_info` gives a lighter summary if you only need counts.
+Read it to orient yourself inside the graph. `sparda_info` gives a lighter summary of counts.
 
 ## The tools you'll see
 
@@ -86,6 +76,16 @@ adapt — don't blindly retry the same call.
 **5. Latency anomalies.** A call far slower than a tool's own baseline surfaces as
 an `immune` event in `/mcp/events`. Treat it as a hint to back off or warn the user.
 
+**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.
+
 ## Writing safely — the mandatory two-phase protocol
 
 Writes are **disabled by default**. The protocol is not optional:
@@ -138,6 +138,15 @@ Writes are **disabled by default**. The protocol is not optional:
 - **General health** → `sparda doctor` checks Node version, framework detection,
   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>` 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.
 
 ---
 *This skill ships with `sparda-mcp` and is regenerated from SPARDA's capability

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.14.1",
+  "version": "0.15.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/fingerprint.js

@@ -0,0 +1,47 @@
+// commands/fingerprint.js — print the portable behavior fingerprint of each
+// entrypoint (ADR-035, Brick 1). The hash is coordinate-free: the SAME behavioral
+// shape in any other repo produces the SAME hash. This is the address a shared
+// diagnosis (an antibody) is filed under — the seam where a local proof becomes
+// collective memory. Read-only, offline, deterministic.
+//   sparda fingerprint          human table
+//   sparda fingerprint --json   raw [{ entrypoint, behaviorHash, descriptor }]
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { fingerprintGraph } from '../ubg/fingerprint.js';
+
+export async function runFingerprint(opts) {
+  const canonical = canonicalizeGraph(
+    compileUBG(opts.cwd, { write: false, openapi: opts.openapi }).graph,
+  );
+  const prints = fingerprintGraph(canonical);
+
+  if (opts.json) {
+    console.log(JSON.stringify(prints, null, 2));
+    return { prints };
+  }
+
+  if (!prints.length) {
+    // Same honesty rule as apocalypse: nothing to address is not a success.
+    console.log(
+      '✗ NO FINGERPRINT — 0 routes reached. SPARDA could not see this app’s surface (a parser-coverage gap); there is nothing to address.',
+    );
+    process.exitCode = 1;
+    return { prints };
+  }
+
+  console.log(`BEHAVIOR FINGERPRINTS — ${prints.length} entrypoint(s), coordinate-free`);
+  for (const p of prints) {
+    const d = p.descriptor;
+    const parts = [
+      `${d.guards} guard${d.guards === 1 ? '' : 's'}`,
+      d.validated ? 'validated' : 'unvalidated',
+      d.effects.length ? d.effects.join(',') : 'no effects',
+    ];
+    if (d.observable) parts.push('observable');
+    console.log(`  ${p.behaviorHash}  ${short(p.entrypoint)}`);
+    console.log(`      ${parts.join(' · ')}`);
+  }
+  return { prints };
+}
+
+const short = (id) => id.replace(/^entrypoint:/, '');

package/src/commands/immunize.js

@@ -0,0 +1,54 @@
+// commands/immunize.js — freeze the app's proven safety into a tiny capsule (ADR-037).
+// The expensive reasoning (compile → obligations → polarity → behaviorHash) runs
+// ONCE here; the output is a self-contained artifact of a few bytes per route that
+// any consumer — CI, an agent, the runtime, another SPARDA install — reads by pure
+// lookup, no recompile, no LLM, no network. BitNet's move applied to trust.
+//   sparda immunize          write .sparda/immunity.json + a summary
+//   sparda immunize --json   print the capsule to stdout
+import path from 'node:path';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { buildCapsule } from '../ubg/immunity.js';
+import { AXES } from '../ubg/polarity.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+export async function runImmunize(opts) {
+  const canonical = canonicalizeGraph(
+    compileUBG(opts.cwd, { write: false, openapi: opts.openapi }).graph,
+  );
+  const capsule = buildCapsule(canonical);
+
+  if (opts.json) {
+    console.log(JSON.stringify(capsule, null, 2));
+    return { capsule };
+  }
+
+  if (!capsule.routes.length) {
+    console.log(
+      '✗ NO CAPSULE — 0 routes reached; nothing to immunize (a parser-coverage gap, not a pass).',
+    );
+    process.exitCode = 1;
+    return { capsule };
+  }
+
+  const outPath = path.join(opts.cwd, '.sparda', 'immunity.json');
+  atomicWrite(outPath, JSON.stringify(capsule) + '\n');
+  const wire = JSON.stringify(capsule).length;
+
+  console.log(
+    `IMMUNITY CAPSULE — ${capsule.routes.length} route(s) frozen into ${capsule.bytes} byte(s) of safety` +
+      ` (5 axes = 5 trits = 1 byte/route)`,
+  );
+  const exposed = AXES.filter((a) => capsule.posture[a].exposed > 0)
+    .map((a) => `${a}×${capsule.posture[a].exposed}`)
+    .join(', ');
+  console.log(
+    `  verdict: ${capsule.proven ? '✓ PROVEN' : '✗ NOT PROVEN'}` +
+      (exposed ? ` — exposed: ${exposed}` : ''),
+  );
+  console.log(
+    `  written: .sparda/immunity.json (${wire} bytes on the wire) — portable, offline, lookup by behaviorHash`,
+  );
+  if (!capsule.proven) process.exitCode = 1;
+  return { capsule, outPath };
+}

package/src/commands/polarity.js

@@ -0,0 +1,57 @@
+// commands/polarity.js — show the ternary behavior matrix (ADR-036).
+// Each route becomes a row of {−, ·, +} over the five safety obligations; the
+// verdict is a sign check and the app posture is a column sum. This is proof as
+// arithmetic — the representation that lets the collective genome compose behavior
+// by adding ternary columns instead of re-running proofs. Read-only, deterministic.
+//   sparda polarity          the matrix + posture + arithmetic verdict
+//   sparda polarity --json   raw { polarity, posture, proven }
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { checkGraph } from '../ubg/apocalypse.js';
+import {
+  AXES,
+  posture,
+  provenByPolarity,
+  polaritySignature,
+  exposedAxes,
+} from '../ubg/polarity.js';
+
+export async function runPolarity(opts) {
+  const canonical = canonicalizeGraph(
+    compileUBG(opts.cwd, { write: false, openapi: opts.openapi }).graph,
+  );
+  const { polarity } = checkGraph(canonical);
+  const proven = provenByPolarity(polarity);
+  const cols = posture(polarity);
+
+  if (opts.json) {
+    console.log(JSON.stringify({ proven, polarity, posture: cols }, null, 2));
+    return { polarity, posture: cols, proven };
+  }
+
+  if (!polarity.length) {
+    console.log(
+      '✗ NO POLARITY — 0 routes reached; nothing to score (a parser-coverage gap, not a pass).',
+    );
+    process.exitCode = 1;
+    return { polarity, posture: cols, proven };
+  }
+
+  console.log(`BEHAVIOR POLARITY — ${polarity.length} route(s) · ${AXES.join(' ')}`);
+  for (const p of polarity) {
+    const flag = exposedAxes(p.vector).length ? ' ✗' : '';
+    console.log(`  ${short(p.entrypoint)}${flag}`);
+    console.log(`      ${polaritySignature(p.vector)}`);
+  }
+  const exposed = AXES.filter((a) => cols[a].exposed > 0)
+    .map((a) => `${a}×${cols[a].exposed}`)
+    .join(', ');
+  console.log(
+    `\n${proven ? '✓ PROVEN' : '✗ NOT PROVEN'} (arithmetic: no gating −1)` +
+      (exposed ? ` — exposed: ${exposed}` : ''),
+  );
+  if (!proven) process.exitCode = 1;
+  return { polarity, posture: cols, proven };
+}
+
+const short = (id) => id.replace(/^entrypoint:/, '');

package/src/index.js

@@ -117,6 +117,21 @@ try {
       await runReview(opts);
       break;
     }
+    case 'fingerprint': {
+      const { runFingerprint } = await import('./commands/fingerprint.js');
+      await runFingerprint(opts);
+      break;
+    }
+    case 'polarity': {
+      const { runPolarity } = await import('./commands/polarity.js');
+      await runPolarity(opts);
+      break;
+    }
+    case 'immunize': {
+      const { runImmunize } = await import('./commands/immunize.js');
+      await runImmunize(opts);
+      break;
+    }
     case 'timeless': {
       const { runTimeless } = await import('./commands/timeless.js');
       await runTimeless(opts, rest);
@@ -161,6 +176,9 @@ Usage:
   npx sparda-mcp ubg       Compile the codebase to its Unified Behavior Graph (.sparda/ubg.json)
   npx sparda-mcp apocalypse  Prove the deploy: guards, invariants, transactions, aggregates (--save-baseline)
   npx sparda-mcp review    Semantic diff of a PR vs a base ref (--base main / --json / --markdown)
+  npx sparda-mcp fingerprint  Portable behavior hash per route — the address for shared diagnoses (--json)
+  npx sparda-mcp polarity  Ternary safety matrix per route — proof as arithmetic (--json)
+  npx sparda-mcp immunize  Freeze proven safety into a tiny capsule (1 byte/route) — .sparda/immunity.json
   npx sparda-mcp timeless  Replay production requests (list | replay <id> | export <id> → vitest)
   npx sparda-mcp mirror    Serve the compiled graph over HTTP — no framework, no source (--port)
   npx sparda-mcp openapi   Emit an OpenAPI 3.1 spec FROM the graph (--out / --json)

package/src/ubg/apocalypse.js

@@ -15,7 +15,7 @@ const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, info: 3 };
 const CONSTRAINING = new Set(['check', 'not_null', 'unique']);
 
 // canonical serialized graph ({ nodes: [], edges: [] }) → indexed view
-function indexGraph(graph) {
+export function indexGraph(graph) {
   const nodes = new Map(graph.nodes.map((n) => [n.id, n]));
   const cfOut = new Map();
   const mutOut = new Map();
@@ -40,7 +40,7 @@ function indexGraph(graph) {
   return { nodes, cfOut, mutOut, gateTargets, compensators, entrypoints };
 }
 
-function reachOf(epId, cfOut) {
+export function reachOf(epId, cfOut) {
   const seen = new Set();
   const queue = [epId];
   while (queue.length) {
@@ -66,6 +66,12 @@ export function checkGraph(graph) {
   const g = indexGraph(graph);
   const findings = [];
   let obligations = 0;
+  // Behavior polarity (ADR-036): per entrypoint, a ternary vector over the same
+  // obligations checked below — +1 protection present, 0 not applicable, -1
+  // violated. Built HERE so a -1 is literally the same condition as the finding
+  // (one source of truth, no drift). The algebra over these vectors lives in
+  // ubg/polarity.js; this function just records them.
+  const polarity = [];
 
   for (const ep of g.entrypoints) {
     const reach = reachOf(ep.id, g.cfOut);
@@ -77,9 +83,11 @@ export function checkGraph(graph) {
       for (const e of g.mutOut.get(n.id) ?? []) writes.push({ effect: n, stateId: e.to });
     }
     const observables = reached.filter((n) => n?.kind === 'effect' && n.meta.observable);
+    const vec = { auth: 0, validation: 0, atomicity: 0, reversibility: 0, aggregate: 0 };
 
     // O1 — every mutation path must pass a guard
     obligations++;
+    if (writes.length) vec.auth = guards.length ? 1 : -1;
     if (writes.length && guards.length === 0) {
       findings.push({
         rule: 'UNGUARDED_MUTATION',
@@ -92,21 +100,20 @@ export function checkGraph(graph) {
 
     // O2 — writes into constrained tables need validated input
     obligations++;
-    if (!ep.meta.inputValidated) {
-      const constrained = writes.filter((w) =>
-        (g.nodes.get(w.stateId)?.meta.invariants ?? []).some((i) =>
-          CONSTRAINING.has(i.type),
-        ),
-      );
-      if (constrained.length) {
-        findings.push({
-          rule: 'UNVALIDATED_CONSTRAINED_WRITE',
-          severity: 'medium',
-          entrypoint: ep.id,
-          message: `${ep.label} writes ${fmtStates(constrained)} whose declared invariants (CHECK/NOT NULL/UNIQUE) can be violated by unvalidated input`,
-          evidence: constrained.map((w) => w.stateId),
-        });
-      }
+    const constrained = writes.filter((w) =>
+      (g.nodes.get(w.stateId)?.meta.invariants ?? []).some((i) =>
+        CONSTRAINING.has(i.type),
+      ),
+    );
+    if (constrained.length) vec.validation = ep.meta.inputValidated ? 1 : -1;
+    if (!ep.meta.inputValidated && constrained.length) {
+      findings.push({
+        rule: 'UNVALIDATED_CONSTRAINED_WRITE',
+        severity: 'medium',
+        entrypoint: ep.id,
+        message: `${ep.label} writes ${fmtStates(constrained)} whose declared invariants (CHECK/NOT NULL/UNIQUE) can be violated by unvalidated input`,
+        evidence: constrained.map((w) => w.stateId),
+      });
     }
 
     // O3 — multi-table writes inside one aggregate must share a transaction
@@ -122,7 +129,9 @@ export function checkGraph(graph) {
       const states = new Set(ws.map((w) => w.stateId));
       if (states.size < 2) continue;
       const txIds = new Set(ws.map((w) => w.effect.meta.transaction?.id ?? null));
-      if (txIds.size !== 1 || txIds.has(null)) {
+      const atomic = txIds.size === 1 && !txIds.has(null);
+      vec.atomicity = atomic && vec.atomicity !== -1 ? 1 : -1;
+      if (!atomic) {
         findings.push({
           rule: 'NON_ATOMIC_AGGREGATE_WRITE',
           severity: 'high',
@@ -137,17 +146,21 @@ export function checkGraph(graph) {
     // when the entrypoint also mutates state (the write can fail after the
     // world already saw the effect)
     obligations++;
-    for (const obs of observables) {
-      if (obs.meta.compensable) continue;
-      if (g.compensators.has(obs.id)) continue; // the undo itself is not a risk
-      if (!writes.length) continue;
-      findings.push({
-        rule: 'IRREVERSIBLE_OBSERVABLE',
-        severity: 'high',
-        entrypoint: ep.id,
-        message: `${ep.label} makes an irreversible external call (${obs.meta.target ?? obs.label}) while also mutating state — no compensation path exists if the write fails`,
-        evidence: [`${obs.id} (${locOf(obs)})`],
-      });
+    if (observables.length && writes.length) {
+      let bad = false;
+      for (const obs of observables) {
+        if (obs.meta.compensable) continue;
+        if (g.compensators.has(obs.id)) continue; // the undo itself is not a risk
+        bad = true;
+        findings.push({
+          rule: 'IRREVERSIBLE_OBSERVABLE',
+          severity: 'high',
+          entrypoint: ep.id,
+          message: `${ep.label} makes an irreversible external call (${obs.meta.target ?? obs.label}) while also mutating state — no compensation path exists if the write fails`,
+          evidence: [`${obs.id} (${locOf(obs)})`],
+        });
+      }
+      vec.reversibility = bad ? -1 : 1;
     }
 
     // O5 — mutating an aggregate member without touching its root
@@ -160,6 +173,7 @@ export function checkGraph(graph) {
           g.nodes.get(o.stateId)?.meta.role === 'aggregate_root' &&
           g.nodes.get(o.stateId)?.meta.consistencyDomain === state.meta.consistencyDomain,
       );
+      vec.aggregate = touchesRoot && vec.aggregate !== -1 ? 1 : -1;
       if (!touchesRoot) {
         findings.push({
           rule: 'AGGREGATE_MEMBER_BYPASS',
@@ -170,9 +184,11 @@ export function checkGraph(graph) {
         });
       }
     }
+
+    polarity.push({ entrypoint: ep.id, vector: vec });
   }
 
-  return { findings: sortFindings(findings), obligations };
+  return { findings: sortFindings(findings), obligations, polarity };
 }
 
 // ---------------------------------------------------------------------------

package/src/ubg/fingerprint.js

@@ -0,0 +1,97 @@
+// ubg/fingerprint.js — portable behavior fingerprints (ADR-035, Brick 1).
+//
+// The UBG's node ids are content-derived but REPO-LOCAL: `logic:src/index.ts#foo:44`
+// names a file, a line, a symbol. Two codebases that share the exact same behavior
+// still get different ids. A *behavior fingerprint* erases those coordinates and
+// keeps only the behavioral SHAPE of an entrypoint's reachable subgraph — verb,
+// guard presence, validation, the kinds of effects it runs, and the invariant
+// classes on the state it writes. Same shape in two different repos → same hash.
+//
+// That hash is an ADDRESS. It turns "a behavior" into something you can look up:
+// the key under which a diagnosis (an antibody) learned once, anywhere, applies
+// everywhere the same shape occurs. This file only computes the address; it makes
+// no network call and stores nothing (hard rule #1). Deterministic, locale-
+// independent, byte-stable machine to machine (the same promise as the graph).
+import crypto from 'node:crypto';
+import { indexGraph, reachOf } from './apocalypse.js';
+import { cmp, stableStringify } from './schema.js';
+
+export const FINGERPRINT_VERSION = 'bh1'; // behavior-hash v1 — bump on shape change
+
+// entrypoint id is `entrypoint:${METHOD} ${path}`. The verb is behavioral; the
+// literal path segments are repo-local, but the *arity* of its parameters
+// (`:id`, `{id}`) is part of the shape.
+function entrypointShape(ep) {
+  const m = /^entrypoint:(\S+)\s+(.*)$/.exec(ep.id);
+  const method = (m?.[1] ?? ep.meta?.method ?? 'GET').toUpperCase();
+  const path = m?.[2] ?? '';
+  const pathParams = (path.match(/:(\w+)|\{(\w+)\}/g) ?? []).length;
+  return { method, pathParams };
+}
+
+// One entrypoint → { behaviorHash, descriptor }. The descriptor is the inspectable
+// pre-image (so a human/agent can see WHY two things share an address); the hash is
+// sha256 over its canonical bytes. Everything here is coordinate-free by design.
+export function fingerprintEntrypoint(indexed, ep) {
+  const { nodes, cfOut, mutOut } = indexed;
+  const reached = [...reachOf(ep.id, cfOut)].map((id) => nodes.get(id)).filter(Boolean);
+
+  const guards = reached.filter((n) => n.kind === 'guard').length;
+
+  const effects = []; // sorted multiset of effect atoms, e.g. "db_write:update"
+  const writes = []; // per-write: invariant CLASSES touched + tx/member flags
+  let observable = false;
+
+  for (const n of reached) {
+    if (n.kind !== 'effect') continue;
+    const type = n.meta?.effectType ?? n.id.split(':')[1] ?? 'effect';
+    const op = n.meta?.op ?? null;
+    effects.push(op ? `${type}:${op}` : type);
+    if (n.meta?.observable) observable = true;
+    for (const e of mutOut.get(n.id) ?? []) {
+      const state = nodes.get(e.to);
+      const invariants = [
+        ...new Set((state?.meta?.invariants ?? []).map((i) => i.type)),
+      ].sort(cmp); // classes only (check/unique/notnull) — never the table or expr
+      writes.push({
+        op: op ?? 'write',
+        invariants,
+        tx: Boolean(n.meta?.transaction),
+        member: state?.meta?.role === 'member',
+      });
+    }
+  }
+
+  effects.sort(cmp);
+  writes.sort((a, b) => cmp(stableStringify(a), stableStringify(b)));
+
+  const { method, pathParams } = entrypointShape(ep);
+  const descriptor = {
+    v: FINGERPRINT_VERSION,
+    method,
+    pathParams,
+    guards,
+    validated: Boolean(ep.meta?.inputValidated),
+    observable,
+    effects,
+    writes,
+  };
+  return { behaviorHash: hashOf(descriptor), descriptor };
+}
+
+// Whole graph → one fingerprint per entrypoint, sorted by id (deterministic).
+export function fingerprintGraph(graph) {
+  const indexed = indexGraph(graph);
+  return indexed.entrypoints
+    .map((ep) => ({ entrypoint: ep.id, ...fingerprintEntrypoint(indexed, ep) }))
+    .sort((a, b) => cmp(a.entrypoint, b.entrypoint));
+}
+
+function hashOf(descriptor) {
+  const digest = crypto
+    .createHash('sha256')
+    .update(stableStringify(descriptor))
+    .digest('hex')
+    .slice(0, 32);
+  return `${FINGERPRINT_VERSION}_${digest}`;
+}

package/src/ubg/immunity.js

@@ -0,0 +1,65 @@
+// ubg/immunity.js — the immunity capsule (ADR-037).
+//
+// The capsule is the "mini-intelligence that costs nothing": SPARDA does the
+// expensive static reasoning ONCE at compile time (graph → obligations → polarity
+// + a portable behaviorHash per route), then freezes the result into a tiny,
+// self-contained artifact. Each route reduces to (behaviorHash, one polarity byte).
+// The capsule needs nothing to "run" — it is a frozen judgment consulted by a pure
+// lookup: no recompile, no LLM, no network. That is BitNet's move applied to trust —
+// amortize the thinking, ship a cheap representation that acts on its own.
+//
+// It is also the atom of the world genome (ADR-035): one app's capsule is its
+// contribution; capsules compose (posture column-sums stack app → fleet → world).
+import { fingerprintGraph } from './fingerprint.js';
+import { checkGraph } from './apocalypse.js';
+import { cmp } from './schema.js';
+import { AXES, posture, provenByPolarity, packVector, exposedAxes } from './polarity.js';
+
+export const CAPSULE_VERSION = 'imm1';
+
+// canonical graph → a compact, portable, deterministic safety capsule.
+export function buildCapsule(graph) {
+  const prints = new Map(fingerprintGraph(graph).map((p) => [p.entrypoint, p]));
+  const { polarity } = checkGraph(graph);
+
+  const routes = polarity
+    .map(({ entrypoint, vector }) => ({
+      behaviorHash: prints.get(entrypoint)?.behaviorHash ?? null,
+      pol: packVector(vector), // one byte: the route's whole safety character
+      exposed: exposedAxes(vector), // convenience; derivable from pol
+    }))
+    .sort((a, b) => cmp(a.behaviorHash ?? '', b.behaviorHash ?? ''));
+
+  return {
+    v: CAPSULE_VERSION,
+    proven: provenByPolarity(polarity),
+    routes,
+    posture: posture(polarity),
+    bytes: routes.length, // the whole app's safety, one byte per route
+  };
+}
+
+// The lookup that makes the capsule act on its own: given a behavior shape, what
+// does this capsule already know about it? Pure, O(routes), no compute. This is the
+// seam an agent (or the runtime) consults BEFORE doing expensive work — the local,
+// offline face of collective immunity.
+export function judge(capsule, behaviorHash) {
+  const hit = capsule.routes.find((r) => r.behaviorHash === behaviorHash);
+  if (!hit) return { known: false };
+  return {
+    known: true,
+    pol: hit.pol,
+    exposed: hit.exposed,
+    safe: hit.exposed.length === 0,
+  };
+}
+
+// Merge capsules into a fleet posture — composition is a column sum, nothing more.
+export function mergePosture(capsules) {
+  const cols = {};
+  for (const a of AXES) cols[a] = { protected: 0, exposed: 0, na: 0 };
+  for (const c of capsules)
+    for (const a of AXES)
+      for (const k of ['protected', 'exposed', 'na']) cols[a][k] += c.posture[a][k];
+  return cols;
+}

package/src/ubg/polarity.js

@@ -0,0 +1,120 @@
+// ubg/polarity.js — the ternary behavior algebra (ADR-036).
+//
+// Inspiration: BitNet reduces every network weight to {-1, 0, +1} so matrix
+// multiplication collapses into addition. We do the analogue for VERIFICATION.
+// Each entrypoint, against each safety obligation, is reduced to one ternary
+// digit: +1 the protection is present, 0 the obligation does not apply, -1 it is
+// violated. The vector is produced in checkGraph (one source of truth with the
+// findings — a -1 IS a finding). This file is the algebra over those vectors:
+//
+//   • a verdict is a sign check     — PROVEN ⇔ no gating axis is -1
+//   • a PR review is a SUBTRACTION  — candidate − base; a negative delta on an
+//                                     axis means the change REMOVED a protection
+//   • a posture is a COLUMN SUM     — count the -1/+1/0 per axis across routes;
+//                                     stack routes → app, stack apps → fleet.
+//
+// That closure — verification as add/subtract over a tiny alphabet — is what lets
+// the collective genome (ADR-035) compose behavior at scale: merging knowledge is
+// adding ternary columns, not re-running proofs. No floats, no drift, deterministic.
+import { cmp } from './schema.js';
+
+// The five obligations apocalypse discharges, in gating order. Severity is the
+// same mapping the findings use, so the arithmetic verdict matches the worded one.
+export const AXES = Object.freeze([
+  'auth', // O1 UNGUARDED_MUTATION
+  'atomicity', // O3 NON_ATOMIC_AGGREGATE_WRITE
+  'reversibility', // O4 IRREVERSIBLE_OBSERVABLE
+  'validation', // O2 UNVALIDATED_CONSTRAINED_WRITE
+  'aggregate', // O5 AGGREGATE_MEMBER_BYPASS
+]);
+
+export const AXIS_SEVERITY = Object.freeze({
+  auth: 'critical',
+  atomicity: 'high',
+  reversibility: 'high',
+  validation: 'medium',
+  aggregate: 'info',
+});
+
+const GATING = new Set(['critical', 'high']); // a -1 here means NOT PROVEN
+export const POLARITY_SYMBOL = Object.freeze({ '-1': '−', 0: '·', 1: '+' });
+
+// A route is "exposed" on an axis when its digit is -1. Gating exposure (auth /
+// atomicity / reversibility) is what flips a verdict to NOT PROVEN.
+export function exposedAxes(vector) {
+  return AXES.filter((a) => vector[a] === -1);
+}
+
+// PROVEN ⇔ no gating axis is -1, across every entrypoint. Pure sign check — the
+// arithmetic twin of verdictOf's `safe`.
+export function provenByPolarity(polarity) {
+  return polarity.every((p) =>
+    exposedAxes(p.vector).every((a) => !GATING.has(AXIS_SEVERITY[a])),
+  );
+}
+
+// Column sums: the app's exposure profile. protected/exposed/na per axis — the
+// ternary matrix collapsed to one row you can stack across apps into a fleet view.
+export function posture(polarity) {
+  const cols = {};
+  for (const a of AXES) cols[a] = { protected: 0, exposed: 0, na: 0 };
+  for (const { vector } of polarity) {
+    for (const a of AXES) {
+      const d = vector[a];
+      cols[a][d === 1 ? 'protected' : d === -1 ? 'exposed' : 'na']++;
+    }
+  }
+  return cols;
+}
+
+// review as subtraction: candidate − base, per shared entrypoint, per axis. A
+// negative delta means this change WEAKENED that axis (a protection removed); a
+// positive delta means it strengthened it. `regressed` is the headline: the axes
+// a PR made worse — the same thing diffGraphs reports in prose, as arithmetic.
+export function polarityDelta(baseList, candList) {
+  const base = new Map(baseList.map((p) => [p.entrypoint, p.vector]));
+  const out = [];
+  for (const { entrypoint, vector } of candList) {
+    const b = base.get(entrypoint);
+    if (!b) continue; // new entrypoint — surfaced by the endpoint diff, not here
+    const deltas = {};
+    const regressed = [];
+    for (const a of AXES) {
+      const d = (vector[a] ?? 0) - (b[a] ?? 0);
+      deltas[a] = d;
+      if (d < 0) regressed.push(a);
+    }
+    if (regressed.length || Object.values(deltas).some((d) => d !== 0)) {
+      out.push({ entrypoint, deltas, regressed });
+    }
+  }
+  return out.sort((x, y) => cmp(x.entrypoint, y.entrypoint));
+}
+
+// Compact printable signature of a vector, e.g. "auth:− validation:+ …" — order
+// fixed by AXES so it is stable across machines.
+export function polaritySignature(vector) {
+  return AXES.map((a) => `${a}:${POLARITY_SYMBOL[vector[a]]}`).join(' ');
+}
+
+// --- BitNet-style packing: a route's whole safety character in ONE byte -------
+// The five axes are five trits {-1,0,+1}. Five trits = 3^5 = 243 states < 256, so
+// the entire polarity vector packs into a single byte (base-3, digit = trit+1).
+// This is the atom of the immunity capsule (ADR-037): frozen judgment, near-zero
+// storage, decoded by a pure table lookup — no recompile, no LLM, no network.
+export function packVector(vector) {
+  let byte = 0;
+  for (let i = AXES.length - 1; i >= 0; i--)
+    byte = byte * 3 + ((vector[AXES[i]] ?? 0) + 1);
+  return byte; // 0..242
+}
+
+export function unpackVector(byte) {
+  const vector = {};
+  let b = byte;
+  for (const a of AXES) {
+    vector[a] = (b % 3) - 1;
+    b = Math.floor(b / 3);
+  }
+  return vector;
+}