@nifrajs/core 1.9.1 → 1.10.0

package/src/index.ts

@@ -12,13 +12,16 @@
  * (it shipped at "0.0.0" through 1.0.0 before those guards existed). Kept narrow (`as const`) so
  * consumers can pin it at the type level — see `test/version.test-d.ts`.
  */
-export const VERSION = "1.9.1" as const
+export const VERSION = "1.10.0" as const
 
 export type Version = typeof VERSION
 
 export * from "./assurance.ts"
+export * from "./capabilities.ts"
+export * from "./classification.ts"
 export * from "./diff.ts"
 export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.ts"
+export * from "./idempotency.ts"
 export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.ts"
 export * from "./reflection.ts"
 export { METHODS, type Method, Router, type RouterMatch } from "./router/router.ts"

package/src/internal/capability-runtime.ts

@@ -0,0 +1,49 @@
+export const CAPABILITY_GUARD = Symbol("nifra.capability.guard")
+const CAPABILITY_ID = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/
+
+export function validCapabilityId(value: string): boolean {
+  return CAPABILITY_ID.test(value)
+}
+
+export interface CapabilityUseEvent {
+  readonly capability: string
+  readonly method: string
+  readonly path: string
+}
+
+export interface CapabilityGuard {
+  readonly allowed: readonly string[]
+  readonly method: string
+  readonly path: string
+  readonly onUse?: (event: CapabilityUseEvent) => void
+}
+
+export function normalizeRouteCapabilities(
+  values: readonly string[] | undefined,
+): readonly string[] {
+  if (values === undefined) return Object.freeze([])
+  if (!Array.isArray(values)) throw new TypeError("route capabilities must be an array")
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const value of values) {
+    if (typeof value !== "string" || !validCapabilityId(value)) {
+      throw new Error(
+        `route capabilities: invalid capability id ${JSON.stringify(value)} (use lowercase dot/dash segments)`,
+      )
+    }
+    if (!seen.has(value)) {
+      seen.add(value)
+      out.push(value)
+    }
+  }
+  return Object.freeze(out)
+}
+
+export function createCapabilityGuard(
+  allowed: readonly string[],
+  method: string,
+  path: string,
+  onUse: ((event: CapabilityUseEvent) => void) | undefined,
+): CapabilityGuard {
+  return Object.freeze({ allowed, method, path, ...(onUse !== undefined ? { onUse } : {}) })
+}

package/src/internal/route-assurance.ts

