sparda-mcp 0.15.0 → 0.17.0

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

@@ -0,0 +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}

package/package.json

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

@@ -5,6 +5,7 @@
 // lookup, no recompile, no LLM, no network. BitNet's move applied to trust.
 //   sparda immunize          write .sparda/immunity.json + a summary
 //   sparda immunize --json   print the capsule to stdout
+import fs from 'node:fs';
 import path from 'node:path';
 import { compileUBG } from '../ubg/compile.js';
 import { canonicalizeGraph } from '../ubg/schema.js';
@@ -32,6 +33,7 @@ export async function runImmunize(opts) {
   }
 
   const outPath = path.join(opts.cwd, '.sparda', 'immunity.json');
+  fs.mkdirSync(path.dirname(outPath), { recursive: true }); // .sparda/ may not exist yet
   atomicWrite(outPath, JSON.stringify(capsule) + '\n');
   const wire = JSON.stringify(capsule).length;
 

package/src/commands/speculate.js

@@ -0,0 +1,74 @@
+// commands/speculate.js — speculative verification (ADR-038).
+// Re-verify the working tree against a FROZEN capsule (.sparda/immunity.json) by
+// hash lookup instead of a full re-proof. Routes whose behavioral shape is already
+// in the capsule are settled for free (accepted if safe, rejected if a known-
+// dangerous shape); only NOVEL shapes need the full prover. This is what makes the
+// agent inner loop fast on a monster repo — most edits touch already-proven shapes.
+//   sparda speculate          triage vs .sparda/immunity.json (run `immunize` first)
+//   sparda speculate --json   raw { acceptanceRate, accepted, rejected, novel }
+import fs from 'node:fs';
+import path from 'node:path';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { speculativeVerify } from '../ubg/speculative.js';
+
+export async function runSpeculate(opts) {
+  const capsulePath = path.join(opts.cwd, '.sparda', 'immunity.json');
+  if (!fs.existsSync(capsulePath)) {
+    throw Object.assign(new Error('No frozen capsule to speculate against.'), {
+      code: 'USER',
+      hint: 'Run `sparda immunize` first to freeze a baseline.',
+    });
+  }
+  let capsule;
+  try {
+    capsule = JSON.parse(fs.readFileSync(capsulePath, 'utf8'));
+  } catch (err) {
+    throw Object.assign(new Error(`Capsule unreadable: ${err.message}`), {
+      code: 'USER',
+      hint: 'Re-run `sparda immunize` to regenerate .sparda/immunity.json.',
+    });
+  }
+
+  const candidate = canonicalizeGraph(
+    compileUBG(opts.cwd, { write: false, openapi: opts.openapi }).graph,
+  );
+  const result = speculativeVerify(capsule, candidate);
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return { result };
+  }
+
+  const pct = (result.acceptanceRate * 100).toFixed(1);
+  console.log(
+    `SPECULATIVE VERIFY — ${result.settled}/${result.total} route(s) settled by lookup, ` +
+      `${result.novel.length} novel (${pct}% verified with zero prover work)`,
+  );
+  for (const r of result.rejected)
+    console.log(
+      `  ✗ known-exposed shape: ${short(r.entrypoint)} [${r.exposed.join(',')}]`,
+    );
+  for (const r of result.novel)
+    console.log(`  ? novel shape (needs full proof): ${short(r.entrypoint)}`);
+  if (!result.novel.length && !result.rejected.length)
+    console.log(
+      '  ✓ every route matched a proven-safe shape — re-verification cost nothing.',
+    );
+
+  // Verdict mirrors apocalypse, computed by lookup: a known-exposed route means the
+  // tree is not proven. Novel shapes aren't a failure — they're work the full prover
+  // still owes; surface them, don't gate on them.
+  console.log(
+    result.rejected.length
+      ? `✗ NOT PROVEN (by lookup) — ${result.rejected.length} known-exposed route(s)` +
+          (result.novel.length ? ` · ${result.novel.length} novel need full proof` : '')
+      : result.novel.length
+        ? `· ${result.novel.length} novel shape(s) need the full prover — run \`sparda apocalypse\``
+        : `✓ PROVEN (by lookup) — every route settled from the frozen capsule, zero prover work`,
+  );
+  if (result.rejected.length) process.exitCode = 1;
+  return { result };
+}
+
+const short = (id) => id.replace(/^entrypoint:/, '');

