sparda-mcp 0.8.0 → 0.9.0

package/README.md

@@ -6,23 +6,27 @@
 
 <br/>
 
-**Your AI can write code. It still can't operate your app.**
+**Compile your backend into a deterministic behavior runtime.**
 
-Claude, Cursor & friends read your *files* — not your *running product*. They can
-refactor a controller, but they can't create an order, fetch a real user, or see why
-production is failing. And giving an AI real access to your API usually means: write
-an OpenAPI spec, build an MCP server, host it, secure it, keep it in sync with every
-route change — and pray it never `DELETE`s the wrong row. Days of glue code, per
-project, forever drifting.
+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.
 
-SPARDA deletes that work:
+SPARDA analyzes your Express, FastAPI, or Next.js application, extracts its behavior, and compiles it into a **SPARDA Behavior Graph (SBG)**. 
+
+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.
+
+All executed 100% locally, with zero runtime dependencies and zero cloud connection.
 
 ```bash
-npx sparda-mcp init   # scan your Express/FastAPI app, inject the MCP router — 3 minutes
-npx sparda-mcp dev    # connect Claude Desktop / Claude Code. Done.
+npx sparda-mcp init   # Scan your app, compile the UBG, inject the SPARDA Runtime
+npx sparda-mcp dev    # Connect Claude Desktop / Cursor over stdio
 ```
 
-No OpenAPI spec. No account. No API key. No server to host.
+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.
 
 ## Quickstart
 
@@ -107,6 +111,9 @@ What we *don't* promise: the honest limits in [docs/SECURITY.md](./docs/SECURITY
 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.
 
 ## What SPARDA gives your AI
 
@@ -166,6 +173,7 @@ runtime, so the guidance never goes stale.
 
 ## 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

@@ -84,6 +84,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:
@@ -136,6 +146,8 @@ 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.
+- **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.8.0",
+  "version": "0.9.0",
   "mcpName": "io.github.zyx77550/sparda-mcp",
   "description": "Turn any codebase into an MCP server with one command. Express & FastAPI → Claude-ready in 3 minutes.",
   "type": "module",

package/src/commands/doctor.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { detectStack } from '../detect.js';
 import { buildNegentropy, renderNegentropy } from './negentropy.js';
+import { resolveSpardaKey } from '../generator/manifest.js';
 
 // Returns { healthy } so the CLI can exit non-zero on any ✗ — scripts/CI can
 // gate on `sparda doctor` (E-012). Informational '·' lines never fail it.
