sparda-mcp 0.8.0 → 0.8.1

package/README.md

@@ -107,6 +107,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
 

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.8.1",
   "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/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/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.',
     });
   }
 

package/templates/express-router.txt

@@ -7,7 +7,21 @@ __IMPORT_LINE__
 const SPARDA_TOOLS = __TOOLS_JSON__;
 const SPARDA_POLICIES = __SPARDING_POLICIES__;
 
-const SPARDA_LOCAL_KEY = "__LOCAL_KEY__";
+// ADR-022: the key is NEVER baked into this committed file. It resolves at
+// runtime — env first, then the gitignored .sparda/key — and fails CLOSED:
+// no key, no /mcp surface. A deploy that ships without .sparda/ is inert.
+__FS_IMPORT__
+let SPARDA_LOCAL_KEY = process.env.SPARDA_LOCAL_KEY || null;
+if (!SPARDA_LOCAL_KEY) {
+  try {
+    for (const p of ['.sparda/key', '../.sparda/key', '../../.sparda/key']) {
+      if (spardaFs.existsSync(p)) {
+        SPARDA_LOCAL_KEY = spardaFs.readFileSync(p, 'utf8').trim() || null;
+        if (SPARDA_LOCAL_KEY) break;
+      }
+    }
+  } catch { /* stays null -> fail closed */ }
+}
 const SPARDA_PORT = __PORT__;
 
 const SPARDA_STATS__STATS_TYPE__ = {};
@@ -299,6 +313,9 @@ async function spardaExecute(tool__ANY_TYPE__, spec__ANY_TYPE__, args__ANY_TYPE_
 __ROUTER_DECL__
 
 spardaRouter.use((req__REQ_TYPE__, res__RES_TYPE__, next__NEXT_TYPE__) => {
+  if (!SPARDA_LOCAL_KEY) {
+    return res.status(503).json({ error: 'key not configured' });
+  }
   if (req.headers['x-sparda-key'] !== SPARDA_LOCAL_KEY) {
     return res.status(401).json({ error: 'unauthorized' });
   }

package/templates/fastapi-router.txt

@@ -19,7 +19,20 @@ import threading
 # json.loads, not a Python literal: JSON true/false/null are not valid Python (E-009)
 SPARDA_TOOLS = json.loads(__TOOLS_JSON__)
 SPARDA_POLICIES = json.loads(__SPARDING_POLICIES__)
-SPARDA_LOCAL_KEY = "__LOCAL_KEY__"
+# ADR-022: the key is NEVER baked into this committed file. It resolves at
+# runtime — env first, then the gitignored .sparda/key — and fails CLOSED:
+# no key, no /mcp surface. A deploy that ships without .sparda/ is inert.
+SPARDA_LOCAL_KEY = os.environ.get("SPARDA_LOCAL_KEY") or None
+if not SPARDA_LOCAL_KEY:
+    try:
+        for p in [".sparda/key", "../.sparda/key", "../../.sparda/key"]:
+            if os.path.exists(p):
+                with open(p, "r", encoding="utf-8") as f:
+                    SPARDA_LOCAL_KEY = f.read().strip() or None
+                if SPARDA_LOCAL_KEY:
+                    break
+    except Exception:
+        pass  # stays None -> fail closed
 SPARDA_PORT = __PORT__
 
 SPARDA_STATS = {}
@@ -363,18 +376,24 @@ async def sparda_read_json(request):
 
 @sparda_router.get("/tools")
 async def get_tools(request: Request):
+    if not SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=503, content={"error": "key not configured"})
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
     return SPARDA_TOOLS
 
 @sparda_router.get("/stats")
 async def get_stats(request: Request):
+    if not SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=503, content={"error": "key not configured"})
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
     return {"uptimeSec": round(time.time() - SPARDA_START), "stats": SPARDA_STATS, "quarantine": SPARDA_QUARANTINE, "recycle": {**SPARDA_RECYCLE, "ratePct": sparda_recycle_rate()}, "purity": sparda_purity_snapshot()}
 
 @sparda_router.get("/events")
 async def get_events(request: Request):
+    if not SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=503, content={"error": "key not configured"})
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
     try:
@@ -388,6 +407,8 @@ async def gossip(request: Request):
     # peer-to-peer convergence (Brief #2), behind the same x-sparda-key as every route.
     # Absorbs a peer's grow-only counts via CRDT max-merge; 204 on success. An unknown tool
     # or malformed count is silently dropped (bounded, no injection).
+    if not SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=503, content={"error": "key not configured"})
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
     body, err = await sparda_read_json(request)
@@ -398,6 +419,8 @@ async def gossip(request: Request):
 
 @sparda_router.post("/invoke")
 async def invoke_tool(request: Request):
+    if not SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=503, content={"error": "key not configured"})
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
 
@@ -543,6 +566,8 @@ async def invoke_tool(request: Request):
 
 @sparda_router.post("/invoke/confirm")
 async def confirm_tool_invocation(request: Request):
+    if not SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=503, content={"error": "key not configured"})
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
     

package/templates/nextjs-router.txt

@@ -8,7 +8,21 @@
 const SPARDA_TOOLS = __TOOLS_JSON__;
 const SPARDA_POLICIES = __SPARDING_POLICIES__;
 
-const SPARDA_LOCAL_KEY = "__LOCAL_KEY__";
+// ADR-022: the key is NEVER baked into this committed file. It resolves at
+// runtime — env first, then the gitignored .sparda/key — and fails CLOSED:
+// no key, no /mcp surface. A Vercel deploy that ships without .sparda/ is inert.
+import spardaFs from 'node:fs';
+let SPARDA_LOCAL_KEY = process.env.SPARDA_LOCAL_KEY || null;
+if (!SPARDA_LOCAL_KEY) {
+  try {
+    for (const p of ['.sparda/key', '../.sparda/key', '../../.sparda/key']) {
+      if (spardaFs.existsSync(p)) {
+        SPARDA_LOCAL_KEY = spardaFs.readFileSync(p, 'utf8').trim() || null;
+        if (SPARDA_LOCAL_KEY) break;
+      }
+    }
+  } catch { /* stays null -> fail closed */ }
+}
 const SPARDA_PORT = __PORT__;
 
 // never statically optimized, always on the Node.js runtime (process, timers)
@@ -336,6 +350,9 @@ async function spardaConfirm(request) {
 
 async function spardaHandle(request, ctx) {
   try {
+    if (!SPARDA_LOCAL_KEY) {
+      return spardaJson(503, { error: 'key not configured' });
+    }
     if (request.headers.get('x-sparda-key') !== SPARDA_LOCAL_KEY) {
       return spardaJson(401, { error: 'unauthorized' });
     }