package/src/commands/ubg.js

@@ -4,6 +4,7 @@
 // there. Artifact: .sparda/ubg.json — regenerable, deterministic, never
 // committed. `--json` prints the raw graph, `--out <file>` redirects it.
 import { compileUBG } from '../ubg/compile.js';
+import { cmp } from '../ubg/schema.js';
 
 export async function runUbg(opts) {
   const { report, json, outPath } = compileUBG(opts.cwd, {
@@ -73,7 +74,7 @@ export async function runUbg(opts) {
 
 const fmtCounts = (obj) =>
   Object.entries(obj)
-    .sort(([a], [b]) => a.localeCompare(b))
+    .sort(([a], [b]) => cmp(a, b))
     .map(([k, v]) => `${k} ${v}`)
     .join(' · ');
 

package/src/detect.js

@@ -41,10 +41,19 @@ export function detectStack(cwd) {
         expressVersion: deps.express,
       };
     }
-    const known = ['@nestjs/core', 'fastify', 'koa'].find((d) => deps[d]);
+    // NestJS (and Medusa/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) => {
+        const abs = path.join(cwd, d);
+        return fs.existsSync(abs) && fs.statSync(abs).isDirectory();
+      });
+      return { framework: 'nestjs', entryFile: entryFile ?? '.', port: 3000 };
+    }
+    const known = ['fastify', 'koa'].find((d) => deps[d]);
     if (known)
       throw err(
-        `${known} detected — not supported yet. Express & FastAPI only in v0.`,
+        `${known} detected — not supported yet. Express, NestJS & FastAPI in v0.`,
         '+1 the framework vote: github.com/zyx77550/sparda/issues/1',
       );
   }

package/src/index.js

@@ -132,6 +132,11 @@ try {
       await runImmunize(opts);
       break;
     }
+    case 'speculate': {
+      const { runSpeculate } = await import('./commands/speculate.js');
+      await runSpeculate(opts);
+      break;
+    }
     case 'timeless': {
       const { runTimeless } = await import('./commands/timeless.js');
       await runTimeless(opts, rest);
@@ -179,6 +184,7 @@ Usage:
   npx sparda-mcp fingerprint  Portable behavior hash per route — the address for shared diagnoses (--json)
   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 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

@@ -11,6 +11,8 @@
 // structural reachability" — the prover is exactly as strong as what the code
 // and DDL declare. It proves the absence of whole bug classes, not of bugs.
 
+import { cmp } from './schema.js';
+
 const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, info: 3 };
 const CONSTRAINING = new Set(['check', 'not_null', 'unique']);
 
@@ -36,7 +38,7 @@ export function indexGraph(graph) {
   }
   const entrypoints = graph.nodes
     .filter((n) => n.kind === 'entrypoint')
-    .sort((a, b) => a.id.localeCompare(b.id));
+    .sort((a, b) => cmp(a.id, b.id));
   return { nodes, cfOut, mutOut, gateTargets, compensators, entrypoints };
 }
 
@@ -125,7 +127,7 @@ export function checkGraph(graph) {
       if (!byDomain.has(domain)) byDomain.set(domain, []);
       byDomain.get(domain).push(w);
     }
