@nifrajs/cli 1.6.0 → 1.12.0

package/docs/llms-full.txt

@@ -1682,6 +1682,89 @@ trustworthy client IP can be derived, and never trusts `X-Forwarded-For` unless
 bodies before routing (fails closed with `411` on a length-less body). The read-time
 guard above (`c.boundedBody` / schema cap) remains the source of truth.
 
+### Route assurance — prove every route is guarded
+
+Installing security middleware is not the same as proving it covers every route. Nifra's
+official auth, CSRF, body-limit, rate-limit, idempotency, IP-restriction, and security-header
+modules publish reflection-safe evidence at the hook where they enforce it. A policy then
+classifies every route and fails closed when evidence is missing or forbidden.
+
+```ts
+// doc-check: skip — configuration file imports your application backend.
+// nifra.assurance.ts
+import { defineAssuranceConfig, NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
+import { app } from "./backend.ts"
+
+export default defineAssuranceConfig({
+  source: app,
+  policy: {
+    // First match owns the route: put narrow exceptions before broad defaults.
+    rules: [
+      { name: "health", match: { paths: ["/health"] }, require: [],
+        forbid: [NIFRA_ASSURANCE.AUTHENTICATED] },
+      { name: "mutation", match: { methods: ["POST", "PUT", "PATCH", "DELETE"] },
+        require: [NIFRA_ASSURANCE.AUTHENTICATED, NIFRA_ASSURANCE.CSRF,
+          NIFRA_ASSURANCE.BODY_BOUNDED] },
+      { name: "read", match: { methods: ["GET", "HEAD"] },
+        require: [NIFRA_ASSURANCE.AUTHENTICATED] },
+    ],
+  },
+})
+
+// CI: nifra assure              # human diagnostics
+// CI: nifra assure --json       # complete machine-readable report
+```
+
+Evidence follows real lifecycle semantics: pre-routing and response hooks cover the whole app,
+while authentication and other order-scoped hooks cover only routes registered after them.
+Method and path filters prevent a narrow guard from claiming broader coverage. The evaluation
+runs only through reflection or `nifra assure`, so requests pay no assurance cost.
+
+### Effect assurance — declared capability versus provenance
+
+Authentication does not reveal what a route can do. Capability assurance compares an exact
+route declaration against every approved effect import reachable through that route's local
+module graph. Static, dynamic, `require`, and re-export edges are scanned; raw provider
+imports fail `nifra check`. Runtime beacons add denial at owned adapters, but are never
+treated as a substitute for static provenance.
+
+```ts
+// doc-check: skip — combines route and assurance-config excerpts.
+// route: exact effect declaration + runtime beacon at the owned adapter seam
+import { useCapability } from "@nifrajs/core/capabilities"
+
+app.post("/orders", { capabilities: ["db.write"] }, async (c) => {
+  useCapability(c, "db.write") // undeclared use fails before the effect
+  return orders.write(c.body)
+})
+
+// in nifra.assurance.ts, alongside policy:
+capabilities: {
+  definitions: [
+    { id: "db.read", zone: "domain", access: "read" },
+    { id: "db.write", zone: "domain", access: "write", idempotency: "request" },
+    { id: "telemetry.write", zone: "operational", access: "write" },
+  ],
+  provenance: {
+    // Use effect-specific facades. A broad module that mixes reads/writes cannot prove either.
+    imports: [
+      { specifier: "@app/db/read", capabilities: ["db.read"] },
+      { specifier: "@app/db/write", capabilities: ["db.write"] },
+    ],
+    forbiddenImports: [
+      { specifier: "postgres", reason: "use the tenant-scoped DB facade" },
+    ],
+  },
+}
+
+// developer: nifra capabilities snapshot
+// CI:        nifra check && nifra assure && nifra capabilities check
+```
+
+Domain writes on `GET`/`HEAD` are hard violations. Each write definition may
+require request idempotency or durable command/provider-key evidence. The lockfile contains only
+method, path, and capability tokens—no payloads or tenant data—and CI never rewrites it.
+
 ### Already built in
 
 These add to Nifra's standing defaults: strict-by-default schema validation (unknown fields
@@ -3148,9 +3231,10 @@ backend over HTTP — so a browser `POST /api/sync` hit the page router and 404/
 until you hand-wrote a dispatch branch in `server-bun.ts`. Now
 `createWebApp` mounts it for you: a request whose pathname is exactly
 `apiPrefix` (default `/api`) or starts with
