@nifrajs/core 4.0.0 → 5.0.0

package/src/assurance.ts

@@ -48,6 +48,80 @@ export { withRouteAssurance }
 /** Isolated request executor used by adversarial contract verification. */
 export type InvariantExecutor = (request: Request) => Response | Promise<Response>
 
+export type ContractTarget = "headers" | "cookies" | "params" | "body" | "query" | "response"
+export type ContractCaseKind = "input-rejection" | "response-conformance"
+export type ContractAuthContext = "authenticated" | "unauthenticated"
+
+export interface ContractExpectedResponse {
+  readonly status: number
+  readonly contentType?: "json" | "text"
+  readonly headers?: Readonly<Record<string, string>>
+  /** When present, the decoded body is compared byte-structure-wise to this value. */
+  readonly body?: unknown
+}
+
+/** A known-good request. Missing body/query values are synthesized from inspectable JSON Schema. */
+export interface ContractWitness {
+  readonly params?: Readonly<Record<string, string>>
+  readonly query?: unknown
+  readonly body?: unknown
+  readonly headers?: ConstructorParameters<typeof Headers>[0]
+  /** Explicit auth state for the prepareRequest hook; the harness never invents credentials. */
+  readonly auth?: ContractAuthContext
+  /** Expected response for a guard/error witness. Omit for the normal success witness. */
+  readonly expected?: ContractExpectedResponse
+}
+
+/** Stable context passed to request/rejection hooks. It contains no request payloads or secrets. */
+export interface ContractCaseContext {
+  readonly seed: number
+  readonly caseId: string
+  readonly route: ReflectedRoute
+  readonly runtime: string
+  readonly kind: ContractCaseKind
+  readonly target: ContractTarget
+  readonly auth?: ContractAuthContext
+  readonly mutation?: string
+}
+
+/** What `invariants.setup` provisions for one L4 run. */
+export interface InvariantSetupResult {
+  /** The isolated target for this run. Replaces `invariants.executor`. */
+  readonly executor?: InvariantExecutor
+  /** 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. */
+export type InvariantSetup = () => Promise<InvariantSetupResult | undefined | void>
+
+/** Fixture options handed to the L4 contract runner (`runAdversarialContract` in `@nifrajs/testing`). */
+export interface InvariantRunOptions {
+  /** Known-good request values keyed by `"METHOD /path"`. Required for opaque Standard Schemas. */
+  readonly witnesses?: Readonly<Record<string, ContractWitness>>
+  /** Attach a session, real row ids or signed tokens. Return a new Request. */
+  readonly prepareRequest?: (
+    request: Request,
+    context: ContractCaseContext,
+  ) => Request | Promise<Request>
+  /** Override rejection semantics, for an app with a custom validation response. */
+  readonly isRejected?: (
+    response: Response,
+    context: ContractCaseContext,
+  ) => boolean | Promise<boolean>
+  /** Run L4 on a subset of the reflected routes. */
+  readonly include?: (route: ReflectedRoute) => boolean
+  /** Maximum validator-proven mutations per body/query schema. Default 32. */
+  readonly maxMutationsPerInput?: number
+}
+
+/** L4 configuration: an isolated `executor`, a `setup` that provisions one, or both. */
+export type InvariantsConfig = InvariantRunOptions &
+  (
+    | { readonly executor: InvariantExecutor; readonly setup?: InvariantSetup }
+    | { readonly executor?: InvariantExecutor; readonly setup: InvariantSetup }
+  )
+
 /** Canonical evidence ids emitted by Nifra's official middleware modules. */
 export const NIFRA_ASSURANCE = NIFRA_ASSURANCE_IDS
 
@@ -103,8 +177,14 @@ export function assure(
 }
 
 export interface AssuranceRouteSelector {
-  /** Omit for every method. */
-  readonly methods?: readonly Method[]
+  /** Omit for every method. `"WS"` selects WebSocket routes. */
+  readonly methods?: readonly (Method | "WS")[]
+  /**
+   * Skip routes under these methods; `"WS"` skips WebSocket routes. Every other method matches, a
+   * custom one such as `PURGE` included, so `["GET", "HEAD", "OPTIONS", "WS"]` selects every route
+   * that can change state.
+   */
+  readonly exceptMethods?: readonly (Method | "WS")[]
   /** Absolute route globs. `*` matches one segment; final `**` matches zero or more. */
   readonly paths?: readonly string[]
   /** Restrict the rule to MCP tool routes (`true`) or non-tool routes (`false`). */
@@ -292,9 +372,7 @@ export interface AssuranceConfig {
     readonly signer?: (keyRef: string) => NifraManifestSigner | Promise<NifraManifestSigner>
   }
   /** Dynamic invariant execution is opt-in and must use a disposable/sandboxed target. */
-  readonly invariants?: {
-    readonly executor: InvariantExecutor
-  }
+  readonly invariants?: InvariantsConfig
   /** Optional application-supplied rule packs appended after built-in verification rules. */
   readonly rulePacks?: readonly AssuranceRulePack[]
   /** Optional sink for an assurance bundle. The CLI validates the callable shape at runtime. */
@@ -307,6 +385,23 @@ export interface AssuranceConfig {
 
 const nonEmpty = (value: string): boolean => value.trim() !== ""
 
+/** A selector's method list, upper-cased. Standard methods and `"WS"` only, so a typo throws rather
+ * than leaving a rule that never matches. */
+function selectorMethods(
+  values: readonly string[] | undefined,
+): readonly (Method | "WS")[] | undefined {
+  if (values === undefined) return undefined
+  return Object.freeze(
+    values.map((value): Method | "WS" => {
+      const method = value.toUpperCase()
+      if (method !== "WS" && !validMethod(method)) {
+        throw new Error(`route assurance: unsupported HTTP method ${JSON.stringify(method)}`)
+      }
+      return method
+    }),
+  )
+}
+
 function normalizeEvidenceIds(
   values: readonly string[] | undefined,
   label: string,
@@ -359,6 +454,7 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
       (key) =>
         ![
           "methods",
+          "exceptMethods",
           "paths",
           "tools",
           "capabilities",
@@ -397,7 +493,7 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
     }
     // An empty list matches nothing, so the rule is inert and its routes fall through to whatever
     // laxer rule comes next - the same hole as a dropped key, the other way round.
-    for (const key of ["methods", "paths"] as const) {
+    for (const key of ["methods", "exceptMethods", "paths"] as const) {
       const list = rule.match[key]
       if (list !== undefined && (!Array.isArray(list) || list.length === 0)) {
         throw new Error(
@@ -405,12 +501,8 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
         )
       }
     }
-    const methods = rule.match.methods?.map((method) => method.toUpperCase())
-    for (const method of methods ?? []) {
-      if (!validMethod(method)) {
-        throw new Error(`route assurance: unsupported HTTP method ${JSON.stringify(method)}`)
-      }
-    }
+    const methods = selectorMethods(rule.match.methods)
+    const exceptMethods = selectorMethods(rule.match.exceptMethods)
     const paths = rule.match.paths?.map((path) => {
       routeGlob(path)
       return path
@@ -480,21 +572,22 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
         `route assurance: rule ${JSON.stringify(name)} both requires and forbids ${overlap}`,
       )
     }
+    const match: { -readonly [K in keyof AssuranceRouteSelector]: AssuranceRouteSelector[K] } = {}
+    if (methods !== undefined) match.methods = methods
+    if (exceptMethods !== undefined) match.exceptMethods = exceptMethods
+    if (paths !== undefined) match.paths = Object.freeze(paths)
+    if (rule.match.tools !== undefined) match.tools = rule.match.tools
+    if (capabilities !== undefined) match.capabilities = Object.freeze([...capabilities])
+    if (access !== undefined) match.access = access
+    if (zone !== undefined) match.zone = zone
+    if (rule.match.classificationAtLeast !== undefined) {
+      match.classificationAtLeast = rule.match.classificationAtLeast
+    }
+    if (rule.match.hasBody !== undefined) match.hasBody = rule.match.hasBody
+    if (rule.match.bodyLimit !== undefined) match.bodyLimit = rule.match.bodyLimit
     return Object.freeze({
       name,
-      match: Object.freeze({
-        ...(methods !== undefined ? { methods: Object.freeze(methods as Method[]) } : {}),
-        ...(paths !== undefined ? { paths: Object.freeze(paths) } : {}),
-        ...(rule.match.tools !== undefined ? { tools: rule.match.tools } : {}),
-        ...(capabilities !== undefined ? { capabilities: Object.freeze([...capabilities]) } : {}),
-        ...(access !== undefined ? { access } : {}),
-        ...(zone !== undefined ? { zone } : {}),
-        ...(rule.match.classificationAtLeast !== undefined
-          ? { classificationAtLeast: rule.match.classificationAtLeast }
-          : {}),
-        ...(rule.match.hasBody !== undefined ? { hasBody: rule.match.hasBody } : {}),
-        ...(rule.match.bodyLimit !== undefined ? { bodyLimit: rule.match.bodyLimit } : {}),
-      }),
+      match: Object.freeze(match),
       require: required,
       forbid: forbidden,
       ...(rule.requireProvenance !== undefined
@@ -511,6 +604,63 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
   })
 }
 
+const INVARIANT_FUNCTIONS = [
+  "executor",
+  "setup",
+  "prepareRequest",
+  "isRejected",
+  "include",
+] as const
+
+function assertInvariantsConfig(invariants: InvariantsConfig): void {
+  if (invariants === null || typeof invariants !== "object") {
+    throw new TypeError("route assurance: invariants must be an object")
+  }
+  for (const name of INVARIANT_FUNCTIONS) {
+    const value: unknown = invariants[name]
+    if (value !== undefined && typeof value !== "function") {
+      throw new TypeError(
+        name === "executor"
+          ? "route assurance: invariant executor must be a function"
+          : `route assurance: invariants.${name} must be a function`,
+      )
+    }
+  }
+  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`,
+        )
+      }
+    }
+  }
+  const max = invariants.maxMutationsPerInput
+  if (max !== undefined && (!Number.isSafeInteger(max) || max < 1)) {
+    throw new RangeError(
+      "route assurance: invariants.maxMutationsPerInput must be a positive integer",
+    )
+  }
+}
+
+function frozenInvariantsConfig(invariants: InvariantsConfig): InvariantsConfig {
+  const witnesses = invariants.witnesses
+  return Object.freeze(
+    witnesses === undefined
+      ? { ...invariants }
+      : { ...invariants, witnesses: Object.freeze({ ...witnesses }) },
+  )
+}
+
 /** Identity helper for a `nifra.assurance.ts` default export. */
 export function defineAssuranceConfig(config: AssuranceConfig): AssuranceConfig {
   if (config.manifest?.path !== undefined && config.manifest.path.trim() === "") {
@@ -519,9 +669,7 @@ export function defineAssuranceConfig(config: AssuranceConfig): AssuranceConfig
   if (config.manifest?.signer !== undefined && typeof config.manifest.signer !== "function") {
     throw new Error("route assurance: manifest signer must be a function")
   }
-  if (config.invariants !== undefined && typeof config.invariants.executor !== "function") {
-    throw new Error("route assurance: invariant executor must be a function")
-  }
+  if (config.invariants !== undefined) assertInvariantsConfig(config.invariants)
   if (config.rulePacks !== undefined) {
     if (!Array.isArray(config.rulePacks))
       throw new TypeError("route assurance: rulePacks must be an array")
@@ -616,7 +764,7 @@ export function defineAssuranceConfig(config: AssuranceConfig): AssuranceConfig
         }
       : {}),
     ...(config.invariants !== undefined
-      ? { invariants: Object.freeze({ executor: config.invariants.executor }) }
+      ? { invariants: frozenInvariantsConfig(config.invariants) }
       : {}),
     ...(config.rulePacks !== undefined ? { rulePacks: Object.freeze([...config.rulePacks]) } : {}),
     ...(config.assureSink !== undefined ? { assureSink: config.assureSink } : {}),
@@ -656,8 +804,9 @@ export function matchesAssuranceSelector(
   definitions?: ReadonlyMap<string, CapabilityDefinition>,
 ): boolean {
   const { methods, paths, tools, capabilities, access, zone, classificationAtLeast } = selector
-  const { hasBody, bodyLimit } = selector
-  if (methods !== undefined && !methods.includes(route.method as Method)) return false
+  const { exceptMethods, hasBody, bodyLimit } = selector
+  if (methods !== undefined && !methods.includes(route.method as Method | "WS")) return false
+  if (exceptMethods?.some((method) => method === route.method) === true) return false
   if (paths !== undefined && !paths.some((pattern) => routeGlob(pattern).test(route.path)))
     return false
   if (tools !== undefined && (route.tool !== undefined) !== tools) return false

package/src/capabilities.ts

@@ -195,6 +195,9 @@ export interface AssuredCapabilityRoute {
   readonly covered: boolean
   /** Highest data-sensitivity the response carries, when the route declares it. */
   readonly classification?: DataClassification
+  /** `"declared"` for a route an opaque mount states it serves: listed on the mount's word, never
+   * analyzed. Absent on an analyzed route. */
+  readonly analysis?: "declared"
 }
 
 /**
@@ -225,6 +228,7 @@ export interface CapabilitySnapshotRoute {
   readonly unproven: readonly string[]
   /** Recorded so a route that starts returning `pii`/`secret` flips the lockfile and forces a review. */
   readonly classification?: DataClassification
+  readonly analysis?: "declared"
 }
 
 export interface CapabilitySnapshot {
@@ -513,6 +517,45 @@ export function evaluateCapabilityAssurance(
   for (const mount of evidenceSet.mounts ?? reflectMounts(source)) {
     if (mount.opaque !== undefined) {
       gaps.push(Object.freeze({ kind: "opaque-mount", path: mount.path, reason: mount.opaque }))
+      for (const route of mount.routes ?? []) {
+        // Only what a declaration alone can contradict: an id the policy lacks, or a write a safe
+        // method can never carry. Evidence-backed checks have nothing to read here.
+        for (const id of route.capabilities) {
+          const definition = definitions.get(id)
+          if (definition === undefined) {
+            findings.push({
+              code: "unknown-capability",
+              method: route.method,
+              path: route.path,
+              capability: id,
+              message: `${route.method} ${route.path} (declared by mount ${mount.path}) declares unknown capability ${id}`,
+            })
+          } else if (
+            SAFE_METHODS.has(route.method) &&
+            definition.zone === "domain" &&
+            definition.access === "write"
+          ) {
+            findings.push({
+              code: "safe-method-domain-write",
+              method: route.method,
+              path: route.path,
+              capability: id,
+              message: `${route.method} ${route.path} (declared by mount ${mount.path}) cannot carry domain write capability ${id}`,
+            })
+          }
+        }
+        routes.push(
+          Object.freeze({
+            method: route.method,
+            path: route.path,
+            declared: route.capabilities,
+            evidence: Object.freeze([]),
+            unproven: route.capabilities,
+            covered: false,
+            analysis: "declared",
+          }),
+        )
+      }
       continue
     }
     findings.push({
@@ -722,6 +765,21 @@ async function runCapabilityInterceptors(
   await nextPromise
 }
 
+/** Preserve the request's effect/admission scope while restricting a nested execution's privileges. */
+export function narrowCapabilityContext(context: object, allowed: readonly string[]): object {
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The private symbol stores only the capability guard installed by owner admission.
+  const guard = (context as { readonly [CAPABILITY_GUARD]?: CapabilityGuard })[CAPABILITY_GUARD]
+  const capabilities = Object.freeze([...new Set(allowed)])
+  for (const capability of capabilities) guardFor(context, capability)
+  const child: object = Object.create(context)
+  if (guard !== undefined) {
+    Object.defineProperty(child, CAPABILITY_GUARD, {
+      value: Object.freeze({ ...guard, allowed: capabilities }),
+    })
+  }
+  return child
+}
+
 function guardFor(context: object, capability: string): CapabilityGuard {
   if (!validCapabilityId(capability)) {
     throw new Error(
@@ -914,6 +972,7 @@ export function snapshotCapabilities(report: CapabilityAssuranceReport): Capabil
         evidenced: Object.freeze([...new Set(route.evidence.map((item) => item.id))].sort()),
         unproven: Object.freeze([...route.unproven].sort()),
         ...(route.classification !== undefined ? { classification: route.classification } : {}),
+        ...(route.analysis !== undefined ? { analysis: route.analysis } : {}),
       }),
     )
     .sort((a, b) => codeUnitOrder(a.path, b.path) || codeUnitOrder(a.method, b.method))

package/src/durable-effect.ts

@@ -235,7 +235,7 @@ async function scanEffectRecords(
 ): Promise<ReconciliationScanPage<DurableEffectRecord>> {
   if (store.scan !== undefined) return await store.scan(input)
   if (store.list === undefined) throw new TypeError("effect store does not support reconciliation")
-  return memoryScan(await store.list(), input)
+  return memoryScan(await store.list(), (record) => record.effectId, input)
 }
 
 export async function reconcileEffectsPage(

package/src/durable-saga.ts

@@ -118,6 +118,12 @@ export interface SagaEngineOptions {
   readonly observer?: EffectLifecycleObserver
   /** Tests/local development only. Production sagas require a durable store. */
   readonly allowMemoryStore?: boolean
+  /**
+   * How long one `resume` or `compensate` call owns a saga. A second call while the lease is live
+   * throws `SagaConcurrencyError` and changes nothing; every transition renews the lease, and a call
+   * that died is taken over once it lapses. Default 5 minutes: longer than any one step should run.
+   */
+  readonly leaseMs?: number
 }
 
 export type SagaAmbiguityResolution =
@@ -191,6 +197,8 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
   const clock = options.now ?? Date.now
   const now = (): number => readClock(clock, "saga clock")
   const observer = options.observer
+  const leaseMs = options.leaseMs ?? 300_000
+  assertPositiveMs(leaseMs, "saga leaseMs")
 
   const load = async (sagaId: string): Promise<SagaRecord> => {
     const record = await options.store.get(sagaId)
@@ -207,6 +215,12 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
       throw new TypeError(`saga ${sagaId}: store returned an invalid record`)
     }
     assertToken(record.definition, "stored saga definition", 128)
+    if (record.owner !== undefined) {
+      assertToken(record.owner, "stored saga owner", 64)
+      if (record.leaseUntil === undefined)
+        throw new TypeError(`saga ${sagaId}: store returned an owner without a lease`)
+      assertTimestamp(record.leaseUntil, "stored saga leaseUntil")
+    }
     assertTimestamp(record.createdAt, "stored saga createdAt")
     assertTimestamp(record.updatedAt, "stored saga updatedAt")
     if (record.createdAt > record.updatedAt)
@@ -252,7 +266,14 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     const next = durableSagaProtocol.transition(current, {
       sagaId: current.sagaId,
       version: current.version,
-      record: Object.freeze({ ...update, version: current.version + 1 }),
+      record: Object.freeze({
+        ...update,
+        // Every transition the owner writes renews its lease.
+        ...(update.owner === undefined
+          ? {}
+          : { leaseUntil: addDuration(now(), leaseMs, "saga leaseUntil") }),
+        version: current.version + 1,
+      }),
     })
     if (next === undefined) throw new SagaConcurrencyError(current.sagaId)
     if (
@@ -275,10 +296,51 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     ...(observer === undefined ? {} : { observers: [observer] }),
   })
 
+  /** Take the saga for `owner`, or throw `SagaConcurrencyError` while another call's lease is live. */
+  const claim = async (record: SagaRecord, owner: string): Promise<SagaRecord> => {
+    if (record.owner === owner) return record
+    if (record.owner !== undefined && record.leaseUntil !== undefined && record.leaseUntil > now())
+      throw new SagaConcurrencyError(record.sagaId)
+    return await save(record, { ...record, owner, updatedAt: now() })
+  }
+
+  /** Give the saga up so the next call need not wait out the lease. */
+  const release = async (sagaId: string, owner: string): Promise<void> => {
+    try {
+      const record = await load(sagaId)
+      if (record.owner !== owner) return
+      const { owner: _owner, leaseUntil: _leaseUntil, ...released } = record
+      await save(record, { ...released, updatedAt: now() })
+    } catch {
+      // A release that fails leaves the lease to lapse; the next call then takes the saga over.
+    }
+  }
+
+  /** The saga as `owner` holds it; once another call took it over, `owner` must stop writing. */
+  const loadOwned = async (sagaId: string, owner: string): Promise<SagaRecord> => {
+    const record = await load(sagaId)
+    if (record.owner !== owner) throw new SagaConcurrencyError(sagaId)
+    return record
+  }
+
   const compensate = async <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 compensateOwned(definition, sagaId, runOptions, owner)
+    } finally {
+      await release(sagaId, owner)
+    }
+  }
+
+  const compensateOwned = async <I, C extends Record<string, unknown>>(
+    definition: SagaDefinition<I, C>,
+    sagaId: string,
+    runOptions: { readonly signal?: AbortSignal },
+    owner: string,
   ): Promise<SagaRecord> => {
     assertSagaDefinition(definition)
     assertToken(sagaId, "saga id", 128)
@@ -287,6 +349,7 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     let record = await load(sagaId)
     if (record.definition !== definition.name) throw new TypeError("saga definition mismatch")
     if (record.state === "completed" || record.state === "compensated") return record
+    record = await claim(record, owner)
     if (
       record.steps.some(
         (step) =>
@@ -402,6 +465,20 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     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)
+    }
+  }
+
+  const resumeOwned = async <I, C extends Record<string, unknown>>(
+    definition: SagaDefinition<I, C>,
+    sagaId: string,
+    runOptions: { readonly signal?: AbortSignal },
+    owner: string,
   ): Promise<SagaRecord> => {
     assertSagaDefinition(definition)
     assertToken(sagaId, "saga id", 128)
@@ -410,6 +487,7 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     let record = await load(sagaId)
     if (record.definition !== definition.name) throw new TypeError("saga definition mismatch")
     if (record.state !== "running") return record
+    record = await claim(record, owner)
     const context: SagaRunContext<C> = {
       async step(name, compensationArgs, execute) {
         throwIfAborted(signal)
@@ -418,15 +496,15 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
           throw new TypeError("saga step execute must be a function")
         if (typeof definition.compensators[name] !== "function")
           throw new TypeError(`saga step ${name} has no compensator`)
-        record = await load(sagaId)
+        record = await loadOwned(sagaId, owner)
+        if (record.state !== "running") throw new SagaConcurrencyError(sagaId)
         const existingIndex = record.steps.findIndex((step) => step.name === name)
         if (existingIndex >= 0) {
           const existing = record.steps[existingIndex] as SagaStepRecord
           if (existing.state === "committed")
             return cloneValue(existing.result) as Awaited<ReturnType<typeof execute>>
           if (existing.state === "executing" || existing.state === "ambiguous") {
-            if (record.state !== "manual-review")
-              record = await save(record, { ...record, state: "manual-review", updatedAt: now() })
+            record = await save(record, { ...record, state: "manual-review", updatedAt: now() })
             throw new SagaAmbiguousStepError(sagaId, name, existing.effectId)
           }
           throw new Error(`saga ${sagaId}: step ${name} cannot resume from ${existing.state}`)
@@ -463,8 +541,9 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
                 })
               },
               async committed(_owned, result) {
-                record = await load(sagaId)
+                record = await loadOwned(sagaId, owner)
                 const index = record.steps.findIndex((candidate) => candidate.effectId === effectId)
+                if (index < 0) throw new SagaConcurrencyError(sagaId)
                 const committed = {
                   ...(record.steps[index] as SagaStepRecord),
                   state: "committed" as const,
@@ -473,8 +552,10 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
                 record = await save(record, withStep(record, index, committed))
               },
               async failed(_owned, failure) {
-                record = await load(sagaId)
+                record = await loadOwned(sagaId, owner)
                 const index = record.steps.findIndex((candidate) => candidate.effectId === effectId)
+                // The step was never recorded: its intent write lost a race, so it never ran.
+                if (index < 0) throw new SagaConcurrencyError(sagaId)
                 const known = failure.error instanceof SagaStepNotCommittedError || !failure.began
                 const failed = {
                   ...(record.steps[index] as SagaStepRecord),
@@ -500,14 +581,17 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     try {
       throwIfAborted(signal)
       await definition.run(context, cloneValue(record.input) as I)
-      record = await load(sagaId)
+      record = await loadOwned(sagaId, owner)
       if (record.state === "running")
         record = await save(record, { ...record, state: "completed", updatedAt: now() })
       return record
     } catch (error) {
+      // Another call holds the saga, or won a write this one lost: what ran is that call's to
+      // finish or roll back, and compensating here would undo it.
+      if (error instanceof SagaConcurrencyError) throw error
       record = await load(sagaId)
-      if (record.state === "manual-review") throw error
-      await compensate(definition, sagaId, runOptions)
+      if (record.state === "manual-review" || record.owner !== owner) throw error
+      await compensateOwned(definition, sagaId, runOptions, owner)
       throw error
     }
   }
@@ -676,7 +760,7 @@ async function scanSagaRecords(
 ): Promise<ReconciliationScanPage<SagaRecord>> {
   if (store.scan !== undefined) return await store.scan(input)
   if (store.list === undefined) throw new TypeError("saga store does not support reconciliation")
-  return memoryScan(await store.list(), input)
+  return memoryScan(await store.list(), (record) => record.sagaId, input)
 }
 
 export async function reconcileSagasPage(

package/src/edge-kit.ts

@@ -8,15 +8,20 @@
  * exposes the one lane the fused body runner already calls, so a compact server reuses it verbatim:
  *
  *   - {@link readBodyFramed}   read + cap + proto-guard + content-type framing (JSON / urlencoded / 415)
- *   - {@link toResponse}       render a {@link ResponseResult} (e.g. a 413 / 415 rejection) to a `Response`
+ *   - {@link capBodyBytes}   the same byte cap on a handler's own reads of the raw request
+ *   - {@link renderResult}     render a {@link ResponseResult} (e.g. a 413 / 415 rejection) to a `Response`
+ *   - {@link toResponse}       render any handler result, a handler's own `Response` included
  *   - {@link plainError}       the structured rejection envelope the lane returns
  *   - {@link queryObjectOf} / {@link searchOf}   query parse without a full WHATWG URL construction
  *   - {@link answerNotFound}   run a not-found handler under the same rules (404 only, no 2xx, fail closed)
+ *   - {@link emitRequestErrorLog}   log an unhandled request error under the app's `errorLogDetail`
  *
  * Everything here carries only structure - bytes, guards, and envelopes - never routing, lifecycle,
  * or app state. It is the interface, not the framework.
  */
 
+export { type ErrorLogDetail, emitRequestErrorLog } from "./server/bare-error-lane.ts"
+export { capBodyBytes } from "./server/body.ts"
 export { readBodyFramed } from "./server/body-lane.ts"
 export { plainError } from "./server/http.ts"
 export {
@@ -27,7 +32,7 @@ export {
 } from "./server/not-found-answer.ts"
 export type { ProtoPoisoning } from "./server/proto-guard.ts"
 export { type QueryValue, queryObjectOf, searchOf } from "./server/query.ts"
-export { toResponse } from "./server/respond.ts"
+export { renderResult, toResponse } from "./server/respond.ts"
 export type { ResponseResult } from "./server/runtime-core.ts"
 export { EMPTY_RESPONSE_CONTROLS } from "./server/runtime-core.ts"
 export type { CtxSet, MaybePromise, RequestSource } from "./server/server.ts"

package/src/effect-scope.ts

@@ -234,10 +234,20 @@ export function createEffectScope(
         })
         return result
       } catch (error) {
-        const errorCode = codeFor(input.errorCode, error, began)
-        const failurePhase = input.failurePhase?.(error, began) ?? (began ? "ambiguous" : "failed")
-        if (failurePhase !== "failed" && failurePhase !== "ambiguous") {
-          throw new TypeError("owned effect failurePhase returned an invalid phase")
+        // A misconfigured `errorCode` or `failurePhase` is thrown only once the effect is settled
+        // with the defaults: thrown here, it left the durable record unfinished.
+        let misconfigured: { readonly error: unknown } | undefined
+        let errorCode = began ? "execution_failed" : "admission_failed"
+        let failurePhase: "failed" | "ambiguous" = began ? "ambiguous" : "failed"
+        try {
+          errorCode = codeFor(input.errorCode, error, began)
+          const phase = input.failurePhase?.(error, began) ?? failurePhase
+          if (phase !== "failed" && phase !== "ambiguous") {
+            throw new TypeError("owned effect failurePhase returned an invalid phase")
+          }
+          failurePhase = phase
+        } catch (invalid) {
+          misconfigured = { error: invalid }
         }
         try {
           await input.transitions?.failed?.(context, { began, errorCode, error })
@@ -253,7 +263,7 @@ export function createEffectScope(
           errorCode,
           ...(input.trace === undefined ? {} : { trace: input.trace }),
         })
-        throw error
+        throw misconfigured === undefined ? error : misconfigured.error
       }
     },
     evidence: () => evidenceScope.evidence(),