sparda-mcp 0.7.0 → 0.8.0

package/README.md

@@ -105,6 +105,8 @@ What we *don't* promise: the honest limits in [docs/SECURITY.md](./docs/SECURITY
 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.
 
 ## What SPARDA gives your AI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.7.0",
+  "version": "0.8.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

@@ -59,14 +59,14 @@ export async function runDoctor(opts) {
         try {
           const r = await fetch(`http://127.0.0.1:${m.port}/mcp/tools`, {
             headers,
-            signal: AbortSignal.timeout(1500),
+            signal: AbortSignal.timeout(5000),
           });
           if (!r.ok) {
             fail(`  ✗ Host app on :${m.port} answered ${r.status}`);
           } else {
             const s = await fetch(`http://127.0.0.1:${m.port}/mcp/stats`, {
               headers,
-              signal: AbortSignal.timeout(1500),
+              signal: AbortSignal.timeout(5000),
             })
               .then((x) => (x.ok ? x.json() : null))
               .catch(() => null);

package/src/commands/evolve.js

@@ -0,0 +1,149 @@
+// commands/evolve.js — R3.4, Darwin/Baldwin: mutate candidate chains from the
+// grammar's hypotheses, trial them against the TWIN (never the host — ADR-021
+// §5), and let the survivors land as SUGGESTIONS: `labs.circuits` entries with
+// `seen: 0` and `evolved: true`. They are not composites and never become one
+// here — crystallization still demands the real observation threshold. An
+// emergent capability is a suggestion until reality confirms it (survival §1).
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildGrammar } from './grammar.js';
+import { createTwinServer, twinFilePath } from './twin.js';
+import { findByKey } from '../server/crystallize.js';
+import { mergeManifestKeySync } from '../server/persistence.js';
+
+const MAX_CANDIDATES_PER_RUN = 10;
+
+// pure: hypothesis edges that no observed circuit already covers → candidates
+export function candidateChains(grammar, circuits = {}) {
+  const out = [];
+  for (const e of grammar.edges ?? []) {
+    if (e.source !== 'hypothesis') continue;
+    const key = `${e.from}>${e.to}`;
+    if (circuits[key]) continue; // reality (or a past run) got there first
+    if (out.some((c) => c.key === key)) continue;
+    out.push({
+      key,
+      steps: [e.from, e.to],
+      links: [{ from: e.from, to: e.to, arg: e.arg, fromKey: e.fromKey }],
+    });
+    if (out.length >= MAX_CANDIDATES_PER_RUN) break;
+  }
+  return out;
+}
+
+// trial one candidate against a running twin: A answers, the linked key is
+// really there, B accepts the fed value. All against the ghost, never the host.
+export async function trialCandidate(candidate, { port, localKey }) {
+  const invoke = async (tool, args) => {
+    const res = await fetch(`http://127.0.0.1:${port}/mcp/invoke`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-sparda-key': localKey },
+      body: JSON.stringify({ tool, args }),
+      signal: AbortSignal.timeout(5000),
+    });
+    return res.json();
+  };
+  const [a, b] = candidate.steps;
+  const link = candidate.links[0];
+  const first = await invoke(a, {});
+  if (first?.upstreamStatus !== 200)
+    return { ok: false, why: `${a} answered ${first?.upstreamStatus}` };
+  const fed = findByKey(first.data, link.fromKey);
+  if (fed === undefined)
+    return { ok: false, why: `'${link.fromKey}' not found in ${a}'s exemplar` };
+  if (typeof fed === 'object')
+    return { ok: false, why: `'${link.fromKey}' is not a scalar` };
+  const second = await invoke(b, { [link.arg]: fed });
+  if (second?.upstreamStatus !== 200)
+    return { ok: false, why: `${b} answered ${second?.upstreamStatus}` };
+  return { ok: true, fedValueType: typeof fed };
+}
+
+export async function runEvolve(opts) {
+  const manifestPath = path.join(opts.cwd, 'sparda.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw Object.assign(new Error('sparda.json not found.'), {
+      code: 'USER',
+      hint: 'run `npx sparda-mcp init` first',
+    });
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+  const twinPath = twinFilePath(opts.cwd);
+  if (!fs.existsSync(twinPath)) {
+    throw Object.assign(
+      new Error(
+        'no twin memory (.sparda/twin.json) — evolution needs the ghost to practice on.',
+      ),
+      {
+        code: 'USER',
+        hint: 'run `npx sparda-mcp twin --learn` against the live app first',
+      },
+    );
+  }
+  let exemplars = {};
+  try {
+    exemplars = JSON.parse(fs.readFileSync(twinPath, 'utf8')).exemplars ?? {};
+  } catch {
+    throw Object.assign(new Error('.sparda/twin.json is not valid JSON.'), {
+      code: 'USER',
+      hint: 're-run `npx sparda-mcp twin --learn`',
+    });
+  }
+
+  const grammar = buildGrammar(manifest, exemplars);
+  const candidates = candidateChains(grammar, manifest.labs?.circuits ?? {});
+  if (!candidates.length) {
+    console.log(
+      '· Nothing to evolve — no untested hypothesis chains (grammar has no new guesses).',
+    );
+    return { survivors: [], failed: [] };
+  }
+
+  // the practice arena: an in-process twin on an ephemeral port
+  const server = createTwinServer(manifest, exemplars);
+  const port = await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve(server.address().port));
+  });
+
+  const survivors = [];
+  const failed = [];
+  try {
+    for (const c of candidates) {
+      const verdict = await trialCandidate(c, { port, localKey: manifest.localKey });
+      if (verdict.ok) survivors.push(c);
+      else failed.push({ key: c.key, why: verdict.why });
+    }
+  } finally {
+    server.close();
+  }
+
+  if (survivors.length) {
+    manifest.labs ??= {};
+    manifest.labs.circuits ??= {};
+    const now = new Date().toISOString();
+    for (const c of survivors) {
+      manifest.labs.circuits[c.key] = {
+        steps: c.steps,
+        links: c.links,
+        seen: 0, // heredity without confirmation: reality still has to speak
+        evolved: true,
+        firstSeen: now,
+        lastSeen: now,
+      };
+    }
+    mergeManifestKeySync(manifestPath, 'labs', manifest.labs);
+  }
+
+  console.log(
+    `✓ Evolution run: ${candidates.length} candidate(s) trialed against the twin — ${survivors.length} survivor(s), ${failed.length} culled`,
+  );
+  for (const c of survivors)
+    console.log(
+      `  + suggested circuit: ${c.steps.join(' → ')} (seen: 0 — crystallizes only after real observations)`,
+    );
+  for (const f of failed) console.log(`  - culled ${f.key}: ${f.why}`);
+  console.log('  The host was never touched: every trial ran against the ghost.');
+  return { survivors, failed };
+}