-`apiPrefix + "/"` is dispatched to `api.fetch(req.url, req)`
-**before** page routing, and the backend's `Response` is returned
-untouched (the request body is passed through, never pre-read).
+`apiPrefix + "/"` is dispatched through Nifra's platform-aware backend mount
+interface **before** page routing. The backend receives the same Workers
+`env` bindings and `waitUntil` lifetime as the web app, and its
+`Response` is returned untouched (the request body is passed through, never pre-read).
 
 ```ts
 // server.ts (prod) — createWebApp serves pages AND auto-mounts the backend at /api/*.
@@ -3224,6 +3308,55 @@ They share the backend: a route `action` and a browser `fetch` can both
 call `POST /api/sync` — one in-process, one over the mount — and get identical
 validation and behavior.
 
+## Nifra — Request budgets
+
+> Propagate one absolute deadline through Nifra requests and downstream adapters without resetting time at each hop.
+
+A timeout should not restart at every hop. Nifra admits one absolute wire deadline, clamps it
+to local policy, and exposes monotonic remaining time beside the existing cancellation signal.
+
+### Clamp once at admission
+
+```ts
+import { server } from "@nifrajs/core"
+
+const app = server({
+  requestTimeoutMs: 2_000,
+  acceptInboundDeadlines: true,
+  maxInboundDeadlineMs: 5_000,
+}).get("/report", async (c) => {
+  // c.signal aborts at the SAME effective deadline.
+  // remaining() is monotonic even if the wall clock jumps.
+  return { remainingMs: c.budget.remaining() }
+})
+```
+
+The canonical header is `x-nifra-deadline`, containing Unix epoch milliseconds.
+Admission is an explicit trust-boundary choice via `acceptInboundDeadlines`; ordinary
+public routes ignore the header by default. Once enabled, a client value can only shorten
+local work. Malformed values return 400, expired values return 408, and a request that exhausts
+an inherited deadline returns 504.
+
+### Reserve time for the caller
+
+```ts
+// doc-check: skip — context and downstream adapter are established by the app
+const child = c.budget.child(50) // keep 50ms to serialize the response
+
+await fetch(url, {
+  signal: child.signal,
+  headers: withDeadlineHeader(undefined, child),
+})
+```
+
+`child(reserveMs)` preserves response cleanup time without resetting the absolute
+deadline. Downstream adapters must also use `remaining()` for their actual timeout;
+forwarding the header alone is decorative.
+
+Configure a finite `requestTimeoutMs` before handing `c.budget` to a
+production adapter. The no-timeout compatibility path is deliberately unbounded and is not
+written to the wire.
+
 ## Nifra — Framework contract
 
 > The one-page contract: LoaderContext shape, loader/action/meta/head signatures, the client↔server boundary, and the build-output contract — every signature verified against the source.
@@ -4160,6 +4293,117 @@ backend you can also ship on its own. Start with [Getting started](/docs).
 Moving a backend (Express, Hono, Fastify, Elysia) instead? See
 [Migrating a backend](/docs/migrate-backend).
 
+## Nifra — Contract-derived adversarial testing
+
+> Turn route schemas into hostile input, response-conformance, replay, shrinking, and runtime-matrix tests with @nifrajs/testing.
+
+A route contract should be more than documentation. `@nifrajs/testing` turns it
+into a laboratory: valid requests, hostile inputs, real boundary rejection, response
+conformance, shrinking, replay seeds, and adapter parity from one small test interface.
+
+### One assertion, every contracted boundary
+
+```ts
+import { assertAdversarialContract } from "@nifrajs/testing"
+import { app } from "../src/app"
+
+const { test } = await import("bun:test")
+
+test("the API contract withstands hostile inputs", async () => {
+  await assertAdversarialContract(app, { seed: 73 })
+})
+```
+
+For every selected route, the laboratory synthesizes a valid **contract witness**. It then
+changes types, removes required fields, crosses numeric and length bounds, inserts unknown
+properties, and descends into nested objects and arrays. A mutation is sent only after the
+route's own Standard Schema validator proves it invalid. Query values are proved after URL
+serialization, exactly as the server receives them.
+
+Invalid inputs must produce 422 by default. A valid witness is also executed for every
+declared `response`, and the real JSON body is validated off the request hot path.
+Use `expectedValidationStatuses` or `isRejected` when your app deliberately
+has a different validation response.
+
+### Opaque schemas stay validator-neutral
+
+Nifra's `t` schemas carry inspectable JSON Schema, so witness generation is
+automatic. Other Standard Schema libraries do not have to expose structure. Supply a known-good
+witness; their own validator still proves every hostile mutation.
+
+```ts
+// Standard Schema guarantees validation, not introspection.
+// Give opaque Zod/Valibot/ArkType routes only their known-good request values.
+await assertAdversarialContract(app, {
+  witnesses: {
+    "POST /users/:id": {
+      params: { id: "user-1" },
+      body: { name: "Ada" },
+      query: { notify: "true" },
+    },
+  },
+})
+```
+
+Missing, invalid, or unsynthesizable witnesses become explicit coverage gaps. The default is
+fail-closed; `requireCoverage: false` makes gaps advisory.
+
+### Auth and tenant context
+
+`prepareRequest` runs for every case and runtime. Use it to attach a test session,
+tenant identity, signed headers, or platform bindings without putting secrets into reports.
+
+```ts
+await assertAdversarialContract(app, {
+  prepareRequest(request, context) {
+    const headers = new Headers(request.headers)
+    headers.set("authorization", "Bearer test-session")
+    headers.set("x-tenant-id", context.runtime === "worker" ? "edge-test" : "local-test")
+    return new Request(request, { headers })
+  },
+})
+```
+
+### One contract, many runtimes
+
+Supply fetch targets to exercise the identical cases through Bun, Node, Deno, or Workers
+adapters. Reflection still comes from the original app, so there is one authoritative contract.
+
+```ts
+const report = await assertAdversarialContract(app, {
+  runtimes: [
+    { name: "bun",    fetch: (request) => bunApp.fetch(request) },
+    { name: "node",   fetch: (request) => nodeAdapter.fetch(request) },
+    { name: "worker", fetch: (request) => worker.fetch(request, env) },
+  ],
+})
+
+// Each target receives the same case IDs and deterministic witnesses.
+console.log(report.seed, report.counts)
+```
+
+### Shrink and replay failures
+
+Unexpectedly accepted hostile inputs are greedily reduced to a smaller validator-invalid
+request. Results do not print request bodies or headers; the stable case ID, runtime, and seed
+are enough to replay deterministically.
+
+```ts
+const report = await runAdversarialContract(app, { seed: 73 })
+const failure = report.failures[0]
+
+// CI can print this small, payload-free replay tuple.
+console.error(failure.replay) // { seed: 73, caseId: "...", runtime: "worker" }
+
+await assertAdversarialContract(app, {
+  seed: failure.replay.seed,
+  only: failure.replay.caseId,
+})
+```
+
+The response-conformance pass executes handlers, including POST/DELETE handlers. Run it with
+isolated fixtures and a test database. Never point a contract laboratory at production.
+
 ## Nifra — Types-first architecture
 
 > One schema is the single source of truth: it drives runtime validation, inferred TypeScript types, the no-codegen typed client, an OpenAPI document, and the MCP contract your agents read.
@@ -4411,6 +4655,38 @@ one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
 done-gate, or `nifra mcp` to give the agent live project tools.
 
+## @nifrajs/budget
+
+Compatibility import for the request-deadline mechanics owned by `@nifrajs/core/budget`. Existing
+Nifra, Hono, and Fetch consumers can keep this import unchanged; new core consumers may use the
+subpath directly. Both paths resolve to the same implementation and classes.
+
+```ts
+import {
+  assertBudgetRemaining,
+  createRequestBudget,
+  withDeadlineHeader,
+} from "@nifrajs/budget"
+
+const budget = createRequestBudget({
+  deadline: Date.now() + 2_000,
+  signal: request.signal,
+})
+
+assertBudgetRemaining(budget, 100)
+await fetch(url, {
+  signal: budget.signal,
+  headers: withDeadlineHeader(undefined, budget.child(50)),
+})
+```
+
+The wire value is an absolute Unix epoch deadline. `remaining()` samples wall time once, then uses a
+monotonic clock so NTP changes cannot extend or shorten admitted work. A budget does not choose retry,
+provider, tenant, or money policy; it only answers how much time remains.
+
+Nifra route handlers receive the same primitive as `c.budget`. `c.signal` remains the cancellation
+signal and aborts at the effective server deadline.
+
 ## @nifrajs/cache
 
 Typed KV cache for nifra — **TTL**, **stale-while-revalidate**, **tag invalidation**, and **single-flight
@@ -4479,9 +4755,40 @@ nifra start   [--port <n>] [--out <dir>]  Serve the built app (client + SSR) on
 nifra context                             Print this project's API + page routes + conventions.
 nifra mcp                                 MCP server (stdio) exposing this project to a coding agent.
 nifra check   [--json]                    Gate: typecheck + lints; --json includes fixes/suggestions.
-nifra doctor  [--json] [--auto-fix]       Catch undeclared imported packages; auto-fix safe local versions.
+nifra assure  [--config <file>] [--json]  Gate reflected routes against enforcement evidence.
+nifra capabilities check [--json]        Gate effect provenance + the reviewed capability lockfile.
+nifra manifest emit [--sign <key-ref>]   Emit the hash-verified route trust artifact after assurance.
+nifra manifest diff <before> <after>      Block promotion on contract/governance regressions.
+nifra doctor  [--json] [--auto-fix]       Catch undeclared imports and duplicate Nifra/React installs.
 ```
 
