@orkestrel/middleware 0.0.18 → 0.0.20

package/dist/src/core/index.cjs

@@ -5,12 +5,12 @@ let _orkestrel_abort = require("@orkestrel/abort");
 let _orkestrel_budget = require("@orkestrel/budget");
 let _orkestrel_timeout = require("@orkestrel/timeout");
 //#region src/core/constants.ts
-/** Default minimum buffered body size (bytes) `createCompression` will compress. */
+/** Holds `1024`, the default minimum buffered body size in bytes `createCompression` will compress. */
 var DEFAULT_COMPRESSION_THRESHOLD = 1024;
 /**
-* Default content-codings `createCompression` offers, in preference order —
-* intersected at construction with what the runtime's `CompressionStream`
-* actually supports.
+* Lists `['gzip', 'deflate']`, the default content-codings `createCompression` offers in
+* preference order — intersected at construction with what the runtime's
+* `CompressionStream` actually supports.
 *
 * @remarks
 * The shipped `@orkestrel/server` peer's {@link Encoding} union is
@@ -20,30 +20,31 @@ var DEFAULT_COMPRESSION_THRESHOLD = 1024;
 * admits; a node-face brotli variant, if one ships, extends this list there.
 */
 var DEFAULT_COMPRESSION_ENCODINGS = Object.freeze(["gzip", "deflate"]);
-/** Default `X-Frame-Options` value `createSecurity` sets. */
+/** Holds `'DENY'`, the default `X-Frame-Options` value `createSecurity` sets. */
 var DEFAULT_FRAME_OPTIONS = "DENY";
 /**
-* Default `Content-Security-Policy` value `createSecurity` sets — a custom
-* `csp` option REPLACES this wholesale, never merges.
+* Holds `"default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'self'; form-action 'self'"`,
+* the default `Content-Security-Policy` value `createSecurity` sets — a custom
+* `csp` option replaces this wholesale, never merges.
 */
 var DEFAULT_CSP = "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'self'; form-action 'self'";
-/** Default `Referrer-Policy` value `createSecurity` sets. */
+/** Holds `'strict-origin-when-cross-origin'`, the default `Referrer-Policy` value `createSecurity` sets. */
 var DEFAULT_REFERRER_POLICY = "strict-origin-when-cross-origin";
-/** Default `Permissions-Policy` value `createSecurity` sets. */
+/** Holds `'camera=(), microphone=(), geolocation=()'`, the default `Permissions-Policy` value `createSecurity` sets. */
 var DEFAULT_PERMISSIONS_POLICY = "camera=(), microphone=(), geolocation=()";
-/** Default `Cross-Origin-Opener-Policy` value `createSecurity` sets. */
+/** Holds `'same-origin'`, the default `Cross-Origin-Opener-Policy` value `createSecurity` sets. */
 var DEFAULT_COOP = "same-origin";
-/** Default `Cross-Origin-Resource-Policy` value `createSecurity` sets. */
+/** Holds `'same-origin'`, the default `Cross-Origin-Resource-Policy` value `createSecurity` sets. */
 var DEFAULT_CORP = "same-origin";
-/** Default `Origin-Agent-Cluster` value `createSecurity` sets. */
+/** Holds `'?1'`, the default `Origin-Agent-Cluster` value `createSecurity` sets. */
 var DEFAULT_CLUSTER = "?1";
-/** Value `createSecurity` sets for `Cross-Origin-Embedder-Policy` when `coep: true`. */
+/** Holds `'require-corp'`, the value `createSecurity` sets for `Cross-Origin-Embedder-Policy` when `coep: true`. */
 var DEFAULT_COEP = "require-corp";
-/** Value `createSecurity` sets for `Strict-Transport-Security` when `hsts: true`. */
+/** Holds `'max-age=31536000; includeSubDomains'`, the value `createSecurity` sets for `Strict-Transport-Security` when `hsts: true`. */
 var DEFAULT_HSTS = "max-age=31536000; includeSubDomains";
-/** Default header `createSecurity` mints/echoes a request identifier into. */
+/** Names `'x-request-id'`, the default header `createSecurity` mints or echoes a request identifier into. */
 var DEFAULT_IDENTIFIER_HEADER = "x-request-id";
