@nifrajs/core 1.9.1 → 1.11.0

package/src/server/server.ts

@@ -5,8 +5,27 @@ import {
   type DeadlineAdmissionOptions,
   NIFRA_DEADLINE_HEADER,
   type RequestBudget,
-} from "@nifrajs/budget"
+} from "../budget.ts"
 import { FrameworkError, RouteConfigError } from "../errors.ts"
+import {
+  canonicalizeIdempotencyBody,
+  computeIdempotencyFingerprint,
+  DEFAULT_IDEMPOTENCY_HEADER,
+  DEFAULT_IDEMPOTENCY_TTL_MS,
+  IdempotencyResponseTooLargeError,
+  type IdempotencyStore,
+  MemoryIdempotencyStore,
+  responseFromStored,
+  serializeResponse,
+  validIdempotencyKey,
+  validIdempotencyNamespace,
+} from "../idempotency.ts"
+import {
+  CAPABILITY_GUARD,
+  type CapabilityUseEvent,
+  createCapabilityGuard,
+  normalizeRouteCapabilities,
+} from "../internal/capability-runtime.ts"
 import {
   type AssuranceDeclaration,
   type AssuranceEvidence,
@@ -14,6 +33,13 @@ import {
   assuranceEvidenceFor,
   NIFRA_ASSURANCE_IDS,
 } from "../internal/route-assurance.ts"
+import {
+  attachEffectLedger,
+  createRequestLedger,
+  DEFAULT_MAX_ENTRIES,
+  type EffectLedgerOptions,
+  type RequestLedger,
+} from "../ledger.ts"
 import { EMPTY_PARAMS, type Method, Router } from "../router/router.ts"
 import type {
   InferOutput,
@@ -148,17 +174,42 @@ type RawAfterHandle = (result: unknown, ctx: RawContext) => MaybePromise<unknown
 type RawErrorHandler = (error: unknown, ctx: RawContext) => MaybePromise<unknown>
 type RawAround = <T>(ctx: RawContext, next: () => MaybePromise<T>) => MaybePromise<T>
 export type OnRequestResult = Response | Request | undefined
-type RawOnRequest = (req: Request) => MaybePromise<OnRequestResult>
+type RawOnRequest = (req: Request, platform?: Platform) => 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
+  readonly namespace: NonNullable<RouteSchema["idempotency"]>["namespace"]
+  readonly maxResponseBytes: number
+}
+
+/** Registration-resolved effect-ledger wiring for one capability-declaring route. */
+interface ResolvedEffectLedger {
+  readonly sink: EffectLedgerOptions["sink"]
+  readonly maxEntries: number
+  readonly chain: boolean
+  /** The registered route pattern — what the sealed ledger names (never the concrete URL). */
+  readonly method: string
+  readonly path: string
+  /** The route's declared capability tokens, surfaced on the sealed ledger. */
+  readonly declared: readonly 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
+  /** Resolved effect-ledger wiring; `undefined` = off (no per-request ledger, no settle step). */
+  readonly ledgered: ResolvedEffectLedger | 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 +364,27 @@ 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
+  /**
+   * Enable the per-request effect ledger. Each route that declares `schema.capabilities` gets a
+   * bounded, token-only ledger; `useCapability(c, id, …)` appends one entry per effect, and the sink
+   * receives the sealed ledger when the response settles (only when it recorded entries). Token-only
+   * by construction — capability ids, phases, counters, digests; never payloads, values, or the
+   * concrete URL (the route *pattern* is recorded). Enabling it moves capability-declaring routes off
+   * the fused fast path (they need a per-request context + a settle step); all other routes are
+   * unaffected, and when unset the request path pays nothing.
+   */
+  readonly effectLedger?: EffectLedgerOptions
+  /**
+   * 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 +426,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
@@ -412,7 +486,7 @@ export interface RunningServer {
  */
 export interface Middleware {
   readonly name?: string
-  readonly onRequest?: (req: Request) => MaybePromise<OnRequestResult>
+  readonly onRequest?: (req: Request, platform?: Platform) => MaybePromise<OnRequestResult>
   readonly around?: <T>(context: Context, next: () => MaybePromise<T>) => MaybePromise<T>
   readonly beforeHandle?: (context: Context) => MaybePromise<unknown>
   readonly afterHandle?: (result: unknown, context: Context) => MaybePromise<unknown>
@@ -1233,6 +1307,14 @@ 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
+  /** Effect-ledger defaults pinned at construction; per-route `ledgered` copies add route identity. */
+  private readonly effectLedger:
+    | Omit<ResolvedEffectLedger, "method" | "path" | "declared">
+    | 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 +1375,26 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     }
     this.gracefulSignals = options.gracefulSignals ?? false
     this.capacityGate = options.admission
+    this.onCapabilityUse = options.onCapabilityUse
+    if (options.effectLedger !== undefined) {
+      const ledger = options.effectLedger
+      if (typeof ledger.sink !== "function") {
+        throw new TypeError("effectLedger.sink must be a function")
+      }
+      const maxEntries = ledger.maxEntries ?? DEFAULT_MAX_ENTRIES
+      if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+        throw new RangeError("effectLedger.maxEntries must be a positive safe integer")
+      }
+      this.effectLedger = Object.freeze({
+        sink: ledger.sink,
+        maxEntries,
+        chain: ledger.chain ?? false,
+      })
+    } else {
+      this.effectLedger = undefined
+    }
+    this.configuredIdempotencyStore = options.idempotencyStore
+    this.lazyIdempotencyStore = undefined
     this.logger = options.logger ?? jsonLogger()
     this.defaultOnValidationError = options.onValidationError
     this.bunServer = undefined
@@ -1330,8 +1432,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * Run before routing on the raw request. Return a `Response` to short-circuit, or a replacement
    * `Request` to continue routing with a rewritten method/URL/headers. Global.
    */
-  onRequest(fn: (req: Request) => MaybePromise<OnRequestResult>): this {
-    this.onRequestHooks.push(fn)
+  onRequest(
+    fn: (req: Request, platform?: Platform<EnvOf<Ctx>>) => MaybePromise<OnRequestResult>,
+  ): this {
+    this.onRequestHooks.push(fn as RawOnRequest)
     return this
   }
 
@@ -1744,9 +1848,48 @@ 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 authenticated = assuranceEvidenceFor(
+      [...this.activeAssurance, ...handlerAssurance, ...this.globalAssurance],
+      method,
+      path,
+    ).some((evidence) => evidence.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED)
+    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, authenticated)
+    // A ledgered route (capabilities declared + `server({ effectLedger })`) needs a per-request
+    // context to carry the ledger and a settle step to seal + sink it, so it too leaves the
+    // fused/contextless fast path. Resolved per route, at registration — like the capability guard.
+    const ledgered: ResolvedEffectLedger | undefined =
+      capabilities.length > 0 && this.effectLedger !== undefined
+        ? Object.freeze({ ...this.effectLedger, method, path, declared: capabilities })
+        : undefined
     const bare =
       schema?.body === undefined &&
       schema?.query === undefined &&
+      idempotent === undefined &&
+      ledgered === undefined &&
       this.derives.length === 0 &&
       this.beforeHandleHooks.length === 0 &&
       this.afterHandleHooks.length === 0 &&
@@ -1755,7 +1898,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 +1907,12 @@ 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,
+      ledgered,
       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 +1939,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 +1956,17 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         }),
       )
     }
