@nifrajs/cli 4.0.2 → 5.1.0

package/src/internal/source-facts.ts

@@ -20,6 +20,13 @@ export interface SourceFacts {
     method: string,
     path: string,
   ): boolean | undefined
+  /** A `.method(argument, …)` member call whose first argument is written exactly as `argument`. */
+  isRouteArgumentAt(
+    source: TSApi.SourceFile,
+    position: number,
+    method: string,
+    argument: string,
+  ): boolean | undefined
   /** A call to the free function `callee` whose argument at `pathIndex` is the literal `path`. */
   isFunctionRouteCallAt(
     source: TSApi.SourceFile,
@@ -75,8 +82,26 @@ function rawResponseExpression(ts: TypeScriptApi, node: TSApi.Expression): boole
   )
 }
 
-export function createSourceFacts(ts: TypeScriptApi): SourceFacts {
+export interface SourceFactsOptions {
+  /** Whether the compiler settings for a parsed file keep an import whose named specifiers are all
+   * type-only (`verbatimModuleSyntax`). Without it such an import is erased. */
+  readonly keepsTypeOnlyImports?: (file: string) => boolean
+}
+
+export function createSourceFacts(
+  ts: TypeScriptApi,
+  options: SourceFactsOptions = {},
+): SourceFacts {
   const cache = new Map<string, { content: string; source: TSApi.SourceFile | undefined }>()
+  // `{}` loads its module in every bundler; a list of type-only specifiers is erased unless the
+  // compiler keeps it as `import {} from "x"`.
+  const loadsModule = (
+    source: TSApi.SourceFile,
+    elements: readonly { readonly isTypeOnly: boolean }[],
+  ): boolean =>
+    elements.length === 0 ||
+    elements.some((element) => !element.isTypeOnly) ||
+    (options.keepsTypeOnlyImports?.(source.fileName) ?? false)
 
   const parse = (file: string, content: string): TSApi.SourceFile | undefined => {
     const cached = cache.get(file)
@@ -111,7 +136,7 @@ export function createSourceFacts(ts: TypeScriptApi): SourceFacts {
       if (reexport.isTypeOnly) return false
       const named = reexport.exportClause
       if (named !== undefined && ts.isNamedExports(named))
-        return named.elements.some((element) => !element.isTypeOnly)
+        return loadsModule(source, named.elements)
       return true // `export *` and `export * as ns`
     }
     const declaration = ancestorAt(ts, source, position, ts.isImportDeclaration)
@@ -121,9 +146,9 @@ export function createSourceFacts(ts: TypeScriptApi): SourceFacts {
     const clause = declaration.importClause
     if (clause === undefined) return true // side-effect import
     if (clause.isTypeOnly) return false
-    if (clause.namedBindings !== undefined && ts.isNamedImports(clause.namedBindings)) {
-      return clause.namedBindings.elements.some((element) => !element.isTypeOnly)
-    }
+    // A default binding is a runtime import whatever its named list holds.
+    const named = clause.name === undefined ? clause.namedBindings : undefined
+    if (named !== undefined && ts.isNamedImports(named)) return loadsModule(source, named.elements)
     return true // default and namespace bindings are runtime imports
   }
 
@@ -142,6 +167,23 @@ export function createSourceFacts(ts: TypeScriptApi): SourceFacts {
     )
   }
 
+  const isRouteArgumentAt = (
+    source: TSApi.SourceFile,
+    position: number,
+    method: string,
+    argument: string,
+  ): boolean | undefined => {
+    const call = ancestorAt(ts, source, position, ts.isCallExpression)
+    if (call === undefined || !ts.isPropertyAccessExpression(call.expression)) return false
+    const first = call.arguments[0]
+    return (
+      call.expression.name.text.toUpperCase() === method &&
+      call.arguments.length > 1 &&
+      first !== undefined &&
+      first.getText(source) === argument
+    )
+  }
+
   const isFunctionRouteCallAt = (
     source: TSApi.SourceFile,
     position: number,
@@ -200,6 +242,7 @@ export function createSourceFacts(ts: TypeScriptApi): SourceFacts {
     parse,
     isValueImportAt,
     isRouteRegistrationAt,
+    isRouteArgumentAt,
     isFunctionRouteCallAt,
     isResponseSyntaxAt,
     isDynamicImportAt,

package/src/internal/typescript-import.ts

@@ -48,11 +48,14 @@ export function unsupportedTypeScriptMessage(version: string): string {
   return `${NIFRA_TS_UNSUPPORTED}: TypeScript ${version} is outside the compiler API versions supported by Nifra scanners. Use TypeScript 5, 6, or 7, or pin the project to TypeScript 6 (for example, \`bun add -d typescript@^6\`).`
 }
 
-export function unsupportedTypeScriptDiagnostic(version: string): Diagnostic {
+export function unsupportedTypeScriptDiagnostic(
+  version: string,
+  message = unsupportedTypeScriptMessage(version),
+): Diagnostic {
   return diagnostic({
     code: NIFRA_TS_UNSUPPORTED,
     severity: "error",
-    message: unsupportedTypeScriptMessage(version),
+    message,
     fix: {
       recipe: "toolchain.install-typescript",
       command: "bun add -d typescript@^6",
@@ -320,9 +323,9 @@ function syntaxKinds(module: UnknownRecord, names: readonly string[]): ReadonlyS
 
 function createVirtualFileSystem(
   sourceFiles: ReadonlyMap<string, string>,
-  root: string,
+  roots: readonly string[],
 ): UnknownRecord {
-  const rootPaths = pathVariants(root)
+  const rootPaths = [...new Set(roots.flatMap(pathVariants))]
   const virtualFiles: string[] = []
   const seenFiles = new Set<string>()
   for (const file of sourceFiles.keys()) {
@@ -412,7 +415,11 @@ function sourceEntries(
     const content = sourceIndex.read(file)
     if (content === undefined) continue
     const absolute = isAbsolute(file) ? file : resolve(root, file)
-    const normalized = normalizedPath(absolute)
+    // The session opens script extensions only; a component's script blocks are opened as TypeScript
+    // beside it, and `createSourceFile` finds them by their text.
+    const normalized = normalizedPath(
+      /\.(?:svelte|vue)$/.test(absolute) ? `${absolute}.ts` : absolute,
+    )
     paths.push(normalized)
     for (const variant of pathVariants(normalized)) files.set(variant, content)
   }
@@ -447,7 +454,9 @@ async function createTypeScript7Session(
 
   const api = new API({
     cwd: sessionRoot,
-    fs: createVirtualFileSystem(files, sessionRoot),
+    // The root as the caller spells it too: a file not yet on disk keeps that spelling (`/var`, not
+    // `/private/var`), and the session reaches it through the caller's config.
+    fs: createVirtualFileSystem(files, [sessionRoot, root]),
   })
   let snapshot: TypeScript7Snapshot | undefined
   let configuredProject: TypeScript7Project | undefined

package/src/introspect.ts

@@ -13,12 +13,12 @@ import {
   snapshotProjectEvidence,
 } from "@nifrajs/core/evidence"
 import { compileRoutePattern, type RoutePatternSegment } from "@nifrajs/core/pattern"
-import type { ReflectedRoute } from "@nifrajs/core/reflection"
+import type { ReflectedMount, ReflectedRoute } from "@nifrajs/core/reflection"
 import type { Manifest } from "@nifrajs/web"
 import { discoverRoutes } from "@nifrajs/web/fs"
 import { normalizeMountPath } from "@nifrajs/web/route-manifest"
 import { codeUnitOrder } from "./internal/code-unit-order.ts"
-import type { LoadedApp } from "./load.ts"
+import type { IntrospectedApp } from "./load.ts"
 import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.ts"
 
 /** Read the backend's registered routes, if it's a `server()` with a `.routes()` method. */
@@ -225,6 +225,22 @@ export function apiRoutesIndexSection(routes: readonly ReflectedRoute[]): string
   return `## API routes (backend/app.ts)\n\n${routes.length} route${routes.length === 1 ? "" : "s"}. Call \`nifra_context\` again with \`path\` (a route prefix) and/or \`kind: "api"\` for the body/query/response contracts + the exact \`client<typeof app>\` call form - or \`nifra_routes\` for the same as structured JSON.\n\n${lines.join("\n")}`
 }
 
+/** The routes opaque mounts declare, under `prefix`, or `undefined` when there are none. Listed apart
+ * from the API routes: nifra serves them but never analyzed them. */
+function declaredMountRoutesSection(
+  mounts: readonly ReflectedMount[],
+  prefix: string | undefined,
+): string | undefined {
+  const lines = mounts.flatMap((mount) =>
+    (mount.routes ?? [])
+      .filter((route) => prefix === undefined || route.path.startsWith(prefix))
+      .map((route) => `- \`${route.method} ${route.path}\` - ${mount.path} (${mount.opaque})`),
+  )
+  return lines.length === 0
+    ? undefined
+    : `## Declared by opaque mounts (not analyzed)\n\n${lines.join("\n")}`
+}
+
 /** Markdown section listing the file-routed pages (URL pattern → source file). */
 export function pageRoutesSection(manifest: Manifest | undefined): string {
   if (!manifest || manifest.routes.length === 0) {
@@ -236,6 +252,10 @@ export function pageRoutesSection(manifest: Manifest | undefined): string {
   return `## Page routes (routes/)\n\n${lines.join("\n")}`
 }
 
+const PAGES_CONVENTION = `- **Pages:** file-routed under \`routes/\`. A route is two files: \`x.tsx\` (browser) and \`x.backend.ts\`
+  (\`loader\`, \`action\`, \`middleware\`; server only). Server code lives under \`backend/\`, code both sides
+  use under \`shared/\`, components under \`frontend/\`; the browser build refuses backend code outright.`
+
 const CONVENTIONS = `## Conventions (summary)
 
 - **Backend:** \`server()\` from \`@nifrajs/core\`; returning a value sends JSON. Validate untrusted input with
@@ -253,9 +273,7 @@ const CONVENTIONS = `## Conventions (summary)
   \`res.data\` from the backend's route types, so the compiler catches any frontend/backend drift. Never
   hand-roll \`fetch\` + ad-hoc response types for an internal API - that's exactly how screens drift. It
   never throws: branch on \`res.ok ? res.data : res.error\`.
-- **Pages:** file-routed under \`routes/\`. A route is two files: \`x.tsx\` (browser) and \`x.backend.ts\`
-  (\`loader\`, \`action\`, \`middleware\`; server only). Server code lives under \`backend/\`, code both sides
-  use under \`shared/\`, components under \`frontend/\`; the browser build refuses backend code outright.
+${PAGES_CONVENTION}
 - \`app.fetch(Request)\` is the universal entry. Full reference: this repo's \`AGENTS.md\`, or \`llms-full.txt\`.`
 
 /** Optional narrowing for {@link describeProject} - a path prefix and/or one section. A filtered
@@ -274,15 +292,18 @@ export interface ContextFilter {
  * body/query/response shapes + the typed-client `call` form), and omits the conventions block (the agent
  * already has it from the index call).
  */
-export function describeProject(app: LoadedApp, filter?: ContextFilter): string {
+export function describeProject(app: IntrospectedApp, filter?: ContextFilter): string {
   let manifest: Manifest | undefined
-  try {
-    manifest = discoverRoutes(app.routesDir)
-  } catch {
-    // No (or unreadable) routes/ - the page-routes section reports that.
+  if (app.framework !== undefined) {
+    try {
+      manifest = discoverRoutes(app.routesDir)
+    } catch {
+      // No (or unreadable) routes/ - the page-routes section reports that.
+    }
   }
   const prefix = filter?.path
-  let routes = backendRoutes(app.backend)
+  const evidence = snapshotProjectEvidence(app.backend)
+  let routes = reflectedRoutesFromEvidence(evidence)
   let pages = manifest
   if (prefix !== undefined && prefix !== "") {
     routes = routes.filter((r) => r.path.startsWith(prefix))
@@ -296,20 +317,34 @@ export function describeProject(app: LoadedApp, filter?: ContextFilter): string
   const sections: string[] = [`# nifra project: ${app.cwd.slice(app.cwd.lastIndexOf("/") + 1)}`]
   if (isIndex) {
     sections.push(
-      "A full-stack nifra app - Web-standard, one app on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below).",
+      app.framework === undefined
+        ? "An API-only nifra app (backend/app.ts, no web config) - Web-standard, one backend on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below)."
+        : "A full-stack nifra app - Web-standard, one app on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below).",
       // Point agents at the verified surface, not recalled APIs - nifra is young, so training data is the
       // wrong source. The MCP tools (nifra_docs / nifra_example) are checked against the installed version.
       "> **Build against THIS surface + the verified tools - do not write nifra APIs from memory** (the\n> framework is young; recalled APIs drift). For framework code, call `nifra_example` (snippets\n> typechecked against the installed version) or `nifra_docs`; verify edits with `nifra_run` + `nifra_check`.",
+    )
+    if (app.framework !== undefined) {
       // The authoritative answer, not the static reading `nifra_check`/`nifra_doctor` give: this runs on
       // the LOADED config, so it is the same decision `nifra dev` and `nifra build` make. Stated in the
       // index because it governs where a plugin goes and which toolchain compiles a component - an edit
       // put in the other pipeline's slot is accepted and then silently never runs.
-      `**Bundler**: ${describePipeline(chooseBuildPipeline(app.resolvedPlugins))}. \`vitePlugins\` feed Vite; \`clientPlugins\`/\`serverPlugins\` feed Bun.build. Both phases (dev and build) use the same one.`,
-    )
+      sections.push(
+        `**Bundler**: ${describePipeline(chooseBuildPipeline(app.resolvedPlugins))}. \`vitePlugins\` feed Vite; \`clientPlugins\`/\`serverPlugins\` feed Bun.build. Both phases (dev and build) use the same one.`,
+      )
+    }
   }
   if (filter?.kind !== "pages") {
     // Index → compact `METHOD path` list; a slice → the full schema + call-form detail.
     sections.push(isIndex ? apiRoutesIndexSection(routes) : apiRoutesSection(routes))
+    const declared = declaredMountRoutesSection(evidence.mounts ?? [], prefix || undefined)
+    if (declared !== undefined) sections.push(declared)
+  }
+  if (app.framework === undefined) {
+    if (filter?.kind === "pages")
+      sections.push("## Page routes\n\nAn API-only app serves no pages.")
+    if (isIndex) sections.push(CONVENTIONS.replace(`${PAGES_CONVENTION}\n`, ""))
+    return sections.join("\n\n")
   }
   if (filter?.kind !== "api") sections.push(pageRoutesSection(pages))
   if (isIndex) sections.push(CONVENTIONS)
@@ -368,7 +403,7 @@ export function routesToJsonFromEvidence(
 }
 
 export function routesToJson(
-  app: LoadedApp,
+  app: IntrospectedApp,
   pathPrefix?: string,
   evidence?: ProjectEvidenceSnapshot,
 ): RouteJson[] {
@@ -382,7 +417,7 @@ export function routesToJson(
 // `nifra routes` answers a different question: "what does this app actually serve, and with which
 // methods?" - so an agent sees instantly that `POST /api/explain` is (or isn't) mounted, instead of
 // discovering it via a 405. It marks which backend routes are AUTO-MOUNTED under the page router's
-// `apiPrefix` (default `/api`), and `--json` makes it machine-consumable. The table-building +
+// `apiPrefix`, and `--json` makes it machine-consumable. The table-building +
 // rendering are pure (no fs / no module loads), so they're unit-tested; the cwd gathering is the thin
 // async wrapper `describeRoutes`.
 // ===================================================================================================
@@ -403,6 +438,9 @@ export interface RouteTableEntry {
    * through the same web app, no hand-wired `if (pathname.startsWith("/api/"))`). Pages are never
    * auto-mounted (they ARE the page router); only API routes carry this flag. */
   readonly autoMounted?: boolean
+  /** True for an API route outside a set `apiPrefix` while `apiStrip` is off: the mount passes the
+   * request's full path, so no HTTP request reaches it; loaders still call it in-process. */
+  readonly inProcessOnly?: boolean
 }
 
 /** A page route + whether its module exports an `action` (→ it also serves POST). The caller resolves
@@ -416,7 +454,7 @@ export interface PageRouteInput {
 export interface RouteTableInput {
   readonly pages: readonly PageRouteInput[]
   readonly api: ReadonlyArray<Pick<ReflectedRoute, "method" | "path">>
-  /** The page router's `apiPrefix` (default `/api`); an API route at/under it is auto-mounted. `""`
+  /** The page router's `apiPrefix`; an API route at/under it is auto-mounted. Unset or `""`
    * disables the auto-mount, so no API route is marked auto-mounted. */
   readonly apiPrefix?: string
   /** The backend declares its routes without the prefix and is served at `apiPrefix + path`: every API
@@ -440,7 +478,7 @@ function isUnderPrefix(path: string, prefix: string): boolean {
  * joined methods, for stable output.
  */
 export function buildRouteTable(input: RouteTableInput): RouteTableEntry[] {
-  const configured = input.apiPrefix ?? "/api"
+  const configured = input.apiPrefix ?? ""
   // Read the prefix as the server's mount table does (`/api/` and `/api/*` are `/api`).
   const apiPrefix = configured === "" ? "" : (normalizeMountPath(configured) ?? configured)
   const stripped = input.apiStrip === true && apiPrefix !== ""
@@ -471,6 +509,8 @@ export function buildRouteTable(input: RouteTableInput): RouteTableEntry[] {
       path,
       methods: [...info.methods].sort(),
       autoMounted: info.autoMounted,
+      // biome-ignore lint/plugin/noConditionalEmptyObjectSpread: only a route outside apiPrefix carries the flag, so every other row keeps its shape.
+      ...(apiPrefix !== "" && !info.autoMounted ? { inProcessOnly: true } : {}),
     })
   }
   return rows.sort(
@@ -509,7 +549,12 @@ export function renderRouteTable(rows: readonly RouteTableEntry[]): string {
   const display = rows.map((r) => ({
     methods: r.methods.join(", "),
     kind: r.kind,
-    path: r.kind === "api" && r.autoMounted ? `${r.path}  (auto-mounted)` : r.path,
+    path:
+      r.kind === "api" && r.autoMounted
+        ? `${r.path}  (auto-mounted)`
+        : r.inProcessOnly === true
+          ? `${r.path}  (in-process only: outside apiPrefix)`
+          : r.path,
     client: clientSpellingFor(r.path),
   }))
   const methodW = Math.max("METHOD".length, ...display.map((d) => d.methods.length))
@@ -542,6 +587,7 @@ export interface RouteJsonRow {
   readonly methods: readonly string[]
   readonly file?: string
   readonly autoMounted?: boolean
+  readonly inProcessOnly?: boolean
   /** The reserved typed-client key a static segment of this path collides with, when one does. */
   readonly reservedKey?: string
   /** The typed-client call spelling that reaches this route, present only alongside `reservedKey`. */
@@ -564,6 +610,8 @@ export function routeTableToJson(rows: readonly RouteTableEntry[]): {
         methods: r.methods,
         ...(r.file !== undefined ? { file: r.file } : {}),
         ...(r.kind === "api" ? { autoMounted: r.autoMounted === true } : {}),
+        // biome-ignore lint/plugin/noConditionalEmptyObjectSpread: `--json` rows gain the key only where it is true, so existing consumers see no change.
+        ...(r.inProcessOnly === true ? { inProcessOnly: true } : {}),
         ...(client === undefined
           ? {}
           : { reservedKey: client.reserved, clientSpelling: client.spelling }),
@@ -683,12 +731,15 @@ interface MaybeActionModule {
  * text (default) or JSON (`--json`). The page-route load mirrors what SSR would do; a load failure
  * degrades to GET-only for that route (never throws the whole command).
  */
-async function collectRouteTable(app: LoadedApp): Promise<RouteTableEntry[]> {
+async function collectRouteTable(app: IntrospectedApp): Promise<RouteTableEntry[]> {
+  const { framework } = app
   let manifest: Manifest | undefined
-  try {
-    manifest = discoverRoutes(app.routesDir)
-  } catch {
-    // No (or unreadable) routes/ - fall through with no pages; the table still shows API routes.
+  if (framework !== undefined) {
+    try {
+      manifest = discoverRoutes(app.routesDir)
+    } catch {
+      // No (or unreadable) routes/ - fall through with no pages; the table still shows API routes.
+    }
   }
   const pages: PageRouteInput[] = []
   for (const route of manifest?.routes ?? []) {
@@ -704,14 +755,39 @@ async function collectRouteTable(app: LoadedApp): Promise<RouteTableEntry[]> {
   const rows = buildRouteTable({
     pages,
     api: backendRoutes(app.backend),
-    ...(app.framework.apiPrefix !== undefined ? { apiPrefix: app.framework.apiPrefix } : {}),
-    ...(app.framework.apiStrip !== undefined ? { apiStrip: app.framework.apiStrip } : {}),
+    ...(framework?.apiPrefix !== undefined ? { apiPrefix: framework.apiPrefix } : {}),
+    ...(framework?.apiStrip !== undefined ? { apiStrip: framework.apiStrip } : {}),
   })
   return rows
 }
 
+/**
+ * The warning `nifra dev` and `nifra build` print for backend routes no HTTP request reaches, read from
+ * the routes the backend registers, prefixes and mounts resolved; `undefined` when there are none.
+ */
+export function unservedRoutesWarning(
+  app: Pick<IntrospectedApp, "framework" | "backend">,
+): string | undefined {
+  const apiPrefix = app.framework?.apiPrefix ?? ""
+  if (apiPrefix === "" || app.backend === undefined) return undefined
+  const rows = buildRouteTable({
+    pages: [],
+    api: backendRoutes(app.backend),
+    apiPrefix,
+    apiStrip: app.framework?.apiStrip === true,
+  }).filter((row) => row.inProcessOnly === true)
+  if (rows.length === 0) return undefined
+  const listed = rows.map((row) => `${row.methods.join(",")} ${row.path}`)
+  const named =
+    listed.length > 3
+      ? `${listed.slice(0, 3).join(", ")} and ${listed.length - 3} more`
+      : listed.join(", ")
+  const one = rows.length === 1
+  return `[nifra] ${one ? "a backend route is" : `${rows.length} backend routes are`} served over HTTP nowhere: ${named}. backend/app.ts is mounted at apiPrefix ${apiPrefix} with apiStrip off, so it sees each request's full path, and ${one ? "this route sits" : "these sit"} outside it; loaders still call ${one ? "it" : "them"} in-process. Register ${one ? "it" : "them"} under ${apiPrefix}, or export \`apiStrip = true\` to serve every backend route at ${apiPrefix} plus its path.`
+}
+
 export async function describeRoutes(
-  app: LoadedApp,
+  app: IntrospectedApp,
   opts: { readonly json?: boolean } = {},
 ): Promise<string> {
   const rows = await collectRouteTable(app)
@@ -720,7 +796,7 @@ export async function describeRoutes(
 
 /** Gather and render the public route graph for `nifra routes --graph`. */
 export async function describeRouteGraph(
-  app: LoadedApp,
+  app: IntrospectedApp,
   opts: { readonly json?: boolean } = {},
 ): Promise<string> {
   const graph = buildRouteGraph(await collectRouteTable(app))

package/src/levels-tool.ts

@@ -13,10 +13,21 @@
 
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
-import type { AssuranceReport } from "@nifrajs/core/assurance"
+import type {
+  AssuranceReport,
+  AssuredRoute,
+  InvariantSetup,
+  InvariantSetupResult,
+  InvariantsConfig,
+} from "@nifrajs/core/assurance"
 import { snapshotCapabilities } from "@nifrajs/core/capabilities"
 import { buildNifraManifest, parseNifraManifest } from "@nifrajs/core/manifest"
-import { type ContractTestApp, runAdversarialContract } from "@nifrajs/testing"
+import {
+  type AdversarialContractOptions,
+  type ContractTestApp,
+  runAdversarialContract,
+} from "@nifrajs/testing"
+import { RESPONSE_CONTRACT_BASELINE_HINT, responseContractGaps } from "./assure.ts"
 import {
   type CapabilityProjectReport,
   diffCapabilitySnapshots,
@@ -176,44 +187,132 @@ export async function collectVerificationLevels(
       "no isolated invariant executor configured - add `invariants.executor` in nifra.assurance.ts",
     )
   } else {
-    const invariants = await runAdversarialContract(config.source as ContractTestApp, {
-      seed: options.seed ?? 1,
-      runtimes: [{ name: "isolated", fetch: config.invariants.executor }],
-      expectedValidationStatuses: [400, 422],
-      requireCoverage: true,
+    l4Reasons.push(...(await runInvariants(config.source, config.invariants, options.seed ?? 1)))
+  }
+  statuses.push({
+    level: 4,
+    name: "invariant-tested",
+    ok: l4Reasons.length === 0,
+    reasons: l4Reasons,
+  })
+
+  return finalize(statuses, assurance.routes)
+}
+
+/**
+ * Run L4 against the configured target. `setup` runs at most once, on the first request, and its
+ * `teardown` runs once the run ends - after a failure too - so an app can provision a throwaway target
+ * only when L4 actually exercises it.
+ */
+async function runInvariants(
+  source: unknown,
+  invariants: InvariantsConfig,
+  seed: number,
+): Promise<string[]> {
+  let provisioned: Promise<InvariantSetupResult | undefined> | undefined
+  const provision = (setup: InvariantSetup): Promise<InvariantSetupResult | undefined> => {
+    provisioned ??= Promise.resolve()
+      .then(setup)
+      .then(
+        (result) => result ?? undefined,
+        (error: unknown) => {
+          throw new Error(`invariants.setup failed: ${messageOf(error)}`)
+        },
+      )
+    return provisioned
+  }
+  const fetch = async (request: Request): Promise<Response> => {
+    const ready = invariants.setup === undefined ? undefined : await provision(invariants.setup)
+    const executor = ready?.executor ?? invariants.executor
+    if (executor === undefined) {
+      throw new Error(
+        "no invariant executor: invariants.setup returned none and invariants.executor is not set",
+      )
+    }
+    return executor(request)
+  }
+  const options: AdversarialContractOptions = {
+    seed,
+    runtimes: [{ name: "isolated", fetch }],
+    expectedValidationStatuses: [400, 422],
+    requireCoverage: true,
+  }
+  const runOptions: Record<string, unknown> = {}
+  for (const name of INVARIANT_RUN_OPTIONS) {
+    if (invariants[name] !== undefined) runOptions[name] = invariants[name]
+  }
+  const reasons: string[] = []
+  try {
+    const report = await runAdversarialContract(source as ContractTestApp, {
+      ...options,
+      ...runOptions,
     })
-    if (!invariants.ok) {
-      l4Reasons.push(
-        ...invariants.failures
+    const target = await targetFailure(provisioned, invariants)
+    if (target !== undefined) reasons.push(target)
+    else if (!report.ok) {
+      reasons.push(
+        ...report.failures
           .slice(0, 5)
           .map(
             (failure) =>
               `${failure.runtime}: ${failure.id} - ${failure.message} (replay seed ${failure.replay.seed})`,
           ),
       )
-      l4Reasons.push(
-        ...invariants.gaps
-          .slice(0, Math.max(0, 5 - l4Reasons.length))
+      reasons.push(
+        ...report.gaps
+          .slice(0, Math.max(0, 5 - reasons.length))
           .map(
             (gap) =>
               `${gap.route ?? "contract"}${gap.target ? ` ${gap.target}` : ""}: ${gap.message}`,
           ),
       )
     }
+  } catch (error) {
+    reasons.push((await targetFailure(provisioned, invariants)) ?? messageOf(error))
+  } finally {
+    const ready = await provisioned?.catch(() => undefined)
+    if (ready?.teardown !== undefined) {
+      try {
+        await ready.teardown()
+      } catch (error) {
+        reasons.push(`invariants teardown failed: ${messageOf(error)}`)
+      }
+    }
   }
-  statuses.push({
-    level: 4,
-    name: "invariant-tested",
-    ok: l4Reasons.length === 0,
-    reasons: l4Reasons,
-  })
+  return reasons
+}
 
-  return finalize(statuses, assurance.routes)
+const INVARIANT_RUN_OPTIONS = [
+  "witnesses",
+  "prepareRequest",
+  "isRejected",
+  "include",
+  "maxMutationsPerInput",
+] as const
+
+/** The setup or missing-executor failure every case hit, if the target never came up. */
+async function targetFailure(
+  provisioned: Promise<InvariantSetupResult | undefined> | undefined,
+  invariants: InvariantsConfig,
+): Promise<string | undefined> {
+  if (provisioned === undefined) return undefined
+  try {
+    const ready = await provisioned
+    if (ready?.executor === undefined && invariants.executor === undefined) {
+      return "no invariant executor: invariants.setup returned none and invariants.executor is not set"
+    }
+    return undefined
+  } catch (error) {
+    return messageOf(error)
+  }
 }
 
+const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)
+
 function finalize(
   statuses: readonly { level: number; name: string; ok: boolean; reasons: string[] }[],
-  routes: readonly { readonly responseContract?: "enforce" | "warn" | "unchecked" }[],
+  routes: readonly AssuredRoute[],
 ): VerificationLevelsResult {
   // Cumulative: the achieved level is the last rung with every rung below it also holding.
   let achieved = -1
@@ -225,6 +324,7 @@ function finalize(
   const enforced = declared.filter((route) => route.responseContract === "enforce").length
   const warnOnly = declared.filter((route) => route.responseContract === "warn").length
   const typedOnly = declared.filter((route) => route.responseContract === "unchecked").length
+  const gaps = responseContractGaps(routes)
   const responseContracts: ResponseContractStatus = {
     declared: declared.length,
     enforced,
@@ -236,14 +336,9 @@ function finalize(
       declared.length === 0
         ? ["no response/error schemas declared"]
         : [
-            ...(typedOnly > 0
-              ? [
-                  `${typedOnly} declared route(s) are typed-only; install responseContract("enforce")`,
-                ]
-              : []),
-            ...(warnOnly > 0
-              ? [`${warnOnly} declared route(s) are warn-only and still send the original payload`]
-              : []),
+            ...(gaps.typedOnlyReason === undefined ? [] : [gaps.typedOnlyReason]),
+            ...(gaps.warnOnlyReason === undefined ? [] : [gaps.warnOnlyReason]),
+            ...(typedOnly + warnOnly > 0 ? [RESPONSE_CONTRACT_BASELINE_HINT] : []),
           ],
   }
   return Object.freeze({