@@ -26,6 +26,7 @@ export const NIFRA_ASSURANCE_IDS = Object.freeze({
   AUTHENTICATED: "nifra.authenticated",
   BODY_BOUNDED: "nifra.body-bounded",
   CSRF: "nifra.csrf",
+  DURABLE_COMMAND: "nifra.durable-command",
   IDEMPOTENCY_KEY: "nifra.idempotency-key",
   IP_RESTRICTED: "nifra.ip-restricted",
   RATE_LIMITED: "nifra.rate-limited",

package/src/reflection.ts

@@ -7,6 +7,8 @@
  * recognizes Nifra/TypeBox carriers and raw JSON Schema without depending on a validator package.
  */
 
+import { type DataClassification, isDataClassification } from "./classification.ts"
+import { normalizeRouteCapabilities } from "./internal/capability-runtime.ts"
 import { type AssuranceEvidence, validEvidence } from "./internal/route-assurance.ts"
 import type { StandardSchemaV1 } from "./schema/standard.ts"
 import type { ToolAnnotations } from "./server/server.ts"
@@ -45,6 +47,9 @@ export interface ReflectedRoute {
   readonly path: string
   readonly schema?: ReflectedRouteSchema
   readonly assurance?: readonly AssuranceEvidence[]
+  readonly capabilities?: readonly string[]
+  /** Highest data-sensitivity the response carries, when declared. */
+  readonly classification?: DataClassification
   readonly tool?: {
     readonly name: string
     readonly description: string
@@ -196,11 +201,20 @@ export function reflectRoutes(source: unknown): readonly ReflectedRoute[] {
     const schema = reflectedRouteSchema(route.schema)
     const tool = reflectedTool(route.tool)
     const assurance = reflectedAssurance(route.assurance)
+    const capabilities = normalizeRouteCapabilities(
+      Array.isArray(route.capabilities) ? (route.capabilities as readonly string[]) : undefined,
+    )
+    const rawClassification = recordOf(route.schema)?.classification
+    const classification: DataClassification | undefined = isDataClassification(rawClassification)
+      ? rawClassification
+      : undefined
     reflected.push({
       method: route.method.toUpperCase(),
       path: route.path,
       ...(schema !== undefined ? { schema } : {}),
       ...(assurance !== undefined ? { assurance } : {}),
+      ...(capabilities.length > 0 ? { capabilities } : {}),
+      ...(classification !== undefined ? { classification } : {}),
       ...(tool !== undefined ? { tool } : {}),
     })
   }

package/src/server/context.ts

@@ -1,7 +1,25 @@
-import type { RequestBudget } from "@nifrajs/budget"
+import type { RequestBudget } from "../budget.ts"
+import type { DataClassification } from "../classification.ts"
+import type { IdempotencyScope, IdempotencyStore } from "../idempotency.ts"
 import type { InferOutput, StandardIssue, StandardSchemaV1 } from "../schema/standard.ts"
 import type { CookieOptions } from "./cookies.ts"
 
+/**
+ * Declares a mutating route as idempotent: the server dedupes retries on an `Idempotency-Key` header
+ * (see {@link RouteSchema.idempotency}). Satisfies the capability-assurance idempotency requirement
+ * for a `write` capability — `scope: "durable"` additionally clears the durable-command requirement.
+ */
+export interface IdempotencyConfig {
+  /** `request` = in-process dedupe; `durable` = cross-restart, backed by a durable store. */
+  readonly scope: IdempotencyScope
+  /** Retention for the stored response. Default 24h. */
+  readonly ttlMs?: number
+  /** Store override. Defaults to the server's shared in-memory store; inject a durable store here. */
+  readonly store?: IdempotencyStore
+  /** Header carrying the key. Default `idempotency-key`. */
+  readonly headerName?: string
+}
+
 /** Flattens an intersection into a single object type for readable hovers. */
 export type Prettify<T> = { [K in keyof T]: T[K] } & {}
 
@@ -25,6 +43,22 @@ export type Params<Path extends string> = Prettify<RawParams<Path>>
 
 /** Per-route input schemas. Each is any Standard Schema (zod/valibot/arktype/…). */
 export interface RouteSchema {
+  /** Declared effect tokens. Reflected for assurance; never read by validation or serialization. */
+  readonly capabilities?: readonly string[]
+  /**
+   * Dedupe retries of this (mutating) route on an `Idempotency-Key` header. The first request runs and
+   * its response is stored; a retry with the same key replays that response without re-running the
+   * handler, and a key reused with a different body is rejected (409). A missing key on an
+   * idempotency-required route fails closed (400). Off the hot path — routes without it are unchanged.
+   */
+  readonly idempotency?: IdempotencyConfig
+  /**
+   * Highest data-sensitivity this route's response body carries (`public` | `pii` | `secret`). A
+   * declarative, compile-time + introspection fact — never validated at runtime. Reflected for tooling,
+   * recorded in the capability lockfile (so a route that starts returning PII is a reviewable change),
+   * and read by downstream policy (e.g. a partner-API surface refusing to expose `pii`/`secret`).
+   */
+  readonly classification?: DataClassification
   readonly body?: StandardSchemaV1
   readonly query?: StandardSchemaV1
   /** Optional **response contract**. When declared: the handler's return is type-checked against it

package/src/server/contract.ts

@@ -1,7 +1,9 @@
+import type { DataClassification } from "../classification.ts"
 import { RouteConfigError } from "../errors.ts"
+import { normalizeRouteCapabilities } from "../internal/capability-runtime.ts"
 import { METHODS, type Method } from "../router/router.ts"
 import type { InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
-import type { Context, Params, RouteSchema } from "./context.ts"
+import type { Context, IdempotencyConfig, Params, RouteSchema } from "./context.ts"
 import type { OutputOf } from "./registry.ts"
 import { Server } from "./server.ts"
 
@@ -27,6 +29,12 @@ export interface OperationDef {
   readonly body?: StandardSchemaV1
   readonly query?: StandardSchemaV1
   readonly response?: StandardSchemaV1
+  /** Declared effect tokens, carried into route reflection and capability assurance. */
+  readonly capabilities?: readonly string[]
+  /** Dedupe retries of this operation on an `Idempotency-Key` header (see {@link RouteSchema.idempotency}). */
+  readonly idempotency?: IdempotencyConfig
+  /** Highest data-sensitivity the response carries (see {@link RouteSchema.classification}). */
+  readonly classification?: DataClassification
   /** Short summary (OpenAPI `summary`). */
   readonly summary?: string
   /** Longer description (OpenAPI `description`, CommonMark). */
@@ -167,6 +175,7 @@ export function defineContract<const C extends ContractShape>(contract: C): C {
     if (seen.has(key)) {
       throw new RouteConfigError("DUPLICATE_ROUTE", `duplicate operation route: ${key}`)
     }
+    normalizeRouteCapabilities(op.capabilities)
     seen.add(key)
   }
   return contract
@@ -219,11 +228,19 @@ export function implement<const C extends ContractShape, H extends HandlersFor<C
     // once here at bind time, not per request — it just carries a reference to the op's existing schema.
     // A response-less op still yields `undefined`, byte-identical to before.
     const schema: RouteSchema | undefined =
-      op.body !== undefined || op.query !== undefined || op.response !== undefined
+      op.body !== undefined ||
+      op.query !== undefined ||
+      op.response !== undefined ||
+      op.capabilities !== undefined ||
+      op.idempotency !== undefined ||
+      op.classification !== undefined
         ? {
             ...(op.body !== undefined ? { body: op.body } : {}),
             ...(op.query !== undefined ? { query: op.query } : {}),
             ...(op.response !== undefined ? { response: op.response } : {}),
+            ...(op.capabilities !== undefined ? { capabilities: op.capabilities } : {}),
+            ...(op.idempotency !== undefined ? { idempotency: op.idempotency } : {}),
+            ...(op.classification !== undefined ? { classification: op.classification } : {}),
           }
         : undefined
     app.register(

package/src/server/server.ts

@@ -5,8 +5,24 @@ import {
   type DeadlineAdmissionOptions,
   NIFRA_DEADLINE_HEADER,
   type RequestBudget,
-} from "@nifrajs/budget"
+} from "../budget.ts"
 import { FrameworkError, RouteConfigError } from "../errors.ts"
+import {
+  computeIdempotencyFingerprint,
+  DEFAULT_IDEMPOTENCY_HEADER,
+  DEFAULT_IDEMPOTENCY_TTL_MS,
+  type IdempotencyStore,
+  MemoryIdempotencyStore,
+  responseFromStored,
+  serializeResponse,
+  validIdempotencyKey,
+} from "../idempotency.ts"
+import {
+  CAPABILITY_GUARD,
+  type CapabilityUseEvent,
+  createCapabilityGuard,
+  normalizeRouteCapabilities,
+} from "../internal/capability-runtime.ts"
 import {
   type AssuranceDeclaration,
   type AssuranceEvidence,
@@ -152,13 +168,22 @@ type RawOnRequest = (req: Request) => MaybePromise<OnRequestResult>
 type RawOnResponse = (response: Response, req: Request) => MaybePromise<Response>
 type RawOnResponseFinalized = (outcome: ResponseFinalization, req: Request) => MaybePromise<void>
 
+/** Registration-resolved idempotency for a route: the config with its store + defaults pinned. */
+interface ResolvedIdempotency {
+  readonly store: IdempotencyStore
+  readonly ttlMs: number
+  readonly headerName: string
+}
+
 interface RouteEntry {
   readonly handler: InternalHandler
   readonly schema: RouteSchema | undefined
+  /** Resolved idempotency config; `undefined` = off (the dedupe lane is never entered). */
+  readonly idempotent: ResolvedIdempotency | undefined
   /** Per-request context extensions captured at registration (order-scoped). */
   readonly derives: ReadonlyArray<RawDerive>
   /** Static context extensions captured at registration. */
-  readonly decorations: Record<string, unknown>
+  readonly decorations: Record<PropertyKey, unknown>
   /** Whether {@link decorations} has any keys — precomputed so the hot path skips a no-op
    * `Object.assign` on the (common) no-decoration route. */
   readonly hasDecorations: boolean
@@ -313,6 +338,17 @@ export interface ServerOptions {
    * shared matched lane where the gate runs); when unset, the request path pays nothing.
    */
   readonly admission?: AdmissionController
+  /**
+   * Optional token-only observation hook called by `useCapability(c, id)`. It receives no request,
+   * parameters, body, tenant, or values. Routes without capability declarations keep the old hot path.
+   */
+  readonly onCapabilityUse?: (event: CapabilityUseEvent) => void
+  /**
+   * Default store backing routes that declare `schema.idempotency` without their own `store`. Defaults
+   * to a shared in-process {@link MemoryIdempotencyStore} (created lazily on first idempotent route).
+   * Inject a durable store here to make request-scoped dedupe survive restarts app-wide.
+   */
+  readonly idempotencyStore?: IdempotencyStore
   /** Structured logger for framework events (redacts secrets). Default: JSON to stderr. */
   readonly logger?: Logger
   /**
@@ -354,6 +390,8 @@ export interface RouteDescriptor {
   readonly schema: RouteSchema | undefined
   /** Effective enforcement evidence, populated only during reflection/introspection. */
   readonly assurance?: readonly AssuranceEvidence[]
+  /** Normalized declared effect tokens, populated only when the route declares any. */
+  readonly capabilities?: readonly string[]
   readonly tool?: {
     readonly name: string
     readonly description: string
@@ -1233,6 +1271,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   private readonly gracefulSignals: boolean
   /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
   private readonly capacityGate: AdmissionController | undefined
+  private readonly onCapabilityUse: ((event: CapabilityUseEvent) => void) | undefined
+  /** App-wide idempotency store (explicit option, else a lazily-created in-process default). */
+  private readonly configuredIdempotencyStore: IdempotencyStore | undefined
+  private lazyIdempotencyStore: IdempotencyStore | undefined
   private readonly logger: Logger
   /** App-wide validation-error fallback; a route's own `schema.onValidationError` takes precedence. */
   private readonly defaultOnValidationError?: RouteSchema["onValidationError"]
@@ -1293,6 +1335,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     }
     this.gracefulSignals = options.gracefulSignals ?? false
     this.capacityGate = options.admission
+    this.onCapabilityUse = options.onCapabilityUse
+    this.configuredIdempotencyStore = options.idempotencyStore
+    this.lazyIdempotencyStore = undefined
     this.logger = options.logger ?? jsonLogger()
     this.defaultOnValidationError = options.onValidationError
     this.bunServer = undefined
@@ -1744,9 +1789,35 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     schema: RouteSchema | undefined,
     handler: (context: never) => unknown,
   ): void {
+    const capabilities = normalizeRouteCapabilities(schema?.capabilities)
+    const handlerAssurance = assuranceDeclarationsOf(handler as unknown as object)
+    const invalidHandlerScope = handlerAssurance.find(
+      (declaration) => declaration.scope !== "plugin",
+    )
+    if (invalidHandlerScope !== undefined) {
+      throw new RouteConfigError(
+        "INVALID_ASSURANCE",
+        `route handler assurance must use plugin scope (received ${invalidHandlerScope.scope})`,
+      )
+    }
+    const routeDecorations: Record<PropertyKey, unknown> = { ...this.decorations }
+    if (capabilities.length > 0) {
+      routeDecorations[CAPABILITY_GUARD] = createCapabilityGuard(
+        capabilities,
+        method,
+        path,
+        this.onCapabilityUse,
+      )
+    }
+    const hasDecorations = Reflect.ownKeys(routeDecorations).length > 0
+    // An idempotency route runs a dedupe lane that must buffer the body and capture the response, so it
+    // never takes the fused/native fast path — force it onto the portable matched lane (which routes
+    // through `fetchMatched`, where the dedupe wrapper lives).
+    const idempotent = this.resolveIdempotency(schema)
     const bare =
       schema?.body === undefined &&
       schema?.query === undefined &&
+      idempotent === undefined &&
       this.derives.length === 0 &&
       this.beforeHandleHooks.length === 0 &&
       this.afterHandleHooks.length === 0 &&
@@ -1755,7 +1826,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       bare && this.aroundHooks.length === 0
         ? this.buildFusedWeb(
             handler as unknown as InternalHandler,
-            Object.keys(this.decorations).length > 0 ? { ...this.decorations } : undefined,
+            hasDecorations ? routeDecorations : undefined,
             isContextlessNoArgArrow(handler),
           )
         : undefined
@@ -1764,10 +1835,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       // with the concrete RawContext the typed handler expects, so this is sound.
       handler: handler as unknown as InternalHandler,
       schema,
+      idempotent,
       fusedWeb,
       derives: [...this.derives],
-      decorations: { ...this.decorations },
-      hasDecorations: Object.keys(this.decorations).length > 0,
+      decorations: routeDecorations,
+      hasDecorations,
       beforeHandle: [...this.beforeHandleHooks],
       afterHandle: [...this.afterHandleHooks],
       onError: [...this.onErrorHooks],
@@ -1794,9 +1866,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         this.onErrorHooks.length === 0,
     }
     this.router.add(method, path, entry)
-    const descriptor: RouteDescriptor = { method, path, schema }
+    const descriptor: RouteDescriptor = {
+      method,
+      path,
+      schema,
+      ...(capabilities.length > 0 ? { capabilities } : {}),
+    }
     this.routeList.push(descriptor)
-    const routeAssurance: AssuranceDeclaration[] = [...this.activeAssurance]
+    const routeAssurance: AssuranceDeclaration[] = [...this.activeAssurance, ...handlerAssurance]
     if (schema?.body !== undefined) {
       routeAssurance.push(
         Object.freeze({
@@ -1806,6 +1883,27 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         }),
       )
     }
+    // Declaring `schema.idempotency` is the evidence that satisfies a write capability's idempotency
+    // requirement (capability assurance reads these ids). `durable` scope additionally proves the
+    // durable-command requirement.
+    if (schema?.idempotency !== undefined) {
+      routeAssurance.push(
+        Object.freeze({
+          id: NIFRA_ASSURANCE_IDS.IDEMPOTENCY_KEY,
+          source: "route-schema",
+          scope: "plugin",
+        }),
+      )
+      if (schema.idempotency.scope === "durable") {
+        routeAssurance.push(
+          Object.freeze({
+            id: NIFRA_ASSURANCE_IDS.DURABLE_COMMAND,
+            source: "route-schema",
+            scope: "plugin",
+          }),
+        )
+      }
+    }
     this.rawEntries.push({
       method,
       path,
@@ -1815,6 +1913,24 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     })
   }
 
+  /** Resolve a route's declared idempotency into a pinned store + defaults, or `undefined` when off. */
+  private resolveIdempotency(schema: RouteSchema | undefined): ResolvedIdempotency | undefined {
+    const config = schema?.idempotency
+    if (config === undefined) return undefined
+    return Object.freeze({
+      store: config.store ?? this.defaultIdempotencyStore(),
+      ttlMs: config.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS,
+      headerName: (config.headerName ?? DEFAULT_IDEMPOTENCY_HEADER).toLowerCase(),
+    })
+  }
+
+  /** The app-wide idempotency store: the configured one, else a lazily-created shared in-process store. */
+  private defaultIdempotencyStore(): IdempotencyStore {
+    if (this.configuredIdempotencyStore !== undefined) return this.configuredIdempotencyStore
+    this.lazyIdempotencyStore ??= new MemoryIdempotencyStore()
+    return this.lazyIdempotencyStore
+  }
+
   /**
    * Merge another server's routes into this one — the composition escape hatch for large apps.
    *
@@ -1986,18 +2102,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       release()
       throw error
     }
-    if (outcome instanceof Promise) {
-      return outcome.then(
-        (response) => {
-          release()
-          return response
-        },
-        (error) => {
-          release()
-          throw error
-        },
-      )
-    }
+    // Release the slot once the response settles — on resolve OR reject — via `finally`, which passes
+    // the value/rejection through unchanged. (A single settle hook, rather than separate then-arms: the
+    // request pipeline resolves handler errors to a Response, so a rejection arm would be unreachable.)
+    if (outcome instanceof Promise) return outcome.finally(release)
     release()
     return outcome
   }
@@ -2297,6 +2405,111 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     wrapResponse: (response: Response) => T,
     onTimeout: () => T,
     webFast: boolean,
+  ): MaybePromise<T> {
+    // An idempotency route runs its dedupe lane first; on a fresh key it delegates to the normal lanes
+    // (with the body buffered). All non-idempotent routes skip straight to the lanes — no added cost.
+    if (entry.idempotent !== undefined) {
+      return this.runIdempotent(source, platform, entry, params, search, wrapResponse)
+    }
+    return this.runMatchedLanes(
+      source,
+      platform,
+      entry,
+      params,
+      search,
+      finalize,
+      wrapResponse,
+      onTimeout,
+      webFast,
+    )
+  }
+
+  /**
+   * Idempotency dedupe lane. Reads the `Idempotency-Key`, fingerprints the request, and consults the
+   * store: a fresh key runs the handler (via {@link runMatchedLanes} with the body buffered) and stores
+   * the response; a repeat key replays it without re-running; a key reused with a different body or an
+   * in-flight duplicate is rejected. Every branch materializes a `Response`, then adapts to `T` via the
+   * caller's `wrapResponse`, so it works on the Web fetch path and the Node-native outcome path alike.
+   */
+  private async runIdempotent<T>(
+    source: RequestSource,
+    platform: Platform | undefined,
+    entry: RouteEntry,
+    params: Record<string, string>,
+    search: string | undefined,
+    wrapResponse: (response: Response) => T,
+  ): Promise<T> {
+    const config = entry.idempotent as ResolvedIdempotency
+    const req = requestOf(source)
+    const key = req.headers.get(config.headerName)
+    if (key === null || !validIdempotencyKey(key)) {
+      return wrapResponse(jsonError(400, "idempotency_key_required"))
+    }
+    const read = await readBoundedBytes(req, this.maxBodyBytes)
+    if (!read.ok) {
+      return wrapResponse(
+        jsonError(read.status, read.status === 413 ? "payload_too_large" : "bad_request"),
+      )
+    }
+    const url = urlPartsOf(req.url)
+    const fingerprint = await computeIdempotencyFingerprint(
+      req.method,
+      `${url.pathname}${url.search}`,
+      read.bytes,
+    )
+
+    const begin = await config.store.begin(key, fingerprint, config.ttlMs)
+    if (begin.state === "replay") return wrapResponse(responseFromStored(begin.response))
+    if (begin.state === "mismatch") return wrapResponse(jsonError(409, "idempotency_key_reused"))
+    if (begin.state === "in-flight") {
+      return wrapResponse(jsonError(409, "idempotency_in_progress", { "Retry-After": "1" }))
+    }
+
+    // Fresh key: re-expose the buffered body as a Request so the normal lanes can read + validate it,
+    // then run those lanes to a concrete Response.
+    const bufferedInit: RequestInit = { method: req.method, headers: req.headers }
+    if (read.bytes.byteLength > 0)
+      bufferedInit.body = read.bytes as NonNullable<RequestInit["body"]>
+    const buffered: RequestSource = new Request(req.url, bufferedInit)
+    let response: Response
+    try {
+      response = await this.runMatchedLanes(
+        buffered,
+        platform,
+        entry,
+        params,
+        search,
+        toResponse,
+        IDENTITY_RESPONSE,
+        RESPONSE_TIMEOUT,
+        false,
+      )
+    } catch (err) {
+      // The lanes never throw (errors resolve to a 500 Response), but stay fail-safe: release the
+      // reservation so a retry isn't wedged, then re-throw.
+      await config.store.abandon(key)
+      throw err
+    }
+    // Cache only successful responses; release the key on any error so the client can retry.
+    if (response.status >= 200 && response.status < 300) {
+      await config.store.complete(key, await serializeResponse(response))
+    } else {
+      await config.store.abandon(key)
+    }
+    return wrapResponse(response)
+  }
+
+  /** Run a matched route through its selected execution lane (fused/bare/bodyOnly/queryOnly/lifecycle). */
+  private runMatchedLanes<T>(
+    source: RequestSource,
+    platform: Platform | undefined,
+    entry: RouteEntry,
+    params: Record<string, string>,
+    search: string | undefined,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+    onTimeout: () => T,
+    webFast: boolean,
   ): MaybePromise<T> {
     // Translate the absolute wire deadline once, clamp it to local policy, then use the resulting
     // duration for both c.signal and c.budget. A client can only shorten work, never extend it.
@@ -2527,7 +2740,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    */
   private buildFusedWeb(
     handler: InternalHandler,
-    decorations: Record<string, unknown> | undefined,
+    decorations: Record<PropertyKey, unknown> | undefined,
     contextless: boolean,
   ): FusedWebRunner {
     const maxBodyBytes = this.maxBodyBytes