sparda-mcp 0.8.1 → 0.10.1

package/README.md

@@ -6,23 +6,27 @@
 
 <br/>
 
-**Your AI can write code. It still can't operate your app.**
+**Compile your backend into a deterministic behavior runtime.**
 
-Claude, Cursor & friends read your *files* — not your *running product*. They can
-refactor a controller, but they can't create an order, fetch a real user, or see why
-production is failing. And giving an AI real access to your API usually means: write
-an OpenAPI spec, build an MCP server, host it, secure it, keep it in sync with every
-route change — and pray it never `DELETE`s the wrong row. Days of glue code, per
-project, forever drifting.
+For twenty years, software communicated via APIs. Then AI agents arrived. The industry's response was simply to expose more endpoints (MCP). But an agent doesn't understand your application; it only sees a list of disconnected tools. That is enough for a human, but not for an autonomous machine.
 
-SPARDA deletes that work:
+SPARDA analyzes your Express, FastAPI, or Next.js application, extracts its behavior, and compiles it into a **SPARDA Behavior Graph (SBG)**. 
+
+This graph acts as a local, deterministic runtime that powers:
+* **MCP Server Integration**: Exposing your endpoints to AI clients dynamically.
+* **SPARDA Twin**: An executable, offline simulation clone of your backend for safe agent testing.
+* **SPARDA Immune**: Real-time graph-based anomaly defense, latency alerts, and auto-quarantine.
+* **SPARDA Evolution**: Statically inferred grammar mapping and in-memory workflow optimization.
+
+All executed 100% locally, with zero runtime dependencies and zero cloud connection.
 
 ```bash
-npx sparda-mcp init   # scan your Express/FastAPI app, inject the MCP router — 3 minutes
-npx sparda-mcp dev    # connect Claude Desktop / Claude Code. Done.
+npx sparda-mcp init   # Scan your app, compile the UBG, inject the SPARDA Runtime
+npx sparda-mcp dev    # Connect Claude Desktop / Cursor over stdio
 ```
 
-No OpenAPI spec. No account. No API key. No server to host.
+No OpenAPI spec to write. No cloud account. No API key. No server to host.
+Exposing raw APIs to AI is the old way. SPARDA compiles the whole system's behavior.
 
 ## Quickstart
 
@@ -80,6 +84,30 @@ 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 SQL invariants (CHECK, NOT NULL, UNIQUE) 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.
+
 To undo everything: **`npx sparda-mcp remove`** restores your code byte-for-byte.
 
 ## The promise — every word is backed by a test in CI
@@ -169,6 +197,7 @@ runtime, so the guidance never goes stale.
 
 ## Security posture (honest)
 - 4 runtime dependencies, exact-pinned.
+- **Dynamic Local Key Resolution.** The generated router contains no baked secrets. It resolves authorization keys at runtime from the `SPARDA_LOCAL_KEY` environment variable or the local gitignored `.sparda/key` file, and fails closed (503) when neither is found. For custom production or staging setups, you can override this behavior by exposing `SPARDA_LOCAL_KEY` in your environment.
 - Local key on every router call; self-reference loop protection; 30s timeouts; 8 KB output truncation.
 - AST-positioned injection with backup and post-injection re-parse; `npx sparda-mcp remove` leaves a clean git diff.
 - Persistence is **value-free**: SPARDA records structure (tool names, field names, fingerprints), never your payloads.

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.8.1",
+  "version": "0.10.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/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

