@nifrajs/cli 1.5.0 → 1.11.0

package/src/check.ts

@@ -16,8 +16,8 @@
  * anything fails. Pure scanners (`scanFetchText`, `scanServerOnlyImports`) are unit-tested.
  */
 
-import { readFileSync } from "node:fs"
-import { dirname, isAbsolute, join } from "node:path"
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, isAbsolute, join, resolve } from "node:path"
 import { Glob } from "bun"
 
 export interface SourceFinding {
@@ -195,8 +195,13 @@ function parseSimpleFetchCall(snippet: string): SimpleFetchCall | undefined {
   return { path, method, start: match.index, end: close + 1 }
 }
 
-function isPotentialNifraBackendSource(code: string): boolean {
-  return code.includes("@nifrajs/core") || /(?<![.\w])server\s*\(/.test(code)
+function isPotentialBackendSource(code: string): boolean {
+  return (
+    code.includes("@nifrajs/core") ||
+    /(?<![.\w])server\s*\(/.test(code) ||
+    /(?:from\s*|import\s*)["']hono["']/.test(code) ||
+    /new\s+Hono(?:<[^>]+>)?\s*\(/.test(code)
+  )
 }
 
 function scanRoutePattern(
@@ -289,7 +294,7 @@ export function scanFetchText(file: string, content: string): SourceFinding[] {
 /** Statically collect simple Nifra route registrations from source, without importing app code. */
 export function scanStaticRouteText(file: string, content: string): StaticRouteFinding[] {
   const code = stripComments(content)
-  if (!isPotentialNifraBackendSource(code)) return []
+  if (!isPotentialBackendSource(code)) return []
   return [
     ...scanRoutePattern(file, content, code, ROUTE_REGISTRATION_DQ),
     ...scanRoutePattern(file, content, code, ROUTE_REGISTRATION_SQ),
@@ -766,6 +771,9 @@ export interface CheckDiagnostic {
     | "response-route"
     | "undeclared-dependency"
     | "server-manifest-drift"
+    | "manifest-drift"
+    | "capability-assurance"
+    | "capability-config"
   /** `error` fails the gate (a real contract break); `warning` is advisory — surfaced to the agent but
    * does NOT fail `nifra check`, for patterns that are sometimes intentional (a route returning a raw
    * `Response`, which silently drops the typed client to `data: never` but is valid for files/redirects). */
@@ -826,6 +834,10 @@ const UNDECLARED_DEP_HINT =
   "imported package is not declared in package.json dependencies — run bun add to declare it"
 const MANIFEST_DRIFT_HINT =
   "server-manifest.ts is out of sync with routes/ — re-run the build to regenerate it (a disk-less worker bakes this route table, so the drift is a silent edge break), then commit it"
+const TRUST_MANIFEST_DRIFT_HINT =
+  "nifra.manifest.json is missing, invalid, or out of sync — run `nifra manifest emit`, review it, and commit the regenerated trust artifact"
+const CAPABILITY_HINT =
+  "effect/capability assurance failed — align the route declaration with approved adapter provenance; never bypass an owned effect seam"
 
 function oneLineDiff(file: string, line: number, before: string, after: string): string {
   return `--- ${file}:${line}\n+++ ${file}:${line}\n@@\n-${before}\n+${after}`
@@ -1150,19 +1162,127 @@ export async function collectCheckResult(
     })
   }
 
+  // G+B+D+F: when the project opts into capability assurance, `nifra check` becomes the static
+  // provenance firewall as well as the typed-contract gate. Loading is explicit/config-owned; projects
+  // without nifra.assurance.ts retain the historical scan and hot path unchanged.
+  const assuranceConfigPath = join(cwd, "nifra.assurance.ts")
+  if (existsSync(assuranceConfigPath)) {
+    try {
+      const { loadAssuranceConfig } = await import("./assure.ts")
+      const config = await loadAssuranceConfig(cwd)
+      let capabilityReport:
+        | Awaited<
+            ReturnType<typeof import("./capabilities-tool.ts")["collectCapabilityProjectReport"]>
+          >["report"]
+        | undefined
+      if (config.capabilities !== undefined) {
+        const { collectCapabilityProjectReport } = await import("./capabilities-tool.ts")
+        const project = await collectCapabilityProjectReport(
+          cwd,
+          config.source,
+          config.capabilities,
+        )
+        capabilityReport = project.report
+        for (const finding of project.report.findings) {
+          const violation =
+            finding.code === "forbidden-effect-import"
+              ? project.violations.find(
+                  (candidate) =>
+                    candidate.method === finding.method && candidate.path === finding.path,
+                )
+              : undefined
+          diagnostics.push({
+            rule: "capability-assurance",
+            severity: "error",
+            ...(violation !== undefined ? { file: violation.module, chain: violation.chain } : {}),
+            message: `${finding.message} — ${CAPABILITY_HINT}`,
+            fix: CAPABILITY_HINT,
+            suggestion: {
+              kind: "manual",
+              title: "Restore declared effect provenance",
+              steps: [
+                "Route effectful work through an import listed in capabilities.provenance.imports.",
+                "Declare the exact capability token on the route; do not widen unrelated routes in the same file.",
+                "For domain writes, add the request-idempotency or durable-command adapter required by the capability definition.",
+                "Run `nifra capabilities snapshot` only after assurance passes, then review the lockfile diff.",
+              ],
+            },
+          })
+        }
+      }
+      if (config.manifest !== undefined) {
+        const { evaluateRouteAssurance } = await import("@nifrajs/core/assurance")
+        const { buildNifraManifest, parseNifraManifest, serializeNifraManifest } = await import(
+          "@nifrajs/core/manifest"
+        )
+        const assurance = evaluateRouteAssurance(config.source, config.policy)
+        const path = resolve(cwd, config.manifest.path ?? "nifra.manifest.json")
+        let message: string | undefined
+        if (!assurance.ok || (capabilityReport !== undefined && !capabilityReport.ok)) {
+          message =
+            "the configured assurance policy is failing, so a trusted manifest cannot be built"
+        } else if (!existsSync(path)) {
+          message = "the configured trust manifest is missing"
+        } else {
+          try {
+            const current = await buildNifraManifest({
+              source: config.source,
+              assurance,
+              ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
+            })
+            const storedText = await Bun.file(path).text()
+            const stored = await parseNifraManifest(storedText, path)
+            const expectedText = `${serializeNifraManifest(current)}\n`
+            if (storedText !== expectedText || stored.contentHash !== current.contentHash) {
+              message = "the configured trust manifest does not match live route reflection"
+            }
+          } catch (error) {
+            message = `the configured trust manifest is invalid: ${error instanceof Error ? error.message : String(error)}`
+          }
+        }
+        if (message !== undefined) {
+          diagnostics.push({
+            rule: "manifest-drift",
+            severity: "error",
+            file: path,
+            message: `${message} — ${TRUST_MANIFEST_DRIFT_HINT}`,
+            fix: TRUST_MANIFEST_DRIFT_HINT,
+            suggestion: {
+              kind: "command",
+              title: "Regenerate the signed-manifest input artifact",
+              command: ["nifra", "manifest", "emit"],
+              steps: [
+                "Review the route, assurance, capability, and classification delta before committing it.",
+              ],
+            },
+          })
+        }
+      }
+    } catch (err) {
+      diagnostics.push({
+        rule: "capability-config",
+        severity: "error",
+        file: "nifra.assurance.ts",
+        message: `capability assurance config could not be evaluated: ${err instanceof Error ? err.message : String(err)}`,
+        suggestion: {
+          kind: "manual",
+          title: "Repair the assurance config",
+          steps: [
+            "Ensure nifra.assurance.ts default-exports defineAssuranceConfig({ source, policy, capabilities }).",
+            "Fix configuration/import errors; the provenance firewall fails closed when its policy cannot load.",
+          ],
+        },
+      })
+    }
+  }
+
   // Cap the diagnostics when asked (the MCP path), so a project with thousands of findings can't return a
   // message that breaks the stdio transport. `ok` reflects the FULL set — truncation never flips it.
   const total = diagnostics.length
   const max = opts.maxDiagnostics
   const shown = max !== undefined && total > max ? diagnostics.slice(0, max) : diagnostics
   return {
-    ok:
-      tc.ok &&
-      fetches.length === 0 &&
-      untypedClients.length === 0 &&
-      serverImports.length === 0 &&
-      manifestDrift.length === 0 &&
-      (!dr.ran || dr.findings.length === 0),
+    ok: !diagnostics.some((diagnostic) => diagnostic.severity === "error"),
     typecheck: tc.ran ? (tc.ok ? "pass" : "fail") : "skipped",
     diagnostics: shown,
     ...(shown.length < total ? { truncated: { shown: shown.length, total } } : {}),
@@ -1198,6 +1318,9 @@ export async function runCheck(
     ["response-route", "route returns a raw Response (typed client → data: never)"],
     ["undeclared-dependency", "undeclared dependency in package.json"],
     ["server-manifest-drift", "server-manifest.ts drifted from routes/"],
+    ["manifest-drift", "versioned trust manifest drift"],
+    ["capability-assurance", "effect/capability assurance"],
+    ["capability-config", "capability assurance config"],
   ] as const) {
     const ds = counts(rule)
     if (rule === "response-route") {

package/src/cli.ts

@@ -72,9 +72,34 @@ Usage:
                                          request field or a removed response field breaks; widening a
                                          request enum or adding a response field doesn't) and fails
                                          closed. Exits non-zero on any breaking change — run it in CI.
+  nifra assure  [--config <file>] [--json]  Route-assurance gate: load nifra.assurance.ts, classify every
+                                         reflected backend route, and fail when required enforcement
+                                         evidence is missing/forbidden or a route is unclassified.
+  nifra capabilities snapshot [--out <file>] [--config <file>]
+                                         Write the deterministic, token-only capability lockfile, but
+                                         only after provenance + idempotency assurance passes.
+  nifra capabilities check [--lockfile <file>] [--config <file>] [--json]
+                                         CI gate: fail on raw effect-import bypasses, declaration/evidence
+                                         drift, unsafe GET/HEAD writes, idempotency gaps, or lockfile drift.
+  nifra manifest emit [--out <file>] [--config <file>] [--sign <key-ref>]
+                                         Emit a deterministic route trust artifact after assurance passes;
+                                         optionally write an Ed25519 signature via the configured KMS signer.
+  nifra manifest diff <before> <after> [--json]
+                                         Hash-verify and compare two manifests; fail on contract, assurance,
+                                         capability, or response-classification regressions.
+  nifra levels  [--json] [--min <n>] [--config <file>]
+                                         Compute the verification ladder (L0 typed contract → L1 route
+                                         assurance → L2 capability lockfile → L3 route manifest → L4
+                                         invariant-tested); --min <n> fails the exit code below level n.
   nifra doctor  [--json] [--auto-fix]    Flag packages imported in source but missing from package.json
                                          (resolve at Bun runtime, break tsc + standalone install);
                                          --auto-fix writes safe local-version dependency fixes.
+  nifra upgrade <version>                Run the per-release upgrade recipe for <version>: sweep every
+                [--write] [--no-verify]  matching dependency pin (preserving ^/~/exact) + apply exact
+                [--list] [--json]        import moves across the workspace, then verify with nifra check.
+                                         Dry-run by default; --write applies then verifies (--no-verify
+                                         to skip). --list shows available targets. Fail-closed on an
+                                         unknown version. Deterministic + idempotent.
   nifra port    [--target <t>] [--json]  Portability linter: print a feature × deploy-target capability
                 [--ci] [--strict]        matrix (in-memory stores, in-process cron/WebSocket, Bun/Deno
                                          globals, node: builtins) with file:line evidence. --target auto-
@@ -89,7 +114,7 @@ Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with
 \`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "1.5.0"
+const CLI_VERSION = "1.11.0"
 
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v: unknown): RenderAdapter => v as RenderAdapter
@@ -181,24 +206,28 @@ async function buildForTarget(app: LoadedApp, target: string, report: boolean):
   if (report) console.log(`\n${renderSizeReport(result.size)}`)
 }
 
-/** Build a fetch-capable app instance for the `static` target's prerender pass. Mirrors `nifra start`:
- * register the framework's SSR Bun plugins (so `.vue`/`.svelte`/Solid routes import), discover routes,
- * and wire the in-process backend so build-time loaders can read data. The returned `Server` already
- * satisfies `buildTarget`'s `PrerenderAppLike` (a `fetch(req)` yielding a `Response`). */
+/** Build the app FACTORY for the `static` target's prerender pass. Mirrors `nifra start`: register the
+ * framework's SSR Bun plugins (so `.vue`/`.svelte`/Solid routes import) once, then return a factory that
+ * `createWebApp`s the app for the client build's manifest. The client entry MUST be the real content-hashed
+ * bundle (`client.entry`) — it's the hydration `<script src>` the prerendered HTML emits, so a placeholder
+ * would 404 and the pages would render but never hydrate (inert controls). Styles/route-preload are wired
+ * from the same manifest so the static HTML matches what `nifra start` serves. */
 async function buildPrerenderApp(
   app: LoadedApp,
-): Promise<{ fetch(req: Request): Response | Promise<Response> }> {
+): Promise<(client: BuiltManifest) => { fetch(req: Request): Response | Promise<Response> }> {
   const { plugin } = await import("bun")
   const { framework: fw, routesDir, backend } = app
   for (const p of asBunPlugins(await resolvePlugins(fw.serverPlugins))) plugin(p)
-  return createWebApp({
-    adapter: asAdapter(fw.adapter),
-    manifest: discoverRoutes(routesDir),
-    // The client entry is irrelevant to the static HTML (it's a hydration script tag) — a placeholder
-    // is fine; the real hashed bundle is emitted to /assets by buildTarget's client build.
-    clientEntry: "/assets/_nifra-entry.js",
-    ...apiOf(backend),
-  })
+  return (client) =>
+    createWebApp({
+      adapter: asAdapter(fw.adapter),
+      manifest: discoverRoutes(routesDir),
+      clientEntry: client.entry,
+      ...(client.routes ? { routePreload: client.routes } : {}),
+      ...(client.css ? { styles: client.css } : {}),
+      ...(client.routeStyles ? { routeStyles: client.routeStyles } : {}),
+      ...apiOf(backend),
+    })
 }
 
 interface BuiltManifest {
@@ -371,6 +400,166 @@ async function main(): Promise<void> {
     }
     return
   }
+  // Route assurance intentionally loads only its explicit config (which imports the backend it audits),
+  // not the full SSR app. Like snapshot/diff, this works for API-only projects.
+  if (command === "assure") {
+    const { runAssurance } = await import("./assure.ts")
+    const configIdx = argv.indexOf("--config")
+    const config = configIdx !== -1 ? argv[configIdx + 1] : undefined
+    if (configIdx !== -1 && (config === undefined || config.startsWith("-"))) {
+      console.error("[nifra] --config needs a file path")
+      process.exitCode = 1
+      return
+    }
+    try {
+      if (
+        !(await runAssurance(process.cwd(), {
+          json: argv.includes("--json"),
+          ...(config !== undefined ? { config } : {}),
+        }))
+      )
+        process.exitCode = 1
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exitCode = 1
+    }
+    return
+  }
+  if (command === "capabilities") {
+    const action = argv[1]
+    const valueAfter = (flag: string): string | undefined => {
+      const index = argv.indexOf(flag)
+      const value = index === -1 ? undefined : argv[index + 1]
+      if (index !== -1 && (value === undefined || value.startsWith("-"))) {
+        throw new Error(`[nifra] ${flag} needs a file path`)
+      }
+      return value
+    }
+    try {
+      const { runCapabilityCheck, runCapabilitySnapshot } = await import("./capabilities-tool.ts")
+      const config = valueAfter("--config")
+      if (action === "snapshot") {
+        const out = valueAfter("--out")
+        if (
+          !(await runCapabilitySnapshot(process.cwd(), {
+            ...(config !== undefined ? { config } : {}),
+            ...(out !== undefined ? { out } : {}),
+          }))
+        )
+          process.exitCode = 1
+      } else if (action === "check") {
+        const lockfile = valueAfter("--lockfile")
+        if (
+          !(await runCapabilityCheck(process.cwd(), {
+            ...(config !== undefined ? { config } : {}),
+            ...(lockfile !== undefined ? { lockfile } : {}),
+            json: argv.includes("--json"),
+          }))
+        )
+          process.exitCode = 1
+      } else {
+        throw new Error("[nifra] capabilities needs `snapshot` or `check`")
+      }
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exitCode = 1
+    }
+    return
+  }
+  if (command === "manifest") {
+    const action = argv[1]
+    const valueAfter = (flag: string): string | undefined => {
+      const index = argv.indexOf(flag)
+      const value = index === -1 ? undefined : argv[index + 1]
+      if (index !== -1 && (value === undefined || value.startsWith("-"))) {
+        throw new Error(`[nifra] ${flag} needs a value`)
+      }
+      return value
+    }
+    try {
+      const { runManifestDiff, runManifestEmit } = await import("./manifest-tool.ts")
+      if (action === "emit") {
+        const config = valueAfter("--config")
+        const out = valueAfter("--out")
+        const sign = valueAfter("--sign")
+        if (
+          !(await runManifestEmit(process.cwd(), {
+            ...(config !== undefined ? { config } : {}),
+            ...(out !== undefined ? { out } : {}),
+            ...(sign !== undefined ? { sign } : {}),
+          }))
+        )
+          process.exitCode = 1
+      } else if (action === "diff") {
+        const paths = argv.slice(2).filter((arg) => !arg.startsWith("-"))
+        if (paths.length !== 2) throw new Error("[nifra] manifest diff needs <before> <after>")
+        if (
+          !(await runManifestDiff(process.cwd(), paths[0]!, paths[1]!, {
+            json: argv.includes("--json"),
+          }))
+        )
+          process.exitCode = 1
+      } else {
+        throw new Error("[nifra] manifest needs `emit` or `diff`")
+      }
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exitCode = 1
+    }
+    return
+  }
+  if (command === "levels") {
+    const valueAfter = (flag: string): string | undefined => {
+      const index = argv.indexOf(flag)
+      const value = index === -1 ? undefined : argv[index + 1]
+      if (index !== -1 && (value === undefined || value.startsWith("-"))) {
+        throw new Error(`[nifra] ${flag} needs a value`)
+      }
+      return value
+    }
+    try {
+      const { runLevels } = await import("./levels-tool.ts")
+      const config = valueAfter("--config")
+      const minRaw = valueAfter("--min")
+      const min = minRaw === undefined ? undefined : Number(minRaw)
+      if (min !== undefined && (!Number.isInteger(min) || min < 0 || min > 4)) {
+        throw new Error("[nifra] --min must be an integer level between 0 and 4")
+      }
+      if (
+        !(await runLevels(process.cwd(), {
+          json: argv.includes("--json"),
+          ...(config !== undefined ? { config } : {}),
+          ...(min !== undefined ? { min } : {}),
+        }))
+      )
+        process.exitCode = 1
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exitCode = 1
+    }
+    return
+  }
+  // `upgrade` is a pure cwd file-transformer (package.json pins + import moves) driven by a per-release
+  // recipe, then verified with `nifra check`. Dispatch before the eager `loadApp` — it must run on any
+  // repo (API-only, not built, or mid-upgrade with edits that don't yet typecheck under dry-run).
+  if (command === "upgrade") {
+    const { runUpgrade } = await import("./upgrade.ts")
+    const version = argv.slice(1).find((arg) => !arg.startsWith("-"))
+    try {
+      const ok = await runUpgrade(process.cwd(), {
+        ...(version !== undefined ? { version } : {}),
+        write: argv.includes("--write"),
+        json: argv.includes("--json"),
+        list: argv.includes("--list"),
+        verify: !argv.includes("--no-verify"),
+      })
+      if (!ok) process.exitCode = 1
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exitCode = 1
+    }
+    return
+  }
   // `port` is a pure cwd-based portability linter (scans source, doesn't run the app) — like `check`/
   // `doctor`, dispatch before the eager `loadApp` so it runs on an API-only / not-yet-built project.
   if (command === "port") {

package/src/levels-tool.ts

@@ -0,0 +1,222 @@
+/**
+ * `nifra levels` — the verification ladder, computed from gates that already exist:
+ *
+ *   L0 typed contract      — `nifra check` passes (compiler-enforced frontend↔backend contract)
+ *   L1 route assurance     — `nifra.assurance.ts` present and every route satisfies its policy
+ *   L2 capability lockfile — capability/effect assurance passes and the lockfile is in sync
+ *   L3 route manifest      — the emitted manifest hash-verifies and matches the current app
+ *   L4 invariant-tested    — every route passes through an explicitly isolated executor
+ *
+ * A level counts only when every level below it holds — the ladder is cumulative, so "L3" is one
+ * honest word for a whole posture. Levels are computed, never self-declared.
+ */
+
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { evaluateRouteAssurance } from "@nifrajs/core/assurance"
+import { type evaluateCapabilityAssurance, snapshotCapabilities } from "@nifrajs/core/capabilities"
+import { runContractInvariants } from "@nifrajs/core/invariants"
+import { buildNifraManifest, parseNifraManifest } from "@nifrajs/core/manifest"
+import { loadAssuranceConfig } from "./assure.ts"
+import {
+  collectCapabilityProjectReport,
+  diffCapabilitySnapshots,
+  parseCapabilityLockfile,
+} from "./capabilities-tool.ts"
+import { collectCheckResult } from "./check.ts"
+import { DEFAULT_MANIFEST_FILE } from "./manifest-tool.ts"
+
+export interface VerificationLevelStatus {
+  readonly level: number
+  readonly name: string
+  readonly ok: boolean
+  /** Why the level does not hold — a gate failure or a missing prerequisite. Empty when ok. */
+  readonly reasons: readonly string[]
+}
+
+export interface VerificationLevelsResult {
+  /** Highest level whose whole ladder holds; -1 when even L0 fails. */
+  readonly achieved: number
+  readonly levels: readonly VerificationLevelStatus[]
+}
+
+export interface CollectLevelsOptions {
+  readonly config?: string
+  /** Deterministic seed for the L4 invariant run. Default 1. */
+  readonly seed?: number
+}
+
+/** Compute the ladder. Each level is evaluated independently, then gated on the levels below. */
+export async function collectVerificationLevels(
+  cwd: string,
+  options: CollectLevelsOptions = {},
+): Promise<VerificationLevelsResult> {
+  const statuses: { level: number; name: string; ok: boolean; reasons: string[] }[] = []
+
+  // L0 — typed contract (`nifra check`).
+  const check = await collectCheckResult(cwd, { maxDiagnostics: 5 })
+  statuses.push({
+    level: 0,
+    name: "typed contract",
+    ok: check.ok,
+    reasons: check.ok ? [] : check.diagnostics.map((d) => `${d.rule}: ${d.message}`).slice(0, 5),
+  })
+
+  // L1-L4 all hang off the assurance config; without it the ladder stops at L0 by definition.
+  let config: Awaited<ReturnType<typeof loadAssuranceConfig>> | undefined
+  try {
+    config = await loadAssuranceConfig(cwd, options.config)
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    for (const [level, name] of [
+      [1, "route assurance"],
+      [2, "capability lockfile"],
+      [3, "route manifest"],
+      [4, "invariant-tested"],
+    ] as const) {
+      statuses.push({ level, name, ok: false, reasons: [reason] })
+    }
+    return finalize(statuses)
+  }
+
+  // L1 — route assurance.
+  const assurance = evaluateRouteAssurance(config.source, config.policy)
+  statuses.push({
+    level: 1,
+    name: "route assurance",
+    ok: assurance.ok,
+    reasons: assurance.findings.map((f) => f.message).slice(0, 5),
+  })
+
+  // L2 — capability assurance + lockfile in sync.
+  const l2Reasons: string[] = []
+  let capabilityReport: ReturnType<typeof evaluateCapabilityAssurance> | undefined
+  if (config.capabilities === undefined) {
+    l2Reasons.push("nifra.assurance.ts declares no capabilities policy")
+  } else {
+    const project = await collectCapabilityProjectReport(cwd, config.source, config.capabilities)
+    capabilityReport = project.report
+    if (!project.report.ok) {
+      l2Reasons.push(...project.report.findings.map((f) => f.message).slice(0, 5))
+    }
+    const lockfilePath = resolve(cwd, config.capabilities.lockfile ?? "capabilities.lock.json")
+    if (!existsSync(lockfilePath)) {
+      l2Reasons.push(`capability lockfile missing (${lockfilePath})`)
+    } else if (project.report.ok) {
+      const recorded = parseCapabilityLockfile(await Bun.file(lockfilePath).text(), lockfilePath)
+      const drift = diffCapabilitySnapshots(recorded, snapshotCapabilities(project.report))
+      if (drift.length > 0) l2Reasons.push(...drift.slice(0, 5))
+    }
+  }
+  statuses.push({
+    level: 2,
+    name: "capability lockfile",
+    ok: l2Reasons.length === 0,
+    reasons: l2Reasons,
+  })
+
+  // L3 — emitted manifest hash-verifies AND matches the current app.
+  const l3Reasons: string[] = []
+  const manifestPath = resolve(cwd, config.manifest?.path ?? DEFAULT_MANIFEST_FILE)
+  if (!existsSync(manifestPath)) {
+    l3Reasons.push(`manifest missing (${manifestPath}) — run \`nifra manifest emit\``)
+  } else {
+    try {
+      const recorded = await parseNifraManifest(await Bun.file(manifestPath).text(), manifestPath)
+      if (assurance.ok && (capabilityReport === undefined || capabilityReport.ok)) {
+        const current = await buildNifraManifest({
+          source: config.source,
+          assurance,
+          ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
+        })
+        if (current.contentHash !== recorded.contentHash) {
+          l3Reasons.push("manifest is stale — the app changed since it was emitted")
+        }
+      } else {
+        l3Reasons.push("manifest cannot be validated while assurance is failing")
+      }
+    } catch (err) {
+      l3Reasons.push(err instanceof Error ? err.message : String(err))
+    }
+  }
+  statuses.push({
+    level: 3,
+    name: "route manifest",
+    ok: l3Reasons.length === 0,
+    reasons: l3Reasons,
+  })
+
+  // L4 — contract-generated invariants against an explicitly isolated executor.
+  const l4Reasons: string[] = []
+  if (config.invariants === undefined) {
+    l4Reasons.push(
+      "no isolated invariant executor configured — add `invariants.executor` in nifra.assurance.ts",
+    )
+  } else {
+    const invariants = await runContractInvariants(config.source as object, {
+      seed: options.seed ?? 1,
+      executor: config.invariants.executor,
+    })
+    if (!invariants.ok) l4Reasons.push(...invariants.findings.map((f) => f.message).slice(0, 5))
+    if (invariants.skipped.length > 0) {
+      l4Reasons.push(
+        ...invariants.skipped
+          .slice(0, 5)
+          .map(
+            (route) => `${route.method} ${route.path} was not invariant-tested: ${route.reason}`,
+          ),
+      )
+    }
+  }
+  statuses.push({
+    level: 4,
+    name: "invariant-tested",
+    ok: l4Reasons.length === 0,
+    reasons: l4Reasons,
+  })
+
+  return finalize(statuses)
+}
+
+function finalize(
+  statuses: readonly { level: number; name: string; ok: boolean; reasons: string[] }[],
+): VerificationLevelsResult {
+  // Cumulative: the achieved level is the last rung with every rung below it also holding.
+  let achieved = -1
+  for (const status of statuses) {
+    if (!status.ok) break
+    achieved = status.level
+  }
+  return Object.freeze({
+    achieved,
+    levels: Object.freeze(
+      statuses.map((status) =>
+        Object.freeze({ ...status, reasons: Object.freeze([...status.reasons]) }),
+      ),
+    ),
+  })
+}
+
+/** CLI entry: print the ladder (or JSON) and return whether the requested floor is met. */
+export async function runLevels(
+  cwd: string,
+  options: CollectLevelsOptions & { readonly json?: boolean; readonly min?: number } = {},
+): Promise<boolean> {
+  const result = await collectVerificationLevels(cwd, options)
+  if (options.json === true) {
+    console.log(JSON.stringify(result, null, 2))
+  } else {
+    for (const status of result.levels) {
+      const mark = status.ok ? "✓" : "✗"
+      console.log(`${mark} L${status.level} ${status.name}`)
+      for (const reason of status.reasons) console.log(`    - ${reason}`)
+    }
+    console.log(
+      result.achieved < 0
+        ? "[nifra] verification level: none (L0 failing)"
+        : `[nifra] verification level: L${result.achieved}`,
+    )
+  }
+  const min = options.min ?? 0
+  return result.achieved >= min
+}