@jarenjs/contract 0.56.0 → 0.67.0

package/src/compat.js

@@ -1,7 +1,7 @@
 //@ts-check
 /**
  * @file Version compatibility — the one implementation of the
- * negotiation rule (docs/CONTRACT-FORMAT.md §10.4, §13.1): two ends
+ * negotiation rule (docs/CONTRACT-FORMAT.md §10.4, §13): two ends
  * speak when they declare the same `version`, or when either end's
  * `compat` list names the other's `version`. The client's `negotiate()`
  * and any server that wants to refuse an incompatible peer both call

package/src/errors.js

@@ -66,6 +66,7 @@ export const CONTRACT_CODES = Object.freeze({
   JC1008: 'openHttpClient, openPortClient, client.url, createContractEffect, createContractSubscription or a projection (publicProjection, toOpenApi, toTypeScript, toMarkdown, contractTools): an argument or option is malformed (not a compiled contract, fetch/keys/sleep/createTaskEffect/projectError not a function, storage without read/write, a non-object input to url, an ops entry naming no or an opaque operation, a tool name outside ^[a-zA-Z0-9_-]{1,64}$ or shared by two operations)',
   JC1009: 'encodeSseEvent (the stream wire): an event, id or data string the SSE frame cannot carry — a bare carriage return inside data, a line terminator inside event or id',
   JC1010: 'client.subscribe was asked for an operation that is not a subscribe operation (invoke carries reads and commands; subscribe carries streams)',
+  JC1011: 'a ledger commit or fail named a ref that settles no started record: the key expired, was reclaimed under a newer generation, or was settled already — the settlement is refused; the binding reports it to onError and the response still goes out',
   // ——— http request-time (ContractRuntimeError, mapped onto the wire) ———
   JC2001: 'no operation matches the request method and path (404)',
   JC2002: 'the path shape is served under other methods (405, Allow lists them)',
@@ -105,6 +106,8 @@ export const CONTRACT_CODES = Object.freeze({
   JC2093: 'the stream ended with a server error event whose code the operation does not declare (kind contract; a declared code is a failure outcome under its own code)',
   JC2094: 'the stream went silent for twice policy.stream.heartbeatMs (kind network, client-side)',
   JC2095: 'a requested resume was refused — informational, carried as resumed:false in the fresh snapshot\'s event data, never an outcome',
+  JC2096: 'the stream\'s bounded queue would overflow — the consumer reads slower than the source emits, or a replay page outran it (kind network, retryable; the stream ends with an error event carrying this code and the carrier tears the connection down)',
+  JC2097: 'the client\'s reconnect budget is exhausted: every attempt after a network loss failed the same way (kind network, not retryable; details carry the attempts made and the last network code, client-side)',
 });
 
 /**

package/src/host.js

@@ -0,0 +1,319 @@
+//@ts-check
+/**
+ * @file The host lifecycle (docs/CONTRACT-FORMAT.md §7.7): one
+ * carrier-neutral coordinator every server binding runs a request
+ * through. A host names two hooks at construction — `identify(meta)`,
+ * before anything of the request is parsed, and `acquire(input,
+ * identity, enter)`, after the input validated and (on HTTP) the
+ * idempotency claim answered `new` — each answering a LEASE `{ host,
+ * release? }` the handler sees as `ctx.host`, or a declared failure the
+ * binding renders like the handler's own. `acquire` hands its lease to
+ * `enter`, the binding's continuation that runs the handler, validates
+ * the output, serializes the response and — when the lease carries
+ * `settlement: { ledger, required: true }` — settles the idempotency
+ * claim through that ledger BEFORE `enter` resolves, so a host that
+ * opened a transaction around `enter` commits the domain write and the
+ * receipt together or not at all. Releases run once each, acquired
+ * before identity, at the boundary the binding declares (the response
+ * exposed, the opaque body settled, the stream done).
+ *
+ * The defaults are exactly `identify → { host: null }` and `acquire →
+ * enter({ host: identity.host })`: a host that names only `identify`
+ * sees its host in `scope(ctx)` and in the handler; one that names
+ * `acquire` owns the handler's host. Every returned lease is validated
+ * by shape (an object with an own `host`); a hook that throws, answers
+ * a malformed lease, never calls `enter` or calls it twice is the host's
+ * fault — observed through the binding's observer and rendered as the
+ * binding's host-fault code (`JC2008` on HTTP, `JC2070` on port and
+ * local); a declared failure is recognized by the `ContractFailure`
+ * brand, never by shape, and validated against the operation like a
+ * handler's. No policy data of the hooks reaches a wire.
+ */
+
+import { isThenable, toPromise } from '@jarenjs/core/function';
+
+import { ContractFailure, isContractFailure } from './errors.js';
+
+/**
+ * What `identify` sees: the matched operation, the trace, the request
+ * signal, the carrier, and the transport facts the carrier has — never
+ * a parsed input, never an auth vocabulary of the binding's own.
+ * @typedef {Object} IdentifyMeta
+ * @property {import('./compile.js').CompiledOperation} op
+ * @property {string} trace
+ * @property {AbortSignal | null} signal
+ * @property {'http' | 'port' | 'local'} carrier
+ * @property {string | null} method - the request line on HTTP; `null` elsewhere
+ * @property {string | null} path
+ * @property {Readonly<Record<string, string | readonly string[]>> | null} headers - the raw request headers on HTTP; `null` elsewhere
+ * @property {typeof ContractFailure} fail - the declared-failure factory
+ */
+
+/**
+ * A lease: the host value the handler sees as `ctx.host`, an optional
+ * release, and — from `acquire` only — an optional required settlement.
+ * @typedef {Object} Lease
+ * @property {unknown} host
+ * @property {(() => unknown) | undefined} release
+ * @property {{ ledger: import('./ledger.js').Ledger, required: true } | null} settlement
+ */
+
+/**
+ * The hooks as a binding validated them at construction.
+ * @typedef {Object} Lifecycle
+ * @property {(meta: IdentifyMeta) => unknown} identify
+ * @property {(input: unknown, identity: { host: unknown }, enter: (lease: unknown) => unknown) => unknown} acquire
+ */
+
+/** The default identity: no host. */
+const DEFAULT_IDENTIFY = () => ({ host: null });
+
+/**
+ * The default acquisition: the identity's host, as is.
+ * @param {unknown} input
+ * @param {{ host: unknown }} identity
+ * @param {(lease: unknown) => unknown} enter
+ */
+const DEFAULT_ACQUIRE = (input, identity, enter) => enter({ host: identity.host });
+
+/**
+ * A host fault of the lifecycle: what the binding observes and renders
+ * as its host-fault code.
+ */
+export class HostLifecycleError extends Error {
+  /**
+   * @param {string} message
+   * @param {unknown} [cause]
+   */
+  constructor(message, cause = undefined) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'HostLifecycleError';
+  }
+}
+
+/**
+ * Validate the hooks a binding was given; each defaults. Rejections are
+ * the binding's `JC1001` through `host`.
+ * @param {{ identify?: unknown, acquire?: unknown }} options
+ * @param {(reason: string) => Error} host - the binding's construction refusal
+ * @returns {Lifecycle}
+ */
+export function resolveLifecycle(options, host) {
+  for (const name of /** @type {const} */ (['identify', 'acquire'])) {
+    const value = options[name];
+    if (value !== undefined && typeof value !== 'function') throw host(`options.${name} must be a function`);
+  }
+  const identify = options.identify === undefined ? DEFAULT_IDENTIFY : /** @type {Lifecycle['identify']} */ (options.identify);
+  const acquire = options.acquire === undefined ? DEFAULT_ACQUIRE : /** @type {Lifecycle['acquire']} */ (options.acquire);
+  return Object.freeze({ identify, acquire });
+}
+
+/**
+ * Read a hook's answer as a lease: an object with an own `host`, an
+ * optional function `release`, and (when `acquired`) an optional
+ * `settlement` whose `ledger` has `commit`/`fail` and whose `required`
+ * is `true`. Anything else is the host's fault.
+ * @param {unknown} value
+ * @param {'identify' | 'acquire'} hook
+ * @returns {Lease}
+ * @throws {HostLifecycleError}
+ */
+export function leaseOf(value, hook) {
+  const v = /** @type {any} */ (value);
+  if (v === null || typeof v !== 'object' || !Object.hasOwn(v, 'host')) {
+    throw new HostLifecycleError(`${hook} must answer a lease { host, release? } — an object with an own host member`);
+  }
+  const release = v.release;
+  if (release !== undefined && typeof release !== 'function') {
+    throw new HostLifecycleError(`${hook}: a lease's release must be a function`);
+  }
+  let settlement = null;
+  if (hook === 'acquire' && v.settlement !== undefined && v.settlement !== null) {
+    const s = v.settlement;
+    if (typeof s !== 'object' || s.required !== true || s.ledger === null || typeof s.ledger !== 'object'
+      || typeof s.ledger.commit !== 'function' || typeof s.ledger.fail !== 'function') {
+      throw new HostLifecycleError('acquire: a lease\'s settlement must be { ledger, required: true } with a ledger that commits and fails');
+    }
+    settlement = { ledger: s.ledger, required: true };
+  }
+  else if (hook === 'identify' && v.settlement !== undefined) {
+    throw new HostLifecycleError('identify: a settlement belongs to the acquired lease, not the identity');
+  }
+  return { host: v.host, release, settlement };
+}
+
+/**
+ * A release that runs at most once, whatever the number of exits that
+ * reach it; its own failure is handed to `observed` and swallowed, and
+ * the answer says whether the release was clean (`true`) — a later
+ * call answers `true` without running anything again.
+ * @param {(() => unknown) | undefined} release
+ * @param {(error: unknown) => void} observed
+ * @returns {() => Promise<boolean>}
+ */
+export function once(release, observed) {
+  let done = false;
+  return () => {
+    if (done || release === undefined) return Promise.resolve(true);
+    done = true;
+    let out;
+    try {
+      out = release();
+    }
+    catch (err) {
+      observed(err);
+      return Promise.resolve(false);
+    }
+    return isThenable(out) ? toPromise(out).then(() => true, (err) => { observed(err); return false; }) : Promise.resolve(true);
+  };
+}
+
+/**
+ * Classify a hook's settled answer: a lease, a declared failure, or a
+ * host fault. Total for hostile values.
+ * @param {unknown} value
+ * @param {'identify' | 'acquire'} hook
+ * @returns {{ kind: 'lease', lease: Lease } | { kind: 'failure', failure: import('./errors.js').ContractFailureValue } | { kind: 'fault', cause: unknown }}
+ */
+export function classifyAnswer(value, hook) {
+  if (isContractFailure(value)) return { kind: 'failure', failure: value };
+  try {
+    return { kind: 'lease', lease: leaseOf(value, hook) };
+  }
+  catch (err) {
+    return { kind: 'fault', cause: err };
+  }
+}
+
+/**
+ * Run `identify`: the hook's answer (sync or async) classified.
+ * @param {Lifecycle} lifecycle
+ * @param {IdentifyMeta} meta
+ * @returns {Promise<ReturnType<typeof classifyAnswer>> | ReturnType<typeof classifyAnswer>}
+ */
+export function identify(lifecycle, meta) {
+  let answer;
+  try {
+    answer = lifecycle.identify(meta);
+  }
+  catch (err) {
+    return { kind: 'fault', cause: err };
+  }
+  return isThenable(answer)
+    ? toPromise(answer).then((value) => classifyAnswer(value, 'identify'), (err) => ({ kind: 'fault', cause: err }))
+    : classifyAnswer(answer, 'identify');
+}
+
+/**
+ * The private carrier a required settlement's failure travels in: the
+ * wire fault the dispatcher intends is preserved while the host's
+ * transaction around `enter` rolls back on the rejection.
+ */
+export class RollbackCarrier extends Error {
+  /**
+   * @param {unknown} response - the response the binding will answer
+   * @param {unknown} cause - what failed inside `enter`
+   */
+  constructor(response, cause) {
+    super('the required settlement did not commit; the host transaction rolls back', { cause });
+    this.name = 'RollbackCarrier';
+    this.response = response;
+  }
+}
+
+/**
+ * Run `acquire` around `enter`. `enter` receives the validated lease and
+ * answers the binding's result (a response, an outcome) or a promise of
+ * it; what the hook itself answers is the value of `enter` — a hook
+ * that resolves before `enter` settled, or to something else, is a
+ * fault. The result: `{ kind: 'entered', lease, result }` when `enter`
+ * ran and settled (its rejection, when it is not a RollbackCarrier of
+ * ours, is a fault of the binding's continuation); `{ kind: 'failure' }`
+ * for a declared failure answered instead of entering; `{ kind:
+ * 'fault' }` for everything else — `enter` never called, called twice,
+ * a malformed lease, a throw.
+ * @param {Lifecycle} lifecycle
+ * @param {unknown} input
+ * @param {{ host: unknown }} identity
+ * @param {(lease: Lease) => unknown} enter
+ * @returns {Promise<{ kind: 'entered', lease: Lease, result: unknown, rolledBack: RollbackCarrier | null, afterFault?: unknown }
+ *   | { kind: 'failure', failure: import('./errors.js').ContractFailureValue }
+ *   | { kind: 'fault', cause: unknown }>}
+ */
+export function acquire(lifecycle, input, identity, enter) {
+  /** @type {Lease | null} */
+  let lease = null;
+  /** @type {{ settled: boolean, value: unknown } | null} */
+  let entered = null;
+  let calls = 0;
+  /** @type {RollbackCarrier | null} */
+  let rolledBack = null;
+  const gate = (/** @type {unknown} */ candidate) => {
+    calls += 1;
+    if (calls > 1) throw new HostLifecycleError('acquire called enter more than once');
+    lease = leaseOf(candidate, 'acquire');
+    let out;
+    try {
+      out = enter(lease);
+    }
+    catch (err) {
+      out = Promise.reject(err);
+    }
+    const settled = toPromise(out).then(
+      (value) => {
+        entered = { settled: true, value };
+        return value;
+      },
+      (err) => {
+        if (err instanceof RollbackCarrier) {
+          rolledBack = err;
+          entered = { settled: true, value: err.response };
+        }
+        throw err;
+      });
+    return settled;
+  };
+  let answer;
+  try {
+    answer = lifecycle.acquire(input, identity, gate);
+  }
+  catch (err) {
+    return Promise.resolve(finish(err, true));
+  }
+  return toPromise(answer).then((value) => finish(value, false), (err) => finish(err, true));
+
+  /**
+   * @param {unknown} value - the hook's settled value or rejection
+   * @param {boolean} rejected
+   */
+  function finish(value, rejected) {
+    if (rejected) {
+      // our own refusal — enter called twice, a malformed lease — is the
+      // host's fault whatever else settled
+      if (value instanceof HostLifecycleError) return { kind: 'fault', cause: value };
+      if (value instanceof RollbackCarrier && entered !== null && lease !== null) {
+        // the host transaction rolled back on our carrier: the intended fault is the answer
+        return { kind: 'entered', lease, result: value.response, rolledBack: value };
+      }
+      if (rolledBack !== null && lease !== null) {
+        // the host wrapped our carrier in a rejection of its own (a transaction that rethrows): the intent stands
+        return { kind: 'entered', lease, result: rolledBack.response, rolledBack };
+      }
+      if (entered !== null && lease !== null) {
+        // the hook rejected after enter settled: the settled result stands, the rejection is the host's fault to observe
+        return { kind: 'entered', lease, result: entered.value, rolledBack: null, afterFault: value };
+      }
+      return { kind: 'fault', cause: value };
+    }
+    if (calls === 0) {
+      if (isContractFailure(value)) return { kind: 'failure', failure: value };
+      return { kind: 'fault', cause: new HostLifecycleError('acquire answered without calling enter and without a declared failure') };
+    }
+    if (entered === null || lease === null) {
+      return { kind: 'fault', cause: new HostLifecycleError('acquire resolved before enter settled') };
+    }
+    return { kind: 'entered', lease, result: entered.value, rolledBack };
+  }
+}
+
+export { ContractFailure };