@@ -0,0 +1,80 @@
+// commands/ubg.js — compile the codebase to its Unified Behavior Graph.
+// The UBG is the IR every future SPARDA tool reads (time-travel debuggers,
+// deploy provers, state-machine runtimes): compile once here, write passes
+// there. Artifact: .sparda/ubg.json — regenerable, deterministic, never
+// committed. `--json` prints the raw graph, `--out <file>` redirects it.
+import { compileUBG } from '../ubg/compile.js';
+
+export async function runUbg(opts) {
+  const { report, json, outPath } = compileUBG(opts.cwd, {
+    write: true,
+    out: opts.out,
+  });
+
+  if (opts.json) {
+    console.log(json);
+    return { report };
+  }
+
+  const { counts } = report;
+  console.log(
+    `✓ UBG compiled: ${rel(outPath, opts.cwd)} — ${counts.totalNodes} nodes, ${counts.totalEdges} edges`,
+  );
+  console.log(
+    `  ${report.framework} · ${report.routes} routes · ${report.tables} SQL tables`,
+  );
+  console.log(`  Nodes: ${fmtCounts(counts.nodes)}`);
+  console.log(`  Edges: ${fmtCounts(counts.edges)}`);
+
+  for (const p of report.passes) {
+    if (p.pass === 'DeadPathElimination' && p.removed)
+      console.log(`  ${p.pass}: ${p.removed} dead node(s) removed`);
+    else if (p.pass === 'StateMinimization' && p.merged)
+      console.log(`  ${p.pass}: ${p.merged} logic block(s) merged`);
+    else if (p.pass === 'TypePropagation' && (p.resolved || p.entrypointsTyped))
+      console.log(
+        `  ${p.pass}: ${p.entrypointsTyped} entrypoint return schema(s), ${p.resolved} type(s) resolved`,
+      );
+    else if (p.pass === 'EffectAlgebra' && p.classified)
+      console.log(
+        `  ${p.pass}: ${p.classified} effect(s) classified, ${p.observable} observable`,
+      );
+    else if (p.pass === 'ConsistencyDomains' && Object.keys(p.domains ?? {}).length) {
+      const names = Object.keys(p.domains).sort();
+      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)
+    console.log(
+      `  ⚠ tables referenced in code but absent from .sql schemas: ${report.link.inferredTables.join(', ')}`,
+    );
+  if (report.skipped.length) {
+    console.log(`  · ${report.skipped.length} construct(s) out of static reach:`);
+    for (const s of report.skipped.slice(0, opts.verbose ? 100 : 5))
+      console.log(`    - ${s.reason}${s.file ? ` (${s.file})` : ''}`);
+    if (!opts.verbose && report.skipped.length > 5)
+      console.log(`    … ${report.skipped.length - 5} more (--verbose)`);
+  }
+  return { report };
+}
+
+const fmtCounts = (obj) =>
+  Object.entries(obj)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, v]) => `${k} ${v}`)
+    .join(' · ');
+
+const rel = (abs, cwd) =>
+  abs.startsWith(cwd) ? abs.slice(cwd.length + 1).replaceAll('\\', '/') : abs;

package/src/flight/box.js

