sparda-mcp 0.10.1 → 0.12.0

package/README.md

@@ -93,7 +93,7 @@ npx sparda-mcp apocalypse
 This command reads the compiled `.sparda/ubg.json` (with zero source code parsing at runtime) and discharges five static correctness obligations:
 * **Unguarded Mutation (Critical)**: Flags any mutation path that does not cross a security `guard`.
 * **Non-Atomic Aggregate Write (High)**: Flags when an API writes to multiple tables of the same Consistency Domain (Aggregate) outside a single transaction scope.
-* **Unvalidated Constrained Write (Medium)**: Flags writes into columns with SQL invariants (CHECK, NOT NULL, UNIQUE) without prior validation (Zod/Pydantic).
+* **Unvalidated Constrained Write (Medium)**: Flags writes into columns with declared invariants (CHECK, NOT NULL, UNIQUE — parsed from your `.sql` DDL **or `schema.prisma`**, Prisma enums included) without prior validation (Zod/Pydantic).
 * **Irreversible Observable Effect (High)**: Flags out-of-process actions (like Stripe charges) that happen alongside state writes without a structural compensation path (like a catch-refund).
 * **Aggregate Member Bypass (Info)**: Flags mutating a member table directly without routing through the aggregate root.
 
@@ -108,6 +108,59 @@ Subsequent runs will diff the candidate graph against this baseline to detect re
 
 If any Critical or High finding is found, `apocalypse` exits with a non-zero code to block your CI pipeline.
 
+**One step in your workflow — findings land in the GitHub Security tab (SARIF):**
+```yaml
+- uses: zyx77550/sparda@main
+  with:
+    sarif: 'true'
+```
+
+## Time Travel: Timeless
+
+Every production request is deterministic between its effects — the compiler knows exactly where the nondeterminism lives (db, http, clock, random, uuid: the effect nodes of the graph). Timeless records only those points (a few KB per request) and replays the request **byte-identically** against your current code, with the database, webhooks and clock virtualized from the recording:
+
+```bash
+npx sparda-mcp timeless                # list recorded flights
+npx sparda-mcp timeless replay <id>    # re-fly it — byte-identical or loud divergence
+npx sparda-mcp timeless export <id>    # the production bug is now a vitest test
+```
+
+Recording is two lines in your app (ESM), with deterministic sampling and GDPR redaction built in:
+```js
+import { getFlightBox } from 'sparda-mcp/src/flight/box.js';
+const box = getFlightBox(); box.arm();
+app.use(box.middleware({ sample: 100 }));   // 1 request in 100; passwords/tokens redacted by default
+const db = box.wrapClient(pgPool);           // your query client, tapped
+```
+
+The closed loop nobody else has: **production bug → recorded flight → failing test → AI writes the fix → `apocalypse` proves the fix breaks no guard, invariant or transaction → deploy.** Replay is per-request (concurrent-race capture is out of scope for v1 — stated, not hidden).
+
+## Any Backend On Earth: OpenAPI Lowering
+
+SPARDA parses Express, FastAPI and Next.js natively — and **every other stack through the format the industry already agreed on**. Go, Java, Rails, Laravel, .NET: if it has an OpenAPI spec, it compiles.
+
+```bash
+npx sparda-mcp ubg --openapi openapi.json
+```
+
+Security schemes become gating `guard` nodes, response schemas become typed returns, declared request bodies count as validated input. Pair the spec with your `.sql` or `schema.prisma` files and the full state layer — invariants, aggregates, state machines — fills in from declared truth. (JSON specs in v1; we refuse to half-parse YAML with zero dependencies.)
+
+## The Mirror VM: delete the framework, the app still answers
+
+The graph is not a diagram — it executes:
+
+```bash
+npx sparda-mcp mirror
+```
+
+```
+MIRROR — the graph is serving. 3 entrypoint(s) on http://127.0.0.1:4477
+  GET    /orders/{orderId}  → {amount, id, status}
+  POST   /orders  🔒 bearerAuth  → {amount, id, status}
+```
+
+No Express. No FastAPI. No source code — just `ubg.json` answering HTTP: guards actually deny (401), responses render the compiled return schemas, unknown paths 404 with the full route table. Front-end teams develop against backends that aren't deployed yet — or aren't written yet (point `mirror` at an OpenAPI spec). Every response carries `x-sparda-mirror: true`; the mirror serves declared behavior, it never invents business values.
+
 To undo everything: **`npx sparda-mcp remove`** restores your code byte-for-byte.
 
 ## The promise — every word is backed by a test in CI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.10.1",