+## `nifra doctor` - dependency health
+
+Doctor diffs source imports against declared dependencies, then resolves identity-sensitive
+dependencies from every workspace package. More than one physical `@nifrajs/*`, `react`, or
+`react-dom` copy fails even when versions match; module identity is path-based. Doctor reports
+paths/importers and never deletes installations.
+
+## `nifra assure` — the route-enforcement gate
+
+Create `nifra.assurance.ts` with a default `defineAssuranceConfig({ source, policy })` export, then run
+`nifra assure` in CI. Official middleware publishes evidence at the same seam where it installs its
+hooks; the gate classifies every reflected route with the first matching rule and exits non-zero for an
+unclassified route, missing evidence, or forbidden evidence. Evaluation is startup/CI-only and adds no
+request-path overhead. Use `--json` for the complete per-route report or `--config` for another file.
+
+## `nifra manifest` — the deploy trust artifact
+
+Add optional `manifest: { path, signer }` settings to `nifra.assurance.ts`, then run
+`nifra manifest emit`. Emission refuses failing route or capability assurance and joins the route
+schemas, enforcement evidence, effect tokens, and field-level response classification into one
+deterministic SHA-256 artifact. `--sign <key-ref>` asks the configured callback to produce a detached
+Ed25519 sidecar, so the private key can stay inside KMS/HSM infrastructure.
+
+At promotion time, `nifra manifest diff previous.json candidate.json` hash-verifies both files and exits
+non-zero on a breaking API change, removed assurance, expanded effect, lost provenance coverage, or
+increased data sensitivity. This is separate from the frontend asset `dist/manifest.json`.
+
 ## `nifra check` — the drift gate (run as "done")
 
 `nifra check` makes nifra's anti-drift guarantees actually fire instead of relying on the agent to
@@ -4534,6 +4841,7 @@ an agent can act on the project, not just read about it. Core tools:
 - **`nifra_test`** — run bounded `bun test` with structured output.
 - **`nifra_check`** — run the drift gate and get the structured `{ ok, typecheck, diagnostics[] }`
   result with suggestions, so the agent verifies its own work and fixes each diagnostic before finishing.
+- **`nifra_assure`** — evaluate `nifra.assurance.ts` and return the complete per-route evidence report.
 - **`nifra_doctor`** — catch imported packages missing from `package.json`; with `autoFix:true`, write
   safe dependency entries when a version can be inferred locally and return exact `bun add` commands
   for anything that needs a package-manager decision.
