sparda-mcp 0.9.0 → 0.12.0

package/README.md

@@ -84,6 +84,83 @@ To output raw JSON for integration:
 npx sparda-mcp report --json
 ```
 
+## Deployment Proof: Apocalypse
+
+SPARDA's Behavior Graph is a formal model of your system. Instead of waiting for runtime failures or relying on static analysis vibes, you can statically prove the safety of your backend before any deployment:
+```bash
+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 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.
+
+To save your current graph as a safe baseline:
+```bash
+npx sparda-mcp apocalypse --save-baseline
+```
+Subsequent runs will diff the candidate graph against this baseline to detect regression vectors:
+* Deletion of any security `guard` (Critical).
+* Deletion of a database SQL invariant (High).
+* API blast radius expansion (Medium).
+
+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/SKILL.md

@@ -1,40 +1,30 @@
 ---
 name: sparda-mcp
 description: >-
-  Drive a SPARDA-generated MCP server to its full potential. Use this whenever
-  you are connected to an MCP server built by SPARDA (sparda-mcp) — recognizable
-  by the tools `sparda_get_context`, `sparda_info`, `sparda_confirm`, or composite
-  tools labelled "[Labs circuit]". It teaches the call-context-first workflow, how
-  to exploit the response-recycling flywheel, the circuit-breaker, crystallized
-  circuits and adaptive immunity, and the mandatory two-phase confirm protocol for
-  write tools. Reach for it before calling raw endpoints, before any write, or when
-  a tool returns 202 (awaiting confirmation) or 503 (quarantined).
+  Drive a SPARDA compiled Behavior Runtime to its full potential. Use this whenever
+  you are connected to a backend running the SPARDA Runtime (compiled into a SPARDA
+  Behavior Graph - SBG) — recognizable by the tools `sparda_get_context`, `sparda_info`,
+  `sparda_confirm`, or composite tools. It teaches the graph-context-first workflow,
+  how to exploit the response-recycling flywheel, the circuit-breaker, crystallized
+  circuits, offline Twin simulations, and the two-phase confirm protocol for writes.
 ---
 
-# Driving a SPARDA MCP server
+# Driving a SPARDA Behavior Runtime
 
-A SPARDA server is **not** a flat list of HTTP endpoints. SPARDA injected a live
-`/mcp` router *inside a real running app*, so its tools are that app's actual
-routes — wrapped in an intelligence layer that makes repeated use **cheaper** (it
-recycles stable answers from memory) and **safer** (it quarantines failing tools
-and gates writes behind human confirmation). Used naively it's just an API. Used
-well, it gets faster and safer the more you call it. This skill is how to use it
-well.
+A SPARDA server is driven by a compiled **SPARDA Behavior Graph (SBG)**. Instead of exposing raw, disconnected endpoints, SPARDA has compiled the host application's states, transitions, permissions, and side-effects into a deterministic behavioral model. The local **SPARDA Runtime** dynamically executes this graph inside the live host process, powering the MCP interface, the Twin simulation clone, and the Immune system offline.
 
 ## Rule 0 — call `sparda_get_context` first, every session
 
-Before anything else, call **`sparda_get_context`** (no params). It returns the
-*live* picture, so you never guess the surface:
+Before anything else, call **`sparda_get_context`** (no params). It returns the *live* state of the SPARDA Behavior Graph:
 
-- the enabled tools + their descriptions, and SPARDA's suggested **workflows**;
-- `runtime` — current `/mcp/stats` (per-tool call/error counts, tool "purity",
-  quarantine state);
-- the last ~20 **events** (errors, latency anomalies, immune diagnoses);
-- **immune memory** (known failure signatures + cached fixes);
-- **recycling** stats (how many calls were served from memory);
-- a `behavior` snapshot (which response fields are stable).
+- the active routes/tools, workflows, and type-propagated schemas;
+- `runtime` — current stats (calls, errors, quarantine states, Twin mode active);
+- the last ~20 **events** (errors, latency anomalies, immune alerts);
+- **immune memory** (cached antibodies and error diagnoses);
+- **recycling** metrics (flywheel memory hit rates);
+- a `behavior` snapshot of stable variables.
 
-Read it before acting. `sparda_info` gives a lighter summary if you only need counts.
+Read it to orient yourself inside the graph. `sparda_info` gives a lighter summary of counts.
 
 ## The tools you'll see
 
@@ -146,6 +136,7 @@ Writes are **disabled by default**. The protocol is not optional:
 - **General health** → `sparda doctor` checks Node version, framework detection,
   manifest validity, the semantic/immune cache, host reachability, and quarantine;
   it exits non-zero so it can gate CI.