+  "version": "0.12.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/apocalypse.js

@@ -0,0 +1,123 @@
+// commands/apocalypse.js — prove a deployment can't break the declared rules.
+// Compiles the tree to SBIR, discharges the static proof obligations, and —
+// when a baseline exists — proves the deploy removed no protection the
+// baseline had. Exit code 1 on any critical/high finding: this command is
+// built to sit in CI between "tests pass" and "deploy".
+//   sparda apocalypse                   check current tree (+ diff vs baseline if saved)
+//   sparda apocalypse --save-baseline   record the current graph as the reference
+//   sparda apocalypse --json            raw findings for tooling
+import fs from 'node:fs';
+import path from 'node:path';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { checkGraph, diffGraphs, verdictOf } from '../ubg/apocalypse.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+const ICONS = { critical: '✗', high: '✗', medium: '⚠', info: '·' };
+
+export async function runApocalypse(opts) {
+  const { graph } = compileUBG(opts.cwd, { write: false });
+  const canonical = canonicalizeGraph(graph);
+  const baselinePath = path.join(opts.cwd, '.sparda', 'ubg.baseline.json');
+
+  if (opts.saveBaseline) {
+    fs.mkdirSync(path.dirname(baselinePath), { recursive: true });
+    atomicWrite(baselinePath, JSON.stringify(canonical, null, 2) + '\n');
+    console.log(
+      `✓ Baseline saved: .sparda/ubg.baseline.json — future deploys are proven against it`,
+    );
+  }
+
+  const { findings: staticFindings, obligations } = checkGraph(canonical);
+  let diffFindings = [];
+  let hasBaseline = false;
+  if (!opts.saveBaseline && fs.existsSync(baselinePath)) {
+    hasBaseline = true;
+    try {
+      const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+      diffFindings = diffGraphs(baseline, canonical).findings;
+    } catch (err) {
+      console.error(`⚠ baseline unreadable (${err.message}) — static checks only`);
+    }
+  }
+
+  const findings = [...staticFindings, ...diffFindings];
+  const verdict = verdictOf(findings);
+
+  if (opts.sarif) {
+    const sarifPath = path.join(opts.cwd, '.sparda', 'apocalypse.sarif');
+    fs.mkdirSync(path.dirname(sarifPath), { recursive: true });
+    atomicWrite(sarifPath, JSON.stringify(toSarif(findings, canonical), null, 2) + '\n');
+    console.log(
+      `✓ SARIF written: .sparda/apocalypse.sarif (${findings.length} result(s))`,
+    );
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({ verdict, obligations, findings }, null, 2));
+  } else {
+    console.log(
+      `APOCALYPSE — deployment proof over ${canonical.nodes.length} nodes, ${canonical.edges.length} edges` +
+        (hasBaseline ? ' (baseline diff included)' : ''),
+    );
+    for (const f of findings) {
+      console.log(`  ${ICONS[f.severity]} [${f.severity}] ${f.rule} — ${f.message}`);
+      if (opts.verbose) for (const ev of f.evidence) console.log(`      evidence: ${ev}`);
+    }
+    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.`,
+      );
+    } else {
+      const c = verdict.counts;
+      console.log(
+        `${verdict.safe ? '⚠ RISKY' : '✗ NOT PROVEN'} — ${c.critical} critical, ${c.high} high, ${c.medium} medium, ${c.info} info`,
+      );
+    }
+  }
+
+  if (!verdict.safe) process.exitCode = 1; // CI gates on this
+  return { verdict, findings, obligations };
+}
+
+// SARIF 2.1.0 — GitHub code scanning eats this directly
+const SARIF_LEVEL = { critical: 'error', high: 'error', medium: 'warning', info: 'note' };
+
+function toSarif(findings, canonical) {
+  const nodeById = new Map(canonical.nodes.map((n) => [n.id, n]));
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: 'sparda-apocalypse',
+            informationUri: 'https://github.com/zyx77550/sparda',
+            rules: [...new Set(findings.map((f) => f.rule))].sort().map((id) => ({ id })),
+          },
+        },
+        results: findings.map((f) => {
+          const loc = nodeById.get(f.entrypoint)?.loc;
+          return {
+            ruleId: f.rule,
+            level: SARIF_LEVEL[f.severity] ?? 'warning',
+            message: { text: f.message },
+            ...(loc
+              ? {
+                  locations: [
+                    {
+                      physicalLocation: {
+                        artifactLocation: { uri: loc.file },
+                        region: { startLine: loc.line || 1 },
+                      },
+                    },
+                  ],
+                }
+              : {}),
+          };
+        }),
+      },
+    ],
+  };
+}

package/src/commands/mirror.js

@@ -0,0 +1,42 @@
+// commands/mirror.js — serve the compiled behavior, delete the framework.
+//   sparda mirror                 compile the tree (or --openapi spec) and serve it
+//   sparda mirror --port 5050     pick the port
+//   sparda ubg --openapi api.json && sparda mirror   any backend on earth
+// The graph answers HTTP: guards deny (401), responses come out typed from
+// the compiled return schemas, unknown paths list what the graph knows.
+// Front-ends develop against backends that aren't deployed — or written.
+import fs from 'node:fs';
+import path from 'node:path';
+import { compileUBG } from '../ubg/compile.js';
+import { createMirrorServer } from '../ubg/mirror.js';
+
+export async function runMirror(opts) {
+  // prefer the already-compiled artifact; compile fresh when absent
+  const artifact = path.join(opts.cwd, '.sparda', 'ubg.json');
+  let graph;
+  if (fs.existsSync(artifact) && !opts.openapi) {
+    graph = JSON.parse(fs.readFileSync(artifact, 'utf8'));
+  } else {
+    graph = JSON.parse(
+      compileUBG(opts.cwd, { write: false, openapi: opts.openapi ?? null }).json,
+    );
+  }
+
+  const { server, routes } = createMirrorServer(graph);
+  const port = Number(opts.port ?? 4477);
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', resolve);
+  });
+
+  console.log(
+    `MIRROR — the graph is serving. ${routes.length} entrypoint(s) on http://127.0.0.1:${port}`,
+  );
+  for (const r of routes) {
+    console.log(
+      `  ${r.method.toUpperCase().padEnd(6)} ${r.path}${r.guarded ? '  🔒 ' + r.guards.join(',') : ''}${r.returns ? '  → {' + Object.keys(r.returns).join(', ') + '}' : ''}`,
+    );
+  }
+  console.log('  (every response carries x-sparda-mirror: true — Ctrl+C to stop)');
+  return { server, routes, port };
+}