@@ -4671,8 +4979,32 @@ export type App = typeof app // hand this to @nifrajs/client for end-to-end type
   `onRequest`/`beforeHandle`/`afterHandle`/`onResponse`/`onError` run around handlers;
   `use(middleware)` applies a bundle.
 - **Hardening built in.** `stop({ drainMs })` graceful shutdown (+ opt-in SIGTERM/
-  SIGINT), `requestTimeoutMs` (+ `ctx.signal`), a streaming body-size cap, and a
+  SIGINT), `requestTimeoutMs` (+ `ctx.signal` and `ctx.budget`), a streaming body-size cap, and a
   redacting structured `Logger`.
+- **One request budget.** `ctx.budget` carries the admitted absolute deadline and monotonic
+  `remaining()` time. An inbound `x-nifra-deadline` can only shorten `requestTimeoutMs`/
+  `maxInboundDeadlineMs`; malformed and expired values fail before the handler. `ctx.signal`
+  remains the cancellation primitive and aborts at that same effective deadline.
+- **Route assurance.** Official auth, CSRF, body-limit, rate-limit, idempotency,
+  IP-restriction, and security-header modules publish reflection-safe enforcement evidence.
+  An ordered `AssurancePolicy` classifies every route and fails closed on missing or forbidden
+  evidence without adding work to the request path.
+
+```ts
+import { defineAssurancePolicy, evaluateRouteAssurance, NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
+
+const policy = defineAssurancePolicy({
+  rules: [
+    { name: "health", match: { paths: ["/health"] }, require: [] },
+    { name: "mutation", match: { methods: ["POST", "PUT", "PATCH", "DELETE"] },
+      require: [NIFRA_ASSURANCE.AUTHENTICATED, NIFRA_ASSURANCE.CSRF] },
+    { name: "read", match: { methods: ["GET", "HEAD"] },
+      require: [NIFRA_ASSURANCE.AUTHENTICATED] },
+  ],
+})
+
+evaluateRouteAssurance(app, policy).ok // pure reflection-time evaluation
+```
 
 ESM-only; requires Bun at runtime. MIT.
 
@@ -4873,6 +5205,16 @@ one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
 done-gate, or `nifra mcp` to give the agent live project tools.
 
