@nifrajs/core 5.7.0 → 5.9.0

package/src/assurance.ts

@@ -88,11 +88,22 @@ export interface ContractCaseContext {
 export interface InvariantSetupResult {
   /** The isolated target for this run. Replaces `invariants.executor`. */
   readonly executor?: InvariantExecutor
+  /**
+   * Known-good requests that name what only exists once the target is up - a real slug, a row id,
+   * a signed-in session - keyed by `"METHOD /path"`. Merged over `invariants.witnesses`: a key in
+   * both takes this one. Validated as the static ones are.
+   */
+  readonly witnesses?: Readonly<Record<string, ContractWitness>>
+  /** Replaces `invariants.prepareRequest` for this run, so it can attach what setup created. */
+  readonly prepareRequest?: InvariantRunOptions["prepareRequest"]
   /** Called once the run ends, after a failure too. */
   readonly teardown?: () => void | Promise<void>
 }
 
-/** Provisions a throwaway L4 target. Called once, before the first L4 request - never on import. */
+/**
+ * Provisions a throwaway L4 target. Called once per L4 run, before its first case is generated, so
+ * the witnesses it returns are known to every case - never on import.
+ */
 // biome-ignore lint/suspicious/noConfusingVoidType: `void` lets a setup that provisions nothing be written as `async () => {}`.
 export type InvariantSetup = () => Promise<InvariantSetupResult | undefined | void>
 
@@ -655,21 +666,7 @@ function assertInvariantsConfig(invariants: InvariantsConfig): void {
   if (invariants.executor === undefined && invariants.setup === undefined) {
     throw new TypeError("route assurance: invariants needs an executor or a setup")
   }
-  const witnesses: unknown = invariants.witnesses
-  if (witnesses !== undefined) {
-    if (witnesses === null || typeof witnesses !== "object" || Array.isArray(witnesses)) {
-      throw new TypeError(
-        'route assurance: invariants.witnesses must map "METHOD /path" to a witness',
-      )
-    }
-    for (const [key, witness] of Object.entries(witnesses)) {
-      if (witness === null || typeof witness !== "object" || Array.isArray(witness)) {
-        throw new TypeError(
-          `route assurance: invariants.witnesses[${JSON.stringify(key)}] must be an object`,
-        )
-      }
-    }
-  }
+  assertWitnesses(invariants.witnesses, "invariants.witnesses")
   const max = invariants.maxMutationsPerInput
   if (max !== undefined && (!Number.isSafeInteger(max) || max < 1)) {
     throw new RangeError(
@@ -678,6 +675,59 @@ function assertInvariantsConfig(invariants: InvariantsConfig): void {
   }
 }
 
+function assertWitnesses(witnesses: unknown, label: string): void {
+  if (witnesses === undefined) return
+  if (witnesses === null || typeof witnesses !== "object" || Array.isArray(witnesses)) {
+    throw new TypeError(`route assurance: ${label} must map "METHOD /path" to a witness`)
+  }
+  for (const [key, witness] of Object.entries(witnesses)) {
+    if (witness === null || typeof witness !== "object" || Array.isArray(witness)) {
+      throw new TypeError(`route assurance: ${label}[${JSON.stringify(key)}] must be an object`)
+    }
+  }
+}
+
+/** One L4 run's options once `invariants.setup` has provisioned its target. */
+export interface AppliedInvariantSetup {
+  /** The config with the setup's executor, witnesses and prepareRequest merged over it. */
+  readonly invariants: InvariantsConfig
+  /** The `"METHOD /path"` witness keys the setup returned, in its order. */
+  readonly setupWitnesses: readonly string[]
+}
+
+/**
+ * Merge what `invariants.setup` returned over the static `invariants`, validating it the way
+ * `defineAssuranceConfig` validates the static fields: its executor and prepareRequest replace the
+ * static ones, and its witnesses are merged over theirs, a key in both taking the setup's. For a
+ * harness that runs L4 itself; `nifra levels` calls it once setup resolves.
+ */
+export function applyInvariantSetup(
+  invariants: InvariantsConfig,
+  result: InvariantSetupResult | undefined,
+): AppliedInvariantSetup {
+  if (result === undefined) return Object.freeze({ invariants, setupWitnesses: [] })
+  if (result === null || typeof result !== "object" || Array.isArray(result)) {
+    throw new TypeError("route assurance: invariants.setup() must resolve to an object or nothing")
+  }
+  for (const name of ["executor", "prepareRequest", "teardown"] as const) {
+    const value: unknown = result[name]
+    if (value !== undefined && typeof value !== "function") {
+      throw new TypeError(`route assurance: invariants.setup().${name} must be a function`)
+    }
+  }
+  assertWitnesses(result.witnesses, "invariants.setup().witnesses")
+  const setupWitnesses = Object.freeze(Object.keys(result.witnesses ?? {}))
+  const merged: InvariantsConfig = {
+    ...invariants,
+    ...(result.executor === undefined ? {} : { executor: result.executor }),
+    ...(result.prepareRequest === undefined ? {} : { prepareRequest: result.prepareRequest }),
+    ...(result.witnesses === undefined
+      ? {}
+      : { witnesses: Object.freeze({ ...invariants.witnesses, ...result.witnesses }) }),
+  }
+  return Object.freeze({ invariants: Object.freeze(merged), setupWitnesses })
+}
+
 function frozenInvariantsConfig(invariants: InvariantsConfig): InvariantsConfig {
   const witnesses = invariants.witnesses
   return Object.freeze(

package/src/canonical-json.ts

@@ -0,0 +1,43 @@
+/**
+ * Canonical JSON: object keys sorted by UTF-16 code unit, no whitespace, `undefined` members left out.
+ *
+ * Content hashes, manifest signatures, idempotency fingerprints and stored digests are all taken over
+ * these bytes, so the output for JSON data never changes. A value JSON cannot carry throws instead of
+ * hashing as something else: a non-finite number, an `undefined` or missing array item, a `Date`,
+ * `Map` or class instance, a function, a symbol, a bigint. A `JSON.rawJSON` value is written verbatim.
+ */
+
+import { isPlainPrototype, isRawJson } from "./server/json-shared.ts"
+
+/** The canonical JSON text of `value`. Throws a `TypeError` on a value JSON cannot carry. */
+export function canonicalJson(value: unknown): string {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return JSON.stringify(value)
+  }
+  if (typeof value === "number") {
+    if (Number.isFinite(value)) return JSON.stringify(value)
+  } else if (Array.isArray(value)) {
+    // Each level is joined into a flat string: a `+=` rope builds faster, but on Bun it costs more
+    // once a caller reads it. An undefined or missing item recurses into the refusal below.
+    const items = new Array<string>(value.length)
+    for (let i = 0; i < value.length; i++) items[i] = canonicalJson(value[i])
+    return `[${items.join(",")}]`
+  } else if (typeof value === "object") {
+    const proto: unknown = Object.getPrototypeOf(value)
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: isRawJSON vouched for it, and a raw JSON value keeps its text in `rawJSON`.
+    if (proto === null && isRawJson?.(value) === true) return (value as { rawJSON: string }).rawJSON
+    if (isPlainPrototype(proto)) {
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a non-array object with a plain or null prototype; only its own string keys are read.
+      const record = value as Readonly<Record<string, unknown>>
+      const members: string[] = []
+      for (const key of Object.keys(record).sort()) {
+        const field = record[key]
+        if (field !== undefined) members.push(`${JSON.stringify(key)}:${canonicalJson(field)}`)
+      }
+      return `{${members.join(",")}}`
+    }
+  }
+  throw new TypeError(
+    `canonical JSON cannot encode ${typeof value === "object" ? "a non-plain object" : typeof value === "number" ? value : typeof value}`,
+  )
+}

package/src/capabilities.ts

@@ -22,6 +22,7 @@ import {
   validCapabilityId,
 } from "./internal/capability-runtime.ts"
 import { codeUnitOrder } from "./internal/code-unit-order.ts"
+import { hasControlCharacter } from "./internal/control-character.ts"
 import { effectScopeForContext } from "./internal/effect-execution.ts"
 import { NIFRA_ASSURANCE_IDS } from "./internal/route-assurance.ts"
 import {
@@ -264,14 +265,6 @@ function validSpecifier(value: string): boolean {
   return value.trim() === value && value !== "" && !hasControlCharacter(value)
 }
 
-function hasControlCharacter(value: string): boolean {
-  for (let index = 0; index < value.length; index++) {
-    const code = value.charCodeAt(index)
-    if (code <= 31 || code === 127) return true
-  }
-  return false
-}
-
 /** Validate and freeze a capability/provenance policy. */
 export function defineCapabilityPolicy(policy: CapabilityPolicy): CapabilityPolicy {
   if (policy.provenance === undefined || policy.provenance === null) {

package/src/data.ts

@@ -1,6 +1,8 @@
 /** Public, token-only data access contracts. Durable adapters and RLS policy enforcement stay outside
  * this package; this subpath defines the typed seam they implement. */
 
+import { hasControlCharacter } from "./internal/control-character.ts"
+
 export const DATA_CAPABILITIES = Object.freeze({
   read: "db.read",
   write: "db.write",
@@ -179,14 +181,6 @@ function assertToken(value: string, label: string): string {
   return value
 }
 
-function hasControlCharacter(value: string): boolean {
-  for (let index = 0; index < value.length; index++) {
-    const code = value.charCodeAt(index)
-    if (code <= 31 || code === 127) return true
-  }
-  return false
-}
-
 /** Create a bounded, opaque RLS/equivalent policy scope for a data adapter. */
 export function rlsScope(token: string, digest?: string): RlsScope {
   const scope = {

package/src/diff.ts

@@ -19,6 +19,7 @@
  */
 
 import { type ProjectEvidenceSnapshot, reflectedRoutesFromEvidence } from "./evidence.ts"
+import { mapSchemaParts } from "./internal/schema-parts.ts"
 import {
   type JsonSchema,
   type ReflectedRoute,
@@ -120,20 +121,9 @@ const snapshotRoute = (route: ReflectedRoute): RouteSnapshot => {
     const snapped = schemaSnapshot(reflection)
     if (snapped !== undefined) errors[status] = snapped
   }
-  const body = schemaSnapshot(schema.body)
-  const headers = schemaSnapshot(schema.headers)
-  const cookies = schemaSnapshot(schema.cookies)
-  const query = schemaSnapshot(schema.query)
-  const params = schemaSnapshot(schema.params)
-  const response = schemaSnapshot(schema.response)
   const sse = schemaSnapshot(schema.sse)
   const snapped: RouteSnapshotSchema = {
-    ...(headers !== undefined ? { headers } : {}),
-    ...(cookies !== undefined ? { cookies } : {}),
-    ...(body !== undefined ? { body } : {}),
-    ...(query !== undefined ? { query } : {}),
-    ...(params !== undefined ? { params } : {}),
-    ...(response !== undefined ? { response } : {}),
+    ...mapSchemaParts(schema, schemaSnapshot),
     ...(sse !== undefined ? { sse } : {}),
     ...(Object.keys(errors).length > 0 ? { errors } : {}),
   }

package/src/durable-adapters.ts

@@ -472,6 +472,29 @@ function recordFromRow<T>(row: Record<string, unknown> | undefined): T | undefin
   return clone(parseWire(text) as T)
 }
 
+/** A scan page from up to `limit + 1` rows: the first `limit` as records, with a cursor at the last of
+ * them when a row is left over. */
+function scanPage<T>(
+  rows: readonly Record<string, unknown>[],
+  limit: number,
+): ReconciliationScanPage<T> {
+  const page = rows.slice(0, limit)
+  return Object.freeze({
+    records: Object.freeze(page.map((row) => recordFromRow<T>(row) as T)),
+    ...(rows.length > limit ? { cursor: String(page.at(-1)?.id) } : {}),
+  })
+}
+
+function leaseFromRow(row: Record<string, unknown>): ReconciliationLease {
+  return Object.freeze({
+    name: String(row.name),
+    owner: String(row.owner),
+    token: String(row.token),
+    expiresAt: Number(row.expires_at),
+    ...(row.cursor === null || row.cursor === undefined ? {} : { cursor: String(row.cursor) }),
+  })
+}
+
 function serializeRecord(record: unknown): string {
   return stringifyWire(record)
 }
@@ -564,12 +587,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
       sqlIdentifiers`SELECT id,payload FROM ${this.recordsTable} WHERE kind=$1 AND state = ANY($2::text[]) AND ($3::bigint IS NULL OR updated_at <= $3) AND ($4::text IS NULL OR id > $4) ORDER BY id LIMIT $5`,
       [kind, input.states, input.updatedBefore ?? null, input.cursor ?? null, input.limit + 1],
     )
-    const hasMore = result.rows.length > input.limit
-    const rows = result.rows.slice(0, input.limit)
-    return Object.freeze({
-      records: Object.freeze(rows.map((row) => recordFromRow<T>(row) as T)),
-      ...(hasMore ? { cursor: String(rows.at(-1)?.id) } : {}),
-    })
+    return scanPage<T>(result.rows, input.limit)
   }
   async acquireLease(
     input: Parameters<DurableRecordBackend["acquireLease"]>[0],
@@ -583,13 +601,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
     )
     const row = result.rows[0]
     if (row === undefined) return undefined
-    return Object.freeze({
-      name: String(row.name),
-      owner: String(row.owner),
-      token: String(row.token),
-      expiresAt: Number(row.expires_at),
-      ...(row.cursor === null || row.cursor === undefined ? {} : { cursor: String(row.cursor) }),
-    })
+    return leaseFromRow(row)
   }
   async renewLease(input: Parameters<DurableRecordBackend["renewLease"]>[0]): Promise<boolean> {
     // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
@@ -744,13 +756,10 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
         input.cursor ?? null,
         input.limit + 1,
       )
-    const present = rows.filter((row): row is Record<string, unknown> => row !== undefined)
-    const hasMore = present.length > input.limit
-    const page = present.slice(0, input.limit)
-    return Object.freeze({
-      records: Object.freeze(page.map((row) => recordFromRow<T>(row) as T)),
-      ...(hasMore ? { cursor: String(page.at(-1)?.id) } : {}),
-    })
+    return scanPage<T>(
+      rows.filter((row): row is Record<string, unknown> => row !== undefined),
+      input.limit,
+    )
   }
   async acquireLease(
     input: Parameters<DurableRecordBackend["acquireLease"]>[0],
@@ -764,13 +773,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
       )
       .get(input.name, input.owner, token, expiresAt, input.now)
     if (row === undefined || row === null) return undefined
-    return Object.freeze({
-      name: String(row.name),
-      owner: String(row.owner),
-      token: String(row.token),
-      expiresAt: Number(row.expires_at),
-      ...(row.cursor === null || row.cursor === undefined ? {} : { cursor: String(row.cursor) }),
-    })
+    return leaseFromRow(row)
   }
   async renewLease(input: Parameters<DurableRecordBackend["renewLease"]>[0]): Promise<boolean> {
     return (
@@ -963,42 +966,42 @@ export class DurableObjectRecordBackend implements DurableRecordBackend {
     })
   }
   async renewLease(input: Parameters<DurableRecordBackend["renewLease"]>[0]): Promise<boolean> {
-    return await this.storage.transaction(async (txn) => {
-      const key = this.leaseKey(input.name)
-      const current = await txn.get<DurableObjectLeaseValue>(key)
-      if (
-        current?.owner !== input.owner ||
-        !safeEqual(current.token, input.token) ||
-        current.expiresAt <= input.now
-      )
-        return false
-      await txn.put(key, { ...current, expiresAt: input.now + input.leaseMs })
-      return true
-    })
+    return await this.updateHeldLease(input, (current) =>
+      current.expiresAt <= input.now
+        ? undefined
+        : { ...current, expiresAt: input.now + input.leaseMs },
+    )
   }
   async checkpointLease(
     input: Parameters<DurableRecordBackend["checkpointLease"]>[0],
   ): Promise<boolean> {
-    return await this.storage.transaction(async (txn) => {
-      const key = this.leaseKey(input.name)
-      const current = await txn.get<DurableObjectLeaseValue>(key)
-      if (current?.owner !== input.owner || !safeEqual(current.token, input.token)) return false
+    return await this.updateHeldLease(input, (current) => {
       const next = { ...current }
       if (input.cursor === undefined) delete next.cursor
       else next.cursor = input.cursor
-      await txn.put(key, next)
-      return true
+      return next
     })
   }
   async releaseLease(input: Parameters<DurableRecordBackend["releaseLease"]>[0]): Promise<boolean> {
-    return await this.storage.transaction(async (txn) => {
-      const key = this.leaseKey(input.name)
-      const current = await txn.get<DurableObjectLeaseValue>(key)
-      if (current?.owner !== input.owner || !safeEqual(current.token, input.token)) return false
+    return await this.updateHeldLease(input, (current) => {
       const next = { ...current, expiresAt: 0 }
       delete next.owner
       delete next.token
-      await txn.put(key, next)
+      return next
+    })
+  }
+  /** Write `next(current)` over the lease while `input`'s owner and token still hold it. */
+  private updateHeldLease(
+    input: { readonly name: string; readonly owner: string; readonly token: string },
+    next: (current: DurableObjectLeaseValue) => DurableObjectLeaseValue | undefined,
+  ): Promise<boolean> {
+    return this.storage.transaction(async (txn) => {
+      const key = this.leaseKey(input.name)
+      const current = await txn.get<DurableObjectLeaseValue>(key)
+      if (current?.owner !== input.owner || !safeEqual(current.token, input.token)) return false
+      const value = next(current)
+      if (value === undefined) return false
+      await txn.put(key, value)
       return true
     })
   }

package/src/durable-saga.ts

@@ -323,31 +323,48 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     return record
   }
 
-  const compensate = async <I, C extends Record<string, unknown>>(
-    definition: SagaDefinition<I, C>,
+  /** Run `owned` under a fresh owner id, then give the saga up however it ended. */
+  const withFreshOwner = async (
     sagaId: string,
-    runOptions: { readonly signal?: AbortSignal } = {},
+    owned: (owner: string) => Promise<SagaRecord>,
   ): Promise<SagaRecord> => {
     const owner = crypto.randomUUID()
     try {
-      return await compensateOwned(definition, sagaId, runOptions, owner)
+      return await owned(owner)
     } finally {
       await release(sagaId, owner)
     }
   }
 
-  const compensateOwned = async <I, C extends Record<string, unknown>>(
+  /** The stored saga, once `definition` and `sagaId` are well formed and `signal` has not fired. */
+  const loadFor = async <I, C extends Record<string, unknown>>(
     definition: SagaDefinition<I, C>,
     sagaId: string,
-    runOptions: { readonly signal?: AbortSignal },
-    owner: string,
+    signal: AbortSignal,
   ): Promise<SagaRecord> => {
     assertSagaDefinition(definition)
     assertToken(sagaId, "saga id", 128)
-    const signal = signalOrNever(runOptions.signal)
     throwIfAborted(signal)
-    let record = await load(sagaId)
+    const record = await load(sagaId)
     if (record.definition !== definition.name) throw new TypeError("saga definition mismatch")
+    return record
+  }
+
+  const compensate = <I, C extends Record<string, unknown>>(
+    definition: SagaDefinition<I, C>,
+    sagaId: string,
+    runOptions: { readonly signal?: AbortSignal } = {},
+  ): Promise<SagaRecord> =>
+    withFreshOwner(sagaId, (owner) => compensateOwned(definition, sagaId, runOptions, owner))
+
+  const compensateOwned = async <I, C extends Record<string, unknown>>(
+    definition: SagaDefinition<I, C>,
+    sagaId: string,
+    runOptions: { readonly signal?: AbortSignal },
+    owner: string,
+  ): Promise<SagaRecord> => {
+    const signal = signalOrNever(runOptions.signal)
+    let record = await loadFor(definition, sagaId, signal)
     if (record.state === "completed" || record.state === "compensated") return record
     record = await claim(record, owner)
     if (
@@ -461,18 +478,12 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     return await save(record, { ...record, state: "compensated", updatedAt: now() })
   }
 
-  const resume = async <I, C extends Record<string, unknown>>(
+  const resume = <I, C extends Record<string, unknown>>(
     definition: SagaDefinition<I, C>,
     sagaId: string,
     runOptions: { readonly signal?: AbortSignal } = {},
-  ): Promise<SagaRecord> => {
-    const owner = crypto.randomUUID()
-    try {
-      return await resumeOwned(definition, sagaId, runOptions, owner)
-    } finally {
-      await release(sagaId, owner)
-    }
-  }
+  ): Promise<SagaRecord> =>
+    withFreshOwner(sagaId, (owner) => resumeOwned(definition, sagaId, runOptions, owner))
 
   const resumeOwned = async <I, C extends Record<string, unknown>>(
     definition: SagaDefinition<I, C>,
@@ -480,12 +491,8 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     runOptions: { readonly signal?: AbortSignal },
     owner: string,
   ): Promise<SagaRecord> => {
-    assertSagaDefinition(definition)
-    assertToken(sagaId, "saga id", 128)
     const signal = signalOrNever(runOptions.signal)
-    throwIfAborted(signal)
-    let record = await load(sagaId)
-    if (record.definition !== definition.name) throw new TypeError("saga definition mismatch")
+    let record = await loadFor(definition, sagaId, signal)
     if (record.state !== "running") return record
     record = await claim(record, owner)
     const context: SagaRunContext<C> = {