package/src/commands/openapi.js

@@ -0,0 +1,61 @@
+// commands/openapi.js — emit an OpenAPI 3.1 spec FROM the behavior graph.
+// We produce the standard the rest of the industry consumes: any backend
+// SPARDA can compile (Express, FastAPI, Next.js — or another spec via
+// --openapi) gets a valid, deterministic spec, richer than most hand-written
+// ones because it comes from what the code actually declares.
+//   sparda openapi                       write .sparda/openapi.json
+//   sparda openapi --out api.json        pick the path
+//   sparda openapi --json                print to stdout
+import path from 'node:path';
+import fs from 'node:fs';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { emitOpenAPI } from '../ubg/openapi-emit.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+export async function runOpenapi(opts) {
+  const { graph } = compileUBG(opts.cwd, {
+    write: false,
+    openapi: opts.openapi ?? null,
+  });
+  const title = packageNameOf(opts.cwd);
+  const spec = emitOpenAPI(canonicalizeGraph(graph), { title });
+  const body = JSON.stringify(spec, null, 2) + '\n';
+
+  if (opts.json) {
+    console.log(body);
+    return { spec };
+  }
+  const target = opts.out
+    ? path.resolve(opts.cwd, opts.out)
+    : path.join(opts.cwd, '.sparda', 'openapi.json');
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  atomicWrite(target, body);
+
+  const pathCount = Object.keys(spec.paths).length;
+  const opCount = Object.values(spec.paths).reduce(
+    (n, p) => n + Object.keys(p).length,
+    0,
+  );
+  console.log(
+    `✓ OpenAPI 3.1 emitted: ${rel(target, opts.cwd)} — ${pathCount} path(s), ${opCount} operation(s)`,
+  );
+  console.log(
+    '  SPARDA produces the standard others consume — feed it to Swagger UI or a codegen.',
+  );
+  return { spec, target };
+}
+
+function packageNameOf(cwd) {
+  try {
+    return (
+      JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).name ??
+      'sparda-compiled-api'
+    );
+  } catch {
+    return 'sparda-compiled-api';
+  }
+}
+
+const rel = (abs, cwd) =>
+  abs.startsWith(cwd) ? abs.slice(cwd.length + 1).replaceAll('\\', '/') : abs;

