@nifrajs/core 2.12.1 → 2.14.1

package/src/binary.ts

@@ -34,6 +34,23 @@ export const NIFRA_BINARY_HEADER = "x-nifra-binary"
 /** A `Response` a route declared as binary. `Jsonify` maps this to `Blob`. */
 export type BinaryResponse = Response & { readonly [NIFRA_BYTES]: true }
 
+/**
+ * Marker on a raw response's TYPE carrying the payload it serializes to. Like {@link NIFRA_BYTES} it is
+ * a unique symbol declared *required*, so an ordinary `Response` cannot satisfy it by accident - an
+ * optional brand would be met by every `Response`, and every raw-response route would wrongly claim a
+ * typed body.
+ */
+declare const NIFRA_RAW: unique symbol
+
+/**
+ * A raw `Response` whose JSON body a route declared as `T`. Returning a bare `Response` drops a route
+ * out of the typed contract - the client reads its `data` as `never`, since a `Response`'s own
+ * properties say nothing about the payload. {@link raw} brands the `Response` with the shape it
+ * actually serializes, so `Jsonify` answers `Jsonify<T>` and the route stays inside the typed client.
+ * The brand is a phantom: nothing is added at runtime.
+ */
+export type RawResponse<T> = Response & { readonly [NIFRA_RAW]: T }
+
 /** What can be sent as bytes without being re-encoded on the way out. */
 export type BinaryBody = ArrayBuffer | ArrayBufferView | Blob | ReadableStream<Uint8Array>
 
@@ -126,3 +143,21 @@ export function bytes(body: BinaryBody, options: BytesOptions = {}): BinaryRespo
     headers,
   }) as BinaryResponse
 }
+
+/**
+ * Brand a hand-built `Response` with the payload type `T` its body serializes to, so a route that must
+ * return a `Response` directly still types `res.data` as `Jsonify<T>` on the client instead of `never`.
+ * Use it for the endpoints that build their own `Response` - a token minted by a third-party SDK, a
+ * redirect that also carries a JSON body, a hand-tuned cache header - but should still be part of the
+ * contract. Purely a type assertion: the `Response` is returned unchanged, nothing is added at runtime.
+ *
+ *     app.get("/livekit-token", async (c) =>
+ *       raw<{ token: string }>(Response.json({ token: await mint(c) })))
+ *     // client: res.data is typed { token: string }
+ *
+ * The payload `T` is the type the body serializes to - it is not validated, so it is a promise the route
+ * must keep. For bytes prefer {@link bytes}, which also sets the media-type headers.
+ */
+export function raw<T>(response: Response): RawResponse<T> {
+  return response as RawResponse<T>
+}

package/src/durable-adapters.ts

@@ -13,6 +13,9 @@ import type {
   SagaRecord,
   SagaStore,
 } from "./durable-execution.ts"
+import { durableApprovalProtocol } from "./internal/durable-approval-protocol.ts"
+import { durableEffectProtocol } from "./internal/durable-effect-protocol.ts"
+import { durableSagaProtocol } from "./internal/durable-saga-protocol.ts"
 import { safeEqual } from "./internal/safe-equal.ts"
 import type { ReconciliationLease, ReconciliationLeaseStore } from "./reconciliation-worker.ts"
 import { parse as parseWire, stringify as stringifyWire } from "./wire.ts"