package/src/commands/grammar.js

@@ -0,0 +1,138 @@
+// commands/grammar.js — R3.3, the Rosetta stone: which call sequences MEAN
+// something in this app. Derived, deterministic, never authoritative
+// (ADR-021 §4): observed edges come from Labs circuits (real data flows seen
+// N times); hypothesis edges come from twin exemplar response keys matching
+// another tool's param names — always labelled, never acted on by themselves.
+// The artifact lives in .sparda/grammar.json (regenerable, never committed).
+import fs from 'node:fs';
+import path from 'node:path';
+import { walkPayload } from '../server/condenser.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+import { twinFilePath } from './twin.js';
+
+const MAX_HYPOTHESES = 50;
+const GRAMMAR_VERSION = 'sparda-grammar/v1';
+
+// bounded key harvest — same walk the condenser trusts, so what the grammar
+// hypothesizes is exactly what a composite could later re-feed
+export function responseKeysOf(exemplarData) {
+  const keys = new Set();
+  walkPayload(exemplarData, (k) => {
+    keys.add(k);
+    if (keys.size >= 40) return false;
+  });
+  return keys;
+}
+
+// pure: (manifest, exemplars|null) → the grammar
+export function buildGrammar(manifest, exemplars = null) {
+  const tools = manifest.tools ?? {};
+  const edges = [];
+  const seenEdge = new Set();
+  const edgeKey = (e) => `${e.from}>${e.to}:${e.arg}`;
+
+  // observed: the circuits ARE the sentences reality already spoke
+  const phrases = [];
+  for (const [key, cir] of Object.entries(manifest.labs?.circuits ?? {})) {
+    phrases.push({
+      key,
+      steps: cir.steps ?? [],
+      seen: cir.seen ?? 0,
+      crystallized: Boolean(cir.composite),
+      ...(cir.evolved ? { evolved: true } : {}),
+    });
+    for (const l of cir.links ?? []) {
+      const e = {
+        from: l.from,
+        to: l.to,
+        fromKey: l.fromKey,
+        arg: l.arg,
+        source: 'observed',
+      };
+      if (!seenEdge.has(edgeKey(e))) {
+        seenEdge.add(edgeKey(e));
+        edges.push(e);
+      }
+    }
+  }
+
+  // hypotheses: an exemplar of A answers with a key another tool B takes as a
+  // param → maybe A feeds B. A guess, said out loud as a guess.
+  if (exemplars) {
+    for (const [from, ex] of Object.entries(exemplars)) {
+      if (!tools[from] || ex?.data === undefined) continue;
+      const keys = responseKeysOf(ex.data);
+      for (const [to, t] of Object.entries(tools)) {
+        if (to === from || !t.enabled || t.method !== 'GET') continue;
+        for (const p of t.params ?? []) {
+          if (edges.length >= MAX_HYPOTHESES + seenEdge.size) break;
+          if (!keys.has(p.name)) continue;
+          const e = { from, to, fromKey: p.name, arg: p.name, source: 'hypothesis' };
+          if (seenEdge.has(edgeKey(e))) continue; // reality already confirmed it
+          seenEdge.add(edgeKey(e));
+          edges.push(e);
+        }
+      }
+    }
+  }
+
+  return {
+    version: GRAMMAR_VERSION,
+    builtAt: new Date().toISOString(),
+    nodes: Object.keys(tools),
+    edges,
+    phrases,
+  };
+}
+
+export async function runGrammar(opts) {
+  const manifestPath = path.join(opts.cwd, 'sparda.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw Object.assign(new Error('sparda.json not found.'), {
+      code: 'USER',
+      hint: 'run `npx sparda-mcp init` first',
+    });
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+  let exemplars = null;
+  const twinPath = twinFilePath(opts.cwd);
+  if (fs.existsSync(twinPath)) {
+    try {
+      exemplars = JSON.parse(fs.readFileSync(twinPath, 'utf8')).exemplars ?? null;
+    } catch {
+      exemplars = null;
+    }
+  }
+
+  const grammar = buildGrammar(manifest, exemplars);
+  const outPath = path.join(opts.cwd, '.sparda', 'grammar.json');
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  atomicWrite(outPath, JSON.stringify(grammar, null, 2) + '\n');
+
+  const observed = grammar.edges.filter((e) => e.source === 'observed');
+  const hypotheses = grammar.edges.filter((e) => e.source === 'hypothesis');
+  console.log(`✓ Grammar written: .sparda/grammar.json — ${grammar.nodes.length} tools`);
+  if (grammar.phrases.length) {
+    console.log(`  Sentences reality has spoken (${grammar.phrases.length}):`);
+    for (const p of grammar.phrases.slice(0, 10))
+      console.log(
+        `    ${p.steps.join(' → ')} ×${p.seen}${p.crystallized ? ' (crystallized)' : ''}${p.evolved ? ' (evolved, unconfirmed)' : ''}`,
+      );
+  } else
+    console.log(
+      '  · no sentences observed yet — enable labs.recordSequences and use the app',
+    );
+  if (observed.length) console.log(`  Observed data flows: ${observed.length}`);
+  if (hypotheses.length) {
+    console.log(
+      `  Hypotheses from twin exemplars (${hypotheses.length}) — guesses, said as guesses:`,
+    );
+    for (const e of hypotheses.slice(0, 10))
+      console.log(`    ${e.from} —'${e.fromKey}'→ ${e.to}`);
+  } else if (!exemplars)
+    console.log(
+      '  · no hypotheses — run `sparda twin --learn` first to give the grammar eyes',
+    );
+  return { grammar };
+}

