@orkestrel/middleware 0.0.18 → 0.0.19

package/dist/src/core/index.d.ts

@@ -1,4 +1,4 @@
-import { ConnectionInfo } from '@orkestrel/server';
+import { Connection } from '@orkestrel/server';
 import { CookieOptions } from '@orkestrel/server';
 import { Encoding } from '@orkestrel/server';
 import { Guard } from '@orkestrel/contract';
@@ -11,9 +11,8 @@ import { TableInterface } from '@orkestrel/database';
 import { TokenSecret } from '@orkestrel/server';
 
 /**
- * Options for `createBearer` — bearer-token authentication.
+ * Configures `createBearer` — bearer-token authentication.
  *
- * @param options - See fields below
  * @remarks
  * - `secret` — the {@link TokenSecret} `verifyToken` checks the extracted
  *   token against (rotation-aware).
@@ -30,7 +29,7 @@ export declare interface BearerOptions {
 }
 
 /**
- * The bearer-authentication state slice `createBearer` stashes on
+ * Describes the bearer-authentication state slice `createBearer` stashes on
  * `context.state` once a token verifies.
  *
  * @remarks
@@ -43,7 +42,7 @@ export declare interface BearerState {
 }
 
 /**
- * The body state slice `createBody` stashes.
+ * Describes the body state slice `createBody` stashes.
  *
  * @remarks
  * `body` holds the same defined value the cached `context.body()` resolved
@@ -55,9 +54,8 @@ export declare interface BodyState {
 }
 
 /**
- * Options for `createBoundary` — the outermost error-rendering battery.
+ * Configures `createBoundary` — the outermost error-rendering battery.
  *
- * @param options - See fields below
  * @remarks
  * - `expose` — when `true`, a non-`HTTPError` throw's `error.message` is
  *   surfaced in the 500 body instead of a generic message. Defaults to
@@ -71,22 +69,22 @@ export declare interface BoundaryOptions {
 }
 
 /**
- * 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' }
  * ```
  */
-export declare function buildClientInfo(ip: string | undefined): ClientInfo;
+export declare function buildClient(ip: string | undefined): Client_2;
 
 /**
- * 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`)
@@ -101,8 +99,8 @@ export declare function buildClientInfo(ip: string | undefined): ClientInfo;
 export declare function buildRateLimitField(remaining: number, resetAt: number, now: number): string;
 
 /**
- * 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
@@ -116,8 +114,8 @@ export declare function buildRateLimitField(remaining: number, resetAt: number,
 export declare function buildRateLimitPolicyField(max: number, window: number): string;
 
 /**
- * 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
@@ -131,26 +129,27 @@ export declare function buildRateLimitPolicyField(max: number, window: number):
 export declare function buildRetryAfter(resetAt: number, now: number): string;
 
 /**
- * The resolved client connection facts `createForwarded` stashes.
+ * Describes the resolved client connection facts `createForwarded` stashes.
  *
  * @remarks
  * `ip` is the first untrusted address walking `X-Forwarded-For` /
  * `Forwarded` right-to-left past the configured trusted hops, falling back
  * to the socket peer when no proxy hop qualifies.
  */
