@nifrajs/testing 4.0.0 → 5.0.0

package/src/agent-eval.ts

@@ -106,7 +106,10 @@ export type ComparisonCode =
   | "improved"
   | "tolerated"
   | "regressed"
+  /** The baseline has a verdict the current report no longer produces. */
   | "missing"
+  /** The current report has a verdict the baseline lacks. */
+  | "added"
   | "incomparable"
 
 /** Explicit tolerance for a score regression. `rubricId` omitted applies to every rubric. */
@@ -120,7 +123,10 @@ export interface ScoreTolerance {
 
 export interface BaselineOptions {
   readonly tolerances?: readonly ScoreTolerance[]
-  /** Comparison codes that fail the assertion. Default `["regressed"]`. */
+  /**
+   * Comparison codes that fail the assertion. Default `["regressed", "missing", "incomparable"]`:
+   * a verdict that disappeared or whose rubric changed shape cannot show it did not regress.
+   */
   readonly failOn?: readonly ComparisonCode[]
 }
 
@@ -207,13 +213,26 @@ function matrixSchedule(caseId: string): readonly FailureDirective[] {
   return [{ point: `agent.${caseId}`, kind: "crash" }]
 }
 
+export interface AgentFailureMatrixOptions {
+  readonly seed?: number
+  /**
+   * Drive the agent under test across one boundary, calling `checkpoint()` where that boundary's
+   * fault lands. The case passes only when the injected crash surfaces from `execute`. Without it
+   * each case runs a bare fixture, which proves the schedule and replay identity, not an agent.
+   */
+  readonly execute?: (
+    boundary: { readonly id: string; readonly kind: AgentFailureMatrixKind },
+    checkpoint: () => void,
+  ) => unknown
+}
+
 /**
- * Run the same token-only crash fixture at each agent boundary. The implementation intentionally
- * delegates scheduling and replay identity to the existing failure laboratory; this is a matrix
- * consumer, not a second fault engine.
+ * Inject a crash at each agent boundary. The implementation intentionally delegates scheduling and
+ * replay identity to the existing failure laboratory; this is a matrix consumer, not a second fault
+ * engine.
  */
 export async function runAgentFailureMatrix(
-  options: { readonly seed?: number } = {},
+  options: AgentFailureMatrixOptions = {},
 ): Promise<AgentFailureMatrixReport> {
   const seed = Number.isFinite(options.seed) ? Math.trunc(options.seed as number) >>> 0 : 0x4e494652
   const cases: AgentFailureMatrixCase[] = []
@@ -223,7 +242,9 @@ export async function runAgentFailureMatrix(
       {
         name: `agent-${caseId}`,
         execute(lab) {
-          lab.checkpoint(`agent.${caseId}`)
+          const checkpoint = (): void => lab.checkpoint(`agent.${caseId}`)
+          if (options.execute !== undefined) return options.execute(entry, checkpoint)
+          checkpoint()
           return true
         },
         verify: ({ error }) => error instanceof FailureInjectedError,
@@ -590,7 +611,7 @@ export async function compareAgentEvalBaseline(
       }),
     )
   }
-  const failOn = new Set(options.failOn ?? ["regressed"])
+  const failOn = new Set(options.failOn ?? ["regressed", "missing", "incomparable"])
   const regressions = comparisons
     .filter((entry) => failOn.has(entry.code))
     .map((entry) => entry.regressionId)
@@ -629,7 +650,8 @@ function classify(
   rubricId: string,
   options: BaselineOptions,
 ): ComparisonCode {
-  if (base === undefined || cur === undefined) return "missing"
+  if (base === undefined) return "added"
+  if (cur === undefined) return "missing"
   if (baseShape === undefined || curShape === undefined || baseShape.digest !== curShape.digest)
     return "incomparable"
   const baseRank = curShape.outcomes.indexOf(base.outcome)

package/src/certification.ts

@@ -252,57 +252,99 @@ export interface CertifiableCacheStore {
   delete(key: string): void | Promise<void>
   invalidateTag(tag: string): void | Promise<void>
   clear(): void | Promise<void>
+  fence?(key: string, tags: readonly string[]): unknown | Promise<unknown>
+  setIfFence?(
+    key: string,
+    entry: CertifiableCacheEntry,
+    tags: readonly string[],
+    token: unknown,
+  ): boolean | Promise<boolean>
 }
 
-export function cacheStoreCertificationProfile(): AdapterCertificationProfile<CertifiableCacheStore> {
+/**
+ * The cache-store profile. `fencing: true` adds the optional `fenced-write` capability: `setIfFence`
+ * refuses a write after an invalidation of its tag, a delete or set of its key, or a clear since its
+ * `fence`, and accepts one after an unrelated change. A store several caches share needs it, or a load
+ * running in one cache can store a value another cache just invalidated.
+ */
+export function cacheStoreCertificationProfile(
+  options: { readonly fencing?: boolean } = {},
+): AdapterCertificationProfile<CertifiableCacheStore> {
+  // Fresh on any clock until 2100: a store that honors expiry on the wall clock must still keep it.
   const entry = (value: unknown): CertifiableCacheEntry => ({
     value,
-    staleAt: 5_000_000,
-    expiresAt: 6_000_000,
+    staleAt: 4_102_444_800_000,
+    expiresAt: 4_102_448_400_000,
   })
-  return {
-    id: "cache-store",
-    version: 1,
-    capabilities: ["roundtrip", "tag-invalidation", "clear"],
-    checks: [
-      {
-        id: "set-get-delete",
-        capability: "roundtrip",
-        async run(store, context) {
-          const key = context.key("roundtrip")
-          await store.set(key, entry({ answer: 42 }), [])
-          const found = await store.get(key)
-          if (JSON.stringify(found?.value) !== '{"answer":42}') throw new Error("CacheRoundtrip")
-          await store.delete(key)
-          if ((await store.get(key)) !== undefined) throw new Error("CacheDelete")
-        },
+  const capabilities = ["roundtrip", "tag-invalidation", "clear"]
+  const checks: CertificationCheck<CertifiableCacheStore>[] = [
+    {
+      id: "set-get-delete",
+      capability: "roundtrip",
+      async run(store, context) {
+        const key = context.key("roundtrip")
+        await store.set(key, entry({ answer: 42 }), [])
+        const found = await store.get(key)
+        if (JSON.stringify(found?.value) !== '{"answer":42}') throw new Error("CacheRoundtrip")
+        await store.delete(key)
+        if ((await store.get(key)) !== undefined) throw new Error("CacheDelete")
       },
-      {
-        id: "invalidate-tag",
-        capability: "tag-invalidation",
-        async run(store, context) {
-          const tagged = context.key("tagged")
-          const other = context.key("other")
-          const tag = context.key("tag")
-          await store.set(tagged, entry(1), [tag])
-          await store.set(other, entry(2), [context.key("other-tag")])
-          await store.invalidateTag(tag)
-          if ((await store.get(tagged)) !== undefined || (await store.get(other))?.value !== 2)
-            throw new Error("CacheTagInvalidation")
-        },
+    },
+    {
+      id: "invalidate-tag",
+      capability: "tag-invalidation",
+      async run(store, context) {
+        const tagged = context.key("tagged")
+        const other = context.key("other")
+        const tag = context.key("tag")
+        await store.set(tagged, entry(1), [tag])
+        await store.set(other, entry(2), [context.key("other-tag")])
+        await store.invalidateTag(tag)
+        if ((await store.get(tagged)) !== undefined || (await store.get(other))?.value !== 2)
+          throw new Error("CacheTagInvalidation")
       },
-      {
-        id: "clear",
-        capability: "clear",
-        async run(store, context) {
-          const key = context.key("clear")
-          await store.set(key, entry(1), [])
-          await store.clear()
-          if ((await store.get(key)) !== undefined) throw new Error("CacheClear")
-        },
+    },
+    {
+      id: "clear",
+      capability: "clear",
+      async run(store, context) {
+        const key = context.key("clear")
+        await store.set(key, entry(1), [])
+        await store.clear()
+        if ((await store.get(key)) !== undefined) throw new Error("CacheClear")
       },
-    ],
+    },
+  ]
+  if (options.fencing === true) {
+    capabilities.push("fenced-write")
+    checks.push({
+      id: "fenced-write",
+      capability: "fenced-write",
+      async run(store, context) {
+        if (store.fence === undefined || store.setIfFence === undefined)
+          throw new Error("CacheFenceMissing")
+        const key = context.key("fenced")
+        const tag = context.key("fenced-tag")
+        const changes: readonly [() => void | Promise<void>, boolean][] = [
+          [() => store.set(context.key("unrelated"), entry(0), []), true],
+          [() => store.invalidateTag(tag), false],
+          [() => store.delete(key), false],
+          [() => store.set(key, entry("newer"), []), false],
+          [() => store.clear(), false],
+        ]
+        for (const [change, writes] of changes) {
+          await store.delete(key)
+          const token = await store.fence(key, [tag])
+          await change()
+          if ((await store.setIfFence(key, entry("loaded"), [tag], token)) !== writes)
+            throw new Error("CacheFencedWrite")
+          if (((await store.get(key))?.value === "loaded") !== writes)
+            throw new Error("CacheFencedWriteStored")
+        }
+      },
+    })
   }
+  return { id: "cache-store", version: 2, capabilities, checks }
 }
 
 export interface CertifiableStoredJob {
@@ -367,6 +409,19 @@ export function jobStoreCertificationProfile(
         if ((await store.counts()).pending !== 0) throw new Error("JobComplete")
       },
     },
+    {
+      // A lease hides the job from every other worker until it runs out, then hands it back.
+      id: "lease-exclusive",
+      capability: "lease-complete",
+      async run(store) {
+        const id = await store.enqueue({ name: "cert", payload: null, runAt: 0, maxAttempts: 3 })
+        const first = await store.lease(0, 1, 100)
+        if (first.length !== 1 || first[0]?.id !== id) throw new Error("JobLease")
+        if ((await store.lease(50, 1, 100)).length !== 0) throw new Error("JobLeaseShared")
+        const expired = await store.lease(101, 1, 100)
+        if (expired.length !== 1 || expired[0]?.id !== id) throw new Error("JobLeaseExpiry")
+      },
+    },
     {
       id: "retry-schedule",
       capability: "retry-schedule",
@@ -422,7 +477,7 @@ export function jobStoreCertificationProfile(
       },
     })
   }
-  return { id: "job-store", version: 1, capabilities, checks }
+  return { id: "job-store", version: 2, capabilities, checks }
 }
 
 export interface CertifiableStorageObject {
@@ -463,10 +518,24 @@ export interface CertifiableStorageAdapter {
   move?(sourceKey: string, destinationKey: string): Promise<void>
 }
 
+/** Keys the storage key contract refuses: a `..` segment anywhere, an absolute path, a backslash, a
+ * NUL, and an empty, `.` or trailing segment. Refusing only `../escape` leaves the rest open. */
+const UNSAFE_STORAGE_KEYS = [
+  "../escape",
+  "cert/../../escape",
+  "/cert/absolute",
+  "cert\\..\\escape",
+  "cert/nul\0",
+  "",
+  "cert//empty-segment",
+  "cert/./dot-segment",
+  "cert/trailing/",
+]
+
 export function storageAdapterCertificationProfile(
   options: { readonly paging?: boolean; readonly presign?: boolean; readonly move?: boolean } = {},
 ): AdapterCertificationProfile<CertifiableStorageAdapter> {
-  const capabilities = ["object-roundtrip", "overwrite", "list-delete"]
+  const capabilities = ["object-roundtrip", "overwrite", "list-delete", "key-safety"]
   const checks: CertificationCheck<CertifiableStorageAdapter>[] = [
     {
       id: "object-roundtrip",
@@ -513,6 +582,29 @@ export function storageAdapterCertificationProfile(
           throw new Error("StorageDelete")
       },
     },
+    {
+      id: "unsafe-keys",
+      capability: "key-safety",
+      async run(store) {
+        const refuses = async (call: () => Promise<unknown>): Promise<boolean> => {
+          try {
+            await call()
+            return false
+          } catch {
+            return true
+          }
+        }
+        for (const key of UNSAFE_STORAGE_KEYS) {
+          const refused = await Promise.all([
+            refuses(() => store.put(key, "x")),
+            refuses(() => store.get(key)),
+            refuses(() => store.exists(key)),
+            refuses(() => store.delete(key)),
+          ])
+          if (refused.includes(false)) throw new Error("StorageUnsafeKey")
+        }
+      },
+    },
   ]
   if (options.paging === true) {
     capabilities.push("cursor-paging")
@@ -576,7 +668,7 @@ export function storageAdapterCertificationProfile(
   }
   return {
     id: "storage-adapter",
-    version: 1,
+    version: 2,
     capabilities,
     checks,
   }

package/src/cookies.ts

@@ -1,7 +1,7 @@
 /**
  * A tiny cookie jar for in-process tests - parses `Set-Cookie` off responses and emits a `Cookie`
  * request header, so a login → authenticated-request flow works without threading headers by hand. It
- * honours removal (`Max-Age=0` / a past `Expires`) so logout clears the cookie; other attributes
+ * honours removal (`Max-Age` of zero or less, or a past `Expires`) so logout clears the cookie; other attributes
  * (Domain/Path/Secure/SameSite) are ignored - everything is same-origin in-process.
  */
 
@@ -27,7 +27,9 @@ function setCookies(headers: Headers): string[] {
 }
 
 function isRemoval(attributes: string): boolean {
-  if (/(^|;)\s*max-age=0(\s|;|$)/.test(attributes)) return true
+  // RFC 6265 5.2.2: any Max-Age of zero or less removes the cookie, and Max-Age outranks Expires.
+  const maxAge = /(?:^|;)\s*max-age=(-?\d+)\s*(?:;|$)/.exec(attributes)
+  if (maxAge !== null) return Number(maxAge[1]) <= 0
   const expires = /expires=([^;]+)/.exec(attributes)
   if (expires === null) return false
   const at = Date.parse(expires[1] as string)

package/src/data-conformance.ts

@@ -215,19 +215,29 @@ export async function runDataAdapterConformance<Adapter, Row, Snapshot, Cursor =
       }
     })
 
+    const keysIn = async (scope: DataConformanceScope): Promise<ReadonlySet<string>> =>
+      new Set((await target.read(primary, scope)).map(target.rowKey))
+    const sameKeys = (a: ReadonlySet<string>, b: ReadonlySet<string>): boolean =>
+      a.size === b.size && [...a].every((key) => b.has(key))
+
     await run("cancellation", async () => {
       const controller = new AbortController()
       controller.abort()
+      let refused = false
       try {
         await target.write(primary, scopes.left, rows.rollback, controller.signal)
       } catch (error) {
-        if (isAbortLike(error) || controller.signal.aborted) return
-        throw error
+        // Any other failure (a refused connection, a rejected row) proves nothing about the signal.
+        if (!isAbortLike(error) && error !== controller.signal.reason) throw error
+        refused = true
       }
-      throw new Error("cancelled write resolved successfully")
+      if (!refused) throw new Error("cancelled write resolved successfully")
+      if ((await keysIn(scopes.left)).has(target.rowKey(rows.rollback)))
+        throw new Error("cancelled write reached durable state")
     })
 
     await run("pagination", async () => {
+      const expected = await keysIn(scopes.left)
       const seen: string[] = []
       const cursors = new Set<string>()
       let cursor: Cursor | undefined
@@ -242,16 +252,22 @@ export async function runDataAdapterConformance<Adapter, Row, Snapshot, Cursor =
         if (pageNumber === 99) throw new Error("pagination did not terminate")
       }
       if (new Set(seen).size !== seen.length) throw new Error("pagination returned a duplicate row")
+      if (!sameKeys(new Set(seen), expected))
+        throw new Error("pagination did not return exactly the scope's rows")
     })
 
     await run("backup-restore", async () => {
+      const left = await keysIn(scopes.left)
+      const right = await keysIn(scopes.right)
       const snapshot = await target.snapshot(primary)
       await target.seed(primary, scopes.left, rows.rollback)
       await target.restore(primary, snapshot)
-      const restored = new Set((await target.read(primary, scopes.left)).map(target.rowKey))
-      if (restored.has(target.rowKey(rows.rollback))) {
-        throw new Error("restore did not remove post-backup data")
-      }
+      // Restore returns every scope to the snapshot: no later row, and no row the snapshot held lost.
+      if (
+        !sameKeys(await keysIn(scopes.left), left) ||
+        !sameKeys(await keysIn(scopes.right), right)
+      )
+        throw new Error("restore did not return the snapshot's rows")
     })
 
     await run("multi-instance", async () => {

package/src/incident.ts

@@ -18,16 +18,23 @@ export interface CapturedRequestInput {
   readonly method?: string
   readonly path: string
   readonly query?: Record<string, string>
+  readonly queryPairs?: readonly (readonly [string, string])[]
   readonly headers?: Record<string, string>
   readonly body?: unknown
+  readonly bodyEncoding?: "text"
 }
 
 export interface CapturedRequest {
   readonly method: string
   readonly path: string
+  /** The query by name; a repeated name keeps its last value. */
   readonly query?: Record<string, string>
+  /** Every query pair in order, present when `query` cannot rebuild it. Replay prefers it. */
+  readonly queryPairs?: readonly (readonly [string, string])[]
   readonly headers?: Record<string, string>
   readonly body?: unknown
+  /** `"text"`: `body` is the request text as sent, and replay sends it verbatim. Absent: JSON. */
+  readonly bodyEncoding?: "text"
 }
 
 export interface IncidentCapsule {
@@ -95,6 +102,29 @@ async function readBody(source: Request | Response): Promise<unknown> {
   return text
 }
 
+/** The request body as captured: parsed JSON when the request said so, its text otherwise. */
+async function readRequestBody(
+  request: Request,
+): Promise<{ readonly body: unknown; readonly text: boolean } | undefined> {
+  const text = await request.clone().text()
+  if (text === "") return undefined
+  if ((request.headers.get("content-type") ?? "").includes("application/json")) {
+    try {
+      return { body: JSON.parse(text), text: false }
+    } catch {}
+  }
+  return { body: text, text: true }
+}
+
+function samePairs(
+  a: readonly (readonly [string, string])[],
+  b: readonly (readonly [string, string])[],
+): boolean {
+  return (
+    a.length === b.length && a.every(([key, value], i) => b[i]?.[0] === key && b[i]?.[1] === value)
+  )
+}
+
 function pickHeaders(
   headers: Headers,
   allow: readonly string[],
@@ -118,25 +148,35 @@ export async function captureIncident(
     method: string
     path: string
     query?: Record<string, string>
+    queryPairs?: readonly (readonly [string, string])[]
     headers?: Record<string, string>
     body?: unknown
+    bodyEncoding?: "text"
   } = { method: "GET", path: "/" }
   if (request instanceof Request) {
     const url = new URL(request.url)
-    const query = Object.fromEntries(url.searchParams.entries())
+    const pairs = [...url.searchParams.entries()]
+    const query = Object.fromEntries(pairs)
     const headers = pickHeaders(request.headers, allow)
-    const body = await readBody(request)
+    const body = await readRequestBody(request)
     req.method = request.method
     req.path = url.pathname
-    if (Object.keys(query).length > 0) req.query = query
+    if (pairs.length > 0) req.query = query
+    // A repeated name, or an order an object cannot hold, is only kept by the pairs.
+    if (!samePairs(pairs, Object.entries(query))) req.queryPairs = pairs
     if (headers !== undefined) req.headers = headers
-    if (body !== undefined) req.body = body
+    if (body !== undefined) {
+      req.body = body.body
+      if (body.text) req.bodyEncoding = "text"
+    }
   } else {
     req.method = request.method ?? "GET"
     req.path = request.path
     if (request.query !== undefined) req.query = request.query
+    if (request.queryPairs !== undefined) req.queryPairs = request.queryPairs
     if (request.headers !== undefined) req.headers = request.headers
     if (request.body !== undefined) req.body = request.body
+    if (request.bodyEncoding !== undefined) req.bodyEncoding = request.bodyEncoding
   }
 
   let status: number
@@ -163,14 +203,22 @@ export async function captureIncident(
 
 function buildRequest(capsule: IncidentCapsule, origin: string): Request {
   const url = new URL(capsule.request.path, origin)
-  for (const [key, value] of Object.entries(capsule.request.query ?? {})) {
-    url.searchParams.set(key, value)
+  if (capsule.request.queryPairs !== undefined) {
+    for (const [key, value] of capsule.request.queryPairs) url.searchParams.append(key, value)
+  } else {
+    for (const [key, value] of Object.entries(capsule.request.query ?? {})) {
+      url.searchParams.set(key, value)
+    }
   }
   const headers = new Headers(capsule.request.headers)
-  const hasBody = capsule.request.body !== undefined
-  if (hasBody && !headers.has("content-type")) headers.set("content-type", "application/json")
+  const body = capsule.request.body
   const init: RequestInit = { method: capsule.request.method, headers }
-  if (hasBody) init.body = JSON.stringify(capsule.request.body)
+  if (capsule.request.bodyEncoding === "text" && typeof body === "string") {
+    init.body = body
+  } else if (body !== undefined) {
+    if (!headers.has("content-type")) headers.set("content-type", "application/json")
+    init.body = JSON.stringify(body)
+  }
   return new Request(url.toString(), init)
 }
 
@@ -233,9 +281,9 @@ export async function assertIncidentReplays(
 const REDACTED = "<redacted>"
 
 /**
- * Redact leaf string values by default (unless the dotted key path is allow-listed). Non-strings are
- * kept - they carry the structure that makes the fixture reproduce - so review the emitted file. This
- * is intentionally aggressive: a committed fixture must not leak PII/secrets.
+ * Redact leaf string values by default (unless the dotted key path is allow-listed). Non-strings and
+ * object keys are kept - they carry the structure that makes the fixture reproduce - and the emitted
+ * file says so in a review banner. A committed fixture must not leak PII/secrets.
  */
 export function redactForEmission(value: unknown, allow: ReadonlySet<string>, path = ""): unknown {
   if (typeof value === "string") return allow.has(path) ? value : REDACTED
@@ -251,6 +299,14 @@ export function redactForEmission(value: unknown, allow: ReadonlySet<string>, pa
   return value
 }
 
+/** Whether a redacted body still holds request data verbatim: a number, a boolean or an object key. */
+function keepsVerbatim(value: unknown): boolean {
+  if (typeof value === "number" || typeof value === "boolean") return true
+  if (Array.isArray(value)) return value.some(keepsVerbatim)
+  if (value !== null && typeof value === "object") return Object.keys(value).length > 0
+  return false
+}
+
 export interface GenerateRegressionTestOptions {
   /** Import specifier for the app under test. Default `"../src/app"`. */
   readonly importPath?: string
@@ -260,12 +316,33 @@ export interface GenerateRegressionTestOptions {
   readonly assertShape?: boolean
   /** Dotted key paths in the request body whose string values are safe to embed verbatim. */
   readonly allow?: readonly string[]
+  /** Query parameter names whose values are safe to embed verbatim. Default none. */
+  readonly allowQuery?: readonly string[]
+  /** Header names (any case) whose values are safe to embed verbatim. Default `["content-type"]`. */
+  readonly allowHeaders?: readonly string[]
+  /** Embed the capsule's `note` verbatim. Default false: a note is free text and is redacted. */
+  readonly keepNote?: boolean
+}
+
+function redactRecord(
+  record: Readonly<Record<string, string>> | undefined,
+  allowed: ReadonlySet<string>,
+  normalize: (name: string) => string,
+): Record<string, string> | undefined {
+  if (record === undefined) return undefined
+  const out: Record<string, string> = {}
+  for (const [name, value] of Object.entries(record)) {
+    out[name] = allowed.has(normalize(name)) ? value : REDACTED
+  }
+  return out
 }
 
 /**
- * Emit a committable regression test from a capsule. Request string values are redacted BY DEFAULT with
- * a sanitize banner - replace the `<redacted>` placeholders with safe, reproducing values before you
- * commit. The test asserts the response contract via {@link assertIncidentReplays}.
+ * Emit a committable regression test from a capsule. Body strings, query values, header values (bar
+ * `content-type`) and the note are redacted BY DEFAULT with a sanitize banner - replace the
+ * `<redacted>` placeholders with safe, reproducing values before you commit. The path is kept
+ * verbatim because it selects the route, so the file always asks for it to be reviewed. The test
+ * asserts the response contract via {@link assertIncidentReplays}.
  */
 export function generateRegressionTest(
   capsule: IncidentCapsule,
@@ -273,26 +350,50 @@ export function generateRegressionTest(
 ): string {
   const importPath = options.importPath ?? "../src/app"
   const appExport = options.appExport ?? "app"
+  if (!/^[A-Za-z_$][\w$]*$/.test(appExport))
+    throw new TypeError(
+      `generateRegressionTest: appExport must be an identifier, got ${JSON.stringify(appExport)}`,
+    )
   const allow = new Set(options.allow ?? [])
+  const allowQuery = new Set(options.allowQuery ?? [])
+  const query = redactRecord(capsule.request.query, allowQuery, (n) => n)
+  const queryPairs = capsule.request.queryPairs?.map(([name, value]): readonly [string, string] => [
+    name,
+    allowQuery.has(name) ? value : REDACTED,
+  ])
+  const headers = redactRecord(
+    capsule.request.headers,
+    new Set((options.allowHeaders ?? ["content-type"]).map((name) => name.toLowerCase())),
+    (name) => name.toLowerCase(),
+  )
   const safeRequest: CapturedRequest = {
     ...capsule.request,
+    ...(query !== undefined ? { query } : {}),
+    ...(queryPairs !== undefined ? { queryPairs } : {}),
+    ...(headers !== undefined ? { headers } : {}),
     ...(capsule.request.body !== undefined
       ? { body: redactForEmission(capsule.request.body, allow) }
       : {}),
   }
-  const emitted: IncidentCapsule = { ...capsule, request: safeRequest }
+  const emitted: IncidentCapsule = {
+    ...capsule,
+    request: safeRequest,
+    ...(capsule.note !== undefined && options.keepNote !== true ? { note: REDACTED } : {}),
+  }
   const redacted = JSON.stringify(emitted, null, 2).includes(REDACTED)
+  const verbatim = keepsVerbatim(safeRequest.body)
 
   return `// GENERATED by nifra incident → regression.
-${redacted ? '// ⚠️  SANITIZE BEFORE COMMITTING: replace every "<redacted>" with a safe, non-PII value that\n//     still reproduces the response. A committed fixture must not carry PII or secrets.\n' : ""}// Asserts the response CONTRACT (status${options.assertShape ? " + shape" : ""}) still reproduces.
+${redacted ? '// ⚠️  SANITIZE BEFORE COMMITTING: replace every "<redacted>" with a safe, non-PII value that\n//     still reproduces the response. A committed fixture must not carry PII or secrets.\n' : ""}${verbatim ? "// ⚠️  REVIEW BEFORE COMMITTING: numbers, booleans and object keys in the request body are kept\n//     verbatim, since they shape the request. Replace any that carry PII or secrets.\n" : ""}// Review the request path before committing: it is kept verbatim because it selects the route.
+// Asserts the response CONTRACT (status${options.assertShape ? " + shape" : ""}) still reproduces.
 import { describe, it } from "bun:test"
 import { assertIncidentReplays, type IncidentCapsule } from "@nifrajs/testing"
-import { ${appExport} } from "${importPath}"
+import { ${appExport} } from ${JSON.stringify(importPath)}
 
 const capsule: IncidentCapsule = ${JSON.stringify(emitted, null, 2)}
 
-describe("regression: ${capsule.request.method} ${capsule.request.path}", () => {
-  it("reproduces status ${capsule.response.status}", async () => {
+describe(${JSON.stringify(`regression: ${capsule.request.method} ${capsule.request.path}`)}, () => {
+  it(${JSON.stringify(`reproduces status ${capsule.response.status}`)}, async () => {
     await assertIncidentReplays(${appExport}, capsule, { assertShape: ${options.assertShape === true} })
   })
 })

package/src/index.ts

@@ -49,6 +49,7 @@ export {
   type AgentFailureMatrixCase,
   AgentFailureMatrixError,
   type AgentFailureMatrixKind,
+  type AgentFailureMatrixOptions,
   type AgentFailureMatrixReport,
   assertAgentEval,
   assertAgentEvalBaseline,