@@ -0,0 +1,245 @@
+// flight/box.js — the FlightBox: one set of patches, two modes.
+// In RECORD mode every nondeterminism point (fetch, Date.now, Math.random,
+// crypto.randomUUID, wrapped db clients) passes through to reality and leaves
+// a tap behind. In REPLAY mode the same points are fed the recorded values in
+// strict FIFO order per kind — label-checked, fail-loud: any mismatch is a
+// FlightDivergence, never a silent fuzzy match. Code OUTSIDE a request
+// context is untouched (AsyncLocalStorage decides), so arming the box in
+// production changes nothing for non-instrumented paths.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { saveFlight } from './format.js';
+
+const MAX_BODY_BYTES = 262144; // 256 KB per recorded http body — bounded flights
+
+export class FlightDivergence extends Error {
+  constructor(message, detail = {}) {
+    super(message);
+    this.name = 'FlightDivergence';
+    this.detail = detail;
+  }
+}
+
+export function createFlightBox() {
+  const als = new AsyncLocalStorage();
+  const originals = {};
+  let armed = false;
+
+  function arm() {
+    if (armed) return;
+    armed = true;
+    originals.fetch = globalThis.fetch;
+    originals.dateNow = Date.now;
+    originals.random = Math.random;
+    originals.randomUUID = globalThis.crypto?.randomUUID?.bind(globalThis.crypto);
+
+    Date.now = function spardaDateNow() {
+      const store = als.getStore();
+      if (!store) return originals.dateNow();
+      if (store.mode === 'record') {
+        const v = originals.dateNow();
+        tapOut(store, 'time', 'Date.now', v);
+        return v;
+      }
+      return takeTap(store, 'time', 'Date.now');
+    };
+
+    Math.random = function spardaRandom() {
+      const store = als.getStore();
+      if (!store) return originals.random();
+      if (store.mode === 'record') {
+        const v = originals.random();
+        tapOut(store, 'random', 'Math.random', v);
+        return v;
+      }
+      return takeTap(store, 'random', 'Math.random');
+    };
+
+    if (originals.randomUUID) {
+      Object.defineProperty(globalThis.crypto, 'randomUUID', {
+        configurable: true,
+        value: function spardaRandomUUID() {
+          const store = als.getStore();
+          if (!store) return originals.randomUUID();
+          if (store.mode === 'record') {
+            const v = originals.randomUUID();
+            tapOut(store, 'uuid', 'crypto.randomUUID', v);
+            return v;
+          }
+          return takeTap(store, 'uuid', 'crypto.randomUUID');
+        },
+      });
+    }
+
+    globalThis.fetch = async function spardaFetch(input, init) {
+      const store = als.getStore();
+      if (!store) return originals.fetch(input, init);
+      const url = typeof input === 'string' ? input : (input?.url ?? String(input));
+      const method = (init?.method ?? 'GET').toUpperCase();
+      const label = `${method} ${url}`;
+      if (store.mode === 'record') {
+        const res = await originals.fetch(input, init);
+        const text = (await res.text()).slice(0, MAX_BODY_BYTES);
+        const headers = { 'content-type': res.headers.get('content-type') ?? '' };
+        tapOut(store, 'http', label, { status: res.status, headers, body: text });
+        return new Response(text, { status: res.status, headers });
+      }
+      const rec = takeTap(store, 'http', label);
+      return new Response(rec.body, { status: rec.status, headers: rec.headers });
+    };
+  }
+
+  function disarm() {
+    if (!armed) return;
+    armed = false;
+    globalThis.fetch = originals.fetch;
+    Date.now = originals.dateNow;
+    Math.random = originals.random;
+    if (originals.randomUUID)
+      Object.defineProperty(globalThis.crypto, 'randomUUID', {
+        configurable: true,
+        value: originals.randomUUID,
+      });
+  }
+
+  // any client exposing .query()/.execute() — pg, mysql2, sqlite wrappers …
+  function wrapClient(client, name = 'db') {
+    const wrapMethod = (method) =>
+      async function spardaQuery(...args) {
+        const store = als.getStore();
+        if (!store) return client[method](...args);
+        const label = `${name}.${method}:${String(args[0]).slice(0, 60)}`;
+        if (store.mode === 'record') {
+          const result = await client[method](...args);
+          tapOut(store, 'db', label, jsonClone(result, label));
+          return result;
+        }
+        return takeTap(store, 'db', label);
+      };
+    return new Proxy(client, {
+      get(target, prop, receiver) {
+        if (
+          (prop === 'query' || prop === 'execute') &&
+          typeof target[prop] === 'function'
+        )
+          return wrapMethod(prop);
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+  }
+
+  // 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 } = {}) {
+    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
+      // untouched — re-recording a replay would shadow it with live values
+      const outer = als.getStore();
+      if (outer?.mode === 'replay') return next();
+      if (process.env.SPARDA_FLIGHT === 'off') return next();
+      const store = { mode: 'record', taps: [] };
+      const chunks = [];
+      const origWrite = res.write.bind(res);
+      const origEnd = res.end.bind(res);
+      res.write = (chunk, ...rest) => {
+        if (chunk) chunks.push(Buffer.from(chunk));
+        return origWrite(chunk, ...rest);
+      };
+      res.end = (chunk, ...rest) => {
+        if (chunk && typeof chunk !== 'function') chunks.push(Buffer.from(chunk));
+        return origEnd(chunk, ...rest);
+      };
+      res.on('finish', () => {
+        const flight = {
+          request: {
+            method: req.method,
+            url: req.originalUrl ?? req.url,
+            headers: { 'content-type': req.headers['content-type'] ?? '' },
+            body: req.body ?? null,
+          },
+          response: {
+            status: res.statusCode,
+            headers: { 'content-type': res.getHeader('content-type') ?? '' },
+            body: Buffer.concat(chunks).toString('utf8').slice(0, MAX_BODY_BYTES),
+          },
+          taps: store.taps,
+        };
+        const saved = saveFlight(cwd, flight);
+        if (onFlight) onFlight(saved, flight);
+      });
+      als.run(store, next);
+    };
+  }
+
+  // replay plumbing — one store per replayed request
+  function makeReplayStore(flight) {
+    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: [] };
+  }
+
+  const runWith = (store, fn) => als.run(store, fn);
+
+  return { arm, disarm, wrapClient, middleware, makeReplayStore, runWith };
+}
+
+function tapOut(store, kind, label, result) {
+  store.taps.push({ seq: store.taps.length, kind, label, result });
+}
+
+// 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) {
+  const queue = store.queues.get(kind);
+  const tap = queue?.shift();
+  if (!tap) {
+    const d = { kind, expected: null, got: label };
+    store.divergences.push(d);
+    throw new FlightDivergence(
+      `replay diverged: code asked for ${kind} "${label}" but the flight has no more ${kind} taps`,
+      d,
+    );
+  }
+  if (tap.label !== label) {
+    const d = { kind, expected: tap.label, got: label };
+    store.divergences.push(d);
+    throw new FlightDivergence(
+      `replay diverged: flight expected ${kind} "${tap.label}", code asked for "${label}"`,
+      d,
+    );
+  }
+  return tap.result;
+}
+
+function jsonClone(value, label) {
+  try {
+    const s = JSON.stringify(value);
+    if (s === undefined) throw new Error('undefined');
+    return JSON.parse(s);
+  } catch {
+    // honesty over convenience: an unserializable tap cannot replay — record
+    // the fact so replay fails loudly instead of returning garbage
+    throw new FlightDivergence(`tap "${label}" returned an unserializable value`, {
+      label,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Process singleton — THE box for app integration and the timeless CLI.
+// The app's wrapClient and the replayer must share ONE AsyncLocalStorage or
+// replay stores are invisible to the app's taps (silent passthrough to the
+// real db — the exact failure mode this singleton exists to kill). Module
+// caching guarantees identity as long as both sides resolve the same
+// sparda-mcp install, which `npx sparda` inside the app's project does.
+// createFlightBox() stays exported for isolated tests.
+// ---------------------------------------------------------------------------
+let singleton = null;
+
+export function getFlightBox() {
+  if (!singleton) singleton = createFlightBox();
+  return singleton;
+}