package/src/commands/seed.js

@@ -272,6 +272,26 @@ export async function runSeed(opts, args) {
     console.log(
       '  Local knowledge always wins; keys, policies and enabled flags were never read.',
     );
+    // R4.5 full — germination: the derived organs regrow from the imported
+    // structure on THIS machine (values never travelled; they never do).
+    if (opts.germinate) {
+      const { buildGrammar } = await import('./grammar.js');
+      const { twinFilePath } = await import('./twin.js');
+      let exemplars = null;
+      try {
+        exemplars =
+          JSON.parse(fs.readFileSync(twinFilePath(opts.cwd), 'utf8')).exemplars ?? null;
+      } catch {
+        exemplars = null; // no local twin memory yet — grammar grows from structure alone
+      }
+      const grammar = buildGrammar(merged, exemplars);
+      const outPath = path.join(opts.cwd, '.sparda', 'grammar.json');
+      fs.mkdirSync(path.dirname(outPath), { recursive: true });
+      atomicWrite(outPath, JSON.stringify(grammar, null, 2) + '\n');
+      console.log(
+        `✓ Germinated: grammar regrown from the imported genome (${grammar.phrases.length} phrases, ${grammar.edges.length} edges) → .sparda/grammar.json`,
+      );
+    }
     return { report };
   }
 