+    // Declaring `schema.idempotency` is evidence for request replay only. It deliberately never proves
+    // durable command execution; that stronger evidence belongs to a command/outbox adapter.
+    if (schema?.idempotency !== undefined) {
+      routeAssurance.push(
+        Object.freeze({
+          id: NIFRA_ASSURANCE_IDS.IDEMPOTENCY_KEY,
+          source: "route-schema",
+          scope: "plugin",
+        }),
+      )
+    }
     this.rawEntries.push({
       method,
       path,
@@ -1815,6 +1976,84 @@ 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,
+    authenticated: boolean,
+  ): ResolvedIdempotency | undefined {
+    const config = schema?.idempotency
+    if (config === undefined) return undefined
+    if (schema?.sse !== undefined) {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        "streaming/SSE responses cannot be used on an idempotency route",
+      )
+    }
+    const store = config.store ?? this.defaultIdempotencyStore()
+    if (config.scope === "durable" && store.durability !== "durable") {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        'durable idempotency requires a durable store (store.durability must be "durable")',
+      )
+    }
+    const ttlMs = config.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS
+    if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        "idempotency ttlMs must be a finite positive number",
+      )
+    }
+    const headerName = (config.headerName ?? DEFAULT_IDEMPOTENCY_HEADER).toLowerCase()
+    try {
+      new Headers().set(headerName, "probe")
+    } catch {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        `invalid idempotency header name ${JSON.stringify(headerName)}`,
+      )
+    }
+    const namespace = config.namespace
+    if (namespace === undefined) {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        "idempotency namespace is required; use a principal resolver or an explicit shared scope",
+      )
+    }
+    if (typeof namespace === "string" && !validIdempotencyNamespace(namespace)) {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        `invalid idempotency namespace ${JSON.stringify(namespace)}`,
+      )
+    }
+    if (authenticated && typeof namespace !== "function") {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        "authenticated idempotency routes require a principal namespace resolver",
+      )
+    }
+    const maxResponseBytes = config.maxResponseBytes ?? this.maxBodyBytes
+    if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1) {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        "idempotency maxResponseBytes must be a positive integer",
+      )
+    }
+    return Object.freeze({
+      store,
+      ttlMs,
+      headerName,
+      namespace,
+      maxResponseBytes,
+    })
+  }
+
+  /** 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 +2225,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
   }
@@ -2177,7 +2408,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     const originalRequest = requestOf(source)
     let current: RequestSource = source
     for (let i = 0; i < hooks.length; i++) {
-      const outcome = (hooks[i] as RawOnRequest)(requestOf(current))
+      const outcome = (hooks[i] as RawOnRequest)(requestOf(current), platform)
       if (outcome instanceof Promise) {
         return outcome.then((early) =>
           this.continueOnRequest(
@@ -2227,7 +2458,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         return wrapResponse(early)
       }
       if (index >= this.onRequestHooks.length) break
-      const outcome = (this.onRequestHooks[index] as RawOnRequest)(requestOf(current))
+      const outcome = (this.onRequestHooks[index] as RawOnRequest)(requestOf(current), platform)
       early = outcome instanceof Promise ? await outcome : outcome
       index++
     }
@@ -2297,6 +2528,160 @@ 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 namespace =
+      typeof config.namespace === "function"
+        ? await config.namespace(req.clone(), platform)
+        : config.namespace
+    if (!validIdempotencyNamespace(namespace)) {
+      return wrapResponse(jsonError(500, "idempotency_namespace_invalid"))
+    }
+    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 canonicalBody = canonicalizeIdempotencyBody(read.bytes, req.headers.get("content-type"))
+    const fingerprint = await computeIdempotencyFingerprint(
+      req.method,
+      `${url.pathname}${url.search}`,
+      canonicalBody,
+      req.headers.get("content-type") ?? "",
+    )
+
+    const begin = await config.store.begin({ namespace, key, fingerprint, ttlMs: config.ttlMs })
+    if (begin.state === "replay") {
+      return wrapResponse(responseFromStored(begin.response, { maxBytes: config.maxResponseBytes }))
+    }
+    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" }))
+    }
+    if (begin.state === "capacity") {
+      return wrapResponse(jsonError(503, "idempotency_store_capacity", { "Retry-After": "1" }))
+    }
+    const reservation = begin.reservation
+
+    // 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,
+      signal: req.signal,
+    }
+    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({ namespace, key, reservation })
+      throw err
+    }
+    // Cache only successful responses; release the key on any error so the client can retry.
+    if (response.status >= 200 && response.status < 300) {
+      let storedResponse: Awaited<ReturnType<typeof serializeResponse>>
+      try {
+        storedResponse = await serializeResponse(response, { maxBytes: config.maxResponseBytes })
+      } catch (error) {
+        if (!(error instanceof IdempotencyResponseTooLargeError)) throw error
+        // The effect may already have happened, so never abandon and permit a duplicate execution.
+        // Commit a small terminal response under the winning key and return that same response now.
+        response = jsonError(507, "idempotency_response_too_large")
+        try {
+          storedResponse = await serializeResponse(response, {
+            maxBytes: config.maxResponseBytes,
+          })
+        } catch (terminalError) {
+          if (!(terminalError instanceof IdempotencyResponseTooLargeError)) throw terminalError
+          // Even an intentionally tiny bound must remain truthful. An empty 507 preserves terminal
+          // status + replay safety without silently storing more bytes than the route permits.
+          response = new Response(null, { status: 507 })
+          storedResponse = await serializeResponse(response, {
+            maxBytes: config.maxResponseBytes,
+          })
+        }
+      }
+      const completed = await config.store.complete({
+        namespace,
+        key,
+        reservation,
+        response: storedResponse,
+      })
+      if (!completed) {
+        return wrapResponse(jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }))
+      }
+    } else {
+      await config.store.abandon({ namespace, key, reservation })
+    }
+    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.
@@ -2371,6 +2756,20 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         platform,
         this.maxBodyBytes,
       )
+      // Ledgered routes (capabilities + effectLedger) carry a bounded per-request ledger; the
+      // `useCapability` beacon appends to it, and the settle step below seals + sinks it. The route
+      // was forced off the fused/contextless lanes at registration, so this branch always runs.
+      let ledger: RequestLedger | undefined
+      if (entry.ledgered !== undefined) {
+        ledger = createRequestLedger({
+          method: entry.ledgered.method,
+          path: entry.ledgered.path,
+          declared: entry.ledgered.declared,
+          maxEntries: entry.ledgered.maxEntries,
+          chain: entry.ledgered.chain,
+        })
+        attachEffectLedger(ctx, ledger)
+      }
 
       if (entry.around.length === 0) {
         outcome = entry.bare
@@ -2396,6 +2795,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
           wrapResponse,
         )
       }
+      // Settle step: seal the ledger and hand it to the sink BEFORE the response is released, on
+      // success and error responses alike (partial work is exactly what an audit must capture). The
+      // lanes above resolve handler errors to responses, so a plain resolve arm is sufficient.
+      if (ledger !== undefined) {
+        const resolved = entry.ledgered as ResolvedEffectLedger
+        const active = ledger
+        outcome = (outcome instanceof Promise ? outcome : Promise.resolve(outcome)).then((value) =>
+          this.settleEffectLedger(active, resolved, value),
+        )
+      }
     }
     // The request timeout only bounds work that is actually pending — a synchronous (bare) result is
     // already complete and can't time out, so it's returned as-is (no 503 race, no promise).
@@ -2414,6 +2823,34 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return outcome
   }
 
+  /**
+   * Seal a ledgered request and deliver the sealed ledger to the sink. An empty ledger (declared
+   * capabilities, none exercised) is not delivered — there is nothing to audit. This post-effect
+   * ledger is observational: transactional/durable audit belongs in
+   * the owned effect transaction, so a sink outage must not turn a successful effect into a retryable
+   * 500 that can duplicate it.
+   */
+  private async settleEffectLedger<T>(
+    ledger: RequestLedger,
+    resolved: ResolvedEffectLedger,
+    value: T,
+  ): Promise<T> {
+    const sealed = await ledger.seal()
+    if (sealed.entries.length === 0) return value
+    try {
+      await resolved.sink(sealed)
+    } catch (err) {
+      // Token-only logging: the route pattern and the failure name — never entry payloads (there are
+      // none) and never the request.
+      this.logger.error("effect ledger sink failed", {
+        method: resolved.method,
+        path: resolved.path,
+        name: err instanceof Error ? err.name : "Error",
+      })
+    }
+    return value
+  }
+
   /** The narrowest bare route: a syntactic `() => ...` handler cannot observe the context argument, so
    * successful requests can skip allocating `RequestContext`. Errors still allocate one for logging. */
   private runContextlessBare<T>(
@@ -2527,7 +2964,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