sparda-mcp 0.17.0 → 0.26.0

package/demo-app/.sparda/immunity.json

@@ -1 +1 @@
-{"v":"imm1","proven":true,"routes":[{"behaviorHash":"bh1_13969839d8a18d54aa0342618e56db6a","pol":121,"exposed":[]},{"behaviorHash":"bh1_2daf8a2b1b0ed393d443991a2b0700f6","pol":121,"exposed":[]},{"behaviorHash":"bh1_58fbf5ac38b6d71abc7204921de6b957","pol":121,"exposed":[]},{"behaviorHash":"bh1_58fbf5ac38b6d71abc7204921de6b957","pol":121,"exposed":[]},{"behaviorHash":"bh1_cc6788289c612af85b8d215b5bdf9b28","pol":121,"exposed":[]}],"posture":{"auth":{"protected":0,"exposed":0,"na":5},"atomicity":{"protected":0,"exposed":0,"na":5},"reversibility":{"protected":0,"exposed":0,"na":5},"validation":{"protected":0,"exposed":0,"na":5},"aggregate":{"protected":0,"exposed":0,"na":5}},"bytes":5}
+{"v":"imm1","proven":false,"surfaceOnly":true,"routes":[{"behaviorHash":"bh1_13969839d8a18d54aa0342618e56db6a","pol":121,"exposed":[]},{"behaviorHash":"bh1_2daf8a2b1b0ed393d443991a2b0700f6","pol":121,"exposed":[]},{"behaviorHash":"bh1_58fbf5ac38b6d71abc7204921de6b957","pol":121,"exposed":[]},{"behaviorHash":"bh1_58fbf5ac38b6d71abc7204921de6b957","pol":121,"exposed":[]},{"behaviorHash":"bh1_cc6788289c612af85b8d215b5bdf9b28","pol":121,"exposed":[]}],"posture":{"auth":{"protected":0,"exposed":0,"na":5},"atomicity":{"protected":0,"exposed":0,"na":5},"reversibility":{"protected":0,"exposed":0,"na":5},"validation":{"protected":0,"exposed":0,"na":5},"aggregate":{"protected":0,"exposed":0,"na":5}},"bytes":5}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.17.0",
+  "version": "0.26.0",
   "mcpName": "io.github.zyx77550/sparda-mcp",
   "description": "Compile backends to behavior graphs. Statically prove security, simulate APIs, and replay bugs.",
   "type": "module",

package/src/commands/apocalypse.js

@@ -78,6 +78,13 @@ export async function runApocalypse(opts) {
             `      no route call sites reached — routes are likely registered indirectly (a loader / DI pattern the static walk can't follow).`,
           );
       }