@@ -55,7 +56,8 @@ export async function runDoctor(opts) {
       );
 
       if (stack) {
-        const headers = { 'x-sparda-key': m.localKey };
+        const key = resolveSpardaKey(opts.cwd, m);
+        const headers = { 'x-sparda-key': key };
         try {
           const r = await fetch(`http://127.0.0.1:${m.port}/mcp/tools`, {
             headers,

package/src/commands/evolve.js

@@ -10,6 +10,7 @@ import { buildGrammar } from './grammar.js';
 import { createTwinServer, twinFilePath } from './twin.js';
 import { findByKey } from '../server/crystallize.js';
 import { mergeManifestKeySync } from '../server/persistence.js';
+import { resolveSpardaKey } from '../generator/manifest.js';
 
 const MAX_CANDIDATES_PER_RUN = 10;
 
@@ -101,7 +102,8 @@ export async function runEvolve(opts) {
   }
 
   // the practice arena: an in-process twin on an ephemeral port
-  const server = createTwinServer(manifest, exemplars);
+  const localKey = resolveSpardaKey(opts.cwd, manifest);
+  const server = createTwinServer(manifest, localKey, exemplars);
   const port = await new Promise((resolve, reject) => {
     server.once('error', reject);
     server.listen(0, '127.0.0.1', () => resolve(server.address().port));
@@ -111,7 +113,7 @@ export async function runEvolve(opts) {
   const failed = [];
   try {
     for (const c of candidates) {
-      const verdict = await trialCandidate(c, { port, localKey: manifest.localKey });
+      const verdict = await trialCandidate(c, { port, localKey });
       if (verdict.ok) survivors.push(c);
       else failed.push({ key: c.key, why: verdict.why });
     }

package/src/commands/negentropy.js

@@ -7,6 +7,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { resolveSpardaKey } from '../generator/manifest.js';
 
 // same fingerprint the generators stamp into sparding.toolFingerprints —
 // method|path|params, sha256/8. Divergence = the route's shape changed.
@@ -191,17 +192,17 @@ export function buildNegentropy({ manifest, currentRoutes, live, detectedPort, c
         `${f} is recorded in sparda.json but absent on disk — the organism has a memory of a body it no longer has`,
         'npx sparda-mcp init --yes (regenerates; carry-over keeps your state)',
       );
-    } else if (
-      manifest.localKey &&
-      !fs.readFileSync(abs, 'utf8').includes(manifest.localKey)
-    ) {
-      add(
-        'zombie',
-        'high',
-        'router/manifest key mismatch',
-        `${f} does not carry the manifest's localKey — a stale router from an older init is still wired in`,
-        'npx sparda-mcp init --yes',
-      );
+    } else {
+      const key = resolveSpardaKey(cwd, manifest);
+      if (key && !fs.readFileSync(abs, 'utf8').includes(key)) {
+        add(
+          'zombie',
+          'high',
+          'router/manifest key mismatch',
+          `${f} does not carry the manifest's localKey — a stale router from an older init is still wired in`,
+          'npx sparda-mcp init --yes',
+        );
+      }
     }
   }
 

package/src/commands/report.js

@@ -6,6 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { c, gradient } from '../ui/style.js';
+import { resolveSpardaKey } from '../generator/manifest.js';
 
 // ── pure: manifest (+ optional live stats) → report data ──────────────────
 
@@ -342,9 +343,10 @@ export async function runReport(opts) {
   }
 
   let live = null;
-  if (manifest.port && manifest.localKey) {
+  const key = resolveSpardaKey(opts.cwd, manifest);
+  if (manifest.port && key) {
     live = await fetch(`http://127.0.0.1:${manifest.port}/mcp/stats`, {
-      headers: { 'x-sparda-key': manifest.localKey },
+      headers: { 'x-sparda-key': key },
       signal: AbortSignal.timeout(1500),
     })
       .then((x) => (x.ok ? x.json() : null))

package/src/commands/twin.js

@@ -13,6 +13,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import http from 'node:http';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+import { resolveSpardaKey } from '../generator/manifest.js';
 
 const EXEMPLAR_CAP = 16384; // 16KB per exemplar — a shape, not an archive
 
@@ -26,7 +27,14 @@ export function eligibleForLearning(tool) {
   return tool.enabled && tool.method === 'GET' && (tool.pathParams ?? []).length === 0;
 }
 
-export async function learnExemplars(manifest, fetchFn = fetch) {
+export async function learnExemplars(manifest, localKey, fetchFn = fetch) {
+  let key = localKey;
+  if (typeof localKey === 'function') {
+    fetchFn = localKey;
+    key = undefined;
+  }
+  key = key ?? manifest.localKey ?? resolveSpardaKey(process.cwd(), manifest);
+
   const exemplars = {};
   const skipped = [];
   for (const [name, t] of Object.entries(manifest.tools ?? {})) {
@@ -46,7 +54,7 @@ export async function learnExemplars(manifest, fetchFn = fetch) {
         method: 'POST',
         headers: {
           'content-type': 'application/json',
-          'x-sparda-key': manifest.localKey,
+          'x-sparda-key': key,
         },
         body: JSON.stringify({ tool: name, args: {} }),
         signal: AbortSignal.timeout(10_000),
@@ -83,13 +91,23 @@ function matchTool(manifest, method, pathname) {
   return null;
 }
 
-export function createTwinServer(manifest, exemplars) {
+export function createTwinServer(manifest, localKeyOrExemplars, maybeExemplars) {
+  let localKey = localKeyOrExemplars;
+  let exemplars = maybeExemplars;
+  if (
+    maybeExemplars === undefined &&
+    localKeyOrExemplars &&
+    typeof localKeyOrExemplars === 'object'
+  ) {
+    exemplars = localKeyOrExemplars;
+    localKey = resolveSpardaKey(process.cwd(), manifest);
+  }
   const json = (res, status, obj) => {
     res.writeHead(status, { 'content-type': 'application/json' });
     res.end(JSON.stringify(obj));
   };
   const answerFor = (name) =>
-    exemplars[name]?.data !== undefined
+    (exemplars ?? {})[name]?.data !== undefined
       ? exemplars[name].data
       : {
           __sparda_twin__: true,
@@ -103,7 +121,7 @@ export function createTwinServer(manifest, exemplars) {
 
     // the /mcp surface, so the unchanged bridge drives the ghost
     if (pathname.startsWith('/mcp')) {
-      if (req.headers['x-sparda-key'] !== manifest.localKey)
+      if (req.headers['x-sparda-key'] !== localKey)
         return json(res, 401, { error: 'unauthorized' });
       if (pathname === '/mcp/tools') return json(res, 200, manifest.tools ?? {});
       if (pathname === '/mcp/stats')
@@ -178,13 +196,14 @@ export async function runTwin(opts, args) {
     });
   }
   const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const localKey = resolveSpardaKey(opts.cwd, manifest);
   const twinPath = twinFilePath(opts.cwd);
 
   if (args.includes('--learn') || opts.learn) {
     console.error(
       '[sparda] twin: learning from the LIVE app (one call per eligible GET)...',
     );
-    const { exemplars, skipped } = await learnExemplars(manifest);
+    const { exemplars, skipped } = await learnExemplars(manifest, localKey);
     const learned = Object.keys(exemplars).length;
     if (!learned && skipped.every((s) => s.reason.startsWith('unreachable'))) {
       throw Object.assign(
@@ -222,7 +241,7 @@ export async function runTwin(opts, args) {
     }
   }
   const port = Number(opts.port) || manifest.port;
-  const server = createTwinServer(manifest, exemplars);
+  const server = createTwinServer(manifest, localKey, exemplars);
   await new Promise((resolve, reject) => {
     server.once('error', reject);
     server.listen(port, '127.0.0.1', resolve);

package/src/commands/ubg.js

@@ -0,0 +1,71 @@
+// commands/ubg.js — compile the codebase to its Unified Behavior Graph.
+// The UBG is the IR every future SPARDA tool reads (time-travel debuggers,
+// deploy provers, state-machine runtimes): compile once here, write passes
+// there. Artifact: .sparda/ubg.json — regenerable, deterministic, never
+// committed. `--json` prints the raw graph, `--out <file>` redirects it.
+import { compileUBG } from '../ubg/compile.js';
+
+export async function runUbg(opts) {
+  const { report, json, outPath } = compileUBG(opts.cwd, {
+    write: true,
+    out: opts.out,
+  });
+
+  if (opts.json) {
+    console.log(json);
+    return { report };
+  }
+
+  const { counts } = report;
+  console.log(
+    `✓ UBG compiled: ${rel(outPath, opts.cwd)} — ${counts.totalNodes} nodes, ${counts.totalEdges} edges`,
+  );
+  console.log(
+    `  ${report.framework} · ${report.routes} routes · ${report.tables} SQL tables`,
+  );
+  console.log(`  Nodes: ${fmtCounts(counts.nodes)}`);
+  console.log(`  Edges: ${fmtCounts(counts.edges)}`);
+
+  for (const p of report.passes) {
+    if (p.pass === 'DeadPathElimination' && p.removed)
+      console.log(`  ${p.pass}: ${p.removed} dead node(s) removed`);
+    else if (p.pass === 'StateMinimization' && p.merged)
+      console.log(`  ${p.pass}: ${p.merged} logic block(s) merged`);
+    else if (p.pass === 'TypePropagation' && (p.resolved || p.entrypointsTyped))
+      console.log(
+        `  ${p.pass}: ${p.entrypointsTyped} entrypoint return schema(s), ${p.resolved} type(s) resolved`,
+      );
+    else if (p.pass === 'EffectAlgebra' && p.classified)
+      console.log(
+        `  ${p.pass}: ${p.classified} effect(s) classified, ${p.observable} observable`,
+      );
+    else if (p.pass === 'ConsistencyDomains' && Object.keys(p.domains ?? {}).length) {
+      const names = Object.keys(p.domains).sort();
+      console.log(
+        `  ${p.pass}: ${names.length} domain(s) — ${names.join(', ')}${p.cycles.length ? ` (⚠ FK cycle: ${p.cycles.join(', ')})` : ''}`,
+      );
+    }
+  }
+
+  if (report.link.inferredTables.length)
+    console.log(
+      `  ⚠ tables referenced in code but absent from .sql schemas: ${report.link.inferredTables.join(', ')}`,
+    );
+  if (report.skipped.length) {
+    console.log(`  · ${report.skipped.length} construct(s) out of static reach:`);
+    for (const s of report.skipped.slice(0, opts.verbose ? 100 : 5))
+      console.log(`    - ${s.reason}${s.file ? ` (${s.file})` : ''}`);
+    if (!opts.verbose && report.skipped.length > 5)
+      console.log(`    … ${report.skipped.length - 5} more (--verbose)`);
+  }
+  return { report };
+}
+
+const fmtCounts = (obj) =>
+  Object.entries(obj)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, v]) => `${k} ${v}`)
+    .join(' · ');
+
+const rel = (abs, cwd) =>
+  abs.startsWith(cwd) ? abs.slice(cwd.length + 1).replaceAll('\\', '/') : abs;

package/src/generator/express.js

@@ -5,7 +5,7 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { parse } from '@babel/parser';
 import { toolNameFor } from '../parser/express.js';
-import { carryOverManifest, defaultSpardingMemory } from './manifest.js';
+import { carryOverManifest, defaultSpardingMemory, ensureSpardaKey } from './manifest.js';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -58,7 +58,7 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
   sparding.toolFingerprints = newFingerprints;
 
   // stable across re-runs so a running bridge/host pair never desyncs
-  const localKey = prev?.localKey ?? crypto.randomUUID();
+  const localKey = ensureSpardaKey(cwd, prev);
   const entryAbs = path.resolve(cwd, entryFile);
   const entryDir = path.dirname(entryAbs);
   const ext = entryFile.endsWith('.ts')
@@ -111,7 +111,10 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
     )
     .replace('__JSON_MW__', "express.json({ limit: '64kb' })")
     .replace('__TOOLS_JSON__', JSON.stringify(tools, null, 2))
-    .replace('__LOCAL_KEY__', localKey)
+    .replace(
+      '__FS_IMPORT__',
+      isESM ? "import spardaFs from 'node:fs';" : "const spardaFs = require('node:fs');",
+    )
     .replace('__PORT__', String(port))
     .replace(/__REQ_TYPE__/g, reqType)
     .replace(/__RES_TYPE__/g, resType)
@@ -150,7 +153,15 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
     ...(prev?.labs ? { labs: prev.labs } : {}),
     sparding,
   };
-  atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
+  // ADR-022: the disk copy NEVER carries the key — it lives in .sparda/key
+  // (written by ensureSpardaKey above). The in-memory return keeps it for
+  // this process only.
+  const manifestOnDisk = { ...manifest };
+  delete manifestOnDisk.localKey;
+  atomicWrite(
+    path.join(cwd, 'sparda.json'),
+    JSON.stringify(manifestOnDisk, null, 2) + '\n',
+  );
 
   return {
     tools,

package/src/generator/fastapi.js

@@ -5,7 +5,7 @@ import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { toolNameFor } from '../parser/express.js';
-import { carryOverManifest, defaultSpardingMemory } from './manifest.js';
+import { carryOverManifest, defaultSpardingMemory, ensureSpardaKey } from './manifest.js';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -65,7 +65,7 @@ export function generateFastAPI({
   sparding.toolFingerprints = newFingerprints;
 
   // stable across re-runs so a running bridge/host pair never desyncs
-  const localKey = prev?.localKey ?? crypto.randomUUID();
+  const localKey = ensureSpardaKey(cwd, prev);
   const entryAbs = path.resolve(cwd, entryFile);
   const entryDir = path.dirname(entryAbs);
   const routerFileName = 'sparda_router.py';
@@ -84,7 +84,6 @@ export function generateFastAPI({
       '__SPARDING_POLICIES__',
       JSON.stringify(JSON.stringify(sparding.policies ?? {})),
     )
-    .replace('__LOCAL_KEY__', localKey)
     .replace('__PORT__', String(port));
 
   atomicWrite(routerAbs, tpl);
@@ -124,7 +123,15 @@ export function generateFastAPI({
     sparding,
   };
 
-  atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
+  // ADR-022: the disk copy NEVER carries the key — it lives in .sparda/key
+  // (written by ensureSpardaKey above). The in-memory return keeps it for
+  // this process only.
+  const manifestOnDisk = { ...manifest };
+  delete manifestOnDisk.localKey;
+  atomicWrite(
+    path.join(cwd, 'sparda.json'),
+    JSON.stringify(manifestOnDisk, null, 2) + '\n',
+  );
 
   return {
     tools,

package/src/generator/manifest.js

@@ -1,6 +1,40 @@
 // generator/manifest.js — carry user state across re-runs of `sparda init`
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
+
+export function resolveSpardaKey(cwd, prevManifest = null) {
+  if (process.env.SPARDA_LOCAL_KEY) {
+    return process.env.SPARDA_LOCAL_KEY;
+  }
+  const spardaDir = path.join(cwd, '.sparda');
+  const keyFile = path.join(spardaDir, 'key');
+  if (fs.existsSync(keyFile)) {
+    try {
+      const key = fs.readFileSync(keyFile, 'utf8').trim();
+      if (key) return key;
+    } catch {}
+  }
+  if (prevManifest && prevManifest.localKey) {
+    try {
+      fs.mkdirSync(spardaDir, { recursive: true });
+      fs.writeFileSync(keyFile, prevManifest.localKey, 'utf8');
+    } catch {}
+    return prevManifest.localKey;
+  }
+  return null;
+}
+
+export function ensureSpardaKey(cwd, prevManifest = null) {
+  let key = resolveSpardaKey(cwd, prevManifest);
+  if (!key) {
+    key = crypto.randomUUID();
+    const spardaDir = path.join(cwd, '.sparda');
+    fs.mkdirSync(spardaDir, { recursive: true });
+    fs.writeFileSync(path.join(spardaDir, 'key'), key, 'utf8');
+  }
+  return key;
+}
 
 // Re-running init must not wipe what the user (or the semantic/immune/Labs
 // passes) wrote into sparda.json: per-tool `enabled` overrides, the cached

package/src/generator/nextjs.js

@@ -9,7 +9,7 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { toolNameFor } from '../parser/express.js';
 import { ensureGitignore } from './express.js';
-import { carryOverManifest, defaultSpardingMemory } from './manifest.js';
+import { carryOverManifest, defaultSpardingMemory, ensureSpardaKey } from './manifest.js';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -60,7 +60,7 @@ export function generateNext({ cwd, appDir, port, routes }) {
   sparding.toolFingerprints = newFingerprints;
 
   // stable across re-runs so a running bridge/host pair never desyncs
-  const localKey = prev?.localKey ?? crypto.randomUUID();
+  const localKey = ensureSpardaKey(cwd, prev);
 
   // .js on purpose: Next enables allowJs in the tsconfig it manages, so the
   // generated handler compiles untouched inside TS projects too.
@@ -75,7 +75,6 @@ export function generateNext({ cwd, appDir, port, routes }) {
   tpl = tpl
     .replace('__TOOLS_JSON__', JSON.stringify(tools, null, 2))
     .replace('__SPARDING_POLICIES__', JSON.stringify(sparding.policies ?? {}))
-    .replace('__LOCAL_KEY__', localKey)
     .replace('__PORT__', String(port));
   atomicWrite(routerAbs, tpl);
 
@@ -102,7 +101,15 @@ export function generateNext({ cwd, appDir, port, routes }) {
     ...(prev?.labs ? { labs: prev.labs } : {}),
     sparding,
   };
-  atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
+  // ADR-022: the disk copy NEVER carries the key — it lives in .sparda/key
+  // (written by ensureSpardaKey above). The in-memory return keeps it for
+  // this process only.
+  const manifestOnDisk = { ...manifest };
+  delete manifestOnDisk.localKey;
+  atomicWrite(
+    path.join(cwd, 'sparda.json'),
+    JSON.stringify(manifestOnDisk, null, 2) + '\n',
+  );
 
   return {
     tools,

package/src/index.js

@@ -94,6 +94,11 @@ try {
       await runEvolve(opts);
       break;
     }
+    case 'ubg': {
+      const { runUbg } = await import('./commands/ubg.js');
+      await runUbg(opts);
+      break;
+    }
     default:
       console.log(`SPARDA v${VERSION} — Turn any codebase into an MCP server.
 
@@ -110,6 +115,7 @@ Usage:
   npx sparda-mcp twin      The living mock (--learn from the live app, then serve the ghost)
   npx sparda-mcp grammar   Which call sequences mean something (observed + hypotheses)
   npx sparda-mcp evolve    Trial hypothesis chains against the twin; survivors become suggestions
+  npx sparda-mcp ubg       Compile the codebase to its Unified Behavior Graph (.sparda/ubg.json)
 
 Flags: --yes (skip prompts)  --port <n>  --quiet  --verbose
        --probe (init: also run the app to discover dynamic routes the AST missed)

package/src/server/stdio.js

@@ -25,6 +25,7 @@ import { writeManifestSync, mergeManifestKeySync } from './persistence.js';
 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';
 
 const EVENT_POLL_MS = Number(process.env.SPARDA_EVENT_POLL_MS ?? 5000);
 // the sampling budgets below are also what the recycling gauge counts as "avoided"
@@ -61,11 +62,11 @@ export async function startStdioBridge({ cwd, portOverride }) {
   }
   const port = Number(portOverride ?? manifest.port);
   const framework = manifest.framework;
-  const key = manifest.localKey;
+  const key = resolveSpardaKey(cwd, manifest);
   if (!key) {
-    throw Object.assign(new Error('localKey missing from sparda.json.'), {
+    throw Object.assign(new Error('localKey missing or not configured.'), {
       code: 'USER',
-      hint: 'Re-run `npx sparda-mcp init` to regenerate it.',
+      hint: 'Re-run `npx sparda-mcp init` to generate it, or set SPARDA_LOCAL_KEY.',
     });
   }