-    for (const [domain, ws] of [...byDomain].sort((a, b) => a[0].localeCompare(b[0]))) {
+    for (const [domain, ws] of [...byDomain].sort((a, b) => cmp(a[0], b[0]))) {
       const states = new Set(ws.map((w) => w.stateId));
       if (states.size < 2) continue;
       const txIds = new Set(ws.map((w) => w.effect.meta.transaction?.id ?? null));
@@ -294,8 +296,8 @@ function sortFindings(findings) {
   return findings.sort(
     (a, b) =>
       SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] ||
-      a.rule.localeCompare(b.rule) ||
-      a.entrypoint.localeCompare(b.entrypoint),
+      cmp(a.rule, b.rule) ||
+      cmp(a.entrypoint, b.entrypoint),
   );
 }
 

package/src/ubg/compile.js

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

package/src/ubg/extract.js

@@ -89,7 +89,11 @@ export function parseModule(absFile) {
   try {
     facts.ast = parse(src, {
       sourceType: 'unambiguous',
-      plugins: ['typescript', 'jsx', ['decorators', { decoratorsBeforeExport: true }]],
+      // decorators-legacy = TypeScript's `experimentalDecorators`, which is what
+      // NestJS/Medusa/TypeORM actually compile with. Unlike the modern `decorators`
+      // plugin it allows PARAMETER decorators (`@Body()`, `@Param()`) — without this
+      // every Nest controller is a parse error and the app reads as 0 routes.
+      plugins: ['typescript', 'jsx', 'decorators-legacy'],
       attachComment: true,
     });
   } catch (err) {
@@ -424,12 +428,16 @@ function inspectCall(node, out, ctx) {
   // raw material StateMachineInference reads (lowercased, same trade-off)
   if (PRISMA_OPS[methodLower] !== undefined) {
     const obj = callee.object;
+    // `prisma.user.create(...)` OR the class-based `this.prisma.user.create(...)`
+    // that NestJS services / Express controller classes use — `clientBaseName`
+    // reads the client name off a bare Identifier or a `this.<field>`.
+    const client = obj.type === 'MemberExpression' ? clientBaseName(obj.object) : null;
     if (
       obj.type === 'MemberExpression' &&
       !obj.computed &&
       obj.property.type === 'Identifier' &&
-      obj.object.type === 'Identifier' &&
-      /prisma|client|db/i.test(obj.object.name)
+      client &&
+      /prisma|client|db/i.test(client)
     ) {
       const op = PRISMA_OPS[methodLower];
       const data = prismaLiteralsOf(node.arguments[0], 'data');
@@ -636,10 +644,29 @@ function literalArg(arg) {
 
 function rootIdentifier(memberExpr) {
   let cur = memberExpr;
-  while (cur.type === 'MemberExpression') cur = cur.object;
+  while (cur.type === 'MemberExpression') {
+    // `this.foo.bar()` — the effective root is the class field `foo`, so
+    // class-based access (NestJS services, controller classes) is read like a
+    // bare `foo.bar()`. Without this, everything rooted at `this` is invisible.
+    if (cur.object.type === 'ThisExpression')
+      return cur.property.type === 'Identifier' ? cur.property.name : null;
+    cur = cur.object;
+  }
   return cur.type === 'Identifier' ? cur.name : null;
 }
 
+// the name a member/identifier refers to, unwrapping `this.<field>` → `<field>`.
+function clientBaseName(node) {
+  if (node.type === 'Identifier') return node.name;
+  if (
+    node.type === 'MemberExpression' &&
+    node.object.type === 'ThisExpression' &&
+    node.property.type === 'Identifier'
+  )
+    return node.property.name;
+  return null;
+}
+
 // knex('users') → users ; supabase.from('users') → users ;
 // supabase.from('users').select() chains: walk member/call chain to a
 // .from('t') or a base call with a string literal argument.

package/src/ubg/mirror.js

@@ -18,6 +18,7 @@
 // denials, and state-machine-aware state — never invented business values. Every
 // response carries `x-sparda-mirror: true`.
 import http from 'node:http';
+import { cmp } from './schema.js';
 
 export function createMirrorServer(graph) {
   const { routes, machines } = buildRouteTable(graph);
@@ -176,7 +177,7 @@ function buildRouteTable(graph) {
   }
 
   const routes = [];
-  for (const node of [...nodes.values()].sort((a, b) => a.id.localeCompare(b.id))) {
+  for (const node of [...nodes.values()].sort((a, b) => cmp(a.id, b.id))) {
     if (node.kind !== 'entrypoint') continue;
     const handlerId = handlerOf.get(node.id);
     const guards = handlerId ? (gateByHandler.get(handlerId) ?? []) : [];

package/src/ubg/nestjs.js

@@ -0,0 +1,303 @@
+// ubg/nestjs.js — NestJS (and DI-framework) route extraction. THE wall-breaker.
+//
+// Nest/Medusa/Inversify apps defeated the old detector: routes aren't `app.get()`
+// calls, they're `@Get()` decorators on controller *methods*, and the real effect
+// (the DB write) lives in a *service* wired by dependency injection, not in the
+// controller. The old parser saw 0 routes → NO PROOF → useless.
+//
+// The insight that makes this tractable statically: in TypeScript, DI is expressed
+// as CONSTRUCTOR PARAMETER TYPES — `constructor(private svc: CatsService)` — which
+// are right there in the AST. So we read the decorators for the route table, read
+// the constructor for the DI wiring, and follow `this.svc.method()` to the service
+// method to scan its real effects. No runtime container, no execution. Same UBG out,
+// so everything downstream (apocalypse/polarity/immunize/speculate) just works.
+import fs from 'node:fs';
+import path from 'node:path';
+import traverseModule from '@babel/traverse';
+import { parseModule, scanFunction } from './extract.js';
+
+const traverse = traverseModule.default ?? traverseModule;
+const HTTP = new Set(['get', 'post', 'put', 'patch', 'delete']);
+const EXCLUDE = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.sparda']);
+
+// → { routes, globalMiddlewares, helpers, skipped, scannedFiles } (extractExpress shape)
+export function extractNest(cwd, entryDir) {
+  const routes = [];
+  const helpers = [];
+  const skipped = [];
+  const scannedFiles = [];
+  const root = path.resolve(cwd, entryDir || '.');
+
+  for (const file of walk(root)) {
+    const mod = parseModule(file);
+    const rel = relOf(cwd, file);
+    if (mod.error) {
+      skipped.push({ reason: `${mod.error} in ${rel}`, file: rel });
+      continue;
+    }
+    let sawController = false;
+
+    traverse(mod.ast, {
+      ClassDeclaration(p) {
+        const cls = p.node;
+        const controller = decoratorArg(cls.decorators, 'Controller');
+        if (controller === undefined) return; // not a controller
+        sawController = true;
+        const prefix = controller.value ?? '';
+        const di = constructorDI(cls); // prop -> service type name
+        const classGuards = useGuards(cls.decorators);
+
+        for (const m of cls.body.body) {
+          if (m.type !== 'ClassMethod' || !m.key || m.key.type !== 'Identifier') continue;
+          const http = httpDecorator(m.decorators);
+          if (!http) continue;
+          const fullPath = joinPath(prefix, http.path);
+          const guards = [...classGuards, ...useGuards(m.decorators)];
+
+          // the handler's effects = the controller method body + every service
+          // method it delegates to through DI (this.<prop>.<call>())
+          const scan = resolveHandlerScan(m, di, mod, cwd, scannedFiles, helpers);
+
+          const chain = [
+            ...guards.map((name) => ({
+              name,
+              sourceFile: rel,
+              sourceLine: m.loc?.start.line ?? 0,
+              fn: null,
+              role: 'middleware',
+            })),
+            {
+              name: m.key.name,
+              sourceFile: rel,
+              sourceLine: m.loc?.start.line ?? 0,
+              fn: null,
+              scan, // precomputed merged scan — translate uses it as-is
+              role: 'handler',
+            },
+          ];
+
+          routes.push({
+            method: http.method,
+            path: fullPath,
+            sourceFile: rel,
+            sourceLine: m.loc?.start.line ?? 0,
+            params: pathParamsOf(fullPath),
+            chain,
+            description: '',
+          });
+        }
+      },
+    });
+
+    if (sawController && !scannedFiles.includes(rel)) scannedFiles.push(rel);
+  }
+
+  routes.sort((a, b) => cmp(a.path, b.path) || cmp(a.method, b.method));
+  return { routes, globalMiddlewares: [], helpers, skipped, scannedFiles };
+}
+
+// --- decorator readers ------------------------------------------------------
+
+// the first string-literal arg of decorator `@Name(...)`, or undefined if the
+// decorator is absent. Returns { value } (value may be '' for a bare `@Name()`).
+function decoratorArg(decorators, name) {
+  for (const d of decorators ?? []) {
+    const call = d.expression;
+    if (call.type === 'CallExpression' && idName(call.callee) === name) {
+      const a0 = call.arguments[0];
+      return { value: a0?.type === 'StringLiteral' ? a0.value : '' };
+    }
+    if (call.type === 'Identifier' && call.name === name) return { value: '' };
+  }
+  return undefined;
+}
+
+function httpDecorator(decorators) {
+  for (const d of decorators ?? []) {
+    const call = d.expression;
+    const name = call.type === 'CallExpression' ? idName(call.callee) : idName(call);
+    if (!name) continue;
+    const verb = name.toLowerCase();
+    if (!HTTP.has(verb)) continue;
+    const a0 = call.type === 'CallExpression' ? call.arguments[0] : null;
+    return { method: verb, path: a0?.type === 'StringLiteral' ? a0.value : '' };
+  }
+  return null;
+}
+
+// every class named in `@UseGuards(A, B)` decorators (class- or method-level)
+function useGuards(decorators) {
+  const out = [];
+  for (const d of decorators ?? []) {
+    const call = d.expression;
+    if (call.type !== 'CallExpression' || idName(call.callee) !== 'UseGuards') continue;
+    for (const arg of call.arguments) {
+      const n = idName(arg);
+      if (n) out.push(n);
+    }
+  }
+  return out;
+}
+
+// constructor(private catsService: CatsService) → { catsService: 'CatsService' }
+function constructorDI(cls) {
+  const di = {};
+  const ctor = cls.body.body.find(
+    (m) => m.type === 'ClassMethod' && m.kind === 'constructor',
+  );
+  for (const param of ctor?.params ?? []) {
+    // `private x: T` is a TSParameterProperty wrapping an Identifier with a type
+    const id = param.type === 'TSParameterProperty' ? param.parameter : param;
+    if (id?.type !== 'Identifier') continue;
+    const typeName = typeRefName(id.typeAnnotation?.typeAnnotation);
+    if (typeName) di[id.name] = typeName;
+  }
+  return di;
+}
+
+// --- DI resolution: follow this.<prop>.<method>() into the service ----------
+
+function resolveHandlerScan(method, di, ownerMod, cwd, scannedFiles, helpers) {
+  const base = scanFunction(method); // the controller body itself
+  const merged = { ...base, effects: [...base.effects] };
+
+  // find `this.<prop>.<m>(...)` calls whose <prop> is a DI'd service
+  traverse(
+    { type: 'File', program: { type: 'Program', body: [method], directives: [] } },
+    {
+      CallExpression(p) {
+        const callee = p.node.callee;
+        if (callee.type !== 'MemberExpression' || callee.property.type !== 'Identifier')
+          return;
+        const recv = callee.object; // this.<prop>
+        if (
+          recv.type !== 'MemberExpression' ||
+          recv.object.type !== 'ThisExpression' ||
+          recv.property.type !== 'Identifier'
+        )
+          return;
+        const serviceType = di[recv.property.name];
+        if (!serviceType) return;
+        const svcFn = resolveServiceMethod(
+          serviceType,
+          callee.property.name,
+          ownerMod,
+          cwd,
+          scannedFiles,
+          helpers,
+        );
+        if (svcFn) mergeScan(merged, scanFunction(svcFn));
+      },
+    },
+    // a minimal scope stand-in; @babel/traverse needs a scope for File roots
+    undefined,
+  );
+  return merged;
+}
+
+// import CatsService from its module, find the class, find the method node
+function resolveServiceMethod(
+  typeName,
+  methodName,
+  ownerMod,
+  cwd,
+  scannedFiles,
+  helpers,
+) {
+  const file = ownerMod.imports.get(typeName);
+  if (!file || !fs.existsSync(file)) return null;
+  const svc = parseModule(file);
+  if (svc.error) return null;
+  const rel = relOf(cwd, file);
+  if (!scannedFiles.includes(rel)) scannedFiles.push(rel);
+  let found = null;
+  for (const node of svc.ast.program.body) {
+    const cls =
+      node.type === 'ClassDeclaration'
+        ? node
+        : node.type === 'ExportNamedDeclaration' &&
+            node.declaration?.type === 'ClassDeclaration'
+          ? node.declaration
+          : null;
+    if (!cls || cls.id?.name !== typeName) continue;
+    for (const m of cls.body.body) {
+      if (
+        m.type === 'ClassMethod' &&
+        m.key.type === 'Identifier' &&
+        m.key.name === methodName
+      ) {
+        found = m;
+        helpers.push({
+          name: `${typeName}.${methodName}`,
+          sourceFile: rel,
+          sourceLine: m.loc?.start.line ?? 0,
+          fn: m,
+        });
+      }
+    }
+  }
+  return found;
+}
+
+function mergeScan(into, add) {
+  into.effects.push(...add.effects);
+  into.returnShapes = [...(into.returnShapes ?? []), ...(add.returnShapes ?? [])];
+  into.calls = [...(into.calls ?? []), ...(add.calls ?? [])];
+  into.validatesInput = into.validatesInput || add.validatesInput;
+  into.async = into.async || add.async;
+  if (add.guardSignals?.deniesWithStatus) into.guardSignals.deniesWithStatus = true;
+}
+
+// --- small AST + path helpers ----------------------------------------------
+
+const idName = (node) =>
+  node?.type === 'Identifier'
+    ? node.name
+    : node?.type === 'CallExpression'
+      ? idName(node.callee)
+      : null;
+
+function typeRefName(t) {
+  if (!t) return null;
+  if (t.type === 'TSTypeReference' && t.typeName?.type === 'Identifier')
+    return t.typeName.name;
+  return null;
+}
+
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+function joinPath(prefix, p) {
+  const norm = (s) => `/${String(s ?? '').replace(/^\/+|\/+$/g, '')}`;
+  const a = prefix ? norm(prefix) : '';
+  const b = p ? norm(p) : '';
+  const joined = `${a}${b}`.replace(/\/{2,}/g, '/');
+  return joined === '' ? '/' : joined;
+}
+
+function pathParamsOf(fullPath) {
+  return [...fullPath.matchAll(/:(\w+)/g)].map((m) => ({
+    name: m[1],
+    in: 'path',
+    type: 'string',
+    required: true,
+  }));
+}
+
+function relOf(cwd, abs) {
+  return path.relative(cwd, abs).split(path.sep).join('/');
+}
+
+function* walk(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries.sort((a, b) => cmp(a.name, b.name))) {
+    if (EXCLUDE.has(e.name)) continue;
+    const abs = path.join(dir, e.name);
+    if (e.isDirectory()) yield* walk(abs);
+    else if (/\.(m?ts|m?js|cts|cjs)$/.test(e.name) && !/\.d\.ts$/.test(e.name)) yield abs;
+  }
+}

package/src/ubg/openapi-emit.js

@@ -6,6 +6,8 @@
 // tool (Swagger UI, client codegen, Postman) reads SPARDA's understanding of
 // a Go/Java/Rails backend it never had a spec for. Deterministic: sorted
 // paths, sorted keys, no timestamps — same graph, same bytes.
+import { cmp } from './schema.js';
+
 const OA_TYPE = {
   string: { type: 'string' },
   integer: { type: 'integer' },
@@ -49,7 +51,7 @@ export function emitOpenAPI(
 
   const entrypoints = [...nodes.values()]
     .filter((n) => n.kind === 'entrypoint')
-    .sort((a, b) => a.id.localeCompare(b.id));
+    .sort((a, b) => cmp(a.id, b.id));
 
   for (const ep of entrypoints) {
     const oaPath = ep.meta.path.replace(/:(\w+)/g, '{$1}'); // :id → {id}
@@ -69,7 +71,7 @@ export function emitOpenAPI(
         required: p.in === 'path' ? true : Boolean(p.required),
         schema: schemaFor(p.type),
       }))
-      .sort((a, b) => a.name.localeCompare(b.name));
+      .sort((a, b) => cmp(a.name, b.name));
     if (parameters.length) op.parameters = parameters;
 
     if (ep.meta.inputValidated && method !== 'get') {

package/src/ubg/speculative.js

@@ -0,0 +1,56 @@
+// ubg/speculative.js — speculative verification (ADR-038).
+//
+// Inspiration: speculative decoding — a cheap draft model proposes, the expensive
+// model verifies, and you only pay full cost on the residual the draft got wrong.
+// The analogue for a proof engine: re-proving a whole app after every agent edit is
+// expensive (seconds on a monster like Dub — 559 routes). But most edits touch shapes
+// SPARDA has ALREADY proven. So we speculate: look each candidate route's behaviorHash
+// up in a frozen capsule (O(1), no compile) and accept/reject from that; only the
+// routes whose SHAPE is novel fall through to the full prover.
+//
+// Stronger than speculative decoding: there, the draft can be wrong and the verifier
+// overrides it. Here a capsule hit is EXACT — identical behaviorHash ⇒ identical
+// behavioral shape ⇒ identical obligations ⇒ the same verdict the full prover would
+// give. The shortcut is provably equal to the full answer; we skip the compute, never
+// the correctness. Zero infra: a hash lookup over a few bytes per route.
+import { fingerprintGraph } from './fingerprint.js';
+import { judge } from './immunity.js';
+import { cmp } from './schema.js';
+
+// (frozen capsule, candidate graph) → a triage: which routes are settled for free
+// from the capsule, and which are NOVEL and must pay the full prover.
+//   accepted — shape known & safe   (0 prover work)
+//   rejected — shape known & exposed (0 prover work)
+//   novel    — shape unseen          → hand to checkGraph/apocalypse
+export function speculativeVerify(capsule, candidateGraph) {
+  const prints = fingerprintGraph(candidateGraph);
+  const accepted = [];
+  const rejected = [];
+  const novel = [];
+
+  for (const { entrypoint, behaviorHash } of prints) {
+    const verdict = judge(capsule, behaviorHash);
+    const row = { entrypoint, behaviorHash };
+    if (!verdict.known) novel.push(row);
+    else if (verdict.safe) accepted.push({ ...row, exposed: [] });
+    else rejected.push({ ...row, exposed: verdict.exposed });
+  }
+
+  const bySort = (a, b) => cmp(a.entrypoint, b.entrypoint);
+  accepted.sort(bySort);
+  rejected.sort(bySort);
+  novel.sort(bySort);
+
+  const total = prints.length;
+  const settled = accepted.length + rejected.length; // verified WITHOUT the prover
+  return {
+    accepted,
+    rejected,
+    novel,
+    total,
+    settled,
+    // the speedup metric: fraction of routes decided by lookup alone (0..1).
+    // 1.0 means the whole re-verification cost nothing; only `novel` pays.
+    acceptanceRate: total ? settled / total : 1,
+  };
+}