@@ -93,20 +96,8 @@ export function createDurableExecutionAdapter(
     get: (effectId) => backend.get<DurableEffectRecord>("effect", effectId),
     async transition(input) {
       const current = await backend.get<DurableEffectRecord>("effect", input.effectId)
-      if (
-        current === undefined ||
-        current.version !== input.version ||
-        current.state !== input.from
-      ) {
-        return false
-      }
-      const next: DurableEffectRecord = {
-        ...current,
-        state: input.to,
-        updatedAt: input.updatedAt,
-        version: current.version + 1,
-        ...(input.errorCode === undefined ? {} : { errorCode: input.errorCode }),
-      }
+      const next = durableEffectProtocol.transition(current, input)
+      if (next === undefined) return false
       return await backend.compareAndSet("effect", input.effectId, input.version, next)
     },
     scan: (input) =>
@@ -119,46 +110,26 @@ export function createDurableExecutionAdapter(
     get: (approvalId) => backend.get<ApprovalRecord>("approval", approvalId),
     async decide(input) {
       const current = await backend.get<ApprovalRecord>("approval", input.approvalId)
-      if (
-        current === undefined ||
-        current.tenantId !== input.tenantId ||
-        current.state !== "pending" ||
-        current.expiresAt <= input.now
-      ) {
-        return false
-      }
-      const decided: ApprovalRecord = {
-        ...current,
-        state: input.decision,
-        decidedBy: input.decidedBy,
-        updatedAt: input.now,
-        version: current.version + 1,
-      }
-      return await backend.compareAndSet("approval", input.approvalId, current.version, decided)
+      const next = durableApprovalProtocol.decide(current, input)
+      if (current === undefined || next === undefined) return false
+      return await backend.compareAndSet("approval", input.approvalId, current.version, next)
     },
     async consume(input): Promise<ApprovalConsumeResult> {
       const current = await backend.get<ApprovalRecord>("approval", input.approvalId)
-      if (current === undefined) return { state: "missing" }
-      if (current.tenantId !== input.tenantId || current.principalId !== input.principalId)
-        return { state: "binding" }
+      const transition = durableApprovalProtocol.consume(current, input)
       if (
-        current.capability !== input.capability ||
-        current.target !== input.target ||
-        !safeEqual(current.digest, input.digest)
+        current === undefined ||
+        transition.result.state !== "consumed" ||
+        transition.next === undefined
       )
-        return { state: "binding" }
-      if (!safeEqual(current.tokenHash, input.tokenHash)) return { state: "token" }
-      if (current.state === "consumed") return { state: "replay" }
-      if (current.state === "denied") return { state: "denied" }
-      if (current.state === "pending") return { state: "pending" }
-      if (current.state === "expired" || current.expiresAt <= input.now) return { state: "expired" }
-      const consumed = await backend.compareAndSet("approval", input.approvalId, current.version, {
-        ...current,
-        state: "consumed",
-        updatedAt: input.now,
-        version: current.version + 1,
-      })
-      return consumed ? { state: "consumed" } : { state: "replay" }
+        return transition.result
+      const consumed = await backend.compareAndSet(
+        "approval",
+        input.approvalId,
+        current.version,
+        transition.next,
+      )
+      return consumed ? transition.result : { state: "replay" }
     },
   }
 
@@ -166,8 +137,12 @@ export function createDurableExecutionAdapter(
     durability: "durable",
     create: (record) => backend.create("saga", record.sagaId, clone(record)),
     get: (sagaId) => backend.get<SagaRecord>("saga", sagaId),
-    compareAndSet: (input) =>
-      backend.compareAndSet("saga", input.sagaId, input.version, clone(input.record)),
+    compareAndSet: (input) => {
+      const next = durableSagaProtocol.transition(undefined, input)
+      return next === undefined
+        ? false
+        : backend.compareAndSet("saga", input.sagaId, input.version, clone(next))
+    },
     scan: (input) => backend.scan<SagaRecord>("saga", input as ReconciliationScanOptions<string>),
   }
 

package/src/durable-execution.ts

@@ -13,7 +13,9 @@ import type {
   CapabilityExecutionJournal,
 } from "./internal/capability-runtime.ts"
 import { validCapabilityId } from "./internal/capability-runtime.ts"
-import { safeEqual } from "./internal/safe-equal.ts"
+import { durableApprovalProtocol } from "./internal/durable-approval-protocol.ts"
+import { durableEffectProtocol } from "./internal/durable-effect-protocol.ts"
+import { durableSagaProtocol } from "./internal/durable-saga-protocol.ts"
 
 export type { CapabilityApprovalGate, CapabilityExecutionIdentity, CapabilityExecutionJournal }
 
@@ -208,8 +210,7 @@ export function createDurableEffectJournal(
     errorCode?: string,
   ): Promise<void> => {
     const record = await current(effectId)
-    if (record.state !== from) throw new DurableEffectTransitionError(effectId, `${from}->${to}`)
-    const accepted = await options.store.transition({
+    const next = durableEffectProtocol.transition(record, {
       effectId,
       version: record.version,
       from,
@@ -217,6 +218,15 @@ export function createDurableEffectJournal(
       updatedAt: now(),
       ...(errorCode === undefined ? {} : { errorCode }),
     })
+    if (next === undefined) throw new DurableEffectTransitionError(effectId, `${from}->${to}`)
+    const accepted = await options.store.transition({
+      effectId,
+      version: record.version,
+      from,
+      to,
+      updatedAt: next.updatedAt,
+      ...(errorCode === undefined ? {} : { errorCode }),
+    })
     if (!accepted) throw new DurableEffectTransitionError(effectId, `${from}->${to}`)
   }
 
@@ -261,7 +271,7 @@ export function createDurableEffectJournal(
         throw new TypeError("durable effect errorCode is invalid")
       const record = await current(effectId)
       const to = input.began ? "unknown" : "failed"
-      const accepted = await options.store.transition({
+      const next = durableEffectProtocol.transition(record, {
         effectId,
         version: record.version,
         from: record.state,
@@ -269,6 +279,16 @@ export function createDurableEffectJournal(
         updatedAt: now(),
         errorCode: input.errorCode,
       })
+      if (next === undefined)
+        throw new DurableEffectTransitionError(effectId, `${record.state}->${to}`)
+      const accepted = await options.store.transition({
+        effectId,
+        version: record.version,
+        from: record.state,
+        to,
+        updatedAt: next.updatedAt,
+        errorCode: input.errorCode,
+      })
       if (!accepted) throw new DurableEffectTransitionError(effectId, `${record.state}->${to}`)
     },
   }
@@ -296,18 +316,10 @@ export class MemoryDurableEffectStore implements DurableEffectStore {
 
   transition(input: Parameters<DurableEffectStore["transition"]>[0]): boolean {
     const current = this.records.get(input.effectId)
-    if (current === undefined || current.version !== input.version || current.state !== input.from)
-      return false
-    this.records.set(
-      input.effectId,
-      Object.freeze({
-        ...current,
-        state: input.to,
-        updatedAt: input.updatedAt,
-        version: current.version + 1,
-        ...(input.errorCode === undefined ? {} : { errorCode: input.errorCode }),
-      }),
-    )
+    const next = durableEffectProtocol.transition(current, input)
+    if (next === undefined) return false
+    if (current === undefined) return false
+    this.records.set(input.effectId, Object.freeze(next))
     bucketMove(this.byState, current.state, input.to, input.effectId)
     return true
   }
@@ -801,64 +813,17 @@ export class MemoryApprovalStore implements ApprovalStore {
   }
   decide(input: Parameters<ApprovalStore["decide"]>[0]): boolean {
     const record = this.records.get(input.approvalId)
-    if (
-      record === undefined ||
-      record.tenantId !== input.tenantId ||
-      record.state !== "pending" ||
-      record.expiresAt <= input.now
-    )
-      return false
-    this.records.set(
-      input.approvalId,
-      Object.freeze({
-        ...record,
-        state: input.decision,
-        decidedBy: input.decidedBy,
-        updatedAt: input.now,
-        version: record.version + 1,
-      }),
-    )
+    const next = durableApprovalProtocol.decide(record, input)
+    if (next === undefined) return false
+    this.records.set(input.approvalId, Object.freeze(next))
     return true
   }
   consume(input: Parameters<ApprovalStore["consume"]>[0]): ApprovalConsumeResult {
     const record = this.records.get(input.approvalId)
-    if (record === undefined) return { state: "missing" }
-    if (
-      record.tenantId !== input.tenantId ||
-      record.principalId !== input.principalId ||
-      record.capability !== input.capability ||
-      record.target !== input.target ||
-      !safeEqual(record.digest, input.digest)
-    )
-      return { state: "binding" }
-    if (!safeEqual(record.tokenHash, input.tokenHash)) return { state: "token" }
-    if (record.state === "consumed") return { state: "replay" }
-    if (record.expiresAt <= input.now || record.state === "expired") {
-      if (record.state !== "expired")
-        this.records.set(
-          input.approvalId,
-          Object.freeze({
-            ...record,
-            state: "expired",
-            updatedAt: input.now,
-            version: record.version + 1,
-          }),
-        )
-      return { state: "expired" }
-    }
-    if (record.state === "pending") return { state: "pending" }
-    if (record.state === "denied") return { state: "denied" }
-    if (record.state !== "approved") return { state: "token" }
-    this.records.set(
-      input.approvalId,
-      Object.freeze({
-        ...record,
-        state: "consumed",
-        updatedAt: input.now,
-        version: record.version + 1,
-      }),
-    )
-    return { state: "consumed" }
+    const transition = durableApprovalProtocol.consume(record, input)
+    if (transition.next !== undefined)
+      this.records.set(input.approvalId, Object.freeze(transition.next))
+    return transition.result
   }
   list(): readonly ApprovalRecord[] {
     return Object.freeze(
@@ -1174,7 +1139,12 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     current: SagaRecord,
     update: Omit<SagaRecord, "version">,
   ): Promise<SagaRecord> => {
-    const next = Object.freeze({ ...update, version: current.version + 1 })
+    const next = durableSagaProtocol.transition(current, {
+      sagaId: current.sagaId,
+      version: current.version,
+      record: Object.freeze({ ...update, version: current.version + 1 }),
+    })
+    if (next === undefined) throw new SagaConcurrencyError(current.sagaId)
     if (
       !(await options.store.compareAndSet({
         sagaId: current.sagaId,
@@ -1190,16 +1160,7 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     index: number,
     step: SagaStepRecord,
     state = record.state,
-  ): Omit<SagaRecord, "version"> => ({
-    ...record,
-    state,
-    steps: Object.freeze(
-      record.steps.map((candidate, candidateIndex) =>
-        candidateIndex === index ? Object.freeze(step) : candidate,
-      ),
-    ),
-    updatedAt: now(),
-  })
+  ): Omit<SagaRecord, "version"> => durableSagaProtocol.withStep(record, index, step, state, now())
   const effectScope = createEffectScope({
     ...(observer === undefined ? {} : { observers: [observer] }),
   })
@@ -1569,13 +1530,10 @@ export class MemorySagaStore implements SagaStore {
   }
   compareAndSet(input: Parameters<SagaStore["compareAndSet"]>[0]): boolean {
     const current = this.records.get(input.sagaId)
-    if (
-      current === undefined ||
-      current.version !== input.version ||
-      input.record.version !== input.version + 1
-    )
-      return false
-    this.records.set(input.sagaId, Object.freeze(cloneValue(input.record)))
+    const next = durableSagaProtocol.transition(current, input)
+    if (next === undefined) return false
+    if (current === undefined) return false
+    this.records.set(input.sagaId, Object.freeze(next))
     bucketMove(this.byState, current.state, input.record.state, input.sagaId)
     return true
   }

package/src/index.ts

@@ -10,7 +10,7 @@
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export const VERSION = "2.12.1" as const
+export const VERSION = "2.14.1" as const
 
 export type Version = typeof VERSION
 

package/src/internal/durable-approval-protocol.ts

@@ -0,0 +1,92 @@
+import type { ApprovalConsumeResult, ApprovalRecord, ApprovalStore } from "../durable-execution.ts"
+import { safeEqual } from "./safe-equal.ts"
+
+export type DurableApprovalDecisionInput = Parameters<ApprovalStore["decide"]>[0]
+export type DurableApprovalConsumeInput = Parameters<ApprovalStore["consume"]>[0]
+
+export interface DurableApprovalConsumeTransition {
+  readonly result: ApprovalConsumeResult
+  readonly next?: ApprovalRecord
+}
+
+export interface DurableApprovalProtocol {
+  decide(
+    current: ApprovalRecord | undefined,
+    input: DurableApprovalDecisionInput,
+  ): ApprovalRecord | undefined
+  consume(
+    current: ApprovalRecord | undefined,
+    input: DurableApprovalConsumeInput,
+  ): DurableApprovalConsumeTransition
+}
+
+function decideApproval(
+  current: ApprovalRecord | undefined,
+  input: DurableApprovalDecisionInput,
+): ApprovalRecord | undefined {
+  if (
+    current === undefined ||
+    current.tenantId !== input.tenantId ||
+    current.state !== "pending" ||
+    current.expiresAt <= input.now
+  ) {
+    return undefined
+  }
+  return Object.freeze({
+    ...current,
+    state: input.decision,
+    decidedBy: input.decidedBy,
+    updatedAt: input.now,
+    version: current.version + 1,
+  })
+}
+
+function consumeApproval(
+  current: ApprovalRecord | undefined,
+  input: DurableApprovalConsumeInput,
+): DurableApprovalConsumeTransition {
+  if (current === undefined) return { result: { state: "missing" } }
+  if (
+    current.tenantId !== input.tenantId ||
+    current.principalId !== input.principalId ||
+    current.capability !== input.capability ||
+    current.target !== input.target ||
+    !safeEqual(current.digest, input.digest)
+  ) {
+    return { result: { state: "binding" } }
+  }
+  if (!safeEqual(current.tokenHash, input.tokenHash)) return { result: { state: "token" } }
+  if (current.state === "consumed") return { result: { state: "replay" } }
+  if (current.state === "denied") return { result: { state: "denied" } }
+  if (current.state === "pending") return { result: { state: "pending" } }
+  if (current.state === "expired" || current.expiresAt <= input.now) {
+    return {
+      result: { state: "expired" },
+      ...(current.state === "expired"
+        ? {}
+        : {
+            next: Object.freeze({
+              ...current,
+              state: "expired" as const,
+              updatedAt: input.now,
+              version: current.version + 1,
+            }),
+          }),
+    }
+  }
+  if (current.state !== "approved") return { result: { state: "token" } }
+  return {
+    result: { state: "consumed" },
+    next: Object.freeze({
+      ...current,
+      state: "consumed" as const,
+      updatedAt: input.now,
+      version: current.version + 1,
+    }),
+  }
+}
+
+export const durableApprovalProtocol: DurableApprovalProtocol = Object.freeze({
+  decide: decideApproval,
+  consume: consumeApproval,
+})

package/src/internal/durable-effect-protocol.ts

@@ -0,0 +1,37 @@
+import type { DurableEffectRecord, DurableEffectState } from "../durable-execution.ts"
+
+export interface DurableEffectTransitionInput {
+  readonly effectId: string
+  readonly version: number
+  readonly from: DurableEffectState
+  readonly to: DurableEffectState
+  readonly updatedAt: number
+  readonly errorCode?: string
+}
+
+export interface DurableEffectProtocol {
+  transition(
+    current: DurableEffectRecord | undefined,
+    input: DurableEffectTransitionInput,
+  ): DurableEffectRecord | undefined
+}
+
+function transitionEffect(
+  current: DurableEffectRecord | undefined,
+  input: DurableEffectTransitionInput,
+): DurableEffectRecord | undefined {
+  if (current === undefined || current.version !== input.version || current.state !== input.from) {
+    return undefined
+  }
+  return Object.freeze({
+    ...current,
+    state: input.to,
+    updatedAt: input.updatedAt,
+    version: current.version + 1,
+    ...(input.errorCode === undefined ? {} : { errorCode: input.errorCode }),
+  })
+}
+
+export const durableEffectProtocol: DurableEffectProtocol = Object.freeze({
+  transition: transitionEffect,
+})

package/src/internal/durable-saga-protocol.ts

@@ -0,0 +1,55 @@
+import type { SagaRecord, SagaState, SagaStepRecord, SagaStore } from "../durable-execution.ts"
+
+export type DurableSagaTransitionInput = Parameters<SagaStore["compareAndSet"]>[0]
+
+export interface DurableSagaProtocol {
+  transition(
+    current: SagaRecord | undefined,
+    input: DurableSagaTransitionInput,
+  ): SagaRecord | undefined
+  withStep(
+    record: SagaRecord,
+    index: number,
+    step: SagaStepRecord,
+    state: SagaState,
+    updatedAt: number,
+  ): Omit<SagaRecord, "version">
+}
+
+function transitionSaga(
+  current: SagaRecord | undefined,
+  input: DurableSagaTransitionInput,
+): SagaRecord | undefined {
+  if (
+    input.record.version !== input.version + 1 ||
+    (current !== undefined &&
+      (current.sagaId !== input.sagaId || current.version !== input.version))
+  ) {
+    return undefined
+  }
+  return Object.freeze({ ...input.record })
+}
+
+function withSagaStep(
+  record: SagaRecord,
+  index: number,
+  step: SagaStepRecord,
+  state: SagaState,
+  updatedAt: number,
+): Omit<SagaRecord, "version"> {
+  return {
+    ...record,
+    state,
+    steps: Object.freeze(
+      record.steps.map((candidate, candidateIndex) =>
+        candidateIndex === index ? Object.freeze(step) : candidate,
+      ),
+    ),
+    updatedAt,
+  }
+}
+
+export const durableSagaProtocol: DurableSagaProtocol = Object.freeze({
+  transition: transitionSaga,
+  withStep: withSagaStep,
+})

package/src/internal/route-catalog.ts

@@ -80,6 +80,12 @@ export class RouteCatalog {
     return this.records
   }
 
+  /** Number of registered routes. Read at hook push time and at seal to detect an order-scoped hook
+   * that captured no route (see `Server.sealConfiguration`). */
+  get size(): number {
+    return this.records.length
+  }
+
   routeDescriptors(): ReadonlyArray<RouteDescriptor> {
     return this.descriptors
   }

package/src/range.ts

@@ -42,10 +42,12 @@ function validSize(size: number): void {
 export function parseByteRange(value: string | null, size: number): ByteRangeResult {
   validSize(size)
   if (value === null) return { kind: "none" }
+  // Bound the input before the regex runs, not after: an oversized header must never reach the
+  // matcher in the first place.
+  if (value.length > MAX_RANGE_HEADER_LENGTH) return { kind: "none" }
   const match = /^bytes\s*=\s*(.+)$/i.exec(value)
   if (match === null) return { kind: "none" }
   const source = match[1]!
-  if (source.length > MAX_RANGE_HEADER_LENGTH) return { kind: "none" }
   let separators = 0
   for (const character of source) {
     if (character === "," && ++separators >= MAX_RANGE_SPECIFIERS) return { kind: "none" }

package/src/server/body.ts

@@ -256,10 +256,8 @@ function cappedStreamOf(
  * An over-cap read rejects with `reject(413)` (a lying `Content-Length` with `reject(400)`), which
  * the lifecycle already treats as control flow - the same contract as `c.boundedBody`.
  */
-function capRequestBodyReads(request: Request, maxBytes: number): void {
-  if (TRANSPORT_CAPPED.has(request)) return
-  TRANSPORT_CAPPED.add(request)
-  const reject = transportCapError
+/** The request's own pre-shadow readers - the fallback surface when the source offers none. */
+function requestBodyReaders(request: Request): RawBodyReaders {
   const bodyDescriptor = descriptorOf(request, "body")
   const raw: RawBodyReaders = {
     get headers() {
@@ -276,6 +274,14 @@ function capRequestBodyReads(request: Request, maxBytes: number): void {
     json: request.json.bind(request),
   }
   if (typeof request.bytes === "function") raw.bytes = request.bytes.bind(request)
+  return raw
+}
+
+function capRequestBodyReads(request: Request, maxBytes: number, preset?: RawBodyReaders): void {
+  if (TRANSPORT_CAPPED.has(request)) return
+  TRANSPORT_CAPPED.add(request)
+  const reject = transportCapError
+  const raw = preset ?? requestBodyReaders(request)
   // One bounded buffer backs every shadowed reader; a second read replays it instead of failing
   // with "body already used" (a strict superset of the native one-shot contract).
   let buffered: Promise<Uint8Array> | undefined
@@ -350,13 +356,24 @@ export function markTransportCap(source: object, maxBytes: number): void {
  * lane's pre-decoded body), and hook-observed references all survive. Framework readers bypass the
  * shadow through {@link rawBodySourceOf} and enforce their own caps - `c.boundedBody(explicit)`
  * still overrides in either direction. An unmarked source (`bodyLimit: "unlimited"`) is untouched.
+ *
+ * A source that owns its transport bytes directly (Node's lazy source reads the socket itself)
+ * supplies them through `RequestSource.rawBodyReaders`: the capped readers then buffer off the
+ * socket instead of routing every read back through a runtime `Request` the source was still
+ * deferring. The cap is identical either way - the same {@link readBoundedBytes} enforces it.
  */
 export function applyTransportCap(source: object, request: Request): void {
   const maxBytes = (source as { [TRANSPORT_CAP]?: number })[TRANSPORT_CAP]
-  // The capped check comes BEFORE the body-null check: post-cap, `request.body` is the shadowed
-  // getter, and re-reading it on every `c.req` access would rebuild capped state for nothing.
-  if (maxBytes === undefined || TRANSPORT_CAPPED.has(request) || request.body === null) return
-  capRequestBodyReads(request, maxBytes)
+  // The capped check comes BEFORE the body probe: post-cap, `request.body` is the shadowed getter,
+  // and re-reading it on every `c.req` access would rebuild capped state for nothing.
+  if (maxBytes === undefined || TRANSPORT_CAPPED.has(request)) return
+  const provide = (source as { rawBodyReaders?: () => RawBodyReaders }).rawBodyReaders
+  const preset = provide === undefined ? undefined : provide.call(source)
+  // The null-body shortcut is only worth its probe when there is no cheaper surface: on a source
+  // that defers its `Request`, reading `request.body` would materialize the very object the preset
+  // readers exist to avoid. Capping a bodiless request costs nothing but the shadowing itself.
+  if (preset === undefined && request.body === null) return
+  capRequestBodyReads(request, maxBytes, preset)
   // A wrapper source (Node's lazy source) delegates its own body readers to the request once it
   // materializes - which are now the shadowed ones. Mirror the raw-reader stash onto the source so
   // framework readers (`rawBodySourceOf(source)`) keep reading pre-shadow there too.

package/src/server/plugin.ts

@@ -86,7 +86,7 @@ export interface PluginTypeCollapsed {
  * every route type flowing through it is about to be widened away.
  */
 // biome-ignore lint/suspicious/noExplicitAny: matches any Server shape to inspect its Registry alone
-type ServerTypeUnpinned<S> = [S] extends [Server<infer R, any>]
+export type ServerTypeUnpinned<S> = [S] extends [Server<infer R, any>]
   ? 0 extends 1 & R
     ? true
     : false