+    } else if (verdict.surfaceOnly) {
+      console.log(
+        `● SURFACE ONLY — ${verdict.entrypoints} route(s) seen, but ZERO behavior resolved (no state, no db/http/fs effects). There was nothing to prove, so this is NOT a clean bill of health — SPARDA saw the surface but not what the code does (a spec, or an effect-resolution gap: DI services, external controllers). Run with --verbose.`,
+      );
+      if (opts.verbose && report.skipped?.length)
+        for (const s of report.skipped)
+          console.log(`      skipped: ${s.reason}${s.file ? ` (${s.file})` : ''}`);
     } else if (verdict.clean) {
       console.log(
         `✓ PROVEN — ${obligations} obligation(s) discharged, zero violations. No declared guard, invariant, transaction or aggregate boundary can be broken by this tree.`,

package/src/commands/dossier.js

@@ -0,0 +1,209 @@
+// commands/dossier.js — the human face of the proof.
+// Everything SPARDA proved about an app, rendered as ONE self-contained HTML file a
+// non-technical reader can open and understand: the verdict, the ternary safety
+// matrix, the exact risks with file:line, and the frozen capsule. Zero deps, no CDN,
+// no network — all CSS inline; deterministic (content derives only from the graph).
+// Written to `.sparda/dossier.html`, which is gitignored — ephemeral by design: it
+// disappears on `sparda remove` / a clean, so the reader keeps it only if they save it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { checkGraph, verdictOf } from '../ubg/apocalypse.js';
+import { buildCapsule } from '../ubg/immunity.js';
+import { AXES, POLARITY_SYMBOL, exposedAxes } from '../ubg/polarity.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+export async function runDossier(opts) {
+  const compiled = compileUBG(opts.cwd, { write: false, openapi: opts.openapi });
+  const canonical = canonicalizeGraph(compiled.graph);
+  const { findings, polarity } = checkGraph(canonical);
+  const verdict = verdictOf(findings, canonical);
+  const capsule = buildCapsule(canonical);
+
+  const data = {
+    app: path.basename(path.resolve(opts.cwd)) || 'app',
+    framework: compiled.report.framework,
+    routes: compiled.report.routes,
+    tables: compiled.report.tables,
+    nodes: canonical.nodes.length,
+    edges: canonical.edges.length,
+    provable: verdict.provable,
+    proven: verdict.provable && verdict.clean,
+    surfaceOnly: verdict.surfaceOnly,
+    guards: verdict.guards,
+    guardsVerified: verdict.guardsVerified,
+    counts: verdict.counts,
+    findings,
+    polarity: polarity.map((p) => ({ entrypoint: p.entrypoint, vector: p.vector })),
+    posture: capsule.posture,
+    capsuleBytes: capsule.bytes,
+    sourceHash: (canonical.meta?.sourceHash ?? '').slice(0, 12),
+  };
+
+  const html = renderDossierHTML(data);
+
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return { data };
+  }
+
+  const outPath = path.join(opts.cwd, '.sparda', 'dossier.html');
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  atomicWrite(outPath, html);
+  console.log(
+    `DOSSIER — ${data.routes} route(s), verdict ${data.proven ? '✓ PROVEN' : data.provable ? '✗ NOT PROVEN' : '✗ NO PROOF'}`,
+  );
+  console.log(
+    `  written: .sparda/dossier.html (${html.length} bytes, self-contained) — open it in any browser.`,
+  );
+  console.log(
+    `  ephemeral: .sparda/ is gitignored, so it vanishes on \`sparda remove\` — save it to keep it.`,
+  );
+  return { data, outPath };
+}
+
+// ── pure renderer: proof data → one self-contained HTML document ────────────
+
+const esc = (s) =>
+  String(s ?? '').replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c],
+  );
+const short = (id) => esc(String(id).replace(/^entrypoint:/, ''));
+
+const SEV_COLOR = {
+  critical: '#e5484d',
+  high: '#e5484d',
+  medium: '#e5a23d',
+  info: '#8b8f9a',
+};
+
+export function renderDossierHTML(d) {
+  const verdictClass = d.proven ? 'ok' : d.surfaceOnly ? 'warn' : 'bad';
+  const verdictText = d.proven
+    ? 'PROVEN'
+    : d.surfaceOnly
+      ? 'SURFACE ONLY — routes seen, no behavior resolved'
+      : d.provable
+        ? 'NOT PROVEN'
+        : 'NO PROOF — the app’s routes could not be read';
+  const verdictLede = d.proven
+    ? 'No declared guard, invariant, transaction or aggregate boundary can be broken by this code.'
+    : d.surfaceOnly
+      ? 'SPARDA saw the route surface but no state or side-effects behind it — there was nothing to prove. This is NOT a clean bill of health (a spec, or an effect-resolution gap).'
+      : d.provable
+        ? `SPARDA found ${d.counts.critical} critical and ${d.counts.high} high risk(s) that must be fixed before this ships.`
+        : 'SPARDA could not see this app’s route surface — this is not a clean bill of health.';
+
+  const cell = (v) => {
+    const cls = v === -1 ? 'neg' : v === 1 ? 'pos' : 'na';
+    return `<td class="${cls}" title="${v === -1 ? 'exposed' : v === 1 ? 'protected' : 'n/a'}">${POLARITY_SYMBOL[v]}</td>`;
+  };
+  const matrixRows = d.polarity
+    .map((p) => {
+      const flagged = exposedAxes(p.vector).length ? ' class="row-bad"' : '';
+      return `<tr${flagged}><th>${short(p.entrypoint)}</th>${AXES.map((a) => cell(p.vector[a])).join('')}</tr>`;
+    })
+    .join('');
+
+  const findingCards = d.findings.length
+    ? d.findings
+        .map(
+          (f) => `
+        <div class="finding" style="--sev:${SEV_COLOR[f.severity] ?? '#8b8f9a'}">
+          <div class="sev">${esc(f.severity)}</div>
+          <div class="fbody">
+            <div class="frule">${esc(f.rule)} · <span class="fep">${short(f.entrypoint)}</span></div>
+            <p>${esc(f.message)}</p>
+          </div>
+        </div>`,
+        )
+        .join('')
+    : '<p class="clean">No risks found — every proof obligation was discharged.</p>';
+
+  const statCard = (n, label) =>
+    `<div class="stat"><b>${esc(n)}</b><span>${esc(label)}</span></div>`;
+
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SPARDA dossier — ${esc(d.app)}</title>
+<style>
+  :root{--bg:oklch(0.16 0.01 255);--panel:oklch(0.22 0.01 255);--line:oklch(0.32 0.01 255);
+    --ink:oklch(0.95 0.01 255);--soft:oklch(0.75 0.01 255);--faint:oklch(0.55 0.01 255);
+    --red:oklch(0.65 0.20 20);--green:oklch(0.75 0.15 150);--amber:oklch(0.75 0.18 70);
+    --mono:"Geist Mono",ui-monospace,Menlo,Consolas,monospace;
+    --sans:Inter,Geist,-apple-system,system-ui,"Segoe UI",Roboto,sans-serif;}
+  @media(prefers-color-scheme:light){:root{--bg:oklch(0.98 0.005 255);--panel:oklch(1 0 0);
+    --line:oklch(0.90 0.01 255);--ink:oklch(0.20 0.01 255);--soft:oklch(0.40 0.01 255);
+    --faint:oklch(0.60 0.01 255);--red:oklch(0.55 0.20 20);--green:oklch(0.50 0.15 150);--amber:oklch(0.60 0.18 70);}}
+  *{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--sans);line-height:1.55;-webkit-font-smoothing:antialiased}
+  .wrap{max-width:960px;margin:0 auto;padding:48px 24px 80px}
+  .top{display:flex;justify-content:space-between;align-items:baseline;border-bottom:1px solid var(--line);padding-bottom:16px;font-family:var(--mono);font-size:13px;color:var(--faint)}
+  .top b{color:var(--ink);letter-spacing:.12em}
+  .hero{padding:48px 0 32px}
+  .stamp{display:inline-flex;align-items:center;gap:12px;font-family:var(--mono);font-weight:700;font-size:16px;padding:12px 24px;border-radius:12px;border:1.5px solid;letter-spacing:.03em;box-shadow:0 4px 12px -4px color-mix(in oklch,currentColor 30%,transparent)}
+  .stamp .dot{width:8px;height:8px;border-radius:50%;background:currentColor;box-shadow:0 0 0 4px color-mix(in oklch,currentColor 22%,transparent)}
+  .ok{color:var(--green);border-color:var(--green);background:color-mix(in oklch,var(--green) 10%,transparent)}
+  .bad{color:var(--red);border-color:var(--red);background:color-mix(in oklch,var(--red) 10%,transparent)}
+  .warn{color:var(--amber);border-color:var(--amber);background:color-mix(in oklch,var(--amber) 10%,transparent)}
+  .hero p{font-size:18px;color:var(--soft);max-width:65ch;margin:24px 0 0;text-wrap:balance}
+  .stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:16px;margin:32px 0}
+  .stat{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:20px;transition:transform 200ms cubic-bezier(0.16,1,0.3,1),border-color 200ms}
+  .stat:hover{transform:translateY(-2px);border-color:var(--soft)}
+  .stat b{display:block;font-size:24px;font-family:var(--mono);letter-spacing:-0.02em;line-height:1.2}.stat span{font-size:13px;color:var(--faint);font-weight:500}
+  h2{font-size:16px;letter-spacing:-0.01em;margin:48px 0 16px;color:var(--ink)}
+  h2 small{color:var(--faint);font-weight:400;font-family:var(--mono)}
+  table{border-collapse:collapse;font-family:var(--mono);font-size:13px;width:100%;overflow-x:auto;display:block}
+  table thead th{color:var(--faint);font-weight:500;padding:8px 12px;text-align:center;font-size:11px;border-bottom:1px solid var(--line)}
+  table tbody th{text-align:left;padding:12px 16px 12px 8px;color:var(--ink);font-weight:500;white-space:nowrap}
+  table tbody tr{border-bottom:1px solid var(--line);transition:background-color 150ms}
+  table tbody tr:hover{background-color:color-mix(in oklch,var(--panel) 60%,transparent)}
+  table td{text-align:center;padding:12px 8px;font-weight:700}
+  td.neg{color:var(--red)}td.pos{color:var(--green)}td.na{color:var(--faint)}
+  tr.row-bad th{color:var(--red)}
+  .finding{display:flex;gap:0;background:var(--panel);border:1px solid var(--line);border-left:4px solid var(--sev);border-radius:12px;margin:16px 0;overflow:hidden;transition:transform 200ms cubic-bezier(0.16,1,0.3,1),box-shadow 200ms}
+  .finding:hover{transform:translateY(-2px);box-shadow:0 8px 24px -8px color-mix(in oklch,var(--bg) 80%,transparent)}
+  .finding .sev{font-family:var(--mono);font-size:11px;font-weight:700;text-transform:uppercase;letter-spacing:.08em;color:var(--sev);padding:16px;align-self:center}
+  .finding .fbody{padding:16px 16px 16px 0}
+  .frule{font-family:var(--mono);font-size:13px;color:var(--ink)}.fep{color:var(--faint)}
+  .finding p{margin:8px 0 0;font-size:14px;color:var(--soft);line-height:1.6}
+  .clean{color:var(--green);font-family:var(--mono)}
+  .legend{font-family:var(--mono);font-size:12px;color:var(--faint);margin-top:12px}
+  .legend b.pos{color:var(--green)}.legend b.neg{color:var(--red)}
+  footer{margin-top:64px;padding-top:24px;border-top:1px solid var(--line);font-family:var(--mono);font-size:12px;color:var(--faint);display:flex;justify-content:space-between;flex-wrap:wrap;gap:8px}
+</style></head><body><div class="wrap">
+  <div class="top"><b>SPARDA</b><span>AI writes. SPARDA proves.</span></div>
+
+  <section class="hero">
+    <span class="stamp ${verdictClass}"><span class="dot"></span>${esc(verdictText)}</span>
+    <p>${esc(verdictLede)}</p>
+    <div class="stats">
+      ${statCard(d.routes, 'routes')}
+      ${statCard(d.nodes, 'graph nodes')}
+      ${statCard(d.tables, 'data tables')}
+      ${statCard(d.capsuleBytes + ' B', 'safety capsule')}
+      ${statCard(esc(d.framework), 'framework')}
+    </div>
+    ${
+      d.guards
+        ? `<p class="legend">${d.guardsVerified}/${d.guards} guard(s) <b class="pos">verified</b> — SPARDA saw a real deny path in the body; the rest are asserted by name (opaque middleware/decorators it could not read).</p>`
+        : ''
+    }
+  </section>
+
+  <h2>The safety matrix <small>each route × five obligations · − exposed · · n/a · + protected</small></h2>
+  <table><thead><tr><th style="text-align:left">route</th>${AXES.map((a) => `<th>${esc(a)}</th>`).join('')}</tr></thead>
+  <tbody>${matrixRows || '<tr><td>—</td></tr>'}</tbody></table>
+  <p class="legend"><b class="neg">−</b> a protection is missing &nbsp; · &nbsp; the obligation doesn’t apply &nbsp; <b class="pos">+</b> the protection is present</p>
+
+  <h2>What SPARDA found</h2>
+  ${findingCards}
+
+  <footer>
+    <span>graph ${esc(d.sourceHash)} · ${esc(d.nodes)} nodes / ${esc(d.edges)} edges</span>
+    <span>generated by SPARDA · residual-labs.fr</span>
+  </footer>
+</div></body></html>`;
+}

package/src/commands/genome.js

@@ -0,0 +1,116 @@
+// commands/genome.js — contribute this app's proofs to the world immune memory (ADR-041).
+// Brick 2: the capsule (immunize) is one app's frozen judgment; the genome is how that
+// judgment travels between strangers' machines as SIGNED, self-verifying antibodies —
+// zero infrastructure, git as the whole backplane.
+//   sparda genome            mint from this app, merge into sparda-genome.jsonl, report
+//   sparda genome --json     print this app's freshly-minted antibodies to stdout
+// The signing identity (an Ed25519 keypair) lives in .sparda/genome.key — PRIVATE, and
+// .sparda/ is gitignored, so the private half can never be committed. The public half
+// rides inside every antibody. The genome file itself is meant to be committed & shared.
+import fs from 'node:fs';
+import path from 'node:path';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { buildCapsule } from '../ubg/immunity.js';
+import {
+  generateIdentity,
+  mintGenome,
+  mergeGenome,
+  parseGenome,
+  serializeGenome,
+  emptyGenome,
+  recall,
+} from '../ubg/genome.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+const GENOME_FILE = 'sparda-genome.jsonl';
+const KEY_FILE = 'genome.key';
+
+export async function runGenome(opts) {
+  const canonical = canonicalizeGraph(
+    compileUBG(opts.cwd, { write: false, openapi: opts.openapi }).graph,
+  );
+  const capsule = buildCapsule(canonical);
+  const identity = loadOrCreateIdentity(opts.cwd);
+  const minted = mintGenome(capsule, identity);
+
+  if (opts.json) {
+    console.log(JSON.stringify(minted, null, 2));
+    return { minted, identity: { issuer: identity.issuer } };
+  }
+
+  if (!minted.length) {
+    console.log(
+      '✗ NO ANTIBODIES — 0 routes carried a behaviorHash; nothing to contribute (a coverage gap, not a pass).',
+    );
+    process.exitCode = 1;
+    return { minted, identity: { issuer: identity.issuer } };
+  }
+
+  // the genome file is the shared memory: load what's there, merge our contribution,
+  // write it back. git push/pull is the replication — there is no server anywhere.
+  const genomePath = path.join(opts.cwd, GENOME_FILE);
+  const existing = fs.existsSync(genomePath)
+    ? parseGenome(fs.readFileSync(genomePath, 'utf8')).genome
+    : emptyGenome();
+  const { genome, added, corroborated } = mergeGenome(existing, minted);
+  atomicWrite(genomePath, serializeGenome(genome));
+
+  console.log(
+    `GENOME — signed ${minted.length} antibody(ies) as ${identity.issuer} (Ed25519, self-verifying)`,
+  );
+  console.log(
+    `  merged: +${added} new, ${corroborated} corroborated → ${genome.antibodies.length} antibody(ies) in ${GENOME_FILE}`,
+  );
+  // surface any behavior the world now disagrees about — load-bearing signal
+  const conflicts = distinctHashes(genome).filter((h) => recall(genome, h).conflict);
+  if (conflicts.length)
+    console.log(
+      `  ⚠ ${conflicts.length} behavior(s) with conflicting verdicts across issuers — inspect before trusting.`,
+    );
+  console.log(
+    `  ${GENOME_FILE} is committable; .sparda/${KEY_FILE} is your PRIVATE key (gitignored) — never share it.`,
+  );
+  return { minted, genome, outPath: genomePath, identity: { issuer: identity.issuer } };
+}
+
+// the local proving identity. Created once, reused forever (carry-over is sacred —
+// a stable issuer is how reputation accrues to this install across sessions).
+function loadOrCreateIdentity(cwd) {
+  const keyPath = path.join(cwd, '.sparda', KEY_FILE);
+  if (fs.existsSync(keyPath)) {
+    try {
+      const saved = JSON.parse(fs.readFileSync(keyPath, 'utf8'));
+      if (saved.publicKey && saved.privateKey && saved.issuer) return saved;
+    } catch {
+      // corrupt key file — fall through and mint a fresh identity
+    }
+  }
+  const identity = generateIdentity();
+  fs.mkdirSync(path.dirname(keyPath), { recursive: true });
+  ensureSpardaIgnored(cwd); // the key is a SECRET — make the "gitignored" claim true
+  atomicWrite(keyPath, JSON.stringify(identity, null, 2) + '\n');
+  return identity;
+}
+
+// guarantee `.sparda/` (which holds the private key) is git-ignored before we write
+// the key — a leaked signing key lets anyone forge antibodies under this issuer.
+function ensureSpardaIgnored(cwd) {
+  const gi = path.join(cwd, '.gitignore');
+  const line = '.sparda/';
+  try {
+    if (fs.existsSync(gi)) {
+      const content = fs.readFileSync(gi, 'utf8');
+      if (!content.split(/\r?\n/).includes(line)) fs.appendFileSync(gi, `\n${line}\n`);
+    } else {
+      fs.writeFileSync(gi, `${line}\n`);
+    }
+  } catch {
+    // best-effort: if we can't touch .gitignore, the key is still only written to
+    // .sparda/ — the user's own ignore rules govern; we simply couldn't add ours.
+  }
+}
+
+function distinctHashes(genome) {
+  return [...new Set((genome.antibodies ?? []).map((a) => a.behaviorHash))];
+}

package/src/commands/immunize.js

@@ -44,13 +44,17 @@ export async function runImmunize(opts) {
   const exposed = AXES.filter((a) => capsule.posture[a].exposed > 0)
     .map((a) => `${a}×${capsule.posture[a].exposed}`)
     .join(', ');
-  console.log(
-    `  verdict: ${capsule.proven ? '✓ PROVEN' : '✗ NOT PROVEN'}` +
-      (exposed ? ` — exposed: ${exposed}` : ''),
-  );
+  const verdictText = capsule.surfaceOnly
+    ? '● SURFACE ONLY — routes seen, no behavior resolved (nothing to prove)'
+    : capsule.proven
+      ? '✓ PROVEN'
+      : '✗ NOT PROVEN';
+  console.log(`  verdict: ${verdictText}` + (exposed ? ` — exposed: ${exposed}` : ''));
   console.log(
     `  written: .sparda/immunity.json (${wire} bytes on the wire) — portable, offline, lookup by behaviorHash`,
   );
-  if (!capsule.proven) process.exitCode = 1;
+  // surface-only is not a risk (nothing to fault) → don't fail CI; only a real
+  // unproven capsule (an exposed axis) gates.
+  if (!capsule.proven && !capsule.surfaceOnly) process.exitCode = 1;
   return { capsule, outPath };
 }

package/src/detect.js

@@ -41,7 +41,18 @@ export function detectStack(cwd) {
         expressVersion: deps.express,
       };
     }
-    // NestJS (and Medusa/DI-framework) apps: routes live in @Controller classes,
+    // Medusa: file-based routing under src/api — a route IS a file
+    // (`src/api/<path>/route.ts`), not an `app.get()` or a @Controller. Checked
+    // before Nest because a Medusa app may transitively pull Nest deps.
+    if (deps['@medusajs/medusa'] || deps['@medusajs/framework']) {
+      const apiDir = ['src/api', 'api'].find((d) => {
+        const abs = path.join(cwd, d);
+        return fs.existsSync(abs) && fs.statSync(abs).isDirectory();
+      });
+      if (apiDir) return { framework: 'medusa', entryFile: apiDir, port: 9000 };
+      // Medusa dep but no api dir: fall through (a plugin/lib package, not an app).
+    }
+    // NestJS (and DI-framework) apps: routes live in @Controller classes,
     // scanned from the source tree rather than followed from a single entry.
     if (deps['@nestjs/core'] || deps['@nestjs/common']) {
       const entryFile = ['src', 'app', '.'].find((d) => {
@@ -209,6 +220,7 @@ function findExpressEntry(cwd, pkg) {
     'src/server.ts',
     'src/index.ts',
     'src/main.ts', // Nx / NestJS-style monorepo layout
+    'src/commands/start.ts',
     'main.ts',
     'app.ts',
     'server.ts',
@@ -231,12 +243,84 @@ function findExpressEntry(cwd, pkg) {
         return path.relative(cwd, abs).split(path.sep).join('/');
     }
   }
+  // No standard-named entry matched — the app's entry is a non-conventional file
+  // (`ParseServer.ts`, `bootstrap.ts`, `application.ts`, …). Scan the tree for the
+  // file that actually creates the app (a bare `express()` call), the same fallback
+  // FastAPI detection already uses. Ranked so a real server (`.listen()`) wins.
+  const found = searchExpressEntry(cwd);
+  if (found) return found;
   throw err(
     'Could not locate your Express entry file (the one calling express()).',
     'Re-run from the project root, or open an issue with your layout.',
   );
 }
 
+// Bounded source-tree scan for the app-creation file: a bare `express()` call (not
+// `express.Router()`/`express.static()`). Ranked: a file that also `.listen()`s (a
+// real server entry) beats a library file; then shallower path; then alphabetical —
+// deterministic. Caps the number of files read so a giant repo can't stall detection.
+function searchExpressEntry(cwd) {
+  const EXCLUDE = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'coverage',
+    '.next',
+    '.sparda',
+    'test',
+    'tests',
+    '__tests__',
+    'spec',
+    'examples',
+    'example',
+  ]);
+  const APP_CALL = /(?<![.\w])express\s*\(\s*\)/; // `express()` app factory
+  const matches = [];
+  const budget = { files: 0 };
+  const walk = (dir) => {
+    if (budget.files > 400) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.') && e.name !== '.') continue;
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!EXCLUDE.has(e.name)) walk(abs);
+      } else if (/\.(m?[tj]s|cjs)$/.test(e.name) && !/\.d\.ts$/.test(e.name)) {
+        if (budget.files++ > 400) return;
+        let src;
+        try {
+          src = fs.readFileSync(abs, 'utf8');
+        } catch {
+          continue;
+        }
+        if (APP_CALL.test(src)) {
+          const rel = path.relative(cwd, abs).split(path.sep).join('/');
+          matches.push({
+            rel,
+            listens: /\.listen\s*\(/.test(src),
+            depth: rel.split('/').length,
+          });
+        }
+      }
+    }
+  };
+  walk(cwd);
+  if (!matches.length) return null;
+  matches.sort(
+    (a, b) =>
+      Number(b.listens) - Number(a.listens) ||
+      a.depth - b.depth ||
+      (a.rel < b.rel ? -1 : 1),
+  );
+  return matches[0].rel;
+}
+
 function detectModuleType(cwd, pkg, entryFile) {
   if (entryFile.endsWith('.mjs')) return 'esm';
   if (entryFile.endsWith('.cjs')) return 'cjs';

package/src/index.js

@@ -137,6 +137,16 @@ try {
       await runSpeculate(opts);
       break;
     }
+    case 'dossier': {
+      const { runDossier } = await import('./commands/dossier.js');
+      await runDossier(opts);
+      break;
+    }
+    case 'genome': {
+      const { runGenome } = await import('./commands/genome.js');
+      await runGenome(opts);
+      break;
+    }
     case 'timeless': {
       const { runTimeless } = await import('./commands/timeless.js');
       await runTimeless(opts, rest);
@@ -185,6 +195,8 @@ Usage:
   npx sparda-mcp polarity  Ternary safety matrix per route — proof as arithmetic (--json)
   npx sparda-mcp immunize  Freeze proven safety into a tiny capsule (1 byte/route) — .sparda/immunity.json
   npx sparda-mcp speculate  Re-verify vs the frozen capsule by lookup — full proof only on novel shapes (--json)
+  npx sparda-mcp dossier   Render the whole proof as one self-contained HTML page anyone can read (.sparda/dossier.html)
+  npx sparda-mcp genome    Sign this app's proofs into the shared world memory — self-verifying antibodies, zero infra (--json)
   npx sparda-mcp timeless  Replay production requests (list | replay <id> | export <id> → vitest)
   npx sparda-mcp mirror    Serve the compiled graph over HTTP — no framework, no source (--port)
   npx sparda-mcp openapi   Emit an OpenAPI 3.1 spec FROM the graph (--out / --json)

package/src/ubg/apocalypse.js

@@ -269,6 +269,24 @@ export function diffGraphs(baseline, candidate) {
 
 // ---------------------------------------------------------------------------
 
+// State-touching behavior SPARDA could actually fault: state nodes + db/http/fs
+// effects. `entropy` (a bare `new Date()`) is not safety-relevant, so it doesn't
+// count — an app of only time-reads has no behavior to prove. This is the effect-level
+// analogue of the provability guard, shared by the verdict and the immunity capsule so
+// the two artifacts never disagree about whether SPARDA saw anything to prove.
+const OBSERVABLE_EFFECT = new Set(['db_write', 'db_read', 'http_call', 'fs_write']);
+export function countObserved(graph) {
+  let n = 0;
+  for (const node of graph.nodes.values ? graph.nodes.values() : graph.nodes) {
+    if (
+      node.kind === 'state' ||
+      (node.kind === 'effect' && OBSERVABLE_EFFECT.has(node.meta?.effectType))
+    )
+      n++;
+  }
+  return n;
+}
+
 export function verdictOf(findings, graph) {
   const counts = { critical: 0, high: 0, medium: 0, info: 0 };
   for (const f of findings) counts[f.severity]++;
@@ -283,12 +301,30 @@ export function verdictOf(findings, graph) {
     ? graph.nodes.filter((n) => n.kind === 'entrypoint').length
     : null;
   const provable = entrypoints === null || entrypoints > 0;
+  const observed = graph ? countObserved(graph) : null;
+  // only assert surface-only for a WHOLE-app proof (graph given with entrypoints);
+  // a partial graph (heal's delta, entrypoints===null) keeps the old semantics.
+  const surfaceOnly = provable && entrypoints > 0 && observed === 0;
+  // guard provenance: how many guards did SPARDA actually VERIFY (see a deny path in
+  // the body) vs only assert by name (opaque middleware/decorators it couldn't read).
+  // Honest signal — it does not change the verdict, but it tells you how much of the
+  // auth posture rests on trust vs proof.
+  const guards = graph ? graph.nodes.filter((n) => n.kind === 'guard') : [];
+  const guardsVerified = guards.filter((g) => g.meta?.verified).length;
+  // `safe` is the CI gate (block a risky deploy): a surface-only app has no
+  // critical/high findings and is NOT risky, so it does not fail the gate — it just
+  // isn't a positive proof. `clean` is the strong claim (PROVEN) and DOES require
+  // observed behavior, so a hollow "everything's fine" can never read as PROVEN.
   return {
     counts,
     entrypoints,
+    observed,
     provable,
+    surfaceOnly,
+    guards: guards.length,
+    guardsVerified,
     safe: provable && counts.critical === 0 && counts.high === 0,
-    clean: provable && findings.length === 0,
+    clean: provable && !surfaceOnly && findings.length === 0,
   };
 }
 

package/src/ubg/compile.js

@@ -7,6 +7,7 @@ import { detectStack } from '../detect.js';
 import { clearModuleCache } from './extract.js';
 import { extractExpress } from './express.js';
 import { extractNest } from './nestjs.js';
+import { extractMedusa } from './medusa.js';
 import { extractNext } from './nextjs.js';
 import { extractFastAPI } from './fastapi.js';
 import { extractOpenAPI } from './openapi.js';
@@ -30,6 +31,7 @@ export function compileUBG(
   const extractors = {
     express: () => extractExpress(cwd, stack.entryFile),
     nestjs: () => extractNest(cwd, stack.entryFile),
+    medusa: () => extractMedusa(cwd, stack.entryFile),
     nextjs: () => extractNext(cwd, stack.entryFile),
     fastapi: () => extractFastAPI(cwd, stack.entryFile, stack.pythonCmd),
     openapi: () => extractOpenAPI(cwd, stack.entryFile),