package/src/commands/twin.js

@@ -0,0 +1,247 @@
+// commands/twin.js — R3.2, the holographic principle: reconstruct a living
+// mock of the app from its boundary (manifest structure + observed I/O).
+//
+// Two verbs, one value boundary (ADR-021):
+//   sparda twin --learn   asks the LIVE router once per eligible GET tool and
+//                         stores capped exemplars in .sparda/twin.json —
+//                         machine-local, gitignored, never the manifest.
+//   sparda twin           serves the clone: same routes, same /mcp surface,
+//                         answered from exemplars. Writes return 202 echoes
+//                         and touch nothing. Stop the app, run the twin, and
+//                         every agent exercises a ghost instead of the truth.
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+const EXEMPLAR_CAP = 16384; // 16KB per exemplar — a shape, not an archive
+
+export function twinFilePath(cwd) {
+  return path.join(cwd, '.sparda', 'twin.json');
+}
+
+// ── learn: one real call per eligible tool, through the live router ────────
+
+export function eligibleForLearning(tool) {
+  return tool.enabled && tool.method === 'GET' && (tool.pathParams ?? []).length === 0;
+}
+
+export async function learnExemplars(manifest, fetchFn = fetch) {
+  const exemplars = {};
+  const skipped = [];
+  for (const [name, t] of Object.entries(manifest.tools ?? {})) {
+    if (!eligibleForLearning(t)) {
+      skipped.push({
+        tool: name,
+        reason: !t.enabled
+          ? 'disabled'
+          : t.method !== 'GET'
+            ? 'write tool — a twin never learns from side effects'
+            : 'required path params — no observed values to fill them (v0.1)',
+      });
+      continue;
+    }
+    try {
+      const res = await fetchFn(`http://127.0.0.1:${manifest.port}/mcp/invoke`, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'x-sparda-key': manifest.localKey,
+        },
+        body: JSON.stringify({ tool: name, args: {} }),
+        signal: AbortSignal.timeout(10_000),
+      });
+      const payload = await res.json();
+      if (payload?.upstreamStatus === 200 && payload.data !== undefined) {
+        const raw = JSON.stringify(payload.data);
+        if (raw.length <= EXEMPLAR_CAP) {
+          exemplars[name] = { data: payload.data, learnedAt: new Date().toISOString() };
+        } else {
+          skipped.push({ tool: name, reason: `response over ${EXEMPLAR_CAP}B cap` });
+        }
+      } else {
+        skipped.push({
+          tool: name,
+          reason: `live call answered ${payload?.upstreamStatus ?? res.status}`,
+        });
+      }
+    } catch (err) {
+      skipped.push({ tool: name, reason: `unreachable: ${err.message}` });
+    }
+  }
+  return { exemplars, skipped };
+}
+
+// ── serve: the ghost — same routes, same /mcp surface, zero side effects ───
+
+function matchTool(manifest, method, pathname) {
+  for (const [name, t] of Object.entries(manifest.tools ?? {})) {
+    if (t.method !== method) continue;
+    const pattern = t.path.replace(/:(\w+)/g, '([^/]+)');
+    if (new RegExp(`^${pattern}$`).test(pathname)) return { name, tool: t };
+  }
+  return null;
+}
+
+export function createTwinServer(manifest, exemplars) {
+  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
+      : {
+          __sparda_twin__: true,
+          tool: name,
+          note: 'no exemplar learned — run `sparda twin --learn` against the live app',
+        };
+
+  return http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    const pathname = url.pathname;
+
+    // the /mcp surface, so the unchanged bridge drives the ghost
+    if (pathname.startsWith('/mcp')) {
+      if (req.headers['x-sparda-key'] !== manifest.localKey)
+        return json(res, 401, { error: 'unauthorized' });
+      if (pathname === '/mcp/tools') return json(res, 200, manifest.tools ?? {});
+      if (pathname === '/mcp/stats')
+        return json(res, 200, {
+          twin: true,
+          uptimeSec: Math.round(process.uptime()),
+          stats: {},
+          quarantine: {},
+          recycle: { servedByCircle: 0, paidFull: 0, ratePct: 0 },
+          purity: {},
+        });
+      if (pathname === '/mcp/events')
+        return json(res, 200, { seq: 0, events: [], twin: true });
+      if (pathname === '/mcp/invoke' && req.method === 'POST') {
+        let body = '';
+        for await (const chunk of req) {
+          body += chunk;
+          if (body.length > 65536) return json(res, 413, { error: 'payload too large' });
+        }
+        let parsed;
+        try {
+          parsed = JSON.parse(body || '{}');
+        } catch {
+          return json(res, 400, { error: 'invalid JSON body' });
+        }
+        const spec = manifest.tools?.[parsed.tool];
+        if (!spec)
+          return json(res, 404, { error: `unknown tool: ${parsed.tool}`, twin: true });
+        if (spec.method !== 'GET')
+          return json(res, 200, {
+            upstreamStatus: 202,
+            data: {
+              __sparda_twin__: true,
+              echo: parsed.args ?? {},
+              note: 'twin: write acknowledged, nothing was touched',
+            },
+            twin: true,
+          });
+        return json(res, 200, {
+          upstreamStatus: 200,
+          data: answerFor(parsed.tool),
+          twin: true,
+        });
+      }
+      return json(res, 404, { error: 'not found', twin: true });
+    }
+
+    // the plain routes themselves, for anything that talks HTTP directly
+    const hit = matchTool(manifest, req.method, pathname);
+    if (!hit)
+      return json(res, 404, {
+        __sparda_twin__: true,
+        error: 'route not in the manifest',
+      });
+    if (hit.tool.method !== 'GET')
+      return json(res, 202, {
+        __sparda_twin__: true,
+        note: 'twin: write acknowledged, nothing was touched',
+      });
+    return json(res, 200, answerFor(hit.name));
+  });
+}
+
+// ── the command ─────────────────────────────────────────────────────────────
+
+export async function runTwin(opts, args) {
+  const manifestPath = path.join(opts.cwd, 'sparda.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw Object.assign(new Error('sparda.json not found.'), {
+      code: 'USER',
+      hint: 'run `npx sparda-mcp init` first',
+    });
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  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 learned = Object.keys(exemplars).length;
+    if (!learned && skipped.every((s) => s.reason.startsWith('unreachable'))) {
+      throw Object.assign(
+        new Error(
+          `host unreachable on :${manifest.port} — the twin learns from the living.`,
+        ),
+        {
+          code: 'USER',
+          hint: 'start the app, then re-run `npx sparda-mcp twin --learn`',
+        },
+      );
+    }
+    fs.mkdirSync(path.dirname(twinPath), { recursive: true });
+    atomicWrite(
+      twinPath,
+      JSON.stringify(
+        { version: 'sparda-twin/v1', learnedAt: new Date().toISOString(), exemplars },
+        null,
+        2,
+      ),
+    );
+    console.log(
+      `✓ Twin learned ${learned} exemplar(s) → .sparda/twin.json (local only, never committed, never seeded)`,
+    );
+    for (const s of skipped) console.log(`  · skipped ${s.tool}: ${s.reason}`);
+    return { learned, skipped };
+  }
+
+  let exemplars = {};
+  if (fs.existsSync(twinPath)) {
+    try {
+      exemplars = JSON.parse(fs.readFileSync(twinPath, 'utf8')).exemplars ?? {};
+    } catch {
+      /* corrupt twin file → shape-only ghost, stated per answer */
+    }
+  }
+  const port = Number(opts.port) || manifest.port;
+  const server = createTwinServer(manifest, exemplars);
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', resolve);
+  }).catch((err) => {
+    throw Object.assign(
+      new Error(
+        `cannot listen on :${port} — ${err.code === 'EADDRINUSE' ? 'the real app is still running there' : err.message}`,
+      ),
+      {
+        code: 'USER',
+        hint: 'stop the app first (the twin replaces it), or pass --port <n>',
+      },
+    );
+  });
+  console.log(
+    `✓ Twin serving on :${port} — ${Object.keys(exemplars).length} exemplar(s), writes are 202 echoes, the real app is untouched`,
+  );
+  console.log(
+    '  Connect the bridge as usual (`npx sparda-mcp dev`) — it cannot tell the ghost from the flesh.',
+  );
+  return { server, port };
+}

