sparda-mcp 0.6.0 → 0.7.1

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.6.0",
+  "version": "0.7.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

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { detectStack } from '../detect.js';
+import { buildNegentropy, renderNegentropy } from './negentropy.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.
@@ -26,9 +27,12 @@ export async function runDoctor(opts) {
     fail(`  ✗ ${e.message}`);
   }
   const manifest = path.join(opts.cwd, 'sparda.json');
+  let liveStats = null; // captured for the negentropy pass
+  let parsedManifest = null;
   if (fs.existsSync(manifest)) {
     try {
       const m = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+      parsedManifest = m;
       const tools = Object.values(m.tools ?? {});
       console.log(
         `  ✓ sparda.json valid (${tools.length} tools, ${tools.filter((t) => t.enabled).length} enabled)`,
@@ -67,6 +71,7 @@ export async function runDoctor(opts) {
               .then((x) => (x.ok ? x.json() : null))
               .catch(() => null);
             if (s) {
+              liveStats = s;
               const totals = Object.values(s.stats ?? {}).reduce(
                 (a, t) => ({ calls: a.calls + t.calls, errors: a.errors + t.errors }),
                 { calls: 0, errors: 0 },
@@ -102,5 +107,41 @@ export async function runDoctor(opts) {
   } else {
     console.log('  · sparda.json not found (run `npx sparda-mcp init`)');
   }
+
+  // ── negentropy pass (opt-in: doctor --app) — R3.1, deterministic ─────────
+  if (opts.app && parsedManifest) {
+    console.log('');
+    let currentRoutes = null;
+    try {
+      if (stack?.framework === 'express') {
+        const { parseExpressProject } = await import('../parser/express.js');
+        currentRoutes = parseExpressProject(opts.cwd, stack.entryFile).routes;
+      } else if (stack?.framework === 'nextjs') {
+        const { parseNextProject } = await import('../parser/nextjs.js');
+        currentRoutes = parseNextProject(opts.cwd, stack.entryFile).routes;
+      } else if (stack?.framework === 'fastapi') {
+        const { parseFastAPIProject } = await import('../parser/fastapi.js');
+        currentRoutes = parseFastAPIProject(
+          opts.cwd,
+          stack.entryFile,
+          stack.pythonCmd,
+        ).routes;
+      }
+    } catch {
+      currentRoutes = null; // drift becomes "not measurable", never a guess
+    }
+    const result = buildNegentropy({
+      manifest: parsedManifest,
+      currentRoutes,
+      live: liveStats,
+      detectedPort: stack?.port ?? null,
+      cwd: opts.cwd,
+    });
+    const { lines, failing } = renderNegentropy(result);
+    for (const l of lines) console.log(l);
+    if (failing) healthy = false;
+  } else if (opts.app) {
+    console.log('\n  · negentropy scan skipped — no sparda.json to compare against');
+  }
   return { healthy };
 }

package/src/commands/negentropy.js

@@ -0,0 +1,234 @@
+// commands/negentropy.js — the Maxwell's demon pass (`doctor --app`, R3.1).
+// Detects rot, deterministically and with zero LLM: schema drift (the code
+// moved, the manifest didn't), stale/unsynced tools, dead current, chronic
+// antigens the immune system keeps diagnosing but nobody fixes, and zombie
+// config. Every finding names its repair. Honest by construction: a gauge
+// that cannot be measured says so instead of guessing.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// same fingerprint the generators stamp into sparding.toolFingerprints —
+// method|path|params, sha256/8. Divergence = the route's shape changed.
+export function fingerprintFor(tool) {
+  const raw = `${tool.method}|${tool.path}|${JSON.stringify(tool.params ?? [])}`;
+  return crypto.createHash('sha256').update(raw).digest('hex').slice(0, 8);
+}
+
+// routes (parser output) → the tool shape the generators build, keyed the
+// same way, so fingerprints are comparable across init/sync/doctor.
+export function toolShapeOf(route) {
+  return {
+    method: route.method.toUpperCase(),
+    path: route.path,
+    params: route.params ?? [],
+  };
+}
+
+// Pure core. inputs:
+//   manifest       — parsed sparda.json (required)
+//   currentRoutes  — parser output for the code as it is NOW, or null (parse failed)
+//   live           — /mcp/stats payload, or null (host down)
+//   detectedPort   — what detect.js sees now, or null
+//   cwd            — for file existence checks (router present?)
+export function buildNegentropy({ manifest, currentRoutes, live, detectedPort, cwd }) {
+  const findings = [];
+  const add = (kind, severity, title, detail, fix) =>
+    findings.push({ kind, severity, title, detail, fix });
+
+  const tools = manifest.tools ?? {};
+  const byKey = new Map(
+    Object.entries(tools).map(([name, t]) => [`${t.method} ${t.path}`, name]),
+  );
+
+  // ── drift: manifest vs the code as parsed right now ──────────────────────
+  if (currentRoutes) {
+    const currentKeys = new Map(
+      currentRoutes.map((r) => [`${r.method.toUpperCase()} ${r.path}`, r]),
+    );
+    for (const [key, name] of byKey) {
+      if (!currentKeys.has(key)) {
+        add(
+          'drift',
+          'high',
+          `stale tool: ${name}`,
+          `${key} is in sparda.json but no longer exists in the code — the AI sees a ghost route`,
+          'npx sparda-mcp sync',
+        );
+      }
+    }
+    for (const [key] of currentKeys) {
+      if (!byKey.has(key)) {
+        add(
+          'drift',
+          'medium',
+          `unsynced route: ${key}`,
+          'exists in the code but not in sparda.json — invisible to the AI',
+          'npx sparda-mcp sync',
+        );
+      }
+    }
+    const storedFps = manifest.sparding?.toolFingerprints ?? {};
+    for (const [key, name] of byKey) {
+      const route = currentKeys.get(key);
+      if (!route || !storedFps[name]) continue;
+      const fp = fingerprintFor(toolShapeOf(route));
+      if (fp !== storedFps[name]) {
+        add(
+          'drift',
+          'medium',
+          `shape drift: ${name}`,
+          `route structure changed since the last sync (fingerprint ${storedFps[name]} → ${fp}) — params the AI knows may be wrong`,
+          'npx sparda-mcp sync',
+        );
+      }
+    }
+  } else {
+    add(
+      'drift',
+      'info',
+      'drift not measurable',
+      'the current code could not be re-parsed — drift against the manifest is unknown',
+      'fix the parse error reported above, then re-run',
+    );
+  }
+
+  // ── dead current: enabled tools nobody exercised this session ────────────
+  if (live) {
+    const stats = live.stats ?? {};
+    const totalCalls = Object.values(stats).reduce((n, s) => n + (s.calls ?? 0), 0);
+    const uptime = live.uptimeSec ?? 0;
+    if (totalCalls > 0 && uptime >= 60) {
+      for (const [name, t] of Object.entries(tools)) {
+        if (!t.enabled) continue;
+        if ((stats[name]?.calls ?? 0) === 0) {
+          add(
+            'dead',
+            'info',
+            `no current: ${name}`,
+            `${t.method} ${t.path} — zero calls since host start (${uptime}s, ${totalCalls} calls elsewhere). RAM gauge: this session only, not a lifetime verdict`,
+            'if this route is dead in the code too, delete it; if it matters, tell the AI about it (semantic pass)',
+          );
+        }
+      }
+    } else {
+      add(
+        'dead',
+        'info',
+        'current not measurable yet',
+        `host up ${uptime}s with ${totalCalls} total calls — not enough observation to call any route dead`,
+        'let the app run under real usage, then re-run',
+      );
+    }
+    for (const [name, q] of Object.entries(live.quarantine ?? {})) {
+      add(
+        'sick',
+        'high',
+        `quarantined: ${name}`,
+        `the immune system is protecting this route (${q.reason ?? 'repeated 5xx'})`,
+        'fix the underlying failure; quarantine lifts itself (half-open probe)',
+      );
+    }
+  } else {
+    add(
+      'dead',
+      'info',
+      'live gauges unavailable',
+      'host not running — dead-current and quarantine checks need the app up',
+      'start the app, then re-run npx sparda-mcp doctor --app',
+    );
+  }
+
+  // ── chronic antigens: diagnosed again and again, never fixed ─────────────
+  const failures = Object.entries(manifest.sparding?.failures ?? {})
+    .map(([sig, f]) => ({ sig, count: f.count ?? 0, lesson: f.lesson ?? '' }))
+    .filter((f) => f.count >= 3)
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 3);
+  for (const f of failures) {
+    add(
+      'sick',
+      'medium',
+      `recurring failure: ${f.sig}`,
+      `${f.count} occurrences${f.lesson ? ` — lesson on file: ${f.lesson}` : ''}`,
+      f.sig.includes('write_disabled')
+        ? 'the AI keeps hitting a write-safety wall: enable the tool deliberately, or leave it and the block keeps doing its job'
+        : 'the diagnosis exists in the journal; the fix does not — repair the route',
+    );
+  }
+  const antibodies = Object.entries(manifest.immune?.antibodies ?? {})
+    .map(([sig, a]) => ({ sig, hits: a.hits ?? 0, diagnosis: a.diagnosis ?? '' }))
+    .filter((a) => a.hits >= 3)
+    .sort((a, b) => b.hits - a.hits)
+    .slice(0, 3);
+  for (const a of antibodies) {
+    add(
+      'sick',
+      'medium',
+      `chronic antigen: ${a.sig}`,
+      `${a.hits} zero-token diagnoses served — the memory works, the wound stays open${a.diagnosis ? ` (${a.diagnosis.slice(0, 100)})` : ''}`,
+      'apply the cached diagnosis for real; the antibody then goes quiet on its own',
+    );
+  }
+
+  // ── zombie config ─────────────────────────────────────────────────────────
+  if (detectedPort && manifest.port && detectedPort !== manifest.port) {
+    add(
+      'zombie',
+      'high',
+      'port drift',
+      `sparda.json says :${manifest.port} but the app now runs on :${detectedPort} — the bridge and the proxy point at the wrong door`,
+      'npx sparda-mcp sync (re-detects and regenerates)',
+    );
+  }
+  for (const f of manifest.generatedFiles ?? []) {
+    const abs = path.resolve(cwd ?? '.', f);
+    if (!fs.existsSync(abs)) {
+      add(
+        'zombie',
+        'high',
+        'router file missing',
+        `${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',
+      );
+    }
+  }
+
+  const summary = { drift: 0, dead: 0, sick: 0, zombie: 0 };
+  for (const f of findings) summary[f.kind] += 1;
+  const actionable = findings.filter((f) => f.severity !== 'info');
+  return { findings, summary, actionable: actionable.length };
+}
+
+// terminal rendering, doctor-style: ✗ fails CI, ⚠ warns, · informs
+export function renderNegentropy(result) {
+  const lines = [];
+  let failing = false;
+  lines.push('  Negentropy scan (doctor --app)');
+  if (result.findings.length === 0) {
+    lines.push('  ✓ no rot detected — manifest, code and gauges agree');
+    return { lines, failing };
+  }
+  for (const f of result.findings) {
+    const glyph = f.severity === 'high' ? '✗' : f.severity === 'medium' ? '⚠' : '·';
+    if (f.severity === 'high') failing = true;
+    lines.push(`  ${glyph} [${f.kind}] ${f.title}`);
+    lines.push(`      ${f.detail}`);
+    lines.push(`      → ${f.fix}`);
+  }
+  lines.push(
+    `  ${result.actionable ? '⚠' : '·'} ${result.findings.length} finding(s) — drift ${result.summary.drift} · dead ${result.summary.dead} · sick ${result.summary.sick} · zombie ${result.summary.zombie}`,
+  );
+  return { lines, failing };
+}

package/src/commands/seed.js

@@ -0,0 +1,282 @@
+// commands/seed.js — the genome (R4.5 lite): everything the organism LEARNED,
+// distilled into a file that can regerminate elsewhere (dev → prod, or a
+// community seed for a popular stack) without re-paying the learning.
+//
+// The closed circle: app → usage → seed → next app. Structure and lessons
+// only — never a value, never a secret, never a security decision:
+//   EXPORTED : semantic descriptions/workflows, immune antibodies, failure
+//              lessons, Labs circuit structure.
+//   NEVER    : localKey, port, policies, per-tool `enabled`, events, paths.
+// An imported seed is UNTRUSTED input: every text field is re-sanitized, the
+// security fields are stripped even if present, and nothing it contains can
+// enable a write or change a policy (hard rule #3 is not negotiable by file).
+import fs from 'node:fs';
+import path from 'node:path';
+import { sanitizeDescription } from '../security/sanitize.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+const SEED_VERSION = 'sparda-seed/v1';
+const MAX_ANTIBODIES = 50; // same cap as the bridge
+const MAX_WORKFLOWS = 20;
+const MAX_CIRCUITS = 30; // same cap as the condenser
+const MAX_FAILURES = 50;
+
+const clean = (raw, fallback = '') => sanitizeDescription(raw, fallback).text;
+
+// ── pure: manifest → seed ──────────────────────────────────────────────────
+
+export function buildSeed(manifest) {
+  const seed = {
+    version: SEED_VERSION,
+    framework: manifest.framework ?? 'unknown',
+    exportedAt: new Date().toISOString(),
+    semantic: { descriptions: {}, workflows: [] },
+    antibodies: {},
+    failures: {},
+    circuits: {},
+  };
+
+  for (const [tool, desc] of Object.entries(manifest.semantic?.descriptions ?? {})) {
+    seed.semantic.descriptions[tool] = clean(desc);
+  }
+  for (const wf of (manifest.semantic?.workflows ?? []).slice(0, MAX_WORKFLOWS)) {
+    seed.semantic.workflows.push({
+      name: clean(wf.name, 'workflow'),
+      description: clean(wf.description),
+      steps: Array.isArray(wf.steps) ? wf.steps.map((s) => clean(s)).slice(0, 20) : [],
+    });
+  }
+  for (const [sig, a] of Object.entries(manifest.immune?.antibodies ?? {}).slice(
+    0,
+    MAX_ANTIBODIES,
+  )) {
+    seed.antibodies[sig] = { diagnosis: clean(a.diagnosis), hits: Number(a.hits) || 0 };
+  }
+  for (const [sig, f] of Object.entries(manifest.sparding?.failures ?? {}).slice(
+    0,
+    MAX_FAILURES,
+  )) {
+    seed.failures[sig] = { count: Number(f.count) || 0, lesson: clean(f.lesson) };
+  }
+  for (const [key, cir] of Object.entries(manifest.labs?.circuits ?? {}).slice(
+    0,
+    MAX_CIRCUITS,
+  )) {
+    // structure only, exactly what the condenser persists — never values
+    seed.circuits[key] = {
+      steps: Array.isArray(cir.steps) ? cir.steps : [],
+      links: Array.isArray(cir.links) ? cir.links : [],
+      seen: Number(cir.seen) || 0,
+      ...(cir.composite
+        ? {
+            composite: {
+              name: clean(cir.composite.name, 'composite'),
+              description: clean(cir.composite.description),
+              source: 'seed',
+            },
+          }
+        : {}),
+    };
+  }
+  return seed;
+}
+
+// ── pure: (manifest, seed) → merged manifest — local knowledge wins ────────
+
+export function mergeSeed(manifest, seed) {
+  if (!seed || seed.version !== SEED_VERSION) {
+    throw Object.assign(new Error('not a SPARDA seed (missing/unknown version field).'), {
+      code: 'USER',
+      hint: `expected "version": "${SEED_VERSION}" — re-export with npx sparda-mcp seed export`,
+    });
+  }
+  const m = structuredClone(manifest);
+  const toolNames = new Set(Object.keys(m.tools ?? {}));
+  const sigToolExists = (sig) => {
+    // signatures are `source|tool|status` — a lesson about a tool this app
+    // does not have is noise, not knowledge
+    const tool = String(sig).split('|')[1];
+    return tool === 'null' || tool === 'undefined' || toolNames.has(tool);
+  };
+  const report = {
+    descriptions: 0,
+    workflows: 0,
+    antibodies: 0,
+    failures: 0,
+    circuits: 0,
+    skipped: 0,
+  };
+
+  m.semantic ??= { descriptions: {}, workflows: [] };
+  m.semantic.descriptions ??= {};
+  m.semantic.workflows ??= [];
+  for (const [tool, desc] of Object.entries(seed.semantic?.descriptions ?? {})) {
+    if (!toolNames.has(tool)) {
+      report.skipped++;
+      continue;
+    }
+    if (m.semantic.descriptions[tool]) continue; // local knowledge wins
+    m.semantic.descriptions[tool] = clean(desc);
+    report.descriptions++;
+  }
+  const wfNames = new Set(m.semantic.workflows.map((w) => w.name));
+  for (const wf of (seed.semantic?.workflows ?? []).slice(0, MAX_WORKFLOWS)) {
+    const name = clean(wf.name, 'workflow');
+    if (wfNames.has(name) || m.semantic.workflows.length >= MAX_WORKFLOWS) continue;
+    wfNames.add(name);
+    m.semantic.workflows.push({
+      name,
+      description: clean(wf.description),
+      steps: Array.isArray(wf.steps) ? wf.steps.map((s) => clean(s)).slice(0, 20) : [],
+      source: 'seed',
+    });
+    report.workflows++;
+  }
+
+  m.immune ??= { antibodies: {} };
+  m.immune.antibodies ??= {};
+  for (const [sig, a] of Object.entries(seed.antibodies ?? {})) {
+    if (!sigToolExists(sig)) {
+      report.skipped++;
+      continue;
+    }
+    if (
+      Object.keys(m.immune.antibodies).length >= MAX_ANTIBODIES &&
+      !m.immune.antibodies[sig]
+    )
+      continue;
+    const existing = m.immune.antibodies[sig];
+    if (existing) {
+      existing.hits = Math.max(Number(existing.hits) || 0, Number(a.hits) || 0);
+    } else {
+      m.immune.antibodies[sig] = {
+        diagnosis: clean(a.diagnosis),
+        hits: Number(a.hits) || 0,
+        firstSeen: new Date().toISOString(),
+        lastSeen: new Date().toISOString(),
+        source: 'seed',
+      };
+      report.antibodies++;
+    }
+  }
+
+  m.sparding ??= {};
+  m.sparding.failures ??= {};
+  for (const [sig, f] of Object.entries(seed.failures ?? {})) {
+    if (!sigToolExists(sig)) {
+      report.skipped++;
+      continue;
+    }
+    const existing = m.sparding.failures[sig];
+    if (existing) {
+      existing.count = Math.max(Number(existing.count) || 0, Number(f.count) || 0);
+    } else if (Object.keys(m.sparding.failures).length < MAX_FAILURES) {
+      m.sparding.failures[sig] = { count: Number(f.count) || 0, lesson: clean(f.lesson) };
+      report.failures++;
+    }
+  }
+
+  m.labs ??= {};
+  m.labs.circuits ??= {};
+  for (const [key, cir] of Object.entries(seed.circuits ?? {})) {
+    if (m.labs.circuits[key]) continue; // local observation wins
+    const stepTools = (Array.isArray(cir.steps) ? cir.steps : [])
+      .map((s) => (typeof s === 'string' ? s : s?.tool))
+      .filter(Boolean);
+    if (!stepTools.every((t) => toolNames.has(t))) {
+      report.skipped++;
+      continue;
+    }
+    if (Object.keys(m.labs.circuits).length >= MAX_CIRCUITS) continue;
+    m.labs.circuits[key] = {
+      steps: cir.steps,
+      links: Array.isArray(cir.links) ? cir.links : [],
+      seen: Number(cir.seen) || 0,
+      firstSeen: new Date().toISOString(),
+      lastSeen: new Date().toISOString(),
+      ...(cir.composite
+        ? {
+            composite: {
+              name: clean(cir.composite.name, 'composite'),
+              description: clean(cir.composite.description),
+              source: 'seed',
+              createdAt: new Date().toISOString(),
+            },
+          }
+        : {}),
+    };
+    report.circuits++;
+  }
+
+  // the file may claim anything — the organism's security is not up for
+  // negotiation: whatever a seed carries, these never cross (hard rule #3/#5)
+  // (localKey, port, policies and per-tool `enabled` were simply never read.)
+  return { manifest: m, report };
+}
+
+// ── the command: seed export [--out f] | seed import <file> ───────────────
+
+export async function runSeed(opts, args) {
+  const sub = args[0];
+  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',
+    });
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    throw Object.assign(new Error('sparda.json is not valid JSON.'), {
+      code: 'USER',
+      hint: 'restore it from git or re-run `npx sparda-mcp init`',
+    });
+  }
+
+  if (sub === 'export') {
+    const seed = buildSeed(manifest);
+    const out = opts.out ?? 'sparda-seed.json';
+    atomicWrite(path.resolve(opts.cwd, out), JSON.stringify(seed, null, 2) + '\n');
+    console.log(
+      `✓ Seed exported: ${out} — ${Object.keys(seed.antibodies).length} antibodies, ${Object.keys(seed.semantic.descriptions).length} descriptions, ${seed.semantic.workflows.length} workflows, ${Object.keys(seed.circuits).length} circuits, ${Object.keys(seed.failures).length} lessons`,
+    );
+    console.log('  Structure and lessons only. No key, no policy, no value ever leaves.');
+    return { seed };
+  }
+
+  if (sub === 'import') {
+    const file = args[1];
+    if (!file) {
+      throw Object.assign(new Error('missing seed file.'), {
+        code: 'USER',
+        hint: 'usage: npx sparda-mcp seed import <sparda-seed.json>',
+      });
+    }
+    const abs = path.resolve(opts.cwd, file);
+    if (!fs.existsSync(abs)) {
+      throw Object.assign(new Error(`seed file not found: ${file}`), { code: 'USER' });
+    }
+    let seed;
+    try {
+      seed = JSON.parse(fs.readFileSync(abs, 'utf8'));
+    } catch {
+      throw Object.assign(new Error('seed file is not valid JSON.'), { code: 'USER' });
+    }
+    const { manifest: merged, report } = mergeSeed(manifest, seed);
+    atomicWrite(manifestPath, JSON.stringify(merged, null, 2) + '\n');
+    console.log(
+      `✓ Seed germinated into sparda.json — +${report.antibodies} antibodies, +${report.descriptions} descriptions, +${report.workflows} workflows, +${report.circuits} circuits, +${report.failures} lessons (${report.skipped} entries skipped: unknown tools here)`,
+    );
+    console.log(
+      '  Local knowledge always wins; keys, policies and enabled flags were never read.',
+    );
+    return { report };
+  }
+
+  throw Object.assign(new Error(`unknown seed subcommand: ${sub ?? '(none)'}`), {
+    code: 'USER',
+    hint: 'usage: npx sparda-mcp seed export [--out file] | seed import <file>',
+  });
+}

package/src/index.js

@@ -20,7 +20,9 @@ const opts = {
   probe: flags.has('--probe'),
   html: flags.has('--html'),
   json: flags.has('--json'),
+  app: flags.has('--app'),
   port: getOpt('port', null),
+  out: getOpt('out', null),
   cwd: process.cwd(),
 };
 
@@ -67,6 +69,14 @@ try {
       await runReport(opts);
       break;
     }
+    case 'seed': {
+      const { runSeed } = await import('./commands/seed.js');
+      await runSeed(
+        opts,
+        rest.filter((a) => !a.startsWith('--')),
+      );
+      break;
+    }
     default:
       console.log(`SPARDA v${VERSION} — Turn any codebase into an MCP server.
 
@@ -77,8 +87,9 @@ Usage:
   npx sparda-mcp sync      Re-sync the router after route changes (no prompts)
   npx sparda-mcp hook      Install the git sentinel (auto-sync after commits)
   npx sparda-mcp remove    Remove SPARDA from this project (clean git diff)
-  npx sparda-mcp doctor    Diagnose your setup
+  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>)
 
 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) => {