package/src/http/body.js

@@ -0,0 +1,337 @@
+//@ts-check
+/**
+ * @file Byte bodies of the HTTP binding, carrier-neutral: the one
+ * normalizer that turns whatever an adapter or a handler hands over (a
+ * string, bytes, an async iterable of chunks, a Web `ReadableStream`)
+ * into the shape the pipeline reads; the bounded collector a JSON
+ * operation drains its source through (a JSON body must be parsed and
+ * validated whole, so it materializes — under the operation's limit
+ * and never past it); and the counting source an opaque handler
+ * receives, which never yields a byte past the limit and cancels its
+ * upstream exactly once. Nothing here keeps a chunk it has handed on:
+ * the opaque path holds one chunk at a time, and the JSON path holds
+ * at most `maxBodyBytes`.
+ */
+
+/**
+ * A body as the pipeline reads it: text, bytes, a pull source of byte
+ * chunks, or none.
+ * @typedef {string | Uint8Array | AsyncIterable<Uint8Array> | null} Body
+ */
+
+/**
+ * The limit crossing a counting source raises to whoever is pulling
+ * it: recognized by class, so a handler that lets it propagate answers
+ * `JC2003` rather than a host fault, and a handler that catches it
+ * decides for itself.
+ */
+export class BodyLimitError extends Error {
+  /** @param {number} limit */
+  constructor(limit) {
+    super(`the request body exceeds its ${limit}-byte limit`);
+    this.name = 'BodyLimitError';
+    /** @type {number} */
+    this.limit = limit;
+  }
+}
+
+/**
+ * Whether a value is an async iterable — the pull shape of a byte source.
+ * @param {unknown} value
+ * @returns {value is AsyncIterable<Uint8Array>}
+ */
+export function isAsyncByteSource(value) {
+  return value !== null && typeof value === 'object' && typeof (/** @type {any} */ (value))[Symbol.asyncIterator] === 'function';
+}
+
+/**
+ * Whether a value is a Web `ReadableStream` (by its reader, the one
+ * member every platform's stream has).
+ * @param {unknown} value
+ * @returns {value is ReadableStream<Uint8Array>}
+ */
+export function isReadableStream(value) {
+  return value !== null && typeof value === 'object' && typeof (/** @type {any} */ (value)).getReader === 'function';
+}
+
+/**
+ * An async iterable over a Web stream's reader. `return()` cancels the
+ * stream once; a completed read releases the lock.
+ * @param {ReadableStream<Uint8Array>} stream
+ * @returns {AsyncIterable<Uint8Array>}
+ */
+function readerSource(stream) {
+  return {
+    [Symbol.asyncIterator]() {
+      const reader = stream.getReader();
+      let done = false;
+      return {
+        async next() {
+          if (done) return { done: true, value: undefined };
+          let r;
+          try {
+            r = await reader.read();
+          }
+          catch (err) {
+            done = true;
+            throw err;
+          }
+          if (r.done) {
+            done = true;
+            reader.releaseLock();
+            return { done: true, value: undefined };
+          }
+          return { done: false, value: r.value };
+        },
+        async return(value) {
+          if (!done) {
+            done = true;
+            try {
+              await reader.cancel();
+            }
+            catch {
+              // a stream that refuses the cancel is already gone
+            }
+          }
+          return { done: true, value };
+        },
+      };
+    },
+  };
+}
+
+/**
+ * Normalize a body: `undefined`/`null` → `null`; a string or bytes
+ * pass; a Web stream becomes an async iterable over its reader; an
+ * async iterable passes. Anything else answers `undefined` — not a
+ * body, for the caller to refuse.
+ * @param {unknown} body
+ * @returns {Body | undefined}
+ */
+export function normalizeBody(body) {
+  if (body === undefined || body === null) return null;
+  if (typeof body === 'string' || body instanceof Uint8Array) return body;
+  if (isReadableStream(body)) return readerSource(body);
+  if (isAsyncByteSource(body)) return body;
+  return undefined;
+}
+
+/**
+ * Concatenate collected chunks into one Uint8Array.
+ * @param {Uint8Array[]} chunks
+ * @param {number} total
+ * @returns {Uint8Array}
+ */
+function concat(chunks, total) {
+  if (chunks.length === 1) return chunks[0];
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (let i = 0; i < chunks.length; i++) {
+    out.set(chunks[i], offset);
+    offset += chunks[i].byteLength;
+  }
+  return out;
+}
+
+/**
+ * Cancel an iterator once, swallowing what the cancel throws.
+ * @param {AsyncIterator<Uint8Array>} iterator
+ */
+async function cancelIterator(iterator) {
+  if (typeof iterator.return !== 'function') return;
+  try {
+    await iterator.return();
+  }
+  catch {
+    // an upstream that refuses its cancel is already gone
+  }
+}
+
+/**
+ * What the collector answers: the whole body, or why it stopped —
+ * `limit` (the read crossed `limit`; the crossing chunk was never
+ * retained), `aborted` (the signal fired between pulls), `error` (the
+ * source threw, or yielded a non-byte chunk). In every failed case the
+ * upstream iterator's `return()` ran exactly once.
+ * @typedef {{ ok: true, bytes: Uint8Array }
+ *   | { ok: false, kind: 'limit' | 'aborted' }
+ *   | { ok: false, kind: 'error', cause: unknown }} Collected
+ */
+
+/**
+ * Drain a byte source into one `Uint8Array` under a limit: at most
+ * `limit` bytes are ever held; the chunk that would cross it is not
+ * retained, the upstream is cancelled once, and the crossing is
+ * reported.
+ * @param {AsyncIterable<Uint8Array>} source
+ * @param {number} limit - inclusive
+ * @param {AbortSignal | null} signal - checked between pulls
+ * @returns {Promise<Collected>}
+ */
+export async function collectBytes(source, limit, signal) {
+  const iterator = source[Symbol.asyncIterator]();
+  /** @type {Uint8Array[]} */
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    if (signal !== null && signal.aborted) {
+      await cancelIterator(iterator);
+      return { ok: false, kind: 'aborted' };
+    }
+    let r;
+    try {
+      r = await iterator.next();
+    }
+    catch (err) {
+      await cancelIterator(iterator);
+      return { ok: false, kind: 'error', cause: err };
+    }
+    if (r.done) break;
+    const chunk = r.value;
+    if (!(chunk instanceof Uint8Array)) {
+      await cancelIterator(iterator);
+      return { ok: false, kind: 'error', cause: new TypeError('a body source must yield Uint8Array chunks') };
+    }
+    total += chunk.byteLength;
+    if (total > limit) {
+      await cancelIterator(iterator);
+      return { ok: false, kind: 'limit' };
+    }
+    chunks.push(chunk);
+  }
+  return { ok: true, bytes: total === 0 ? new Uint8Array(0) : concat(chunks, total) };
+}
+
+/**
+ * The state of a counting source, readable by the binding that made it.
+ * @typedef {Object} SourceState
+ * @property {boolean} started - a chunk was pulled
+ * @property {boolean} finished - EOF was reached, or the source was cancelled
+ * @property {boolean} cancelled - `return()` ran (a crossing, a consumer's return, the binding's cancel)
+ * @property {boolean} crossed - the limit was crossed
+ * @property {number} bytes - the bytes yielded so far
+ */
+
+/**
+ * A counting source over an upstream: what an opaque handler receives.
+ * @typedef {AsyncIterable<Uint8Array> & { cancel: () => Promise<void>, state: SourceState }} CountingSource
+ */
+
+/**
+ * Wrap an upstream source so it never yields a byte past `limit`: the
+ * chunk that would cross it is not yielded — the upstream is cancelled
+ * once and a `BodyLimitError` is thrown to the puller. `return()` (a
+ * consumer that stops early) and `cancel()` (the binding, when a
+ * response goes out with the request unread) both cancel the upstream
+ * exactly once; `state` says what happened.
+ * @param {AsyncIterable<Uint8Array>} upstream
+ * @param {number} limit
+ * @returns {CountingSource}
+ */
+export function countingSource(upstream, limit) {
+  /** @type {SourceState} */
+  const state = { started: false, finished: false, cancelled: false, crossed: false, bytes: 0 };
+  /** @type {AsyncIterator<Uint8Array> | null} */
+  let iterator = null;
+  const cancel = async () => {
+    if (state.finished) return;
+    state.finished = true;
+    state.cancelled = true;
+    if (iterator === null) iterator = upstream[Symbol.asyncIterator]();
+    await cancelIterator(iterator);
+  };
+  return {
+    [Symbol.asyncIterator]() {
+      return {
+        async next() {
+          if (state.finished) return { done: true, value: undefined };
+          state.started = true;
+          if (iterator === null) iterator = upstream[Symbol.asyncIterator]();
+          let r;
+          try {
+            r = await iterator.next();
+          }
+          catch (err) {
+            state.finished = true;
+            throw err;
+          }
+          if (state.finished) return { done: true, value: undefined };
+          if (r.done) {
+            state.finished = true;
+            return { done: true, value: undefined };
+          }
+          const chunk = r.value;
+          if (!(chunk instanceof Uint8Array)) {
+            await cancel();
+            throw new TypeError('a body source must yield Uint8Array chunks');
+          }
+          state.bytes += chunk.byteLength;
+          if (state.bytes > limit) {
+            state.crossed = true;
+            await cancel();
+            throw new BodyLimitError(limit);
+          }
+          return { done: false, value: chunk };
+        },
+        async return(value) {
+          await cancel();
+          return { done: true, value };
+        },
+      };
+    },
+    cancel,
+    state,
+  };
+}
+
+/**
+ * Run `after` once when a response source completes, throws or is
+ * cancelled by its consumer — the hook a binding uses to release what
+ * the response held (an unread request source). A throw from the
+ * source reaches the consumer after the hook; the hook's own answer
+ * is awaited but never replaces the source's outcome.
+ * @param {AsyncIterable<Uint8Array>} source
+ * @param {(cause: unknown) => unknown} after - `cause` is the throw, or `undefined` on EOF/return
+ * @returns {AsyncIterable<Uint8Array>}
+ */
+export function onSettled(source, after) {
+  let settled = false;
+  /** @param {unknown} cause */
+  const settle = async (cause) => {
+    if (settled) return;
+    settled = true;
+    try {
+      await after(cause);
+    }
+    catch {
+      // the hook's failure is not the stream's
+    }
+  };
+  return {
+    [Symbol.asyncIterator]() {
+      const iterator = source[Symbol.asyncIterator]();
+      return {
+        async next() {
+          if (settled) return { done: true, value: undefined };
+          let r;
+          try {
+            r = await iterator.next();
+          }
+          catch (err) {
+            await settle(err);
+            throw err;
+          }
+          if (r.done) await settle(undefined);
+          return r;
+        },
+        async return(value) {
+          if (!settled) {
+            await cancelIterator(iterator);
+            await settle(undefined);
+          }
+          return { done: true, value };
+        },
+      };
+    },
+  };
+}