-export declare interface ClientInfo {
+declare interface Client_2 {
     readonly ip?: string;
 }
+export { Client_2 as Client }
 
 /**
- * The client-facts state slice `createForwarded` stashes.
+ * Describes the client-facts state slice `createForwarded` stashes.
  */
 export declare interface ClientState {
-    readonly client?: ClientInfo;
+    readonly client?: Client_2;
 }
 
 /**
- * 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
@@ -166,9 +165,8 @@ export declare interface ClientState {
 export declare function compressBytes(bytes: Uint8Array<ArrayBuffer>, encoding: Exclude<Encoding, 'identity'>): Promise<Uint8Array<ArrayBuffer>>;
 
 /**
- * Options for `createCompression` — response-body compression.
+ * Configures `createCompression` — response-body compression.
  *
- * @param options - See fields below
  * @remarks
  * - `threshold` — the minimum buffered body size (bytes) worth compressing;
  *   defaults to {@link DEFAULT_COMPRESSION_THRESHOLD}.
@@ -186,7 +184,7 @@ export declare interface CompressionOptions {
 }
 
 /**
- * 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.
  *
@@ -197,16 +195,16 @@ export declare interface CompressionOptions {
  * `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
+ * 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
@@ -218,27 +216,42 @@ export declare interface CompressionOptions {
  * })
  * ```
  */
-export declare function compressResponse(request: Request, context: MiddlewareContext<unknown>, response: Response, options: {
+export declare function compressResponse(request: Request, context: MiddlewareContext<unknown>, response: Response, options: CompressResponseOptions): Promise<Response>;
+
+/**
+ * Describes the already-resolved settings `compressResponse` runs its shared
+ * negotiate → skip → threshold → compress skeleton against — the shape each
+ * face's `createCompression` builds from its own option bag.
+ *
+ * @remarks
+ * - `threshold` — the minimum body size (bytes) worth compressing.
+ * - `filter` — the per-response opt-out predicate; absent allows every
+ *   response.
+ * - `encodings` — the codings offered, in preference order, already narrowed
+ *   to what this face can actually produce.
+ * - `compress` — the runtime's compression primitive for one negotiated
+ *   coding.
+ */
+export declare interface CompressResponseOptions {
     readonly threshold: number;
     readonly filter?: (request: Request, response: Response) => boolean;
     readonly encodings: readonly Encoding[];
     readonly compress: (bytes: Uint8Array<ArrayBuffer>, encoding: Exclude<Encoding, 'identity'>) => Promise<Uint8Array<ArrayBuffer>>;
-}): Promise<Response>;
+}
 
 /**
- * The connection-facts state slice `createLimiter`'s default key derivation
+ * Describes the connection-facts state slice `createLimiter`'s default key derivation
  * falls back to when neither {@link BearerState} nor {@link ClientState} is
  * present — the raw socket peer surfaced on `context.state` by the server's
  * `state` option.
  */
 export declare interface ConnectionState {
-    readonly connection?: ConnectionInfo;
+    readonly connection?: Connection;
 }
 
 /**
- * Options for `createCookieTransport` — the signed-cookie {@link SessionTransport}.
+ * Configures `createCookieTransport` — the signed-cookie {@link SessionTransportInterface}.
  *
- * @param options - See fields below
  * @remarks
  * - `name` — the cookie name; defaults to {@link DEFAULT_SESSION_COOKIE}.
  * - `secret` — the {@link TokenSecret} the session id is signed with (`signToken`).
@@ -252,9 +265,8 @@ export declare interface CookieTransportOptions {
 }
 
 /**
- * Options for `createCors` — Cross-Origin Resource Sharing.
+ * Configures `createCors` — Cross-Origin Resource Sharing.
  *
- * @param options - See fields below
  * @remarks
  * - `origin` — the allowed origin(s): `'*'` (default), a single origin
  *   string, or an allow-list `readonly string[]` (reflects the request
@@ -270,7 +282,7 @@ export declare interface CorsOptions {
 }
 
 /**
- * Bearer-token authentication battery.
+ * Creates the bearer-token authentication battery.
  *
  * @typeParam TState - The consumer's opaque per-request state type, must carry {@link BearerState}
  * @param options - See {@link BearerOptions}
@@ -286,7 +298,7 @@ export declare interface CorsOptions {
 export declare function createBearer<TState extends BearerState>(options: BearerOptions): MiddlewareHandler<TState>;
 
 /**
- * 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}.
  *
@@ -297,8 +309,7 @@ export declare function createBearer<TState extends BearerState>(options: Bearer
  * @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
+ * no `limit`/`decompression` options. `state.body` is
  * stashed from the SAME awaited call the 400 check reads — `context.body()`
  * is never invoked twice.
  *
@@ -310,7 +321,7 @@ export declare function createBearer<TState extends BearerState>(options: Bearer
 export declare function createBody<TState extends BodyState = BodyState>(): MiddlewareHandler<TState>;
 
 /**
- * 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
@@ -326,7 +337,7 @@ export declare function createBody<TState extends BodyState = BodyState>(): Midd
 export declare function createBoundary<TState>(options?: BoundaryOptions): MiddlewareHandler<TState>;
 
 /**
- * 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
@@ -342,11 +353,11 @@ export declare function createBoundary<TState>(options?: BoundaryOptions): Middl
 export declare function createCompression<TState>(options?: CompressionOptions): MiddlewareHandler<TState>;
 
 /**
- * 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
@@ -354,10 +365,10 @@ export declare function createCompression<TState>(options?: CompressionOptions):
  * const transport = createCookieTransport({ secret: 'shh' })
  * ```
  */
-export declare function createCookieTransport(options: CookieTransportOptions): SessionTransport;
+export declare function createCookieTransport(options: CookieTransportOptions): SessionTransportInterface;
 
 /**
- * Cross-Origin Resource Sharing battery.
+ * Creates the Cross-Origin Resource Sharing battery.
  *
  * @typeParam TState - The consumer's opaque per-request state type
  * @param options - See {@link CorsOptions}
@@ -372,7 +383,7 @@ export declare function createCookieTransport(options: CookieTransportOptions):
 export declare function createCors<TState>(options?: CorsOptions): MiddlewareHandler<TState>;
 
 /**
- * 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}
@@ -388,33 +399,33 @@ export declare function createCors<TState>(options?: CorsOptions): MiddlewareHan
 export declare function createCSRF<TState extends CSRFState & SessionState & ConnectionState>(options: CSRFOptions): MiddlewareHandler<TState>;
 
 /**
- * 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 })
  * ```
  */
-export declare function createDatabaseSessionStore<S extends SessionInterface = Session>(table: TableInterface<SessionRow>, is: Guard<S>, options?: {
-    readonly ttl?: number;
-    readonly lifetime?: number;
-}): SessionStoreInterface<S>;
+export declare function createDatabaseSessionStore<S extends SessionInterface = Session>(table: TableInterface<SessionRow>, guard: Guard<S>, options?: SessionLimits): SessionStoreInterface<S>;
 
 /**
- * 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}
@@ -424,7 +435,7 @@ export declare function createDatabaseSessionStore<S extends SessionInterface =
  * @remarks
  * MUST sit 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
@@ -434,7 +445,7 @@ export declare function createDatabaseSessionStore<S extends SessionInterface =
 export declare function createDeadline<TState>(options: DeadlineOptions): MiddlewareHandler<TState>;
 
 /**
- * Dynamic response `ETag` + conditional GET battery.
+ * Creates the dynamic response `ETag` + conditional GET battery.
  *
  * @typeParam TState - The consumer's opaque per-request state type
  * @param options - See {@link ETagOptions}
@@ -449,7 +460,7 @@ export declare function createDeadline<TState>(options: DeadlineOptions): Middle
 export declare function createETag<TState>(options?: ETagOptions): MiddlewareHandler<TState>;
 
 /**
- * The trusted-proxy client-IP resolver battery.
+ * Creates the trusted-proxy client-IP resolver battery.
  *
  * @typeParam TState - The consumer's opaque per-request state type, must carry {@link ClientState} and {@link ConnectionState}
  * @param options - See {@link ForwardedOptions}
@@ -464,11 +475,11 @@ export declare function createETag<TState>(options?: ETagOptions): MiddlewareHan
 export declare function createForwarded<TState extends ClientState & ConnectionState>(options: ForwardedOptions): MiddlewareHandler<TState>;
 
 /**
- * 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
@@ -476,10 +487,10 @@ export declare function createForwarded<TState extends ClientState & ConnectionS
  * const transport = createHeaderTransport()
  * ```
  */
-export declare function createHeaderTransport(options?: HeaderTransportOptions): SessionTransport;
+export declare function createHeaderTransport(options?: HeaderTransportOptions): SessionTransportInterface;
 
 /**
- * Fixed-window rate-limiting battery.
+ * Creates the fixed-window rate-limiting battery.
  *
  * @typeParam TState - The consumer's opaque per-request state type, must carry {@link BearerState}, {@link ClientState}, and {@link ConnectionState}
  * @param options - See {@link LimiterOptions}
@@ -494,28 +505,42 @@ export declare function createHeaderTransport(options?: HeaderTransportOptions):
 export declare function createLimiter<TState extends BearerState & ClientState & ConnectionState>(options: LimiterOptions<TState>): MiddlewareHandler<TState>;
 
 /**
- * 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
  * const store = createMemorySessionStore({ ttl: 60_000 })
  * ```
  */
-export declare function createMemorySessionStore<S>(options?: MemorySessionStoreOptions): SessionStoreInterface<S>;
+export declare function createMemorySessionStore<S extends SessionInterface>(options?: MemorySessionStoreOptions): SessionStoreInterface<S>;
 
 /**
- * Security-headers + request-identifier battery.
+ * 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
+ * ```
+ */
+export declare function createRestoredSession(value: unknown): Session | undefined;
+
+/**
+ * Creates the security-headers + request-identifier battery.
  *
  * @typeParam TState - The consumer's opaque per-request state type, must carry {@link IdentifierState}
  * @param options - See {@link SecurityOptions}
@@ -530,7 +555,7 @@ export declare function createMemorySessionStore<S>(options?: MemorySessionStore
 export declare function createSecurity<TState extends IdentifierState>(options?: SecurityOptions): MiddlewareHandler<TState>;
 
 /**
- * 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})
@@ -538,7 +563,7 @@ export declare function createSecurity<TState extends IdentifierState>(options?:
  * @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
@@ -548,7 +573,7 @@ export declare function createSecurity<TState extends IdentifierState>(options?:
 export declare function createSession<S extends SessionInterface = SessionInterface, TState extends SessionState & ConnectionState = SessionState & ConnectionState>(options: SessionOptions<S, TState>): MiddlewareHandler<TState>;
 
 /**
- * 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
@@ -564,9 +589,8 @@ export declare function createSession<S extends SessionInterface = SessionInterf
 export declare function createTelemetry<TState>(options: TelemetryOptions): MiddlewareHandler<TState>;
 
 /**
- * Options for `createCSRF` — session-bound double-submit CSRF protection.
+ * Configures `createCSRF` — session-bound double-submit CSRF protection.
  *
- * @param options - See fields below
  * @remarks
  * - `secret` — the {@link TokenSecret} the CSRF token is signed with.
  * - `cookie` — the signed-cookie name; defaults to {@link DEFAULT_CSRF_COOKIE}.
@@ -587,7 +611,7 @@ export declare interface CSRFOptions {
 }
 
 /**
- * The CSRF state slice `createCSRF` stashes — the raw token a safe-method
+ * Describes the CSRF state slice `createCSRF` stashes — the raw token a safe-method
  * response exposes for a subsequent mutating request to submit back.
  */
 export declare interface CSRFState {
@@ -595,26 +619,28 @@ export declare interface CSRFState {
 }
 
 /**
- * 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 —
  * 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
@@ -622,28 +648,26 @@ export declare interface CSRFState {
  *
  * @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())
  * ```
  */
 export declare class DatabaseSessionStore<S extends SessionInterface = Session> implements SessionStoreInterface<S> {
     #private;
-    constructor(table: TableInterface<SessionRow>, is: Guard<S>, options?: {
-        readonly ttl?: number;
-        readonly lifetime?: number;
-    });
+    constructor(table: TableInterface<SessionRow>, guard: Guard<S>, restore: SessionRestoreFunction, options?: SessionLimits);
     get(id: string, now: number): Promise<S | undefined>;
-    set(id: string, session: S, now: number): Promise<void>;
+    set(session: S, now: number): Promise<void>;
     delete(id: string): Promise<void>;
 }
 
 /**
- * Options for `createDeadline` — the application-level per-request deadline.
+ * Configures `createDeadline` — the application-level per-request deadline.
  *
- * @param options - See fields below
  * @remarks
- * - `ms` — the deadline in milliseconds, armed via `@orkestrel/timeout` and
- *   linked to the request's `signal` via `@orkestrel/abort`'s `linkSignal`.
+ * - `ms` — the deadline in milliseconds, armed through `@orkestrel/timeout` and
+ *   linked to the request's `signal` through `@orkestrel/abort`'s `linkSignal`.
  * - `status` — the response status returned when the deadline fires before
  *   the downstream chain settles; defaults to {@link DEFAULT_DEADLINE_STATUS}.
  */
@@ -652,20 +676,20 @@ export declare interface DeadlineOptions {
     readonly status?: number;
 }
 
-/** Default header `createBearer` reads the token from. */
+/** Names the default header `createBearer` reads the token from. */
 export declare const DEFAULT_BEARER_HEADER = "authorization";
 
-/** Default scheme prefix `createBearer` strips before verification. */
+/** Names the default scheme prefix `createBearer` strips before verification. */
 export declare const DEFAULT_BEARER_SCHEME = "Bearer";
 
-/** Default `Origin-Agent-Cluster` value `createSecurity` sets. */
+/** Holds the default `Origin-Agent-Cluster` value `createSecurity` sets. */
 export declare const DEFAULT_CLUSTER = "?1";
 
-/** Value `createSecurity` sets for `Cross-Origin-Embedder-Policy` when `coep: true`. */
+/** Holds the value `createSecurity` sets for `Cross-Origin-Embedder-Policy` when `coep: true`. */
 export declare const DEFAULT_COEP = "require-corp";
 
 /**
- * Default content-codings `createCompression` offers, in preference order —
+ * Lists the default content-codings `createCompression` offers, in preference order —
  * intersected at construction with what the runtime's `CompressionStream`
  * actually supports.
  *
@@ -678,76 +702,75 @@ export declare const DEFAULT_COEP = "require-corp";
  */
 export declare const DEFAULT_COMPRESSION_ENCODINGS: readonly Encoding[];
 
-/** Default minimum buffered body size (bytes) `createCompression` will compress. */
+/** Holds the default minimum buffered body size (bytes) `createCompression` will compress. */
 export declare const DEFAULT_COMPRESSION_THRESHOLD = 1024;
 
-/** Default `Cross-Origin-Opener-Policy` value `createSecurity` sets. */
+/** Holds the default `Cross-Origin-Opener-Policy` value `createSecurity` sets. */
 export declare const DEFAULT_COOP = "same-origin";
 
-/** Default `Cross-Origin-Resource-Policy` value `createSecurity` sets. */
+/** Holds the default `Cross-Origin-Resource-Policy` value `createSecurity` sets. */
 export declare const DEFAULT_CORP = "same-origin";
 
-/** Default headers `createCors` advertises on a preflight response. */
+/** Lists the default headers `createCors` advertises on a preflight response. */
 export declare const DEFAULT_CORS_HEADERS: readonly string[];
 
-/** Default methods `createCors` advertises on a preflight response. */
+/** Lists the default methods `createCors` advertises on a preflight response. */
 export declare const DEFAULT_CORS_METHODS: readonly string[];
 
 /**
- * Default `Content-Security-Policy` value `createSecurity` sets — a custom
+ * Holds the default `Content-Security-Policy` value `createSecurity` sets — a custom
  * `csp` option REPLACES this wholesale, never merges.
  */
 export declare const DEFAULT_CSP = "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'self'; form-action 'self'";
 
-/** Default signed-cookie name `createCSRF` writes the CSRF token under. */
+/** Names the default signed cookie `createCSRF` writes the CSRF token under. */
 export declare const DEFAULT_CSRF_COOKIE = "csrf";
 
-/** Default body field `createCSRF` falls back to reading a mutating request's submitted token from. */
+/** Names the default body field `createCSRF` falls back to reading a mutating request's submitted token from. */
 export declare const DEFAULT_CSRF_FIELD = "_csrf";
 
-/** Default header `createCSRF` reads a mutating request's submitted token from. */
+/** Names the default header `createCSRF` reads a mutating request's submitted token from. */
 export declare const DEFAULT_CSRF_HEADER = "x-csrf-token";
 
-/** Default methods `createCSRF` treats as safe (mint instead of verify). */
+/** Lists the default methods `createCSRF` treats as safe (mint instead of verify). */
 export declare const DEFAULT_CSRF_SAFE_METHODS: readonly string[];
 
-/** Default response status `createDeadline` returns when its deadline fires first. */
+/** Holds the default response status `createDeadline` returns when its deadline fires first. */
 export declare const DEFAULT_DEADLINE_STATUS = 503;
 
-/** Default `X-Frame-Options` value `createSecurity` sets. */
+/** Holds the default `X-Frame-Options` value `createSecurity` sets. */
 export declare const DEFAULT_FRAME_OPTIONS = "DENY";
 
-/** Value `createSecurity` sets for `Strict-Transport-Security` when `hsts: true`. */
+/** Holds the value `createSecurity` sets for `Strict-Transport-Security` when `hsts: true`. */
 export declare const DEFAULT_HSTS = "max-age=31536000; includeSubDomains";
 
-/** Default header `createSecurity` mints/echoes a request identifier into. */
+/** Names the default header `createSecurity` mints/echoes a request identifier into. */
 export declare const DEFAULT_IDENTIFIER_HEADER = "x-request-id";
 
-/** Default maximum number of distinct rate-limit keys `createLimiter` tracks before LRU eviction. */
+/** Holds the default maximum number of distinct rate-limit keys `createLimiter` tracks before LRU eviction. */
 export declare const DEFAULT_LIMITER_CAPACITY = 10000;
 
-/** Default 429 body message `createLimiter` sends when a key is over budget. */
+/** Holds the default 429 body message `createLimiter` sends when a key is over budget. */
 export declare const DEFAULT_LIMITER_MESSAGE = "rate limit exceeded";
 
-/** Default `Permissions-Policy` value `createSecurity` sets. */
+/** Holds the default `Permissions-Policy` value `createSecurity` sets. */
 export declare const DEFAULT_PERMISSIONS_POLICY = "camera=(), microphone=(), geolocation=()";
 
-/** Default `Referrer-Policy` value `createSecurity` sets. */
+/** Holds the default `Referrer-Policy` value `createSecurity` sets. */
 export declare const DEFAULT_REFERRER_POLICY = "strict-origin-when-cross-origin";
 
-/** Default maximum number of distinct session ids `createMemorySessionStore` tracks before LRU (by last write) eviction. */
+/** Holds the default maximum number of distinct session ids `createMemorySessionStore` tracks before LRU (by last write) eviction. */
 export declare const DEFAULT_SESSION_CAPACITY = 10000;
 
-/** Default cookie name `createCookieTransport` writes the signed session id under. */
+/** Names the default cookie `createCookieTransport` writes the signed session id under. */
 export declare const DEFAULT_SESSION_COOKIE = "session";
 
-/** Default header `createHeaderTransport` carries the session id in. */
+/** Names the default header `createHeaderTransport` carries the session id in. */
 export declare const DEFAULT_SESSION_HEADER = "session-id";
 
 /**
- * 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
@@ -766,7 +789,7 @@ export declare const DEFAULT_SESSION_HEADER = "session-id";
 export declare function detectEncodings(candidates: readonly Encoding[]): readonly Encoding[];
 
 /**
- * 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
@@ -778,7 +801,7 @@ export declare function detectEncodings(candidates: readonly Encoding[]): readon
  *
  * @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
@@ -789,9 +812,8 @@ export declare function detectEncodings(candidates: readonly Encoding[]): readon
 export declare function equalsConstantTime(a: string, b: string): boolean;
 
 /**
- * Options for `createETag` — dynamic response ETag + conditional GET.
+ * Configures `createETag` — dynamic response ETag + conditional GET.
  *
- * @param options - See fields below
  * @remarks
  * - `weak` — mint a weak `W/"…"` ETag (default `true`) or a strong `"…"` one
  *   (`false`).
@@ -801,8 +823,8 @@ export declare interface ETagOptions {
 }
 
 /**
- * Scope a battery to run everywhere EXCEPT a set of exact pathnames — there
- * it steps aside via `next()`.
+ * Scopes a battery to run everywhere EXCEPT a set of exact pathnames — there
+ * 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`
@@ -817,9 +839,8 @@ export declare interface ETagOptions {
 export declare function except<TState>(paths: string | readonly string[], handler: MiddlewareHandler<TState>): MiddlewareHandler<TState>;
 
 /**
- * Options for `createForwarded` — the trusted-proxy client-IP resolver.
+ * Configures `createForwarded` — the trusted-proxy client-IP resolver.
  *
- * @param options - See fields below
  * @remarks
  * Construction requires EXACTLY ONE of the two forms (a `TypeError` guards
  * both-set and neither-set):
@@ -834,9 +855,8 @@ export declare type ForwardedOptions = {
 };
 
 /**
- * Options for `createHeaderTransport` — the bare-header {@link SessionTransport}.
+ * Configures `createHeaderTransport` — the bare-header {@link SessionTransportInterface}.
  *
- * @param options - See fields below
  * @remarks
  * - `header` — the header carrying the session id; defaults to
  *   {@link DEFAULT_SESSION_HEADER}.
@@ -846,7 +866,7 @@ export declare interface HeaderTransportOptions {
 }
 
 /**
- * The request-identifier state slice `createSecurity` stashes when its
+ * Describes the request-identifier state slice `createSecurity` stashes when its
  * `identifier` option is enabled.
  */
 export declare interface IdentifierState {
@@ -854,21 +874,21 @@ export declare interface IdentifierState {
 }
 
 /**
- * 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 is eligible for the compression/ETag buffering pipeline
+ * — the shared cheap-skip predicate both batteries apply before ever touching
+ * `response.arrayBuffer()`.
  *
  * @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
+ * (`skipHeader`, for example `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
@@ -878,11 +898,11 @@ export declare interface IdentifierState {
 export declare function isBufferingIneligible(method: string, response: Response, skipHeader: string): boolean;
 
 /**
- * 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
@@ -893,12 +913,12 @@ export declare function isBufferingIneligible(method: string, response: Response
 export declare function isCompressionNegotiated(encoding: Encoding | undefined): encoding is Exclude<Encoding, 'identity'>;
 
 /**
- * Determine whether a value implements {@link MultipartBody} — a total
- * structural guard (§14): `files` keyed by field name to arrays of
+ * 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` when `value` is shaped like a {@link MultipartBody}
+ * @returns True if `value` is shaped like a {@link MultipartBody}; false otherwise
  *
  * @example
  * ```ts
@@ -908,21 +928,34 @@ export declare function isCompressionNegotiated(encoding: Encoding | undefined):
 export declare function isMultipartBody(value: unknown): value is MultipartBody;
 
 /**
- * Determine whether a value is one staged {@link MultipartFile} record — a
- * total structural guard (§14) checking every required field's shape.
+ * 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` when `value` is shaped like a {@link MultipartFile}
+ * @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
+ * ```
  */
 export declare function isMultipartFile(value: unknown): value is MultipartFile;
 
 /**
- * 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
@@ -932,29 +965,29 @@ export declare function isMultipartFile(value: unknown): value is MultipartFile;
 export declare function isPreflight(method: string, headers: Headers): boolean;
 
 /**
- * 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.
+ * 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`), 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}
+ * @returns True if `value` is shaped like a {@link SessionInterface}; false otherwise
  *
  * @example
  * ```ts
- * isSession({ id: 'a', data: new Map() }) // true
  * isSession(new Session('a')) // true
+ * isSession({ id: 'a', state: new Map() }) // false — the mutators are missing
  * ```
  */
 export declare function isSession(value: unknown): value is SessionInterface;
 
 /**
- * Determine whether a value implements {@link SessionControlInterface} — a
- * total structural guard (§14): callable `regenerate` and `destroy`.
+ * Determines whether a value implements {@link SessionControlInterface} — a
+ * total structural guard: callable `regenerate` and `destroy`.
  *
  * @param value - The candidate value
- * @returns `true` when `value` is shaped like a {@link SessionControlInterface}
+ * @returns True if `value` is shaped like a {@link SessionControlInterface}; false otherwise
  *
  * @example
  * ```ts
@@ -964,15 +997,14 @@ export declare function isSession(value: unknown): value is SessionInterface;
 export declare function isSessionControl(value: unknown): value is SessionControlInterface;
 
 /**
- * Options for `createLimiter` — fixed-window rate limiting.
+ * Configures `createLimiter` — fixed-window rate limiting.
  *
  * @typeParam TState - The consumer's opaque per-request state type `key` reads
- * @param options - See fields below
  * @remarks
  * - `max` — the number of requests admitted per key per `window`.
  * - `window` — the window length in milliseconds.
  * - `capacity` — the maximum number of distinct keys tracked before the
- *   least-recently-used key is evicted (true LRU — every access, not just
+ *   least-recently-used key is evicted (true LRU — every access, not only
  *   insertion, refreshes recency); defaults to {@link DEFAULT_LIMITER_CAPACITY}.
  * - `key` — derives the bucket key from the request; defaults to the
  *   bearer-token-then-client-IP idiom (see the battery's guide).
@@ -997,7 +1029,7 @@ export declare interface LimiterOptions<TState = unknown> {
 }
 
 /**
- * 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.
@@ -1016,7 +1048,7 @@ export declare interface LimiterOptions<TState = unknown> {
  *
  * @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
@@ -1027,18 +1059,18 @@ export declare interface LimiterOptions<TState = unknown> {
 export declare function matchesTrustedEntry(address: string, entry: string): boolean;
 
 /**
- * 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
+ * `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, 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
+ * `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`
@@ -1053,21 +1085,20 @@ export declare function matchesTrustedEntry(address: string, entry: string): boo
  * @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())
  * ```
  */
-export declare class MemorySessionStore<S> implements SessionStoreInterface<S> {
+export declare class MemorySessionStore<S extends SessionInterface> implements SessionStoreInterface<S> {
     #private;
     constructor(options?: MemorySessionStoreOptions);
     get(id: string, now: number): Promise<S | undefined>;
-    set(id: string, session: S, now: number): Promise<void>;
+    set(session: S, now: number): Promise<void>;
     delete(id: string): Promise<void>;
 }
 
 /**
- * Options for `createMemorySessionStore` — the default in-process {@link SessionStoreInterface}.
+ * Configures `createMemorySessionStore` — the default in-process {@link SessionStoreInterface}.
  *
- * @param options - See fields below
  * @remarks
  * - `ttl` — the idle timeout in milliseconds (lazy eviction on `get`).
  * - `lifetime` — the absolute lifetime in milliseconds from first `set`
@@ -1081,15 +1112,13 @@ export declare class MemorySessionStore<S> implements SessionStoreInterface<S> {
  *   sink only — it must never call back into the store (no re-entrant
  *   `get`/`set`); mutations during eviction are unsupported.
  */
-export declare interface MemorySessionStoreOptions {
-    readonly ttl?: number;
-    readonly lifetime?: number;
+export declare interface MemorySessionStoreOptions extends SessionLimits {
     readonly capacity?: number;
     readonly evict?: (id: string) => void;
 }
 
 /**
- * The parsed multipart request body `createMultipart` stashes — files keyed
+ * Describes the parsed multipart request body `createMultipart` stashes — files keyed
  * by their field name, plus every plain text field.
  */
 export declare interface MultipartBody {
@@ -1098,7 +1127,7 @@ export declare interface MultipartBody {
 }
 
 /**
- * One staged multipart upload's public record — the shape the node-face
+ * Represents one staged multipart upload's public record — the shape the node-face
  * `createMultipart` battery (`@orkestrel/middleware/server`) produces per
  * uploaded file.
  *
@@ -1106,7 +1135,7 @@ export declare interface MultipartBody {
  * Declared here rather than in the node-bound server surface so the
  * fetch/string-pure {@link MultipartState} slice — referenced by any
  * environment narrowing `context.state` — never depends on the node face.
- * The server's concrete `UploadedFileInterface` is structurally compatible
+ * The server's concrete `UploadedFile` is structurally compatible
  * with this shape.
  */
 export declare interface MultipartFile {
@@ -1120,7 +1149,7 @@ export declare interface MultipartFile {
 }
 
 /**
- * The multipart state slice `createMultipart` stashes.
+ * Describes the multipart state slice `createMultipart` stashes.
  *
  * @remarks
  * Present only once `createMultipart` has fully parsed a multipart request.
@@ -1133,8 +1162,8 @@ export declare interface MultipartState {
 }
 
 /**
- * Scope a battery to run ONLY on a set of exact pathnames — elsewhere it
- * steps aside via `next()`.
+ * Scopes a battery to run ONLY on a set of exact pathnames — elsewhere 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`
@@ -1149,7 +1178,7 @@ export declare interface MultipartState {
 export declare function only<TState>(paths: string | readonly string[], handler: MiddlewareHandler<TState>): MiddlewareHandler<TState>;
 
 /**
- * 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()`.
@@ -1168,7 +1197,7 @@ export declare function only<TState>(paths: string | readonly string[], handler:
 export declare function rebuildResponse(body: ConstructorParameters<typeof Response>[0], response: Response, headers?: ConstructorParameters<typeof Headers>[0]): Response;
 
 /**
- * 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
@@ -1184,7 +1213,7 @@ export declare function rebuildResponse(body: ConstructorParameters<typeof Respo
  * 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
@@ -1192,21 +1221,17 @@ export declare function rebuildResponse(body: ConstructorParameters<typeof Respo
  * resolveForwardedFor('203.0.113.7, 10.0.0.1', { proxies: 1 }) // '203.0.113.7'
  * ```
  */
-export declare function resolveForwardedFor(header: string | undefined, trust: {
-    readonly proxies: number;
-} | {
-    readonly trusted: readonly string[];
-}): string | undefined;
+export declare function resolveForwardedFor(header: string | undefined, trust: ForwardedOptions): string | undefined;
 
 /**
- * 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`.
@@ -1223,7 +1248,7 @@ export declare function resolveForwardedFor(header: string | undefined, trust: {
 export declare function resolveKey(state: BearerState & ClientState & ConnectionState): string;
 
 /**
- * Resolve an opt-in, value-bearing security header — `string | boolean`
+ * Resolves an opt-in, value-bearing security header — `string | boolean`
  * (default OFF, `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.
@@ -1241,22 +1266,7 @@ export declare function resolveKey(state: BearerState & ClientState & Connection
 export declare function resolveOptInHeader(value: string | boolean | undefined, fallback: string): string | undefined;
 
 /**
- * Rebuild a `Session` from an untrusted snapshot value (the inverse of
- * {@link snapshotSession}) — a durable store's `get` deserialization step.
- *
- * @param value - The candidate snapshot, of unknown shape
- * @returns A rebuilt `Session`, or `undefined` when `value` is malformed
- *
- * @example
- * ```ts
- * restoreSession({ id: 'abc', data: { userId: 'u_1' } }) // Session { id: 'abc', data: Map }
- * restoreSession({ id: 1 }) // undefined
- * ```
- */
-export declare function restoreSession(value: unknown): Session | undefined;
-
-/**
- * `createSecurity`'s `identifier` sub-option — request-id minting/echo
+ * Describes `createSecurity`'s `identifier` sub-option — request-id minting/echo
  * policy, or `false` to disable the feature entirely.
  *
  * @remarks
@@ -1269,9 +1279,8 @@ export declare type SecurityIdentifierOptions = {
 } | false;
 
 /**
- * Options for `createSecurity` — the security-headers + request-id battery.
+ * Configures `createSecurity` — the security-headers + request-id battery.
  *
- * @param options - See fields below
  * @remarks
  * Every header option is `string | false` (a custom value replaces the
  * default wholesale, `false` omits the header) unless noted; unset uses the
@@ -1305,35 +1314,41 @@ export declare interface SecurityOptions {
 }
 
 /**
- * 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).
+ * 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
- * `data` is a live, mutable `Map` a handler reads/writes directly;
- * `createSession` persists it to the configured store on the way out.
+ * `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.data.set('userId', 'u_1')
+ * session.set('userId', 'u_1')
  * ```
  */
 export declare class Session implements SessionInterface {
-    readonly id: string;
-    readonly data: Map<string, unknown>;
+    #private;
     constructor(id: string);
+    get id(): string;
+    get state(): ReadonlyMap<string, unknown>;
+    set(key: string, value: unknown): void;
+    delete(key: string): boolean;
+    clear(): void;
 }
 
 /**
- * The `@orkestrel/database` column shape for a
+ * Holds the `@orkestrel/database` column shape for a
  * {@link import('./types.js').SessionRow} table — pass 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
@@ -1349,19 +1364,19 @@ export declare class Session implements SessionInterface {
 export declare const sessionColumns: {
     id: StringShape;
     session: JSONShape;
-    lastSeen: NumberShape;
-    createdAt: NumberShape;
+    seen: NumberShape;
+    created: NumberShape;
 };
 
 /**
- * The mid-handler control handle `createSession` stashes alongside the
+ * Describes the mid-handler control handle `createSession` stashes alongside the
  * session itself — the OWASP anti-fixation / logout primitives.
  *
  * @remarks
  * `regenerate` and `destroy` record intent SYNCHRONOUSLY when called; the
  * store I/O and transport write happen after the handler's `next()` returns
  * (`destroy` supersedes a prior `regenerate`). `regenerate` mints a new id,
- * carries the session's `data` over, and invalidates the old id.
+ * carries the session's `state` over, and invalidates the old id.
  */
 export declare interface SessionControlInterface {
     regenerate(): void;
@@ -1369,47 +1384,86 @@ export declare interface SessionControlInterface {
 }
 
 /**
- * Whether a session has aged past its idle timeout or absolute lifetime as
+ * Describes the per-session instants a store stamps and `sessionExpired` measures
+ * against.
+ *
+ * @remarks
+ * - `seen` — the instant of the most recent live read or write.
+ * - `created` — the instant of the first `set`, preserved across every
+ *   later re-`set` of the same id.
+ */
+export declare interface SessionCursors {
+    readonly seen: number;
+    readonly created: number;
+}
+
+/**
+ * Represents one in-process session entry — the payload {@link MemorySessionStore} holds
+ * against an id, alongside the same cursors a persisted row carries.
+ *
+ * @typeParam S - The stored session entity type
+ */
+export declare interface SessionEntry<S extends SessionInterface> extends SessionCursors {
+    readonly session: S;
+}
+
+/**
+ * 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
  * ```
  */
-export declare function sessionExpired(cursors: {
-    readonly lastSeen: number;
-    readonly createdAt: number;
-}, now: number, limits: {
-    readonly ttl?: number;
-    readonly lifetime?: number;
-}): boolean;
+export declare function sessionExpired(cursors: SessionCursors, now: number, limits: SessionLimits): boolean;
 
 /**
- * A server-managed session's public surface — an id and its mutable data bag.
+ * Represents a server-managed session's public surface — an id, its live state, and the
+ * mutators that write it.
  *
  * @remarks
- * `data` is a live `Map` a handler reads/writes directly; `createSession`
- * persists it to the configured {@link SessionStoreInterface} on the way out.
+ * `state` is a `ReadonlyMap` view a handler reads directly: TypeScript
+ * refuses a write through it, and `set`, `delete`, and `clear` are the write
+ * path. `createSession` persists the state to the configured
+ * {@link SessionStoreInterface} on the way out. `clear` empties the state
+ * without ending the session — `SessionControlInterface.destroy` does that.
  */
 export declare interface SessionInterface {
     readonly id: string;
-    readonly data: Map<string, unknown>;
+    readonly state: ReadonlyMap<string, unknown>;
+    set(key: string, value: unknown): void;
+    delete(key: string): boolean;
+    clear(): void;
+}
+
+/**
+ * Describes the idle and absolute-lifetime thresholds a session store enforces —
+ * `sessionExpired`'s limits argument and both shipped stores' construction
+ * options.
+ *
+ * @remarks
+ * - `ttl` — the idle timeout in milliseconds; absent means no idle expiry.
+ * - `lifetime` — the absolute lifetime in milliseconds from the first `set`;
+ *   absent means no absolute expiry.
+ */
+export declare interface SessionLimits {
+    readonly ttl?: number | undefined;
+    readonly lifetime?: number | undefined;
 }
 
 /**
- * Options for `createSession` — the generic session battery.
+ * Configures `createSession` — the generic session battery.
  *
- * @typeParam S - The session data payload type `create` produces
+ * @typeParam S - The session entity type `create` produces
  * @typeParam TState - The consumer's opaque per-request state type `mint` reads
- * @param options - See fields below
  * @remarks
- * - `transport` — the {@link SessionTransport} (`createCookieTransport(...)`,
+ * - `transport` — the {@link SessionTransportInterface} (`createCookieTransport(...)`,
  *   `createHeaderTransport(...)`, or a custom one).
  * - `store` — the {@link SessionStoreInterface}; defaults to
  *   `createMemorySessionStore({ ttl, lifetime, capacity, evict })`.
@@ -1426,14 +1480,12 @@ export declare interface SessionInterface {
  *   defaults to `new Session(id)`.
  * - `mint` — decides whether to auto-mint a session when none resolves;
  *   defaults to always minting (auto-session).
- * - `require` — when `true`, a request that resolves no session and does not
+ * - `required` — when `true`, a request that resolves no session and does not
  *   mint one renders a 404 instead of proceeding sessionless. Defaults to `false`.
- * - `ends` — when `true`, a `DELETE` request carrying a valid session id
- *   deletes the session and short-circuits with `204`. Defaults to `false`.
  * - `clock` — the injected time source fed to the store; defaults to `Date.now`.
  */
-export declare interface SessionOptions<S, TState = unknown> {
-    readonly transport: SessionTransport;
+export declare interface SessionOptions<S extends SessionInterface, TState = unknown> {
+    readonly transport: SessionTransportInterface;
     readonly store?: SessionStoreInterface<S>;
     readonly ttl?: number;
     readonly lifetime?: number;
@@ -1441,25 +1493,47 @@ export declare interface SessionOptions<S, TState = unknown> {
     readonly evict?: (id: string) => void;
     readonly create?: (id: string) => S;
     readonly mint?: (context: MiddlewareContext<TState>) => boolean | Promise<boolean>;
-    readonly require?: boolean;
-    readonly ends?: boolean;
+    readonly required?: boolean;
     readonly clock?: () => number;
 }
 
 /**
- * One persisted session row — an opaque snapshot column plus the store-owned
+ * Rebuilds a session entity from an untrusted stored snapshot, or resolves `undefined` when the value is malformed.
+ *
+ * @remarks
+ * The step {@link DatabaseSessionStore} is constructed with, and the seam a
+ * consumer implements to restore its own session entity from a persisted row.
+ * `createDatabaseSessionStore` supplies `createRestoredSession` as that step.
+ */
+export declare type SessionRestoreFunction = (value: unknown) => SessionInterface | undefined;
+
+/**
+ * Represents one persisted session row — an opaque snapshot column plus the store-owned
  * idle/absolute-lifetime cursors, the shape a {@link DatabaseSessionStore}'s
  * backing table holds.
  */
-export declare interface SessionRow {
+export declare interface SessionRow extends SessionCursors {
     readonly id: string;
     readonly session: unknown;
-    readonly lastSeen: number;
-    readonly createdAt: number;
 }
 
 /**
- * The session state slice `createSession` stashes.
+ * Represents a session's serializable projection — the value `snapshotSession` produces
+ * and a durable store's `set` writes.
+ *
+ * @remarks
+ * `state` is the wire member a persisted row carries, built on a
+ * null-prototype record so a session key literally named `__proto__`
+ * round-trips as an own enumerable property. It holds the same entries the
+ * entity's own `state` view publishes.
+ */
+export declare interface SessionSnapshot {
+    readonly id: string;
+    readonly state: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Describes the session state slice `createSession` stashes.
  *
  * @remarks
  * `session` is present whenever a request resolves or mints a session;
@@ -1471,24 +1545,34 @@ export declare interface SessionState {
 }
 
 /**
- * The pluggable session persistence seam `createSession`'s `store` option
- * implements — a point-access store (AGENTS §5) keyed by session id.
+ * Describes the pluggable session persistence seam `createSession`'s `store` option
+ * implements — a point-access store keyed by session id.
  *
- * @typeParam S - The session data payload type
+ * @typeParam S - The stored session entity type
  * @remarks
  * Every primitive is async and takes a trailing `now` clock reading (the
  * same seam `createSession`'s `clock` option feeds) so a store can apply its
  * own idle/absolute expiry against the caller's injected time rather than
- * its own wall clock. `delete` of an absent id is a no-op, never throws.
- */
-export declare interface SessionStoreInterface<S> {
+ * its own wall clock. `set` reads the id from the session it is handed —
+ * a stored value carries its own id, so no separate id is passed. `delete` of
+ * an absent id is a no-op, never throws.
+ *
+ * `get` must resolve a value satisfying {@link isSession} — an `id` string,
+ * a `state` `Map` view, and the mutators — or `undefined`. `createSession`
+ * dereferences the resolved value's `id` and `state` without re-checking
+ * them, so a store that resolves an off-shape value corrupts the battery's
+ * own state rather than being refused at the seam. The shipped
+ * `DatabaseSessionStore` enforces this with the caller-supplied guard it is
+ * constructed with.
+ */
+export declare interface SessionStoreInterface<S extends SessionInterface> {
     get(id: string, now: number): Promise<S | undefined>;
-    set(id: string, session: S, now: number): Promise<void>;
+    set(session: S, now: number): Promise<void>;
     delete(id: string): Promise<void>;
 }
 
 /**
- * The transport seam `createSession`'s `transport` option implements — how a
+ * Describes the transport seam `createSession`'s `transport` option implements — how a
  * session id travels to and from the client (a signed cookie, a header, …).
  *
  * @remarks
@@ -1498,24 +1582,25 @@ export declare interface SessionStoreInterface<S> {
  * called only when a session is freshly minted or regenerated; `clear` is
  * called on `destroy()`. `write`'s `encrypted` flag is the request's resolved
  * transport security (derived from `context.url.protocol`) so a cookie
- * transport can resolve its own `Secure` attribute via `resolveSecure`
+ * transport can resolve its own `Secure` attribute through `resolveSecure`
  * without re-deriving connection facts itself.
  */
-export declare interface SessionTransport {
+export declare interface SessionTransportInterface {
     read(request: Request): string | undefined | Promise<string | undefined>;
     write(response: Response, id: string, encrypted: boolean): void | Promise<void>;
     clear(response: Response): void;
 }
 
 /**
- * Snapshot a session's `data` Map into a plain, serializable record — the
+ * 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
  * `__proto__` accessor (which would silently drop the entry and risk
@@ -1523,16 +1608,13 @@ export declare interface SessionTransport {
  *
  * @example
  * ```ts
- * snapshotSession(session) // { id: 'abc', data: { userId: 'u_1' } }
+ * snapshotSession(session) // { id: 'abc', state: { userId: 'u_1' } }
  * ```
  */
-export declare function snapshotSession(session: SessionInterface): {
-    readonly id: string;
-    readonly data: Record<string, unknown>;
-};
+export declare function snapshotSession(session: SessionInterface): SessionSnapshot;
 
 /**
- * One access-log-style entry `createTelemetry` records after a response
+ * Represents one access-log-style entry `createTelemetry` records after a response
  * settles — the access-log/timing seam's payload shape.
  *
  * @remarks
@@ -1551,9 +1633,8 @@ export declare interface TelemetryEntry {
 }
 
 /**
- * Options for `createTelemetry` — the request timing/access-log seam.
+ * Configures `createTelemetry` — the request timing/access-log seam.
  *
- * @param options - See fields below
  * @remarks
  * - `record` — invoked once per request with the settled {@link
  *   TelemetryEntry}; its own throw is swallowed so a broken sink can never
@@ -1564,17 +1645,36 @@ export declare interface TelemetryOptions {
 }
 
 /**
- * Copy every entry of one session's `data` into another — the regenerate
- * data-carry `createSession`'s `control.regenerate()` applies (ruling D).
+ * Copies every entry of one session's `state` into another — the regenerate
+ * state-carry `createSession`'s `control.regenerate()` applies.
+ *
+ * @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
+ * transferSessionState(oldSession, newSession)
+ * ```
+ */
+export declare function transferSessionState(from: SessionInterface, to: SessionInterface): void;
+
+/**
+ * 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 from - The source session whose `data` is copied
- * @param to - The destination session `data` is copied into
+ * @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
- * transferSessionData(oldSession, newSession)
+ * validateSessionLimits({ ttl: 60_000 }) // returns; the thresholds are usable
  * ```
  */
-export declare function transferSessionData(from: SessionInterface, to: SessionInterface): void;
+export declare function validateSessionLimits(limits: SessionLimits | undefined): void;
 
 export { }