package/src/commands/ubg.js

@@ -9,6 +9,7 @@ export async function runUbg(opts) {
   const { report, json, outPath } = compileUBG(opts.cwd, {
     write: true,
     out: opts.out,
+    openapi: opts.openapi ?? null,
   });
 
   if (opts.json) {

package/src/commands/verify.js

@@ -0,0 +1,36 @@
+// commands/verify.js — prove the compiler's own laws on THIS project.
+// Runs the SBIR compiler-law audit and reports each check. Exit code 1 if any
+// law fails: run it in CI to guarantee the graph your tools trust was built
+// under determinism and soundness — not just asserted to be.
+//   sparda verify                 audit the detected app
+//   sparda verify --openapi s.json   audit an OpenAPI-lowered backend
+import { verifyProject } from '../ubg/verify.js';
+
+export async function runVerify(opts) {
+  const { checks, passed, total, ok } = verifyProject(opts.cwd, {
+    openapi: opts.openapi ?? null,
+  });
+
+  console.log(`VERIFY — SBIR compiler laws on this project (${passed}/${total} checks)`);
+  let lastLaw = null;
+  for (const c of checks) {
+    if (c.law !== lastLaw) {
+      console.log(`  ${c.law}`);
+      lastLaw = c.law;
+    }
+    console.log(
+      `    ${c.pass ? '✓' : '✗'} ${c.name}${c.pass || !c.detail ? '' : ` — ${c.detail}`}`,
+    );
+  }
+  if (ok) {
+    console.log(
+      '✓ PROVEN — every compiler law holds on this input. The graph is trustworthy.',
+    );
+  } else {
+    console.log(
+      '✗ LAW VIOLATED — the compiler broke its own contract on this input. This is a bug; please open an issue.',
+    );
+    process.exitCode = 1;
+  }
+  return { ok, checks };
+}

package/src/detect.js

@@ -199,6 +199,8 @@ function findExpressEntry(cwd, pkg) {
     'src/app.ts',
     'src/server.ts',
     'src/index.ts',
+    'src/main.ts', // Nx / NestJS-style monorepo layout
+    'main.ts',
     'app.ts',
     'server.ts',
     'index.ts',

package/src/flight/box.js

@@ -129,7 +129,22 @@ export function createFlightBox() {
 
   // Express middleware — mount early; the request's whole async tree records.
   // The flight is finalized and written on response finish.
-  function middleware({ cwd = process.cwd(), onFlight = null } = {}) {
+  //   sample: 1     record every request (default); N records every Nth —
+  //                 a deterministic counter, never Math.random (Law 3 applies
+  //                 to the recorder too)
+  //   redactKeys:   body keys scrubbed at record time, deep, case-insensitive.
+  //                 Redaction happens BEFORE the flight touches disk — the
+  //                 secret never exists in the artifact. Redacted flights
+  //                 replay fine as long as handlers don't echo those fields
+  //                 back (if they do, the replay diverges loudly — honest).
+  let requestCounter = 0;
+  function middleware({
+    cwd = process.cwd(),
+    onFlight = null,
+    sample = 1,
+    redactKeys = DEFAULT_REDACT_KEYS,
+  } = {}) {
+    const redactSet = new Set(redactKeys.map((k) => k.toLowerCase()));
     return function spardaFlightRecorder(req, res, next) {
       // replay wins over record: when the timeless CLI replays through an app
       // that mounts this recorder, the outer replay store must reach the taps
@@ -137,6 +152,7 @@ export function createFlightBox() {
       const outer = als.getStore();
       if (outer?.mode === 'replay') return next();
       if (process.env.SPARDA_FLIGHT === 'off') return next();
+      if (sample > 1 && requestCounter++ % sample !== 0) return next();
       const store = { mode: 'record', taps: [] };
       const chunks = [];
       const origWrite = res.write.bind(res);
@@ -155,7 +171,7 @@ export function createFlightBox() {
             method: req.method,
             url: req.originalUrl ?? req.url,
             headers: { 'content-type': req.headers['content-type'] ?? '' },
-            body: req.body ?? null,
+            body: redactDeep(req.body ?? null, redactSet),
           },
           response: {
             status: res.statusCode,
@@ -171,14 +187,17 @@ export function createFlightBox() {
     };
   }
 
-  // replay plumbing — one store per replayed request
-  function makeReplayStore(flight) {
+  // replay plumbing — one store per replayed request.
+  // lenient: labels may differ (a FIX reformulates a query — same kind, same
+  // order, new text); relabels are reported, never silent. Running out of
+  // taps stays fatal in both modes — fail-loud is not negotiable.
+  function makeReplayStore(flight, { lenient = false } = {}) {
     const queues = new Map();
     for (const tap of flight.taps) {
       if (!queues.has(tap.kind)) queues.set(tap.kind, []);
       queues.get(tap.kind).push(tap);
     }
-    return { mode: 'replay', queues, divergences: [] };
+    return { mode: 'replay', queues, divergences: [], relabels: [], lenient };
   }
 
   const runWith = (store, fn) => als.run(store, fn);
@@ -190,6 +209,36 @@ function tapOut(store, kind, label, result) {
   store.taps.push({ seq: store.taps.length, kind, label, result });
 }
 
+// GDPR hygiene: these never reach the flight file. Only the content-type
+// header is ever captured, so headers (authorization, cookie) are safe by
+// construction — this list covers the request BODY.
+export const DEFAULT_REDACT_KEYS = [
+  'password',
+  'passwd',
+  'secret',
+  'token',
+  'apikey',
+  'api_key',
+  'authorization',
+  'cookie',
+  'creditcard',
+  'card_number',
+  'cvv',
+  'ssn',
+];
+
+function redactDeep(value, redactSet, depth = 0) {
+  if (depth > 6 || value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map((v) => redactDeep(v, redactSet, depth + 1));
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    out[k] = redactSet.has(k.toLowerCase())
+      ? '[REDACTED]'
+      : redactDeep(v, redactSet, depth + 1);
+  }
+  return out;
+}
+
 // strict FIFO per kind, label-checked — the "quasi infallible" contract:
 // the replayed code must ask reality the SAME questions in the SAME order
 function takeTap(store, kind, label) {
@@ -204,6 +253,10 @@ function takeTap(store, kind, label) {
     );
   }
   if (tap.label !== label) {
+    if (store.lenient) {
+      store.relabels.push({ kind, was: tap.label, now: label });
+      return tap.result;
+    }
     const d = { kind, expected: tap.label, got: label };
     store.divergences.push(d);
     throw new FlightDivergence(

package/src/index.js

@@ -16,6 +16,7 @@ const getOpt = (name, dflt) => {
 const opts = {
   yes: flags.has('--yes') || flags.has('-y'),
   saveBaseline: flags.has('--save-baseline'),
+  sarif: flags.has('--sarif'),
   verbose: flags.has('--verbose'),
   quiet: flags.has('--quiet'),
   probe: flags.has('--probe'),
@@ -26,6 +27,7 @@ const opts = {
   germinate: flags.has('--germinate'),
   port: getOpt('port', null),
   out: getOpt('out', null),
+  openapi: getOpt('openapi', null),
   cwd: process.cwd(),
 };
 
@@ -110,6 +112,21 @@ try {
       await runTimeless(opts, rest);
       break;
     }
+    case 'mirror': {
+      const { runMirror } = await import('./commands/mirror.js');
+      await runMirror(opts);
+      break;
+    }
+    case 'openapi': {
+      const { runOpenapi } = await import('./commands/openapi.js');
+      await runOpenapi(opts);
+      break;
+    }
+    case 'verify': {
+      const { runVerify } = await import('./commands/verify.js');
+      await runVerify(opts);
+      break;
+    }
     default:
       console.log(`SPARDA v${VERSION} — Turn any codebase into an MCP server.
 
@@ -129,6 +146,9 @@ Usage:
   npx sparda-mcp ubg       Compile the codebase to its Unified Behavior Graph (.sparda/ubg.json)
   npx sparda-mcp apocalypse  Prove the deploy: guards, invariants, transactions, aggregates (--save-baseline)
   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)
+  npx sparda-mcp verify    Prove the compiler's own laws (determinism, soundness, round-trip) on this app
 
 Flags: --yes (skip prompts)  --port <n>  --quiet  --verbose
        --probe (init: also run the app to discover dynamic routes the AST missed)

package/src/ubg/compile.js

@@ -8,7 +8,9 @@ import { clearModuleCache } from './extract.js';
 import { extractExpress } from './express.js';
 import { extractNext } from './nextjs.js';
 import { extractFastAPI } from './fastapi.js';
+import { extractOpenAPI } from './openapi.js';
 import { parseSqlSchemas } from './sql.js';
+import { parsePrismaSchemas } from './prisma.js';
 import { translate } from './translate.js';
 import { linkDataFlow } from './link.js';
 import { optimize } from './pipeline.js';
@@ -17,15 +19,18 @@ import { serializeGraph, sourceHashOf, writeGraph } from './serialize.js';
 
 export function compileUBG(
   cwd,
-  { write = true, out = null, optimizePasses = true } = {},
+  { write = true, out = null, optimizePasses = true, openapi = null } = {},
 ) {
   clearModuleCache(); // each compile run parses fresh — no stale-file ghosts
 
-  const stack = detectStack(cwd);
+  // --openapi: the universal lowering — no framework detection, ANY backend
+  // that carries a spec enters the graph (Go, Java, Rails, .NET, whatever)
+  const stack = openapi ? { framework: 'openapi', entryFile: openapi } : detectStack(cwd);
   const extractors = {
     express: () => extractExpress(cwd, stack.entryFile),
     nextjs: () => extractNext(cwd, stack.entryFile),
     fastapi: () => extractFastAPI(cwd, stack.entryFile, stack.pythonCmd),
+    openapi: () => extractOpenAPI(cwd, stack.entryFile),
   };
   if (!extractors[stack.framework]) {
     throw Object.assign(
@@ -36,13 +41,17 @@ export function compileUBG(
   const extracted = extractors[stack.framework]();
 
   const sql = parseSqlSchemas(cwd);
+  const prisma = parsePrismaSchemas(cwd);
+  // DDL beats ORM on a name collision — the database is the closer truth
+  const sqlNames = new Set(sql.tables.map((t) => t.name));
+  const tables = [...sql.tables, ...prisma.tables.filter((t) => !sqlNames.has(t.name))];
 
   const graph = translate({
     framework: stack.framework,
     routes: extracted.routes,
     globalMiddlewares: extracted.globalMiddlewares,
     helpers: extracted.helpers,
-    tables: sql.tables,
+    tables,
   });
   validateGraph(graph);
 
@@ -56,7 +65,7 @@ export function compileUBG(
     entry: stack.entryFile,
     sourceHash: sourceHashOf(cwd, [
       ...extracted.scannedFiles,
-      ...sql.tables.map((t) => t.sourceFile),
+      ...tables.map((t) => t.sourceFile),
     ]),
   };
 
@@ -64,10 +73,11 @@ export function compileUBG(
     framework: stack.framework,
     entry: stack.entryFile,
     routes: extracted.routes.length,
-    tables: sql.tables.length,
+    tables: tables.length,
+    ...(prisma.tables.length ? { prismaTables: prisma.tables.length } : {}),
     link: linkReport,
     passes: passReports,
-    skipped: [...extracted.skipped, ...sql.skipped],
+    skipped: [...extracted.skipped, ...sql.skipped, ...prisma.skipped],
     counts: countGraph(graph),
   };