package/src/index.js

@@ -21,6 +21,8 @@ const opts = {
   html: flags.has('--html'),
   json: flags.has('--json'),
   app: flags.has('--app'),
+  learn: flags.has('--learn'),
+  germinate: flags.has('--germinate'),
   port: getOpt('port', null),
   out: getOpt('out', null),
   cwd: process.cwd(),
@@ -77,6 +79,21 @@ try {
       );
       break;
     }
+    case 'twin': {
+      const { runTwin } = await import('./commands/twin.js');
+      await runTwin(opts, rest);
+      break;
+    }
+    case 'grammar': {
+      const { runGrammar } = await import('./commands/grammar.js');
+      await runGrammar(opts);
+      break;
+    }
+    case 'evolve': {
+      const { runEvolve } = await import('./commands/evolve.js');
+      await runEvolve(opts);
+      break;
+    }
     default:
       console.log(`SPARDA v${VERSION} — Turn any codebase into an MCP server.
 
@@ -89,7 +106,10 @@ Usage:
   npx sparda-mcp remove    Remove SPARDA from this project (clean git diff)
   npx sparda-mcp doctor    Diagnose your setup (--app: negentropy scan — drift, dead routes, rot)
   npx sparda-mcp report    The black box: what AI agents did to this app
-  npx sparda-mcp seed      Export/import the learned genome (export [--out f] | import <f>)
+  npx sparda-mcp seed      Export/import the learned genome (export [--out f] | import <f> [--germinate])
+  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
 
 Flags: --yes (skip prompts)  --port <n>  --quiet  --verbose
        --probe (init: also run the app to discover dynamic routes the AST missed)

package/src/server/crystallize.js

@@ -32,6 +32,112 @@ export function fallbackComposite(circuit) {
   };
 }
 
+// ── R2.4: nothing disappears, x becomes y ──────────────────────────────────
+// Tool names derive from method+path, so a renamed route means a vanished step
+// name. Instead of letting the composite die silently at wake-up, we look for
+// the step's UNIQUE deterministic successor: an enabled GET whose name keeps
+// the old name's segments in order (api_users ⊂ api_v2_users) and ends on the
+// same resource segment. One candidate → re-map; zero or many → dormant with a
+// recorded reason. Never a guess: ambiguity is a reason, not a coin flip.
+
+function nameSegments(toolName) {
+  const parts = String(toolName).split('_');
+  return ['get', 'post', 'put', 'patch', 'delete'].includes(parts[0])
+    ? parts.slice(1)
+    : parts;
+}
+
+function isSubsequence(small, big) {
+  let i = 0;
+  for (const seg of big) if (seg === small[i]) i++;
+  return i === small.length;
+}
+
+export function successorFor(oldName, toolSpecs, exclude = new Set()) {
+  const oldSegs = nameSegments(oldName);
+  if (!oldSegs.length) return null;
+  const last = oldSegs[oldSegs.length - 1];
+  const candidates = Object.entries(toolSpecs)
+    .filter(([name, t]) => {
+      if (exclude.has(name) || !t.enabled || t.method !== 'GET') return false;
+      const segs = nameSegments(name);
+      return segs[segs.length - 1] === last && isSubsequence(oldSegs, segs);
+    })
+    .map(([name]) => name);
+  return candidates.length === 1 ? candidates[0] : null;
+}
+
+// (circuits map, today's tools) → what survives, what becomes, what sleeps.
+// Pure: never mutates the input; the caller decides what to persist.
+export function remapComposites(circuits, toolSpecs) {
+  const remapped = [];
+  const dormant = [];
+  for (const [oldKey, circuit] of Object.entries(circuits ?? {})) {
+    if (!circuit?.composite?.name) continue;
+    if (eligibleForCrystallization(circuit, toolSpecs)) continue; // alive as-is
+
+    const disabled = (circuit.steps ?? []).filter(
+      (s) => toolSpecs[s] && !toolSpecs[s].enabled,
+    );
+    if (disabled.length) {
+      // the user disabled a step on purpose — respect it, do not re-route around it
+      dormant.push({
+        composite: circuit.composite.name,
+        key: oldKey,
+        reason: `step disabled by the user: ${disabled.join(', ')} — composite sleeps until re-enabled`,
+      });
+      continue;
+    }
+
+    const renames = {};
+    const newSteps = [];
+    let resolvable = true;
+    for (const step of circuit.steps ?? []) {
+      if (toolSpecs[step]?.enabled && toolSpecs[step].method === 'GET') {
+        newSteps.push(step);
+        continue;
+      }
+      const successor = successorFor(step, toolSpecs, new Set(newSteps));
+      if (!successor) {
+        resolvable = false;
+        dormant.push({
+          composite: circuit.composite.name,
+          key: oldKey,
+          reason: `step vanished with no unique successor: ${step} — structure kept, waiting for a sync that brings it back`,
+        });
+        break;
+      }
+      renames[step] = successor;
+      newSteps.push(successor);
+    }
+    if (!resolvable) continue;
+
+    const next = structuredClone(circuit);
+    next.steps = newSteps;
+    next.links = (next.links ?? []).map((l) => ({
+      ...l,
+      from: renames[l.from] ?? l.from,
+      to: renames[l.to] ?? l.to,
+    }));
+    if (!eligibleForCrystallization(next, toolSpecs)) {
+      dormant.push({
+        composite: circuit.composite.name,
+        key: oldKey,
+        reason:
+          'successor found but the re-mapped circuit is not crystallizable — kept dormant',
+      });
+      continue;
+    }
+    remapped.push({
+      oldKey,
+      newKey: next.steps.join('>'),
+      circuit: next,
+      renames,
+    });
+  }
+  return { remapped, dormant };
+}
+
 // a sampled name is untrusted input: normalize hard, reject anything shapeless
 export function normalizeCompositeName(raw) {
   const n = String(raw ?? '')

package/src/server/stdio.js

@@ -15,6 +15,7 @@ import { createIdleHarvester } from './idle.js';
 import { createSequenceRecorder, sequenceRecordingEnabled } from './condenser.js';
 import {
   eligibleForCrystallization,
+  remapComposites,
   fallbackComposite,
   normalizeCompositeName,
   compositeSchema,
@@ -228,11 +229,59 @@ export async function startStdioBridge({ cwd, portOverride }) {
   // composites born in past sessions wake up with the bridge — re-validated
   // against today's tools (a route may have changed or been disabled since)
   if (recorder) {
+    // R2.4 — nothing disappears, x becomes y: a step whose route was renamed is
+    // re-mapped to its UNIQUE deterministic successor instead of killing the
+    // composite silently; the unmappable go dormant WITH a recorded lesson.
+    const { remapped, dormant } = remapComposites(
+      manifest.labs?.circuits ?? {},
+      toolSpecs,
+    );
     for (const [sig, c] of Object.entries(manifest.labs?.circuits ?? {})) {
       if (c.composite?.name && eligibleForCrystallization(c, toolSpecs)) {
         composites.set(uniqueCompositeName(c.composite.name), { sig, circuit: c });
       }
     }
+    for (const r of remapped) {
+      delete manifest.labs.circuits[r.oldKey];
+      manifest.labs.circuits[r.newKey] = r.circuit;
+      composites.set(uniqueCompositeName(r.circuit.composite.name), {
+        sig: r.newKey,
+        circuit: r.circuit,
+      });
+      manifest.sparding ??= {};
+      manifest.sparding.events ??= [];
+      manifest.sparding.events.push({
+        ts: new Date().toISOString(),
+        tool: r.circuit.composite.name,
+        decision: 'audit',
+        risk: 'low',
+        reasons: [
+          `composite re-mapped (R2.4): ${Object.entries(r.renames)
+            .map(([a, b]) => `${a} → ${b}`)
+            .join(', ')}`,
+        ],
+      });
+      if (manifest.sparding.events.length > 100) manifest.sparding.events.shift();
+      console.error(
+        `[sparda] R2.4: composite '${r.circuit.composite.name}' re-mapped (${Object.entries(
+          r.renames,
+        )
+          .map(([a, b]) => `${a} → ${b}`)
+          .join(', ')})`,
+      );
+    }
+    for (const d of dormant) {
+      manifest.sparding ??= {};
+      manifest.sparding.failures ??= {};
+      const fsig = `composite|${d.composite}|dormant`;
+      const prev = manifest.sparding.failures[fsig] ?? { count: 0, lesson: '' };
+      manifest.sparding.failures[fsig] = { count: prev.count + 1, lesson: d.reason };
+      console.error(`[sparda] R2.4: composite '${d.composite}' dormant — ${d.reason}`);
+    }
+    if (remapped.length || dormant.length) {
+      mergeManifestKeySync(manifestPath, 'labs', manifest.labs);
+      mergeManifestKeySync(manifestPath, 'sparding', manifest.sparding);
+    }
   }
 
   const descFor = (name, t) => {