+## @nifrajs/events
+
+Portable, versioned event contracts — a typed, transport-agnostic event envelope validated by any Standard Schema.
+
+An envelope may carry the bounded `@nifrajs/core/causality` context for its exact event id. Creation
+and parsing reject mismatched nodes and unknown fields, so arbitrary payloads cannot hitchhike in the
+lineage metadata.
+
+See the [nifra docs](https://github.com/nifrajs/nifra#readme).
+
 ## @nifrajs/i18n
 
 Framework-agnostic i18n for nifra — locale negotiation + a tiny ICU message formatter on the platform Intl. Dependency-free.
@@ -5268,10 +5610,38 @@ const app = server()
   (`error` for 5xx, `ok` otherwise).
 - **Exposes `c.trace`** (`{ traceId, spanId, parentSpanId?, sampled, traceparent }`) — spread
   `traceHeaders(c.trace)` into any downstream `fetch`/`ctx.api` call to continue the trace.
+- **Exposes `c.causality`** - a bounded, payload-free request node that survives durable command,
+  event, workflow, projection, and repair seams. `traceHeaders(c.trace, c.causality)` forwards both
+  conventions to a trusted downstream service.
 - **Exposes `c.observation`** — integrations can start correctly-parented child observations or
   attach an adapter without rebuilding request lifecycle state.
 - `responseHeader: true` also sets `traceparent` on the response (browser/client correlation).
 
+## Durable causality and trust
+
+Pass a durable recorder to append the request root before the handler runs. An explicitly configured
+recorder is correctness evidence, so its failure fails the request closed:
+
+```ts
+app.use(tracing({
+  exporter,
+  causality: {
+    recorder: durableGraphStore,
+    acceptInbound: (request) => verifyInternalServiceCredential(request),
+  },
+}))
+```
+
+Inbound causality headers are **not trusted by default**. This prevents an internet client from
+injecting fake parents into another execution timeline. Supply `acceptInbound` only at an authenticated
+service-to-service boundary; a false, thrown, or rejected decision starts a fresh graph. W3C
+`traceparent` remains normal observability context, but a fresh durable execution id includes the
+server-generated span id and is not copied from the untrusted header.
+
+Use `causalitySpanLink(context)` when durable work opens a later observation. It creates a real OTel
+link to the nearest observed causal ancestor and drops invalid/unanchored contexts rather than
+inventing trace identity.
+
 ## Adapters
 
 Implement `ObservationAdapter` to send spans wherever you collect them. `SpanExporter` remains as a
@@ -5467,10 +5837,139 @@ import { assertSafeKey, StorageKeyError } from "@nifrajs/storage"
 
 ## @nifrajs/testing
 
-Testing helpers for nifra apps. [`@nifrajs/client`](../client)'s **`testClient`** is already the typed,
-no-network in-process request client (nifra's supertest / `inject`). This package adds what it doesn't: a
-**cookie jar** and a **cookie-persisting `testSession`**, so a login → authenticated-request flow tests as
-easily as a single request.
+Contract-derived adversarial testing and stateful in-process helpers for Nifra apps.
+
+## Contract laboratory
+
+`assertAdversarialContract` turns the schemas already registered on an app into executable tests. It:
+
+- synthesizes a valid **contract witness** from inspectable JSON Schema;
+- makes small nested **hostile mutations** and sends only values the route's own Standard Schema
+  validator has proved invalid after HTTP transport normalization;
+- expects rejection at the real request boundary (422 by default);
+- executes a valid witness and validates the real success body against `response`;
+- runs the same stable case IDs across a Bun/Node/Workers runtime matrix; and
+- retains a replay seed and greedily shrinks unexpected acceptance failures.
+
+```ts
+import { test } from "bun:test"
+import { assertAdversarialContract } from "@nifrajs/testing"
+import { app } from "../src/app"
+
+test("the API contract withstands hostile inputs", async () => {
+  await assertAdversarialContract(app, {
+    seed: 73,
+    prepareRequest(request) {
+      const headers = new Headers(request.headers)
+      headers.set("authorization", "Bearer test-session")
+      return new Request(request, { headers })
+    },
+  })
+})
+```
+
+Nifra's `t` schemas carry JSON Schema, so witnesses are automatic. Standard Schema deliberately does
+not require introspection; for an opaque Zod/Valibot/ArkType schema, provide only its known-good values:
+
+```ts
+await assertAdversarialContract(app, {
+  witnesses: {
+    "POST /users/:id": {
+      params: { id: "user-1" },
+      body: { name: "Ada" },
+      query: { notify: "true" },
+    },
+  },
+})
+```
+
+The validator still decides which generated mutations are truly invalid; the supplied witness does not
+weaken validation. A missing/invalid witness is a coverage gap, not a silent pass. Set
+`requireCoverage: false` only when gaps are intentionally advisory.
+
+To exercise adapter parity, pass runtime fetch targets. The reflected `app` remains the one source of
+the contract:
+
+```ts
+const report = await assertAdversarialContract(app, {
+  runtimes: [
+    { name: "bun", fetch: (request) => bunApp.fetch(request) },
+    { name: "node", fetch: (request) => nodeAdapter.fetch(request) },
+    { name: "worker", fetch: (request) => worker.fetch(request, env) },
+  ],
+})
+```
+
+`runAdversarialContract` returns the same structured report without throwing. Every failure includes
+`replay: { seed, caseId, runtime }`; rerun one case with `only: caseId`. Contract runs execute one valid
+request for each declared response schema, so use an isolated test app/database—never point the
+laboratory at production.
+
+`nifra levels` L4 uses this same deep engine through the explicitly configured isolated executor;
+the older core invariant runner remains only as a compatibility export.
+
+## Durable failure laboratory
+
+`createFailureLab` injects replayable failures at named seams in a disposable test adapter. It
+supports crash-after-commit, duplicate delivery, event reordering, virtual delay, budget expiry,
+lost provider replies, and checkpoint contention. It never sleeps and its evidence records only
+the schedule tokens - not requests, events, provider results, error messages, or stacks.
+
+```ts
+import { FailureInjectedError, runFailureScenario } from "@nifrajs/testing"
+
+let committed = false
+const report = await runFailureScenario({
+  name: "outbox-crash-after-commit",
+  execute(lab) {
+    committed = true // the real disposable transaction committed
+    lab.checkpoint("outbox.after_commit")
+  },
+  verify: ({ error }) => committed && error instanceof FailureInjectedError,
+}, {
+  seed: 73,
+  schedule: [{ kind: "crash", point: "outbox.after_commit" }],
+})
+
+expect(report.ok).toBe(true)
+// Re-run with report.replay.seed + report.replay.schedule.
+```
+
+Use `lab.deliveries()` around a relay batch, `lab.provider()` around a provider call,
+`lab.remaining()` before a deadline-bound hop, and `lab.checkpointContended()` at a projection CAS.
+The laboratory is a test port: production code does not import it and pays no hot-path cost.
+
+## Adapter certification
+
+`@nifrajs/testing/certification` turns an adapter interface into portable, hash-verifiable evidence.
+Built-in profiles cover storage (including optional paging/signing/copy-move), cache, jobs, Node/Deno-
+style runtimes, and durable event delivery. Every check receives a fresh adapter, capability status is
+explicit, and failures retain only the error class - never provider messages or credentials.
+
+```ts
+import {
+  certifyAdapter,
+  storageAdapterCertificationProfile,
+  verifyAdapterCertification,
+} from "@nifrajs/testing/certification"
+
+const report = await certifyAdapter({
+  profile: storageAdapterCertificationProfile({ paging: true, presign: true, move: true }),
+  adapterId: "s3-production-shape",
+  createAdapter: () => createDisposableS3Adapter(),
+})
+
+if (!report.ok || !(await verifyAdapterCertification(report))) throw new Error("adapter uncertified")
+```
+
+Run profiles only against disposable namespaces. The certification module is structural and
+dependency-free, so adapter packages keep it in test/CI and acquire no production runtime dependency.
+
+## Stateful sessions
+
+[`@nifrajs/client`](../client)'s **`testClient`** is already the typed, no-network in-process request
+client (Nifra's supertest / `inject`). `testSession` adds a **cookie jar**, so a login → authenticated
+request flow tests as easily as a single request.
 
 ```ts
 import { testSession } from "@nifrajs/testing"
@@ -5493,6 +5992,12 @@ that every call carries and captures cookies via a shared jar.
 
 ## API
 
+- `assertAdversarialContract(app, options?)` → green report or throws `AdversarialContractError`.
+- `runAdversarialContract(app, options?)` → structured `{ ok, results, failures, gaps, seed }` report.
+- `createFailureLab(options)` → deterministic controller for isolated durable adapters.
+- `runFailureScenario(scenario, options)` → token-only `{ ok, replay, evidence, error? }` report.
+- `certifyAdapter({ profile, adapterId, createAdapter })` → capability matrix + SHA-256 evidence.
+- `verifyAdapterCertification(report)` → recompute and verify portable certification evidence.
 - `testSession<App>(app, { origin?, cookies? })` → `{ client: Treaty<App>, cookies: CookieJar }`.
 - `cookieJar()` → `CookieJar` — `header()` · `applyTo(headers)` · `store(response)` · `set` · `get` · `clear` · `size`.
   Honours removal (`Max-Age=0` / past `Expires`); other cookie attributes are ignored (in-process, same-origin).
@@ -5841,7 +6346,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/client
 
-`ActionArgs`, `ActionData`, `ApiError`, `ApiProxy`, `client`, `ClientOptions`, `FetchFn`, `inProcessClient`, `Jsonify`, `LoaderArgs`, `LoaderData`, `RegistryOf`, `Result`, `SubscribeOptions`, `Subscription`, `testClient`, `Treaty`, `TreatyFromRegistry`
+`ActionArgs`, `ActionData`, `ApiError`, `ApiProxy`, `client`, `ClientOptions`, `FetchFn`, `inProcessClient`, `InProcessClient`, `Jsonify`, `LoaderArgs`, `LoaderData`, `RegistryOf`, `Result`, `SubscribeOptions`, `Subscription`, `testClient`, `Treaty`, `TreatyFromRegistry`
 
 ## @nifrajs/content
 
@@ -5849,7 +6354,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/core
 
-`AnyServer`, `attachWebSocket`, `commonSecretPatterns`, `Context`, `ContextForOp`, `ContractShape`, `CookieOptions`, `defineContract`, `defineIdentityPlugin`, `definePlugin`, `defineRouterPlugin`, `DurableObjectNamespaceLike`, `ExecutionContext`, `FRAMEWORK_NAME`, `FrameworkError`, `FrameworkName`, `Handler`, `HandlersFor`, `IdentityPlugin`, `implement`, `InferInput`, `InferOutput`, `jsonLogger`, `LogFields`, `Logger`, `McpPromptDescriptor`, `McpResourceDescriptor`, `Method`, `METHODS`, `Middleware`, `NifraPlugin`, `NifraWebSocket`, `NodeServeOutcome`, `OnRequestResult`, `OperationDef`, `Params`, `parseCookies`, `Platform`, `Prettify`, `PromptArgument`, `PromptMessage`, `redactLogFields`, `RedactOptions`, `Registry`, `RegistryFor`, `RegistryFromImpl`, `ResponseControls`, `ResponseDef`, `ResponseFinalization`, `robots`, `RobotsOptions`, `RobotsRule`, `RouteConfigError`, `RouteConfigErrorCode`, `RouteDescriptor`, `RouteInfo`, `Router`, `RouterMatch`, `RouteSchema`, `RunningServer`, `ScheduledController`, `ScheduledHandler`, `serializeCookie`, `server`, `Server`, `ServerOptions`, `SignatureEncoding`, `signValue`, `silentLogger`, `sitemap`, `SitemapChangeFreq`, `SitemapEntry`, `SitemapOptions`, `sse`, `SSEContext`, `SSEInit`, `SSEMessage`, `SSEStream`, `StandardIssue`, `StandardResult`, `StandardSchemaV1`, `StandardTypes`, `StandardWebSocket`, `toFetchHandler`, `ToolAnnotations`, `TopicRegistry`, `typedSSEStream`, `TypedSSEStream`, `unsignValue`, `validateStandard`, `ValidationOutcome`, `verifyWebhook`, `VerifyWebhookOptions`, `Version`, `VERSION`, `WebhookFailureReason`, `WebhookProvider`, `WebhookResult`, `WebSocketContext`, `WebSocketData`, `WebSocketHandler`, `WebSocketUpgradeOutcome`
+`AdmissionController`, `AdmissionDecision`, `AnyServer`, `attachWebSocket`, `commonSecretPatterns`, `Context`, `ContextForOp`, `ContractShape`, `CookieOptions`, `defineContract`, `defineIdentityPlugin`, `definePlugin`, `defineRouterPlugin`, `DurableObjectNamespaceLike`, `ExecutionContext`, `FRAMEWORK_NAME`, `FrameworkError`, `FrameworkName`, `Handler`, `HandlersFor`, `IdentityPlugin`, `implement`, `InferInput`, `InferOutput`, `jsonLogger`, `LogFields`, `Logger`, `McpPromptDescriptor`, `McpResourceDescriptor`, `Method`, `METHODS`, `Middleware`, `NifraPlugin`, `NifraWebSocket`, `NodeServeOutcome`, `OnRequestResult`, `OperationDef`, `Params`, `parseCookies`, `Platform`, `Prettify`, `PromptArgument`, `PromptMessage`, `redactLogFields`, `RedactOptions`, `Registry`, `RegistryFor`, `RegistryFromImpl`, `ResponseControls`, `ResponseDef`, `ResponseFinalization`, `robots`, `RobotsOptions`, `RobotsRule`, `RouteConfigError`, `RouteConfigErrorCode`, `RouteDescriptor`, `RouteInfo`, `Router`, `RouterMatch`, `RouteSchema`, `RunningServer`, `ScheduledController`, `ScheduledHandler`, `serializeCookie`, `server`, `Server`, `ServerOptions`, `SignatureEncoding`, `signValue`, `silentLogger`, `sitemap`, `SitemapChangeFreq`, `SitemapEntry`, `SitemapOptions`, `sse`, `SSEContext`, `SSEInit`, `SSEMessage`, `SSEStream`, `StandardIssue`, `StandardResult`, `StandardSchemaV1`, `StandardTypes`, `StandardWebSocket`, `toFetchHandler`, `ToolAnnotations`, `TopicRegistry`, `typedSSEStream`, `TypedSSEStream`, `unsignValue`, `validateStandard`, `ValidationOutcome`, `verifyWebhook`, `VerifyWebhookOptions`, `Version`, `VERSION`, `WebhookFailureReason`, `WebhookProvider`, `WebhookResult`, `WebSocketContext`, `WebSocketData`, `WebSocketHandler`, `WebSocketUpgradeOutcome`
 
 ## @nifrajs/cron
 
@@ -5867,6 +6372,10 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 `boolean`, `defineEnv`, `DefineEnvOptions`, `enumValue`, `env`, `EnvResult`, `EnvShape`, `InferOutput`, `number`, `port`, `StandardResult`, `StandardSchemaV1`, `string`, `url`
 
+## @nifrajs/events
+
+`createEventRegistry`, `defineEventContract`, `EventContract`, `EventContractError`, `EventEnvelope`, `EventParseResult`, `EventRegistry`, `RegistryParseResult`
+
 ## @nifrajs/i18n
 
 `createFormatter`, `Formatter`, `Locale`, `Messages`, `negotiateLocale`, `NegotiateOptions`
@@ -5893,7 +6402,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/middleware
 
-`apiKey`, `ApiKeyStaticOptions`, `ApiKeyVerifyOptions`, `appendTrailingSlash`, `AuthPlugin`, `basicAuth`, `BasicAuthPlugin`, `BasicAuthStaticOptions`, `BasicAuthVerifyOptions`, `bearer`, `BearerOptions`, `bodyLimit`, `BodyLimitOptions`, `buildOpenApiDocument`, `cache`, `cacheControl`, `CacheControlOptions`, `CachedResponse`, `CacheOptions`, `combine`, `Composable`, `compression`, `CompressionOptions`, `cors`, `CorsOptions`, `createCsrfToken`, `csrf`, `CsrfOptions`, `etag`, `ETagOptions`, `healthcheck`, `HealthcheckOptions`, `idempotency`, `IdempotencyClaim`, `IdempotencyOptions`, `IdempotencyRecord`, `IdempotencyStore`, `IpMatcher`, `ipRestriction`, `IpRestrictionOptions`, `jwk`, `JwkKey`, `jwks`, `JwksOptions`, `jwt`, `JwtAlgorithm`, `JwtClaims`, `JwtHeader`, `JwtKeyResolver`, `JwtOptions`, `JwtPlugin`, `JwtVerificationKey`, `language`, `LanguageMatch`, `LanguageOptions`, `logger`, `LoggerOptions`, `MemoryIdempotencyStore`, `MemoryIdempotencyStoreOptions`, `MemoryResponseCache`, `MemoryResponseCacheOptions`, `MemoryStore`, `MemoryStoreOptions`, `methodOverride`, `MethodOverrideOptions`, `namedCombine`, `openapi`, `OpenApiInfo`, `OpenApiOptions`, `OpenApiServer`, `OpenApiTag`, `OpenApiUiOptions`, `pickLanguage`, `poweredBy`, `PoweredByOptions`, `prettyJson`, `PrettyJsonOptions`, `rateLimit`, `RateLimitOptions`, `RateLimitResult`, `RateLimitStore`, `requestId`, `RequestIdOptions`, `RequestLogFields`, `responseCache`, `ResponseCacheStore`, `RouteLike`, `securityHeaders`, `SecurityHeadersOptions`, `SecurityRequirement`, `timing`, `TimingControls`, `TimingMetric`, `TimingOptions`, `TrailingSlashOptions`, `trimTrailingSlash`, `tryVerifyJwt`, `VerifiedJwt`, `verifyCsrfToken`, `verifyJwt`, `VerifyJwtOptions`, `VerifyJwtResult`
+`AdmissionControllerHandle`, `AdmissionEvidence`, `AdmissionOptions`, `AdmissionPolicy`, `AdmissionSnapshot`, `apiKey`, `ApiKeyStaticOptions`, `ApiKeyVerifyOptions`, `appendTrailingSlash`, `AuthPlugin`, `basicAuth`, `BasicAuthPlugin`, `BasicAuthStaticOptions`, `BasicAuthVerifyOptions`, `bearer`, `BearerOptions`, `bodyLimit`, `BodyLimitOptions`, `buildOpenApiDocument`, `cache`, `cacheControl`, `CacheControlOptions`, `CachedResponse`, `CacheOptions`, `combine`, `Composable`, `compression`, `CompressionOptions`, `cors`, `CorsOptions`, `createAdmissionController`, `createCsrfToken`, `createEventLoopLagSampler`, `csrf`, `CsrfOptions`, `etag`, `ETagOptions`, `healthcheck`, `HealthcheckOptions`, `idempotency`, `IdempotencyClaim`, `IdempotencyOptions`, `IdempotencyRecord`, `IdempotencyStore`, `IpMatcher`, `ipRestriction`, `IpRestrictionOptions`, `jwk`, `JwkKey`, `jwks`, `JwksOptions`, `jwt`, `JwtAlgorithm`, `JwtClaims`, `JwtHeader`, `JwtKeyResolver`, `JwtOptions`, `JwtPlugin`, `JwtVerificationKey`, `language`, `LanguageMatch`, `LanguageOptions`, `logger`, `LoggerOptions`, `LoopDelayHistogram`, `LoopDelayMonitor`, `MemoryIdempotencyStore`, `MemoryIdempotencyStoreOptions`, `MemoryResponseCache`, `MemoryResponseCacheOptions`, `MemoryStore`, `MemoryStoreOptions`, `methodOverride`, `MethodOverrideOptions`, `namedCombine`, `openapi`, `OpenApiInfo`, `OpenApiOptions`, `OpenApiServer`, `OpenApiTag`, `OpenApiUiOptions`, `pickLanguage`, `poweredBy`, `PoweredByOptions`, `prettyJson`, `PrettyJsonOptions`, `rateLimit`, `RateLimitOptions`, `RateLimitResult`, `RateLimitStore`, `requestId`, `RequestIdOptions`, `RequestLogFields`, `responseCache`, `ResponseCacheStore`, `RouteLike`, `securityHeaders`, `SecurityHeadersOptions`, `SecurityRequirement`, `ShedReason`, `timing`, `TimingControls`, `TimingMetric`, `TimingOptions`, `TrailingSlashOptions`, `trimTrailingSlash`, `tryVerifyJwt`, `VerifiedJwt`, `verifyCsrfToken`, `verifyJwt`, `VerifyJwtOptions`, `VerifyJwtResult`
 
 ## @nifrajs/mock
 
@@ -5905,7 +6414,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/otel
 
-`ActiveObservation`, `AttributeValue`, `combineObservationAdapters`, `consoleSpanExporter`, `createObservationLifecycle`, `EndObservation`, `formatTraceparent`, `generateSpanId`, `generateTraceId`, `NifraSpan`, `ObservationAdapter`, `ObservationClock`, `ObservationContext`, `ObservationLifecycle`, `ObservationLifecycleOptions`, `ObservationParent`, `ParsedTraceparent`, `parseTraceparent`, `SpanExporter`, `SpanStatus`, `StartObservation`, `TraceContext`, `traceHeaders`, `tracing`, `TracingOptions`
+`ActiveObservation`, `AttributeValue`, `causalitySpanLink`, `combineObservationAdapters`, `consoleSpanExporter`, `createObservationLifecycle`, `EndObservation`, `formatTraceparent`, `generateSpanId`, `generateTraceId`, `NifraSpan`, `ObservationAdapter`, `ObservationClock`, `ObservationContext`, `ObservationLifecycle`, `ObservationLifecycleOptions`, `ObservationLink`, `ObservationParent`, `ParsedTraceparent`, `parseTraceparent`, `SpanExporter`, `SpanStatus`, `StartObservation`, `TraceContext`, `traceHeaders`, `tracing`, `TracingOptions`
 
 ## @nifrajs/prompt
 
@@ -5925,7 +6434,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/testing
 
-`AppLike`, `cookieJar`, `CookieJar`, `testSession`, `TestSession`, `TestSessionOptions`
+`AdapterCertificationError`, `AdapterCertificationProfile`, `AdapterCertificationReport`, `AdversarialContractError`, `AdversarialContractOptions`, `AdversarialContractReport`, `AdversarialContractResult`, `AppLike`, `assertAdapterCertification`, `assertAdversarialContract`, `assertIncidentReplays`, `cacheStoreCertificationProfile`, `CapturedRequest`, `CapturedRequestInput`, `captureIncident`, `CaptureIncidentOptions`, `CertifiableCacheEntry`, `CertifiableCacheStore`, `CertifiableDomainEvent`, `CertifiableEventDeliveryAdapter`, `CertifiableEventRecord`, `CertifiableJobStore`, `CertifiableRuntimeAdapter`, `CertifiableRuntimeServer`, `CertifiableStorageAdapter`, `CertificationCapabilityEvidence`, `CertificationCheck`, `CertificationCheckEvidence`, `certifyAdapter`, `ContractCaseContext`, `ContractCaseKind`, `ContractCoverageGap`, `ContractCoverageGapCode`, `ContractReplay`, `ContractRuntime`, `ContractTarget`, `ContractTestApp`, `ContractWitness`, `cookieJar`, `CookieJar`, `createFailureLab`, `defineCertificationProfile`, `eventDeliveryCertificationProfile`, `FailureDirective`, `FailureEvidence`, `FailureInjectedError`, `FailureKind`, `FailureLab`, `FailureLabOptions`, `FailureReplay`, `FailureScenario`, `FailureScenarioReport`, `generateRegressionTest`, `GenerateRegressionTestOptions`, `IncidentCapsule`, `IncidentReplayError`, `IncidentReplayResult`, `jobStoreCertificationProfile`, `redactForEmission`, `replayIncident`, `ReplayIncidentOptions`, `runAdversarialContract`, `runFailureScenario`, `runtimeAdapterCertificationProfile`, `shapeOf`, `storageAdapterCertificationProfile`, `testSession`, `TestSession`, `TestSessionOptions`, `verifyAdapterCertification`
 
 ## @nifrajs/uploads
 
@@ -5933,7 +6442,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/web
 
-`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumeratePrerenderedPaths`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `GetStaticPaths`, `hashQueryKey`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderedPage`, `renderPage`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `routeStyles`, `ScriptDescriptor`, `serializeData`, `ServerOnly`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `styles`, `Submission`, `SubmitOptions`, `withISR`
+`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumeratePrerenderedPaths`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `hashQueryKey`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NavigateOptions`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderedPage`, `renderPage`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `routeStyles`, `ScriptDescriptor`, `serializeData`, `ServerOnly`, `setBrowserNavigate`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `styles`, `Submission`, `SubmitOptions`, `withISR`
 
 ## @nifrajs/web-preact