+- **Formal Deployment Proof** → `sparda apocalypse` reads the compiled graph (`ubg.json`) and proves five correctness obligations: catches unguarded mutations, non-atomic aggregate writes, unvalidated writes to constrained tables, uncompensated observable effects, and aggregate root bypasses. Run `sparda apocalypse --save-baseline` to store the reference graph; subsequent runs diff against the baseline to catch dropped guards, dropped SQL invariants, or grown blast radiuses.
 - **Clone learning / Transfer sémantique** → Use `sparda seed export` to package your app's descriptions, workflows, and antibodies. Then `sparda seed import --germinate` in another clone to import the structure and germinate simulated twin instances.
 - **Learn exemplars** → Start your live app and run `sparda twin --learn` to fetch actual response data and construct `.sparda/twin.json` locally.
 

package/package.json

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

@@ -0,0 +1,187 @@
+// commands/timeless.js — production bugs become unit tests.
+//   sparda timeless                 list recorded flights
+//   sparda timeless replay <id>     re-fly the request against current code
+//   sparda timeless export <id>     generate a vitest test that replays it
+// Recording side: mount the recorder in the app (2 lines, documented in the
+// README) — `const flight = createFlightBox(); app.use(flight.middleware())`.
+// Replay imports the real entry file with `listen()` suppressed, feeds every
+// recorded tap back in strict order, and compares the response byte-for-byte.
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import { pathToFileURL } from 'node:url';
+import { detectStack } from '../detect.js';
+import { getFlightBox } from '../flight/box.js';
+import { replayFlight } from '../flight/replayer.js';
+import { listFlights, loadFlight } from '../flight/format.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+const err = (message, hint) => Object.assign(new Error(message), { code: 'USER', hint });
+
+export async function runTimeless(opts, args) {
+  const [sub, id] = args.filter((a) => !a.startsWith('--'));
+
+  if (!sub || sub === 'list') return list(opts);
+  if (sub === 'replay') return replay(opts, requireId(id));
+  if (sub === 'export') return exportTest(opts, requireId(id));
+  throw err(
+    `unknown timeless subcommand "${sub}"`,
+    'use: list | replay <id> | export <id>',
+  );
+}
+
+const requireId = (id) => {
+  if (!id) throw err('flight id required', 'run `sparda timeless` to list flights');
+  return id;
+};
+
+function list(opts) {
+  const flights = listFlights(opts.cwd);
+  if (!flights.length) {
+    console.log(
+      'No flights recorded. Mount the recorder in your app (ESM):\n' +
+        "  import { getFlightBox } from 'sparda-mcp/src/flight/box.js';\n" +
+        '  const box = getFlightBox(); box.arm();\n' +
+        '  app.use(box.middleware());\n' +
+        '  const db = box.wrapClient(rawDb); // your query client\n' +
+        "  (CJS: const { getFlightBox } = await import('sparda-mcp/src/flight/box.js'))",
+    );
+    return { flights };
+  }
+  console.log(`${flights.length} flight(s) in .sparda/flight/`);
+  for (const f of flights) {
+    const { request, response } = loadFlight(opts.cwd, f);
+    console.log(
+      `  ${f}  ${request.method} ${request.url} → ${response.status} (${response.body.length}b, ${loadFlight(opts.cwd, f).taps.length} taps)`,
+    );
+  }
+  return { flights };
+}
+
+async function replay(opts, id) {
+  const flight = loadFlight(opts.cwd, id);
+  // the SHARED box: if the app integrates the recorder, its wrapClient rides
+  // the same AsyncLocalStorage this replay store lands on — load it BEFORE
+  // the app so both resolve the singleton
+  const box = getFlightBox();
+  const app = await loadApp(opts.cwd);
+  box.arm();
+  let result;
+  try {
+    result = await replayFlight(app, flight, box);
+  } finally {
+    box.disarm();
+  }
+
+  console.log(
+    `TIMELESS — replaying ${flight.request.method} ${flight.request.url} (${flight.taps.length} taps virtualized)`,
+  );
+  if (result.match) {
+    console.log(
+      `✓ byte-identical replay — status ${result.actual.status}, every tap consumed, zero divergence`,
+    );
+  } else {
+    if (!result.statusMatch)
+      console.log(
+        `  ✗ status: expected ${result.expected.status}, got ${result.actual.status}`,
+      );
+    if (!result.bodyMatch)
+      console.log(
+        `  ✗ body differs\n    expected: ${result.expected.body.slice(0, 200)}\n    actual:   ${result.actual.body.slice(0, 200)}`,
+      );
+    for (const d of result.divergences)
+      console.log(
+        `  ✗ divergence: expected ${d.kind} "${d.expected}", code asked "${d.got}"`,
+      );
+    for (const l of result.leftover)
+      console.log(
+        `  ✗ ${l.unconsumed} unconsumed ${l.kind} tap(s) — the code skipped step(s)`,
+      );
+    console.log(
+      '✗ NOT identical — the code no longer does what it did during the flight',
+    );
+    process.exitCode = 1;
+  }
+  return { result };
+}
+
+async function exportTest(opts, id) {
+  const flight = loadFlight(opts.cwd, id);
+  const stack = detectStack(opts.cwd);
+  if (stack.framework !== 'express')
+    throw err(
+      'timeless export supports Express apps in v1',
+      'FastAPI replay is a later round',
+    );
+
+  const testDir = path.join(opts.cwd, 'tests');
+  fs.mkdirSync(testDir, { recursive: true });
+  const testFile = path.join(testDir, `flight-${id}.test.js`);
+  const relEntry = path
+    .relative(testDir, path.resolve(opts.cwd, stack.entryFile))
+    .split(path.sep)
+    .join('/');
+
+  atomicWrite(
+    testFile,
+    `// flight-${id}.test.js — generated by \`sparda timeless export ${id}\`
+// Replays a recorded production request against the current code. A failure
+// means the behavior changed: if the change is the intended fix, re-record
+// the flight and re-export — this file asserts the PAST, on purpose.
+import { describe, it, expect } from 'vitest';
+import { getFlightBox } from 'sparda-mcp/src/flight/box.js';
+import { replayFlight } from 'sparda-mcp/src/flight/replayer.js';
+import { loadFlight } from 'sparda-mcp/src/flight/format.js';
+import appModule from '${relEntry.startsWith('.') ? relEntry : './' + relEntry}';
+
+describe('flight ${id} — ${flight.request.method} ${flight.request.url}', () => {
+  it('replays byte-identically', async () => {
+    const app = appModule.default ?? appModule;
+    const flight = loadFlight(process.cwd(), '${id}');
+    // the SHARED box — the app's own wrapClient must see the replay store
+    const box = getFlightBox();
+    box.arm();
+    try {
+      const result = await replayFlight(app, flight, box);
+      expect(result.divergences).toEqual([]);
+      expect(result.actual.status).toBe(result.expected.status);
+      expect(result.bodyMatch).toBe(true);
+      expect(result.leftover).toEqual([]);
+    } finally {
+      box.disarm();
+    }
+  });
+});
+`,
+  );
+  console.log(`✓ Test written: tests/flight-${id}.test.js — the bug is now a unit test`);
+  return { testFile };
+}
+
+// import the real entry with listen() suppressed — replay never binds ports
+async function loadApp(cwd) {
+  const stack = detectStack(cwd);
+  if (stack.framework !== 'express')
+    throw err(
+      'timeless replay supports Express apps in v1',
+      'FastAPI replay is a later round',
+    );
+  const origListen = http.Server.prototype.listen;
+  http.Server.prototype.listen = function suppressedListen(...args) {
+    const cb = args.find((a) => typeof a === 'function');
+    if (cb) setImmediate(cb);
+    return this;
+  };
+  try {
+    const mod = await import(pathToFileURL(path.resolve(cwd, stack.entryFile)).href);
+    const app = mod.default ?? mod;
+    if (typeof app !== 'function')
+      throw err(
+        'the entry file does not export the Express app',
+        'add `module.exports = app` (CJS) or `export default app` (ESM) to your entry',
+      );
+    return app;
+  } finally {
+    http.Server.prototype.listen = origListen;
+  }
+}

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) {
@@ -44,7 +45,16 @@ export async function runUbg(opts) {
       console.log(
         `  ${p.pass}: ${names.length} domain(s) — ${names.join(', ')}${p.cycles.length ? ` (⚠ FK cycle: ${p.cycles.join(', ')})` : ''}`,
       );
-    }
+    } else if (p.pass === 'CapabilityExtraction' && p.capabilities)
+      console.log(
+        `  ${p.pass}: ${p.capabilities} capability(ies), ${p.guardsAnnotated} guard(s) annotated`,
+      );
+    else if (p.pass === 'ResourceLifetimes' && p.annotated)
+      console.log(
+        `  ${p.pass}: ${p.annotated} state(s)${p.immortal.length ? ` — immortal: ${p.immortal.join(', ')}` : ''}`,
+      );
+    else if (p.pass === 'StateMachineInference' && p.machines)
+      console.log(`  ${p.pass}: ${p.machines} machine(s) inferred`);
   }
 
   if (report.link.inferredTables.length)

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',