-/** Default methods `createCors` advertises on a preflight response. */
+/** Lists the default methods `createCors` advertises on a preflight response. */
 var DEFAULT_CORS_METHODS = Object.freeze([
 	"GET",
 	"POST",
@@ -52,73 +53,47 @@ var DEFAULT_CORS_METHODS = Object.freeze([
 	"DELETE",
 	"OPTIONS"
 ]);
-/** Default headers `createCors` advertises on a preflight response. */
+/** Lists the default headers `createCors` advertises on a preflight response. */
 var DEFAULT_CORS_HEADERS = Object.freeze(["Content-Type", "Authorization"]);
-/** Default response status `createDeadline` returns when its deadline fires first. */
+/** Holds `503`, the default response status `createDeadline` returns when its deadline fires first. */
 var DEFAULT_DEADLINE_STATUS = 503;
-/** Default header `createBearer` reads the token from. */
+/** Names `'authorization'`, the default header `createBearer` reads the token from. */
 var DEFAULT_BEARER_HEADER = "authorization";
-/** Default scheme prefix `createBearer` strips before verification. */
+/** Names `'Bearer'`, the default scheme prefix `createBearer` strips before verification. */
 var DEFAULT_BEARER_SCHEME = "Bearer";
-/** Default maximum number of distinct rate-limit keys `createLimiter` tracks before LRU eviction. */
+/** Holds `10_000`, the default maximum number of distinct rate-limit keys `createLimiter` tracks before LRU eviction. */
 var DEFAULT_LIMITER_CAPACITY = 1e4;
-/** Default maximum number of distinct session ids `createMemorySessionStore` tracks before LRU (by last write) eviction. */
+/** Holds `10_000`, the default maximum number of distinct session ids `createMemorySessionStore` tracks before LRU (by last write) eviction. */
 var DEFAULT_SESSION_CAPACITY = 1e4;
-/** Default 429 body message `createLimiter` sends when a key is over budget. */
+/** Holds `'rate limit exceeded'`, the default 429 body message `createLimiter` sends when a key is over budget. */
 var DEFAULT_LIMITER_MESSAGE = "rate limit exceeded";
-/** Default cookie name `createCookieTransport` writes the signed session id under. */
+/** Names `'session'`, the default cookie `createCookieTransport` writes the signed session id under. */
 var DEFAULT_SESSION_COOKIE = "session";
-/** Default header `createHeaderTransport` carries the session id in. */
+/** Names `'session-id'`, the default header `createHeaderTransport` carries the session id in. */
 var DEFAULT_SESSION_HEADER = "session-id";
-/** Default signed-cookie name `createCSRF` writes the CSRF token under. */
+/** Names `'csrf'`, the default signed cookie `createCSRF` writes the CSRF token under. */
 var DEFAULT_CSRF_COOKIE = "csrf";
-/** Default header `createCSRF` reads a mutating request's submitted token from. */
+/** Names `'x-csrf-token'`, the default header `createCSRF` reads a mutating request's submitted token from. */
 var DEFAULT_CSRF_HEADER = "x-csrf-token";
-/** Default body field `createCSRF` falls back to reading a mutating request's submitted token from. */
+/** Names `'_csrf'`, the default body field `createCSRF` falls back to reading a mutating request's submitted token from. */
 var DEFAULT_CSRF_FIELD = "_csrf";
-/** Default methods `createCSRF` treats as safe (mint instead of verify). */
+/** Lists `['GET', 'HEAD', 'OPTIONS']`, the default methods `createCSRF` treats as safe (mint instead of verify). */
 var DEFAULT_CSRF_SAFE_METHODS = Object.freeze([
 	"GET",
 	"HEAD",
 	"OPTIONS"
 ]);
 //#endregion
-//#region src/core/Session.ts
-/**
-* A server-managed session's default entity — the `create` option's default
-* value factory for `createSession` (ruling G: `Session` ships WITHOUT a
-* `createSession` factory of its own, since that name belongs to the
-* battery).
-*
-* @remarks
-* `data` is a live, mutable `Map` a handler reads/writes directly;
-* `createSession` persists it to the configured store on the way out.
-*
-* @example
-* ```ts
-* const session = new Session('abc123')
-* session.data.set('userId', 'u_1')
-* ```
-*/
-var Session = class {
-	id;
-	data;
-	constructor(id) {
-		this.id = id;
-		this.data = /* @__PURE__ */ new Map();
-	}
-};
-//#endregion
 //#region src/core/helpers.ts
 /**
-* Derive `createLimiter`'s default rate-limit bucket key from a request's
+* Derives `createLimiter`'s default rate-limit bucket key from a request's
 * resolved identity facts.
 *
 * @remarks
 * Prefers a verified bearer token ({@link BearerState.token}) as
 * `token:<value>`; else a resolved client IP ({@link ClientState.client.ip},
 * set when `createForwarded` is mounted) or the raw socket peer
-* ({@link ConnectionState.connection.ip}) collapsed via `clientRateKey`
+* ({@link ConnectionState.connection.ip}) collapsed through `computeClientKey`
 * (IPv6 to its `/64` network) as `ip:<key>`; else the literal `ip:unknown`.
 * Never reads `X-Forwarded-For` itself — that trust decision belongs solely
 * to `createForwarded`.
@@ -135,12 +110,12 @@ var Session = class {
 function resolveKey(state) {
 	if (state.token !== void 0) return `token:${state.token}`;
 	const ip = state.client?.ip ?? state.connection?.ip;
-	if (ip !== void 0) return `ip:${(0, _orkestrel_server.clientRateKey)(ip)}`;
+	if (ip !== void 0) return `ip:${(0, _orkestrel_server.computeClientKey)(ip)}`;
 	return "ip:unknown";
 }
 /**
-* Build the `Retry-After` header value — whole seconds until a window reset,
-* floored at a minimum of `1` (ruling I).
+* Builds the `Retry-After` header value — whole seconds until a window reset,
+* floored at a minimum of `1`.
 *
 * @param resetAt - The window reset instant (same clock unit as `now`)
 * @param now - The current instant
@@ -156,8 +131,8 @@ function buildRetryAfter(resetAt, now) {
 	return String(Math.max(1, seconds));
 }
 /**
-* Build the draft `RateLimit` structured header field (ruling I) — emitted
-* only when `createLimiter`'s `policy` option is `true`.
+* Builds the draft `RateLimit` structured header field — emitted only when
+* `createLimiter`'s `policy` option is `true`.
 *
 * @param remaining - The requests still admitted this window
 * @param resetAt - The window reset instant (same clock unit as `now`)
@@ -173,8 +148,8 @@ function buildRateLimitField(remaining, resetAt, now) {
 	return `"default";r=${remaining};t=${Math.max(1, Math.ceil((resetAt - now) / 1e3))}`;
 }
 /**
-* Build the draft `RateLimit-Policy` structured header field (ruling I) —
-* emitted only when `createLimiter`'s `policy` option is `true`.
+* Builds the draft `RateLimit-Policy` structured header field — emitted only
+* when `createLimiter`'s `policy` option is `true`.
 *
 * @param max - The window's admitted request count
 * @param window - The window length in milliseconds
@@ -189,7 +164,7 @@ function buildRateLimitPolicyField(max, window) {
 	return `"default";q=${max};w=${Math.ceil(window / 1e3)}`;
 }
 /**
-* Whether a candidate address is a bare (non-CIDR) trusted-hop match — an
+* Checks whether a candidate address is a bare (non-CIDR) trusted-hop match — an
 * exact string match, or a simple prefix-CIDR match for IPv4 (`/8`–`/32`).
 * An IPv6 entry matches by exact string only — there is no IPv6 CIDR
 * support.
@@ -201,14 +176,14 @@ function buildRateLimitPolicyField(max, window) {
 * never claims full CIDR generality beyond IPv4.
 *
 * @remarks
-* An IPv6 `trusted` roster entry is compared as an EXACT string — it must be
+* An IPv6 `trusted` roster entry is compared as an exact string — it must be
 * supplied in canonical form (no zero-compression normalization, no case
 * folding) by the caller; this function performs no IPv6 normalization of
 * its own.
 *
 * @param address - The candidate hop address
 * @param entry - One `trusted` roster entry — an exact address or an IPv4 CIDR
-* @returns `true` when `address` is covered by `entry`
+* @returns True if `address` is covered by `entry`; false otherwise
 *
 * @example
 * ```ts
@@ -235,13 +210,13 @@ function matchesTrustedEntry(address, entry) {
 	return (networkInt & mask) === (addressInt & mask);
 }
 /**
-* Walk `X-Forwarded-For` right-to-left and resolve the first UNTRUSTED hop
+* Walks `X-Forwarded-For` right-to-left and resolves the first untrusted hop
 * address — `createForwarded`'s core algorithm.
 *
 * @remarks
 * Parses `X-Forwarded-For` only. With `proxies` set, trusts exactly that
 * many hops counted from the right (the closest to this server) and returns
-* the next one left of them; with `trusted` set, trusts every CONSECUTIVE
+* the next one left of them; with `trusted` set, trusts every consecutive
 * hop from the right that matches one of the roster
 * ({@link matchesTrustedEntry}) and returns the first hop that does not. If
 * the rightmost hop (the immediate sender) does not match the roster, the
@@ -251,7 +226,7 @@ function matchesTrustedEntry(address, entry) {
 * socket peer).
 *
 * @param header - The raw `X-Forwarded-For` header value (comma-separated hops), if present
-* @param trust - Either a trusted hop COUNT or a `trusted` CIDR/exact roster
+* @param trust - The {@link ForwardedOptions} form in force — a trusted hop count or a `trusted` CIDR/exact roster
 * @returns The first untrusted hop address, or `undefined` when none qualifies
 *
 * @example
@@ -277,9 +252,8 @@ function resolveForwardedFor(header, trust) {
 	}
 }
 /**
-* Feature-detect which of `candidates` the runtime's `CompressionStream`
-* actually supports — `createCompression`'s construction-time intersection
-* (ruling J).
+* Feature-detects which of `candidates` the runtime's `CompressionStream`
+* actually supports — `createCompression`'s construction-time intersection.
 *
 * @remarks
 * Probes each candidate with `new CompressionStream(candidate)` inside a
@@ -306,7 +280,7 @@ function detectEncodings(candidates) {
 	return supported;
 }
 /**
-* Compress bytes with the host-independent `CompressionStream` primitive.
+* Compresses bytes with the host-independent `CompressionStream` primitive.
 *
 * @param bytes - The uncompressed response bytes
 * @param encoding - The negotiated actionable coding
@@ -326,21 +300,22 @@ async function compressBytes(bytes, encoding) {
 	return new Uint8Array(compressed);
 }
 /**
-* Whether a response is eligible for the compression/ETag buffering pipeline
-* (ruling J) — the shared cheap-skip predicate both batteries apply before
-* ever touching `response.arrayBuffer()`.
+* Checks whether a response must skip the compression and ETag buffering pipeline
+* — the shared cheap-skip predicate both batteries apply before ever touching
+* `response.arrayBuffer()`, true for a `HEAD` request, a `204`/`304` or
+* otherwise bodyless response, an `event-stream` response, and a response
+* already carrying the header the caller is about to set.
 *
 * @remarks
-* Skips a `HEAD` request, a `204`/`304` or otherwise bodyless response, an
-* `event-stream` response (SSE — buffering would hang the connection), and a
-* response that already carries the header the caller is about to set
-* (`skipHeader`, e.g. `Content-Encoding` for compression, `ETag` for the
-* ETag battery).
+* Buffering an `event-stream` response would hang the connection, so SSE skips
+* whatever its size. `skipHeader` is the header whose presence already answers
+* the question — `Content-Encoding` for compression, `ETag` for the ETag
+* battery.
 *
 * @param method - The request's HTTP method
 * @param response - The candidate response
 * @param skipHeader - The response header whose presence means "already handled"
-* @returns `true` when the response should be left untouched
+* @returns True if the response must be left untouched; false otherwise
 *
 * @example
 * ```ts
@@ -357,11 +332,11 @@ function isBufferingIneligible(method, response, skipHeader) {
 	return false;
 }
 /**
-* Whether a negotiated `Accept-Encoding` outcome is worth acting on —
-* `createCompression`'s negotiation-eligibility half of ruling J's skip list.
+* Checks whether a negotiated `Accept-Encoding` outcome is worth acting on —
+* `createCompression`'s negotiation-eligibility half of the skip list.
 *
 * @param encoding - The negotiated coding, or `undefined` when negotiation failed
-* @returns `true` when `encoding` names an actionable, non-`identity` coding
+* @returns True if `encoding` names an actionable, non-`identity` coding; false otherwise
 *
 * @example
 * ```ts
@@ -373,8 +348,8 @@ function isCompressionNegotiated(encoding) {
 	return encoding !== void 0 && encoding !== "identity";
 }
 /**
-* Resolve an opt-in, value-bearing security header — `string | boolean`
-* (default OFF, `true` uses the secure default), the shape `createSecurity`'s
+* Resolves an opt-in, value-bearing security header — `string | boolean`
+* (off by default, `true` uses the secure default), the shape `createSecurity`'s
 * `coep`/`hsts` options use, distinct from the plain value-or-`false` shape
 * `resolveSecurityHeader` (the peer substrate) handles.
 *
@@ -394,7 +369,7 @@ function resolveOptInHeader(value, fallback) {
 	return value;
 }
 /**
-* Rebuild a `Response` around a replacement body while preserving its
+* Rebuilds a `Response` around a replacement body while preserving its
 * status/statusText — the buffered-response reconstruction shared by the
 * compression and ETag batteries after they have consumed
 * `response.arrayBuffer()`.
@@ -418,7 +393,7 @@ function rebuildResponse(body, response, headers) {
 	});
 }
 /**
-* The shared negotiate → skip → threshold → compress → header-set skeleton
+* Runs the shared negotiate → skip → threshold → compress → header-set skeleton
 * both faces' `createCompression` batteries compose — response-body
 * compression over a caller-supplied set of feature-detected codings.
 *
@@ -428,17 +403,17 @@ function rebuildResponse(body, response, headers) {
 * even when a later skip declines to compress) → `negotiateEncoding` over
 * `options.encodings` → {@link isCompressionNegotiated} → `isCompressibleType`
 * on `Content-Type` → a fast skip when the response already carries a
-* numeric `Content-Length` BELOW `options.threshold` (avoids buffering a
-* body known too small to be worth compressing) → buffer via
+* numeric `Content-Length` below `options.threshold` (avoids buffering a
+* body known too small to be worth compressing) → buffer through
 * `response.arrayBuffer()` → a threshold passthrough when the buffered size
 * is still below `options.threshold` → `options.compress` → set
-* `Content-Encoding` and a fresh `Content-Length` via {@link rebuildResponse}.
+* `Content-Encoding` and a fresh `Content-Length` through {@link rebuildResponse}.
 * Returns `response` unchanged (aside from the `Vary` stamp) on any skip.
 *
 * @param request - The inbound `Request` (read for `Accept-Encoding`)
 * @param context - The `MiddlewareContext` (read for `context.method`)
 * @param response - The downstream `Response` to consider compressing
-* @param options - The threshold, optional filter, offered encodings, and the runtime's `compress` primitive
+* @param options - See {@link CompressResponseOptions}
 * @returns The original `response` when skipped, or a new compressed `Response`
 *
 * @example
@@ -474,99 +449,28 @@ async function compressResponse(request, context, response, options) {
 	return rebuildResponse(compressed, response, headers);
 }
 /**
-* Copy every entry of one session's `data` into another — the regenerate
-* data-carry `createSession`'s `control.regenerate()` applies (ruling D).
-*
-* @param from - The source session whose `data` is copied
-* @param to - The destination session `data` is copied into
-*
-* @example
-* ```ts
-* transferSessionData(oldSession, newSession)
-* ```
-*/
-function transferSessionData(from, to) {
-	for (const [key, value] of from.data) to.data.set(key, value);
-}
-/**
-* Determine whether a value implements {@link SessionInterface} — a total
-* structural guard (§14): an `id` string plus a `data` `Map`. Prototype-agnostic
-* — accepts a plain object, a null-prototype object, AND a class instance
-* (a real `Session`), since a restored/stored session is routinely a class
-* instance, not a literal.
-*
-* @param value - The candidate value
-* @returns `true` when `value` is shaped like a {@link SessionInterface}
-*
-* @example
-* ```ts
-* isSession({ id: 'a', data: new Map() }) // true
-* isSession(new Session('a')) // true
-* ```
-*/
-function isSession(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const id = Reflect.get(value, "id");
-	const data = Reflect.get(value, "data");
-	return (0, _orkestrel_contract.isString)(id) && data instanceof Map;
-}
-/**
-* Determine whether a value implements {@link SessionControlInterface} — a
-* total structural guard (§14): callable `regenerate` and `destroy`.
-*
-* @param value - The candidate value
-* @returns `true` when `value` is shaped like a {@link SessionControlInterface}
-*
-* @example
-* ```ts
-* isSessionControl({ regenerate() {}, destroy() {} }) // true
-* ```
-*/
-function isSessionControl(value) {
-	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
-	return typeof value.regenerate === "function" && typeof value.destroy === "function";
-}
-/**
-* Determine whether a value is one staged {@link MultipartFile} record — a
-* total structural guard (§14) checking every required field's shape.
-*
-* @param value - The candidate value
-* @returns `true` when `value` is shaped like a {@link MultipartFile}
-*/
-function isMultipartFile(value) {
-	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
-	return (0, _orkestrel_contract.isString)(value.field) && (0, _orkestrel_contract.isString)(value.name) && typeof value.size === "number" && (0, _orkestrel_contract.isString)(value.mime) && typeof value.validated === "boolean" && (0, _orkestrel_contract.isString)(value.status) && (0, _orkestrel_contract.isString)(value.path);
-}
-/**
-* Determine whether a value implements {@link MultipartBody} — a total
-* structural guard (§14): `files` keyed by field name to arrays of
-* {@link MultipartFile}, and a `fields` string record.
+* Copies every entry of one session's `state` into another — the regenerate
+* state-carry `createSession`'s `control.regenerate()` applies.
 *
-* @param value - The candidate value
-* @returns `true` when `value` is shaped like a {@link MultipartBody}
+* @param from - The source session whose `state` is copied
+* @param to - The destination session the entries are written into, through
+* its own `set` mutator
 *
 * @example
 * ```ts
-* isMultipartBody({ files: {}, fields: { name: 'a' } }) // true
+* transferSessionState(oldSession, newSession)
 * ```
 */
-function isMultipartBody(value) {
-	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
-	if (!(0, _orkestrel_contract.isRecord)(value.files) || !(0, _orkestrel_contract.isRecord)(value.fields)) return false;
-	for (const entries of Object.values(value.files)) {
-		if (!Array.isArray(entries)) return false;
-		for (const entry of entries) if (!isMultipartFile(entry)) return false;
-	}
-	for (const fieldValue of Object.values(value.fields)) if (!(0, _orkestrel_contract.isString)(fieldValue)) return false;
-	return true;
+function transferSessionState(from, to) {
+	for (const [key, value] of from.state) to.set(key, value);
 }
 /**
-* Determine whether a request is a CORS PREFLIGHT — an `OPTIONS` request
+* Determines whether a request is a CORS preflight — an `OPTIONS` request
 * carrying an `Access-Control-Request-Method` header.
 *
 * @param method - The request's HTTP method
 * @param headers - The request's `Headers`
-* @returns `true` when the request is a CORS preflight `createCors` must answer
+* @returns True if the request is a CORS preflight `createCors` must answer; false otherwise
 *
 * @example
 * ```ts
@@ -577,22 +481,22 @@ function isPreflight(method, headers) {
 	return method === "OPTIONS" && headers.has("access-control-request-method");
 }
 /**
-* A parsed client-info fact for {@link ClientInfo} — a leaf shaping helper
-* `createForwarded` uses to build its stashed slice.
+* Builds the {@link Client} slice `createForwarded` stashes, from the
+* resolved client IP — a leaf shaping helper.
 *
 * @param ip - The resolved client IP, if any
-* @returns The {@link ClientInfo} slice value
+* @returns The {@link Client} slice value
 *
 * @example
 * ```ts
-* buildClientInfo('203.0.113.7') // { ip: '203.0.113.7' }
+* buildClient('203.0.113.7') // { ip: '203.0.113.7' }
 * ```
 */
-function buildClientInfo(ip) {
+function buildClient(ip) {
 	return { ...ip !== void 0 ? { ip } : {} };
 }
 /**
-* Constant-time string equality — `createCSRF`'s double-submit token
+* Compares two strings in constant time — `createCSRF`'s double-submit token
 * comparison, avoiding a timing oracle on the submitted-vs-cookie match.
 *
 * @remarks
@@ -604,7 +508,7 @@ function buildClientInfo(ip) {
 *
 * @param a - The first string
 * @param b - The second string
-* @returns `true` when `a` and `b` are exactly equal
+* @returns True if `a` and `b` are exactly equal; false otherwise
 *
 * @example
 * ```ts
@@ -619,81 +523,173 @@ function equalsConstantTime(a, b) {
 	return diff === 0;
 }
 /**
-* Whether a session has aged past its idle timeout or absolute lifetime as
+* Checks whether a session has aged past its idle timeout or absolute lifetime as
 * of `now` — the pure expiry predicate `MemorySessionStore` delegates to.
 *
-* @param cursors - The session's `lastSeen` (idle) and `createdAt` (absolute) instants
+* @param cursors - See {@link SessionCursors}
 * @param now - The current instant (same clock unit as `cursors`)
-* @param limits - The optional `ttl` (idle) and `lifetime` (absolute) thresholds
-* @returns `true` when either configured threshold has elapsed
+* @param limits - See {@link SessionLimits}
+* @returns True if either configured threshold has elapsed; false otherwise
 *
 * @example
 * ```ts
-* sessionExpired({ lastSeen: 0, createdAt: 0 }, 1_000, { ttl: 500 }) // true
+* sessionExpired({ seen: 0, created: 0 }, 1_000, { ttl: 500 }) // true
 * ```
 */
 function sessionExpired(cursors, now, limits) {
-	if (limits.ttl !== void 0 && now - cursors.lastSeen >= limits.ttl) return true;
-	if (limits.lifetime !== void 0 && now - cursors.createdAt >= limits.lifetime) return true;
+	if (limits.ttl !== void 0 && now - cursors.seen >= limits.ttl) return true;
+	if (limits.lifetime !== void 0 && now - cursors.created >= limits.lifetime) return true;
 	return false;
 }
 /**
-* Snapshot a session's `data` Map into a plain, serializable record — the
+* Validates a store's idle and absolute-lifetime thresholds, throwing when
+* either is present and malformed — the shared construction gate
+* {@link MemorySessionStore} and {@link DatabaseSessionStore} both apply, so
+* one malformed `ttl` is refused identically by whichever store receives it.
+*
+* @param limits - See {@link SessionLimits}
+* @returns Nothing; a successful return means both thresholds are usable
+* @throws {TypeError} Thrown when `ttl` or `lifetime` is present and is not a
+* positive finite number
+*
+* @example
+* ```ts
+* validateSessionLimits({ ttl: 60_000 }) // returns; the thresholds are usable
+* ```
+*/
+function validateSessionLimits(limits) {
+	if (limits?.ttl !== void 0 && (!(0, _orkestrel_contract.isFiniteNumber)(limits.ttl) || limits.ttl <= 0)) throw new TypeError("SessionLimits.ttl must be a positive finite number when provided");
+	if (limits?.lifetime !== void 0 && (!(0, _orkestrel_contract.isFiniteNumber)(limits.lifetime) || limits.lifetime <= 0)) throw new TypeError("SessionLimits.lifetime must be a positive finite number when provided");
+}
+/**
+* Snapshots a session's `state` into a plain, serializable record — the
 * projection a durable store's `set` writes to disk.
 *
 * @param session - The session to snapshot
-* @returns A plain-object copy of `session.data`, keyed alongside `session.id`
+* @returns A {@link SessionSnapshot} whose `state` is a plain-object copy of
+* `session.state`, keyed alongside `session.id`
 *
 * @remarks
-* `data` is built on a null-prototype object (`Object.create(null)`), never
+* `state` is built on a null-prototype object (`Object.create(null)`), never
 * a `{}` literal — a session key literally named `__proto__` must round-trip
-* as an OWN enumerable property instead of hitting `Object.prototype`'s
+* as an own enumerable property instead of hitting `Object.prototype`'s
 * `__proto__` accessor (which would silently drop the entry and risk
 * polluting the shared prototype).
 *
 * @example
 * ```ts
-* snapshotSession(session) // { id: 'abc', data: { userId: 'u_1' } }
+* snapshotSession(session) // { id: 'abc', state: { userId: 'u_1' } }
 * ```
 */
 function snapshotSession(session) {
-	const data = Object.create(null);
-	for (const [key, value] of session.data) data[key] = value;
+	const state = Object.create(null);
+	for (const [key, value] of session.state) state[key] = value;
 	return {
 		id: session.id,
-		data
+		state
 	};
 }
+//#endregion
+//#region src/core/validators.ts
 /**
-* Rebuild a `Session` from an untrusted snapshot value (the inverse of
-* {@link snapshotSession}) — a durable store's `get` deserialization step.
+* Determines whether a value implements {@link SessionInterface} — a total
+* structural guard: an `id` string, a `state` `Map`, and the `set`, `delete`,
+* and `clear` mutators. Prototype-agnostic — accepts a plain object, a
+* null-prototype object, and a class instance (a real `Session`), because a
+* restored or stored session is routinely a class instance rather than a literal.
 *
-* @param value - The candidate snapshot, of unknown shape
-* @returns A rebuilt `Session`, or `undefined` when `value` is malformed
+* @param value - The candidate value
+* @returns True if `value` is shaped like a {@link SessionInterface}; false otherwise
 *
 * @example
 * ```ts
-* restoreSession({ id: 'abc', data: { userId: 'u_1' } }) // Session { id: 'abc', data: Map }
-* restoreSession({ id: 1 }) // undefined
+* isSession(new Session('a')) // true
+* isSession({ id: 'a', state: new Map() }) // false — the mutators are missing
 * ```
 */
-function restoreSession(value) {
-	if (!(0, _orkestrel_contract.isRecord)(value)) return void 0;
-	if (!(0, _orkestrel_contract.isString)(value.id) || !(0, _orkestrel_contract.isRecord)(value.data)) return void 0;
-	const session = new Session(value.id);
-	for (const [key, entry] of Object.entries(value.data)) session.data.set(key, entry);
-	return session;
+function isSession(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const id = Reflect.get(value, "id");
+	const state = Reflect.get(value, "state");
+	if (!(0, _orkestrel_contract.isString)(id) || !(state instanceof Map)) return false;
+	const set = Reflect.get(value, "set");
+	const remove = Reflect.get(value, "delete");
+	const clear = Reflect.get(value, "clear");
+	return typeof set === "function" && typeof remove === "function" && typeof clear === "function";
+}
+/**
+* Determines whether a value implements {@link SessionControlInterface} — a
+* total structural guard: callable `regenerate` and `destroy`.
+*
+* @param value - The candidate value
+* @returns True if `value` is shaped like a {@link SessionControlInterface}; false otherwise
+*
+* @example
+* ```ts
+* isSessionControl({ regenerate() {}, destroy() {} }) // true
+* ```
+*/
+function isSessionControl(value) {
+	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+	return typeof value.regenerate === "function" && typeof value.destroy === "function";
+}
+/**
+* Determines whether a value is one staged {@link MultipartFile} record — a
+* total structural guard checking every required field's shape.
+*
+* @param value - The candidate value
+* @returns True if `value` is shaped like a {@link MultipartFile}; false otherwise
+*
+* @example
+* ```ts
+* isMultipartFile({
+* 	field: 'avatar',
+* 	name: 'a.png',
+* 	size: 3,
+* 	mime: 'image/png',
+* 	validated: true,
+* 	status: 'staged',
+* 	path: '/tmp/a',
+* }) // true
+* ```
+*/
+function isMultipartFile(value) {
+	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+	return (0, _orkestrel_contract.isString)(value.field) && (0, _orkestrel_contract.isString)(value.name) && typeof value.size === "number" && (0, _orkestrel_contract.isString)(value.mime) && typeof value.validated === "boolean" && (0, _orkestrel_contract.isString)(value.status) && (0, _orkestrel_contract.isString)(value.path);
+}
+/**
+* Determines whether a value implements {@link MultipartBody} — a total
+* structural guard: `files` keyed by field name to arrays of
+* {@link MultipartFile}, and a `fields` string record.
+*
+* @param value - The candidate value
+* @returns True if `value` is shaped like a {@link MultipartBody}; false otherwise
+*
+* @example
+* ```ts
+* isMultipartBody({ files: {}, fields: { name: 'a' } }) // true
+* ```
+*/
+function isMultipartBody(value) {
+	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+	if (!(0, _orkestrel_contract.isRecord)(value.files) || !(0, _orkestrel_contract.isRecord)(value.fields)) return false;
+	for (const entries of Object.values(value.files)) {
+		if (!Array.isArray(entries)) return false;
+		for (const entry of entries) if (!isMultipartFile(entry)) return false;
+	}
+	for (const fieldValue of Object.values(value.fields)) if (!(0, _orkestrel_contract.isString)(fieldValue)) return false;
+	return true;
 }
 //#endregion
 //#region src/core/shapers.ts
 /**
-* The `@orkestrel/database` column shape for a
-* {@link import('./types.js').SessionRow} table — pass as-is to
+* Holds the `@orkestrel/database` column shape for a
+* {@link import('./types.js').SessionRow} table. Pass it as-is to
 * `createDatabase({ tables: { sessions: sessionColumns } })` so an app
 * declaring a durable session table never hand-writes the shape.
 *
 * @remarks
-* `lastSeen`/`createdAt` are `integerShape({ min: 0 })` — the table validates
+* `seen`/`created` are `integerShape({ min: 0 })` — the table validates
 * them as integers, so
 * {@link import('./stores/DatabaseSessionStore.js').DatabaseSessionStore}'s
 * `now` clock must yield integer milliseconds (`Date.now()`, the implicit
@@ -709,24 +705,67 @@ function restoreSession(value) {
 var sessionColumns = {
 	id: (0, _orkestrel_contract.stringShape)(),
 	session: (0, _orkestrel_contract.jsonShape)(),
-	lastSeen: (0, _orkestrel_contract.integerShape)({ min: 0 }),
-	createdAt: (0, _orkestrel_contract.integerShape)({ min: 0 })
+	seen: (0, _orkestrel_contract.integerShape)({ min: 0 }),
+	created: (0, _orkestrel_contract.integerShape)({ min: 0 })
+};
+//#endregion
+//#region src/core/Session.ts
+/**
+* Represents a server-managed session's default entity — the `create` option's default
+* value for `createSession`. It ships without a bare `create*` factory of its
+* own, because the name `createSession` belongs to the battery;
+* `createRestoredSession` rebuilds one from a stored snapshot.
+*
+* @remarks
+* `state` is a `ReadonlyMap` view over the entity's own `Map`: TypeScript
+* refuses a write through it, and `set`, `delete`, and `clear` are the write
+* path. `createSession` persists the state to the configured store on the way
+* out.
+*
+* @example
+* ```ts
+* const session = new Session('abc123')
+* session.set('userId', 'u_1')
+* ```
+*/
+var Session = class {
+	#id;
+	#state;
+	constructor(id) {
+		this.#id = id;
+		this.#state = /* @__PURE__ */ new Map();
+	}
+	get id() {
+		return this.#id;
+	}
+	get state() {
+		return this.#state;
+	}
+	set(key, value) {
+		this.#state.set(key, value);
+	}
+	delete(key) {
+		return this.#state.delete(key);
+	}
+	clear() {
+		this.#state.clear();
+	}
 };
 //#endregion
 //#region src/core/stores/MemorySessionStore.ts
 /**
-* The default in-process {@link SessionStoreInterface} — a `Map`-backed store
+* Implements the default in-process {@link SessionStoreInterface} — a `Map`-backed store
 * enforcing both an idle timeout and an absolute lifetime, with lazy
 * (read-time) eviction, a bounded capacity, and no background timers.
 *
-* @typeParam S - The session data payload type
+* @typeParam S - The stored session entity type
 *
 * @remarks
-* `get` evicts a session whose idle time (`now - lastSeen >= ttl`) or
-* absolute lifetime (`now - createdAt >= lifetime`) has elapsed — the
-* lifetime check fires EVEN IF the session was continuously touched, since
-* `createdAt` is stamped once at the first `set` and preserved across every
-* later re-`set` of the same id. A live read touches `lastSeen`. `delete` of
+* `get` evicts a session whose idle time (`now - seen >= ttl`) or
+* absolute lifetime (`now - created >= lifetime`) has elapsed — the
+* lifetime check fires even if the session was continuously touched, because
+* `created` is stamped once at the first `set` and preserved across every
+* later re-`set` of the same id. A live read touches `seen`. `delete` of
 * an absent id is a no-op.
 *
 * Capacity is enforced as least-recently-used **by last write**: `set`
@@ -741,7 +780,7 @@ var sessionColumns = {
 * @example
 * ```ts
 * const store = new MemorySessionStore({ ttl: 60_000, lifetime: 3_600_000 })
-* await store.set('abc', { userId: 'u_1' }, Date.now())
+* await store.set(new Session('abc'), Date.now())
 * ```
 */
 var MemorySessionStore = class {
@@ -751,10 +790,7 @@ var MemorySessionStore = class {
 	#capacity;
 	#evict;
 	constructor(options) {
-		if (options?.ttl !== void 0 && !(0, _orkestrel_contract.isFiniteNumber)(options.ttl)) throw new TypeError("MemorySessionStore requires options.ttl to be a finite number when provided");
-		if (options?.ttl !== void 0 && options.ttl <= 0) throw new TypeError("MemorySessionStore requires options.ttl to be positive when provided");
-		if (options?.lifetime !== void 0 && !(0, _orkestrel_contract.isFiniteNumber)(options.lifetime)) throw new TypeError("MemorySessionStore requires options.lifetime to be a finite number when provided");
-		if (options?.lifetime !== void 0 && options.lifetime <= 0) throw new TypeError("MemorySessionStore requires options.lifetime to be positive when provided");
+		validateSessionLimits(options);
 		if (options?.capacity !== void 0 && (!(0, _orkestrel_contract.isFiniteNumber)(options.capacity) || !Number.isInteger(options.capacity) || options.capacity <= 0)) throw new TypeError("MemorySessionStore requires options.capacity to be a positive integer when provided");
 		if (options?.evict !== void 0 && !(0, _orkestrel_contract.isFunction)(options.evict)) throw new TypeError("MemorySessionStore requires options.evict to be a function when provided");
 		this.#entries = /* @__PURE__ */ new Map();
@@ -771,18 +807,23 @@ var MemorySessionStore = class {
 			this.#notify(id);
 			return;
 		}
-		entry.lastSeen = now;
+		this.#entries.set(id, {
+			session: entry.session,
+			seen: now,
+			created: entry.created
+		});
 		return entry.session;
 	}
-	async set(id, session, now) {
+	async set(session, now) {
+		const id = session.id;
 		const existing = this.#entries.get(id);
 		if (existing === void 0) this.#reserve(now);
-		const createdAt = existing?.createdAt ?? now;
+		const created = existing?.created ?? now;
 		this.#entries.delete(id);
 		this.#entries.set(id, {
 			session,
-			lastSeen: now,
-			createdAt
+			seen: now,
+			created
 		});
 	}
 	async delete(id) {
@@ -790,8 +831,8 @@ var MemorySessionStore = class {
 	}
 	#expired(entry, now) {
 		return sessionExpired(entry, now, {
-			...this.#ttl !== void 0 ? { ttl: this.#ttl } : {},
-			...this.#lifetime !== void 0 ? { lifetime: this.#lifetime } : {}
+			ttl: this.#ttl,
+			lifetime: this.#lifetime
 		});
 	}
 	#reserve(now) {
@@ -818,26 +859,28 @@ var MemorySessionStore = class {
 //#endregion
 //#region src/core/stores/DatabaseSessionStore.ts
 /**
-* A durable {@link SessionStoreInterface} over an `@orkestrel/database`
+* Implements a durable {@link SessionStoreInterface} over an `@orkestrel/database`
 * table — the same idle-timeout + absolute-lifetime contract as
 * {@link MemorySessionStore}, backed by a caller-supplied `TableInterface`
 * instead of an in-process `Map`.
 *
-* @typeParam S - The session data payload type
+* @typeParam S - The stored session entity type
 *
 * @remarks
 * `get` reads the row, evicts (removes the row) once `sessionExpired`
-* reports either threshold elapsed, then rebuilds the session via
-* {@link restoreSession} — a malformed snapshot or one that fails the
-* caller's `is` guard resolves `undefined` rather than throwing. A live read
-* touches `lastSeen`. `set` preserves an existing row's `createdAt` across a
+* reports either threshold elapsed, then rebuilds the session through the
+* `restore` step it was constructed with — a malformed snapshot or one that
+* fails the caller's guard resolves `undefined` rather than throwing.
+* `createDatabaseSessionStore` supplies `createRestoredSession` as that step,
+* so a caller reaching the factory never states it. A live read
+* touches `seen`. `set` preserves an existing row's `created` across a
 * re-`set` of the same id (stamped once at the first `set`), mirroring
 * {@link MemorySessionStore}. `delete` of an absent id is a no-op (the
 * table's `remove` contract).
 *
-* A malformed-snapshot or failed-guard `undefined` LEAVES the row in place —
+* A malformed-snapshot or failed-guard `undefined` leaves the row in place —
 * unlike the expired path, which removes it. This is deliberate: a
-* caller-contextual `is` guard may reject a session that is still perfectly
+* caller-contextual guard may reject a session that is still perfectly
 * valid for another flow reading the same table (a differently-shaped `S`,
 * a stricter guard mid-rollout), so `get` never destroys data on a guard
 * miss. A row that no caller's guard ever accepts again self-heals once its
@@ -845,18 +888,23 @@ var MemorySessionStore = class {
 *
 * @example
 * ```ts
-* const store = new DatabaseSessionStore(table, isSession, { ttl: 60_000 })
-* await store.set('abc', new Session('abc'), Date.now())
+* const store = new DatabaseSessionStore(table, isSession, createRestoredSession, {
+* 	ttl: 60_000,
+* })
+* await store.set(new Session('abc'), Date.now())
 * ```
 */
 var DatabaseSessionStore = class {
 	#table;
-	#is;
+	#guard;
+	#restore;
 	#ttl;
 	#lifetime;
-	constructor(table, is, options) {
+	constructor(table, guard, restore, options) {
+		validateSessionLimits(options);
 		this.#table = table;
-		this.#is = is;
+		this.#guard = guard;
+		this.#restore = restore;
 		this.#ttl = options?.ttl;
 		this.#lifetime = options?.lifetime;
 	}
@@ -864,24 +912,25 @@ var DatabaseSessionStore = class {
 		const row = await this.#table.get(id);
 		if (row === void 0) return void 0;
 		if (sessionExpired(row, now, {
-			...this.#ttl !== void 0 ? { ttl: this.#ttl } : {},
-			...this.#lifetime !== void 0 ? { lifetime: this.#lifetime } : {}
+			ttl: this.#ttl,
+			lifetime: this.#lifetime
 		})) {
 			await this.#table.remove(id);
 			return;
 		}
-		const session = restoreSession(row.session);
-		if (session === void 0 || !this.#is(session)) return void 0;
-		await this.#table.update(id, { lastSeen: now });
+		const session = this.#restore(row.session);
+		if (session === void 0 || !this.#guard(session)) return void 0;
+		await this.#table.update(id, { seen: now });
 		return session;
 	}
-	async set(id, session, now) {
-		const createdAt = (await this.#table.get(id))?.createdAt ?? now;
+	async set(session, now) {
+		const id = session.id;
+		const created = (await this.#table.get(id))?.created ?? now;
 		await this.#table.set({
 			id,
 			session: snapshotSession(session),
-			lastSeen: now,
-			createdAt
+			seen: now,
+			created
 		});
 	}
 	async delete(id) {
@@ -891,7 +940,7 @@ var DatabaseSessionStore = class {
 //#endregion
 //#region src/core/middlewares.ts
 /**
-* The outermost error-rendering battery — catches a downstream throw and
+* Creates the outermost error-rendering battery — catches a downstream throw and
 * renders it as a `Response`.
 *
 * @typeParam TState - The consumer's opaque per-request state type
@@ -899,9 +948,20 @@ var DatabaseSessionStore = class {
 * @returns A `MiddlewareHandler<TState>`
 * @throws {TypeError} When `options.expose` or `options.report` is malformed
 *
-* @example
+* @example Mount a battery
 * ```ts
+* import { createBoundary, createSecurity } from '@orkestrel/middleware'
+* import type { IdentifierState } from '@orkestrel/middleware'
+* import { compose } from '@orkestrel/server'
+*
+* interface State extends IdentifierState {}
+*
 * const boundary = createBoundary({ expose: false })
+* const security = createSecurity({ hsts: true })
+*
+* const handle = compose<State>([boundary, security], async (_request, context) => {
+* 	return Response.json({ identifier: context.state.identifier })
+* })
 * ```
 */
 function createBoundary(options) {
@@ -923,7 +983,7 @@ function createBoundary(options) {
 	};
 }
 /**
-* The access-log/timing seam — records one {@link TelemetryEntry} per request
+* Creates the access-log/timing seam — records one {@link TelemetryEntry} per request
 * after the response settles.
 *
 * @typeParam TState - The consumer's opaque per-request state type
@@ -960,7 +1020,7 @@ function createTelemetry(options) {
 	};
 }
 /**
-* Response-body compression — negotiates and compresses a buffered response
+* Creates the response-body compression battery — negotiates and compresses a buffered response
 * body over the runtime's feature-detected `CompressionStream` codings.
 *
 * @typeParam TState - The consumer's opaque per-request state type
@@ -990,7 +1050,8 @@ function createCompression(options) {
 	};
 }
 /**
-* Security-headers + request-identifier battery.
+* Creates the security-headers + request-identifier battery — sets each documented
+* header default, and mints or echoes a request identifier.
 *
 * @typeParam TState - The consumer's opaque per-request state type, must carry {@link IdentifierState}
 * @param options - See {@link SecurityOptions}
@@ -1052,7 +1113,8 @@ function createSecurity(options) {
 	};
 }
 /**
-* Cross-Origin Resource Sharing battery.
+* Creates the Cross-Origin Resource Sharing battery — answers a preflight itself, and
+* reflects an allow-listed origin or serves the configured wildcard.
 *
 * @typeParam TState - The consumer's opaque per-request state type
 * @param options - See {@link CorsOptions}
@@ -1093,7 +1155,7 @@ function createCors(options) {
 	};
 }
 /**
-* The application-level per-request deadline battery.
+* Creates the application-level per-request deadline battery.
 *
 * @typeParam TState - The consumer's opaque per-request state type
 * @param options - See {@link DeadlineOptions}
@@ -1101,9 +1163,9 @@ function createCors(options) {
 * @throws {TypeError} When `options.ms` or `options.status` is malformed
 *
 * @remarks
-* MUST sit OUTSIDE `createBody` in the chain — it reconstructs the inbound
+* Mount this battery outside `createBody` in the chain — it reconstructs the inbound
 * `Request` (to link its `signal` to the deadline `signal`), which throws if
-* the body was already consumed upstream (e.g. by `createBody`'s cached read).
+* the body was already consumed upstream (for example by `createBody`'s cached read).
 *
 * @example
 * ```ts
@@ -1138,7 +1200,8 @@ function createDeadline(options) {
 	};
 }
 /**
-* The trusted-proxy client-IP resolver battery.
+* Creates the trusted-proxy client-IP resolver battery — walks `X-Forwarded-For` past
+* the hops its options declare trusted.
 *
 * @typeParam TState - The consumer's opaque per-request state type, must carry {@link ClientState} and {@link ConnectionState}
 * @param options - See {@link ForwardedOptions}
@@ -1164,12 +1227,12 @@ function createForwarded(options) {
 	const trust = hasProxies ? { proxies: options.proxies } : { trusted: options.trusted };
 	return async (request, context, next) => {
 		const ip = resolveForwardedFor(request.headers.get("x-forwarded-for") ?? void 0, trust) ?? context.state.connection?.ip;
-		Object.assign(context.state, { client: buildClientInfo(ip) });
+		Object.assign(context.state, { client: buildClient(ip) });
 		return next();
 	};
 }
 /**
-* Dynamic response `ETag` + conditional GET battery.
+* Creates the dynamic response `ETag` + conditional GET battery (RFC 7232).
 *
 * @typeParam TState - The consumer's opaque per-request state type
 * @param options - See {@link ETagOptions}
@@ -1207,7 +1270,8 @@ function createETag(options) {
 	};
 }
 /**
-* Bearer-token authentication battery.
+* Creates the bearer-token authentication battery — reads the token from its header and
+* verifies it with `verifyToken`.
 *
 * @typeParam TState - The consumer's opaque per-request state type, must carry {@link BearerState}
 * @param options - See {@link BearerOptions}
@@ -1243,7 +1307,8 @@ function createBearer(options) {
 	};
 }
 /**
-* Fixed-window rate-limiting battery.
+* Creates the fixed-window rate-limiting battery — checks a key's budget before
+* consuming it, so one window admits exactly `max` requests.
 *
 * @typeParam TState - The consumer's opaque per-request state type, must carry {@link BearerState}, {@link ClientState}, and {@link ConnectionState}
 * @param options - See {@link LimiterOptions}
@@ -1290,7 +1355,7 @@ function createLimiter(options) {
 			bucket = {
 				budget: (0, _orkestrel_budget.createBudget)({
 					max,
-					consume: Number
+					consumer: Number
 				}),
 				resetAt: now + window
 			};
@@ -1320,7 +1385,7 @@ function createLimiter(options) {
 	};
 }
 /**
-* The body-driving battery — eagerly awaits the cached `context.body()` so
+* Creates the body-driving battery — eagerly awaits the cached `context.body()` so
 * its throws (or a malformed-JSON `undefined`) surface before the handler
 * runs, and stashes the resolved value onto {@link BodyState.body}.
 *
@@ -1331,9 +1396,8 @@ function createLimiter(options) {
 * @remarks
 * The shipped `MiddlewareContext.body()` is a parameterless, server-owned
 * cache (`ServerOptions.limit` governs its size cap) — this battery carries
-* no `limit`/`decompression` options (a deliberate break from the deleted old
-* `createBodyParser` surface, which configured them itself). `state.body` is
-* stashed from the SAME awaited call the 400 check reads — `context.body()`
+* no `limit`/`decompression` options. `state.body` is
+* stashed from the same awaited call the 400 check reads — `context.body()`
 * is never invoked twice.
 *
 * @example
@@ -1351,7 +1415,7 @@ function createBody() {
 	};
 }
 /**
-* The generic session battery — resolves, mints, and persists a session
+* Creates the generic session battery — resolves, mints, and persists a session
 * across the request, with a mid-handler `regenerate`/`destroy` control handle.
 *
 * @typeParam S - The session entity type the store persists (must implement {@link SessionInterface})
@@ -1359,7 +1423,7 @@ function createBody() {
 * @param options - See {@link SessionOptions}
 * @returns A `MiddlewareHandler<TState>`
 * @throws {TypeError} When any option is malformed
-* @throws {HTTPError} `404` when `require` is set and no session resolves or mints
+* @throws {HTTPError} `404` when `required` is set and no session resolves or mints
 *
 * @example
 * ```ts
@@ -1367,14 +1431,13 @@ function createBody() {
 * ```
 */
 function createSession(options) {
-	if (!(0, _orkestrel_contract.isFunction)(options.transport.read) || !(0, _orkestrel_contract.isFunction)(options.transport.write) || !(0, _orkestrel_contract.isFunction)(options.transport.clear)) throw new TypeError("SessionOptions.transport must implement SessionTransport");
+	if (!(0, _orkestrel_contract.isFunction)(options.transport.read) || !(0, _orkestrel_contract.isFunction)(options.transport.write) || !(0, _orkestrel_contract.isFunction)(options.transport.clear)) throw new TypeError("SessionOptions.transport must implement SessionTransportInterface");
 	if (options.store !== void 0 && (!(0, _orkestrel_contract.isFunction)(options.store.get) || !(0, _orkestrel_contract.isFunction)(options.store.set) || !(0, _orkestrel_contract.isFunction)(options.store.delete))) throw new TypeError("SessionOptions.store must implement SessionStoreInterface when provided");
 	if (options.ttl !== void 0 && !(0, _orkestrel_contract.isFiniteNumber)(options.ttl)) throw new TypeError("SessionOptions.ttl must be a finite number when provided");
 	if (options.lifetime !== void 0 && !(0, _orkestrel_contract.isFiniteNumber)(options.lifetime)) throw new TypeError("SessionOptions.lifetime must be a finite number when provided");
 	if (options.create !== void 0 && !(0, _orkestrel_contract.isFunction)(options.create)) throw new TypeError("SessionOptions.create must be a function when provided");
 	if (options.mint !== void 0 && !(0, _orkestrel_contract.isFunction)(options.mint)) throw new TypeError("SessionOptions.mint must be a function when provided");
-	if (options.require !== void 0 && !(0, _orkestrel_contract.isBoolean)(options.require)) throw new TypeError("SessionOptions.require must be a boolean when provided");
-	if (options.ends !== void 0 && !(0, _orkestrel_contract.isBoolean)(options.ends)) throw new TypeError("SessionOptions.ends must be a boolean when provided");
+	if (options.required !== void 0 && !(0, _orkestrel_contract.isBoolean)(options.required)) throw new TypeError("SessionOptions.required must be a boolean when provided");
 	if (options.clock !== void 0 && !(0, _orkestrel_contract.isFunction)(options.clock)) throw new TypeError("SessionOptions.clock must be a function when provided");
 	const transport = options.transport;
 	const clock = options.clock ?? Date.now;
@@ -1386,17 +1449,12 @@ function createSession(options) {
 	});
 	const create = options.create;
 	const mint = options.mint;
-	const requireSession = options.require ?? false;
-	const ends = options.ends ?? false;
+	const requireSession = options.required ?? false;
 	return async (request, context, next) => {
 		const now = clock();
 		const encrypted = context.state.connection?.encrypted ?? false;
 		const incomingId = await transport.read(request);
 		let session = incomingId !== void 0 ? await store.get(incomingId, now) : void 0;
-		if (ends && context.method === "DELETE" && session !== void 0) {
-			await store.delete(session.id);
-			return new Response(null, { status: 204 });
-		}
 		let minted = false;
 		if (session === void 0) {
 			if (mint !== void 0 ? await mint(context) : true) {
@@ -1414,7 +1472,7 @@ function createSession(options) {
 				regenerate() {
 					if (destroyed) return;
 					const newSession = create === void 0 ? new Session(crypto.randomUUID()) : create(crypto.randomUUID());
-					transferSessionData(activeSession, newSession);
+					transferSessionState(activeSession, newSession);
 					regenerated = newSession;
 				},
 				destroy() {
@@ -1429,11 +1487,11 @@ function createSession(options) {
 				await store.delete(activeSession.id);
 				await transport.clear(response);
 			} else if (regenerated !== void 0) {
-				await store.set(regenerated.id, regenerated, clock());
+				await store.set(regenerated, clock());
 				await store.delete(activeSession.id);
 				await transport.write(response, regenerated.id, encrypted);
 			} else {
-				await store.set(activeSession.id, activeSession, clock());
+				await store.set(activeSession, clock());
 				if (minted) await transport.write(response, activeSession.id, encrypted);
 			}
 		}
@@ -1441,7 +1499,7 @@ function createSession(options) {
 	};
 }
 /**
-* Session-bound double-submit CSRF protection battery.
+* Creates the session-bound double-submit CSRF protection battery.
 *
 * @typeParam TState - The consumer's opaque per-request state type, must carry {@link CSRFState}, {@link SessionState}, and {@link ConnectionState}
 * @param options - See {@link CSRFOptions}
@@ -1498,8 +1556,8 @@ function createCSRF(options) {
 	};
 }
 /**
-* Scope a battery to run ONLY on a set of exact pathnames — elsewhere it
-* steps aside via `next()`.
+* Scopes a battery to a set of exact pathnames and nowhere else — outside that set
+* it steps aside through `next()`.
 *
 * @typeParam TState - The consumer's opaque per-request state type
 * @param paths - One pathname, or a set of pathnames, matched exactly against `context.url.pathname`
@@ -1519,8 +1577,8 @@ function only(paths, handler) {
 	};
 }
 /**
-* Scope a battery to run everywhere EXCEPT a set of exact pathnames — there
-* it steps aside via `next()`.
+* Scopes a battery to every pathname outside a set of exact ones — on that set it
+* steps aside through `next()`.
 *
 * @typeParam TState - The consumer's opaque per-request state type
 * @param paths - One pathname, or a set of pathnames, matched exactly against `context.url.pathname`
@@ -1542,11 +1600,11 @@ function except(paths, handler) {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create a signed-cookie {@link SessionTransport} — the session id travels as
+* Creates a signed-cookie {@link SessionTransportInterface} — the session id travels as
 * a `signToken`-signed cookie value.
 *
 * @param options - See {@link CookieTransportOptions}
-* @returns A {@link SessionTransport}
+* @returns A {@link SessionTransportInterface}
 * @throws {TypeError} When `options.secret` or `options.name` is malformed
 *
 * @example
@@ -1577,11 +1635,11 @@ function createCookieTransport(options) {
 	};
 }
 /**
-* Create a bare-header {@link SessionTransport} — the session id travels
+* Creates a bare-header {@link SessionTransportInterface} — the session id travels
 * verbatim in a request/response header.
 *
 * @param options - See {@link HeaderTransportOptions}
-* @returns A {@link SessionTransport}
+* @returns A {@link SessionTransportInterface}
 * @throws {TypeError} When `options.header` is malformed
 *
 * @example
@@ -1605,18 +1663,17 @@ function createHeaderTransport(options) {
 	};
 }
 /**
-* Create the default in-process {@link SessionStoreInterface} — a `Map`-backed
+* Creates the default in-process {@link SessionStoreInterface} — a `Map`-backed
 * store enforcing an idle timeout and an absolute lifetime.
 *
-* @typeParam S - The session data payload type
+* @typeParam S - The session entity type
 * @param options - See {@link MemorySessionStoreOptions}
 * @returns A {@link SessionStoreInterface}
 * @throws {TypeError} When `options.ttl` or `options.lifetime` is malformed
 *
 * @remarks
-* The {@link Session} entity is the `create` option's default value factory
-* for `createSession` and deliberately ships WITHOUT its own `create*`
-* factory — the name `createSession` belongs to the battery, not this class.
+* The store holds whatever {@link SessionInterface} entity `createSession`'s
+* `create` option produced, keyed by that entity's own `id`.
 *
 * @example
 * ```ts
@@ -1627,28 +1684,51 @@ function createMemorySessionStore(options) {
 	return new MemorySessionStore(options);
 }
 /**
-* Create a {@link DatabaseSessionStore} as a {@link SessionStoreInterface} —
+* Creates a {@link DatabaseSessionStore} as a {@link SessionStoreInterface} —
 * the durable counterpart to `createMemorySessionStore`, over a caller-opened
 * `@orkestrel/database` table (declare it with {@link sessionColumns}).
 *
-* @typeParam S - The session data payload type
+* @typeParam S - The session entity type
 * @param table - The backing `TableInterface<SessionRow>`
-* @param is - A {@link Guard} narrowing a restored snapshot to `S`
-* @param options - The idle `ttl` / absolute `lifetime` thresholds
+* @param guard - A {@link Guard} narrowing a restored snapshot to `S`
+* @param options - See {@link SessionLimits}
 * @returns A {@link SessionStoreInterface}
+* @throws {TypeError} When `options.ttl` or `options.lifetime` is malformed
 *
 * @remarks
 * This factory only wraps `new DatabaseSessionStore(...)` — it never opens a
 * database or driver itself; the caller owns that lifecycle and passes in an
-* already-open table.
+* already-open table. It supplies {@link createRestoredSession} as the store's
+* snapshot rebuild step, which is why the store imports nothing from this
+* file.
 *
 * @example
 * ```ts
 * const store = createDatabaseSessionStore(db.table('sessions'), isSession, { ttl: 60_000 })
 * ```
 */
-function createDatabaseSessionStore(table, is, options) {
-	return new DatabaseSessionStore(table, is, options);
+function createDatabaseSessionStore(table, guard, options) {
+	return new DatabaseSessionStore(table, guard, createRestoredSession, options);
+}
+/**
+* Rebuilds a {@link Session} from an untrusted snapshot value — the inverse of
+* `snapshotSession` and a durable store's `get` deserialization step.
+*
+* @param value - The candidate snapshot, of unknown shape
+* @returns A rebuilt {@link Session}, or `undefined` when `value` is malformed
+*
+* @example
+* ```ts
+* createRestoredSession({ id: 'abc', state: { userId: 'u_1' } }) // Session { id: 'abc' }
+* createRestoredSession({ id: 1 }) // undefined
+* ```
+*/
+function createRestoredSession(value) {
+	if (!(0, _orkestrel_contract.isRecord)(value)) return void 0;
+	if (!(0, _orkestrel_contract.isString)(value.id) || !(0, _orkestrel_contract.isRecord)(value.state)) return void 0;
+	const session = new Session(value.id);
+	for (const [key, entry] of Object.entries(value.state)) session.set(key, entry);
+	return session;
 }
 //#endregion
 exports.DEFAULT_BEARER_HEADER = DEFAULT_BEARER_HEADER;
@@ -1680,7 +1760,7 @@ exports.DEFAULT_SESSION_HEADER = DEFAULT_SESSION_HEADER;
 exports.DatabaseSessionStore = DatabaseSessionStore;
 exports.MemorySessionStore = MemorySessionStore;
 exports.Session = Session;
-exports.buildClientInfo = buildClientInfo;
+exports.buildClient = buildClient;
 exports.buildRateLimitField = buildRateLimitField;
 exports.buildRateLimitPolicyField = buildRateLimitPolicyField;
 exports.buildRetryAfter = buildRetryAfter;
@@ -1700,6 +1780,7 @@ exports.createForwarded = createForwarded;
 exports.createHeaderTransport = createHeaderTransport;
 exports.createLimiter = createLimiter;
 exports.createMemorySessionStore = createMemorySessionStore;
+exports.createRestoredSession = createRestoredSession;
 exports.createSecurity = createSecurity;
 exports.createSession = createSession;
 exports.createTelemetry = createTelemetry;
@@ -1719,10 +1800,10 @@ exports.rebuildResponse = rebuildResponse;
 exports.resolveForwardedFor = resolveForwardedFor;
 exports.resolveKey = resolveKey;
 exports.resolveOptInHeader = resolveOptInHeader;
-exports.restoreSession = restoreSession;
 exports.sessionColumns = sessionColumns;
 exports.sessionExpired = sessionExpired;
 exports.snapshotSession = snapshotSession;
-exports.transferSessionData = transferSessionData;
+exports.transferSessionState = transferSessionState;
+exports.validateSessionLimits = validateSessionLimits;
 
 //# sourceMappingURL=index.cjs.map