@orkestrel/middleware 0.0.1 → 0.0.2

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

@@ -1,8 +1,13 @@
 import { ConnectionInfo } from '@orkestrel/server';
 import { CookieOptions } from '@orkestrel/server';
 import { Encoding } from '@orkestrel/server';
+import { Guard } from '@orkestrel/contract';
+import { JSONShape } from '@orkestrel/contract';
 import { MiddlewareContext } from '@orkestrel/server';
 import { MiddlewareHandler } from '@orkestrel/server';
+import { NumberShape } from '@orkestrel/contract';
+import { StringShape } from '@orkestrel/contract';
+import { TableInterface } from '@orkestrel/database';
 import { TokenSecret } from '@orkestrel/server';
 
 /**
@@ -37,6 +42,19 @@ export declare interface BearerState {
     token?: string;
 }
 
+/**
+ * The body state slice `createBody` stashes.
+ *
+ * @remarks
+ * `body` holds the same value the cached `context.body()` resolved to
+ * (`undefined` when the request declared no body, or a body `createBody`
+ * did not reject) — a mid-handler read without a second `context.body()`
+ * await.
+ */
+export declare interface BodyState {
+    body?: unknown;
+}
+
 /**
  * Options for `createBoundary` — the outermost error-rendering battery.
  *
@@ -254,9 +272,10 @@ export declare function createBearer<TState extends BearerState>(options: Bearer
 
 /**
  * The body-driving battery — eagerly awaits the cached `context.body()` so
- * its throws (or a malformed-JSON `undefined`) surface before the handler runs.
+ * its throws (or a malformed-JSON `undefined`) surface before the handler
+ * runs, and stashes the resolved value onto {@link BodyState.body}.
  *
- * @typeParam TState - The consumer's opaque per-request state type
+ * @typeParam TState - The consumer's opaque per-request state type, must carry {@link BodyState}
  * @returns A `MiddlewareHandler<TState>`
  * @throws {HTTPError} `400` when the request declares `application/json` and the body resolves `undefined`
  *
@@ -264,14 +283,16 @@ export declare function createBearer<TState extends BearerState>(options: Bearer
  * 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).
+ * `createBodyParser` surface, which configured them itself). `state.body` is
+ * stashed from the SAME awaited call the 400 check reads — `context.body()`
+ * is never invoked twice.
  *
  * @example
  * ```ts
  * const body = createBody()
  * ```
  */
-export declare function createBody<TState>(): MiddlewareHandler<TState>;
+export declare function createBody<TState extends BodyState = BodyState>(): MiddlewareHandler<TState>;
 
 /**
  * The outermost error-rendering battery — catches a downstream throw and
@@ -351,6 +372,32 @@ 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} —
+ * the durable counterpart to `createMemorySessionStore`, over a caller-opened
+ * `@orkestrel/database` table (declare it with {@link sessionColumns}).
+ *
+ * @typeParam S - The session data payload 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
+ * @returns A {@link SessionStoreInterface}
+ *
+ * @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.
+ *
+ * @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>;
+
 /**
  * The application-level per-request deadline battery.
  *
@@ -532,6 +579,49 @@ export declare interface CSRFState {
     csrf?: string;
 }
 
+/**
+ * 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
+ *
+ * @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
+ * 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
+ * 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
+ * `ttl`/`lifetime` elapses on a later `get`.
+ *
+ * @example
+ * ```ts
+ * const store = new DatabaseSessionStore(table, isSession, { ttl: 60_000 })
+ * await store.set('abc', 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;
+    });
+    get(id: string, now: number): Promise<S | undefined>;
+    set(id: string, session: S, now: number): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
 /**
  * Options for `createDeadline` — the application-level per-request deadline.
  *
@@ -695,6 +785,22 @@ export declare interface ETagOptions {
     readonly weak?: boolean;
 }
 
+/**
+ * Scope a battery to run everywhere EXCEPT a set of exact pathnames — there
+ * it steps aside via `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`
+ * @param handler - The battery to run when `paths` does not match
+ * @returns A `MiddlewareHandler<TState>`
+ *
+ * @example
+ * ```ts
+ * const scoped = except('/health', createTelemetry({ record }))
+ * ```
+ */
+export declare function except<TState>(paths: string | readonly string[], handler: MiddlewareHandler<TState>): MiddlewareHandler<TState>;
+
 /**
  * Options for `createForwarded` — the trusted-proxy client-IP resolver.
  *
@@ -812,7 +918,10 @@ 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`.
+ * 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}
@@ -820,6 +929,7 @@ export declare function isPreflight(method: string, headers: Headers): boolean;
  * @example
  * ```ts
  * isSession({ id: 'a', data: new Map() }) // true
+ * isSession(new Session('a')) // true
  * ```
  */
 export declare function isSession(value: unknown): value is SessionInterface;
@@ -1007,6 +1117,22 @@ export declare interface MultipartState {
     multipart?: MultipartBody;
 }
 
+/**
+ * Scope a battery to run ONLY on a set of exact pathnames — elsewhere it
+ * steps aside via `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`
+ * @param handler - The battery to run when `paths` matches
+ * @returns A `MiddlewareHandler<TState>`
+ *
+ * @example
+ * ```ts
+ * const scoped = only('/admin', createBearer({ secret }))
+ * ```
+ */
+export declare function only<TState>(paths: string | readonly string[], handler: MiddlewareHandler<TState>): MiddlewareHandler<TState>;
+
 /**
  * Rebuild a `Response` around a replacement body while preserving its
  * status/statusText — the buffered-response reconstruction shared by the
@@ -1099,6 +1225,21 @@ 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
  * policy, or `false` to disable the feature entirely.
@@ -1170,6 +1311,31 @@ export declare class Session implements SessionInterface {
     constructor(id: string);
 }
 
+/**
+ * The `@orkestrel/database` column shape for a {@link 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
+ * them as integers, so `DatabaseSessionStore`'s `now` clock must yield
+ * integer milliseconds (`Date.now()`, the implicit default `createSession`
+ * clock). A fractional clock (`performance.now()`) fails the write with a
+ * validation error; `MemorySessionStore` carries no such column shape and
+ * accepts a fractional clock without complaint.
+ *
+ * @example
+ * ```ts
+ * const db = createDatabase({ driver, tables: { sessions: sessionColumns } })
+ * ```
+ */
+export declare const sessionColumns: {
+    id: StringShape;
+    session: JSONShape;
+    lastSeen: NumberShape;
+    createdAt: NumberShape;
+};
+
 /**
  * The mid-handler control handle `createSession` stashes alongside the
  * session itself — the OWASP anti-fixation / logout primitives.
@@ -1185,6 +1351,28 @@ export declare interface SessionControlInterface {
     destroy(): void;
 }
 
+/**
+ * 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 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
+ *
+ * @example
+ * ```ts
+ * sessionExpired({ lastSeen: 0, createdAt: 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;
+
 /**
  * A server-managed session's public surface — an id and its mutable data bag.
  *
@@ -1241,6 +1429,18 @@ export declare interface SessionOptions<S, TState = unknown> {
     readonly clock?: () => number;
 }
 
+/**
+ * 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 {
+    readonly id: string;
+    readonly session: unknown;
+    readonly lastSeen: number;
+    readonly createdAt: number;
+}
+
 /**
  * The session state slice `createSession` stashes.
  *
@@ -1290,6 +1490,30 @@ export declare interface SessionTransport {
     clear(response: Response): void;
 }
 
+/**
+ * Snapshot a session's `data` Map 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`
+ *
+ * @remarks
+ * `data` 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
+ * polluting the shared prototype).
+ *
+ * @example
+ * ```ts
+ * snapshotSession(session) // { id: 'abc', data: { userId: 'u_1' } }
+ * ```
+ */
+export declare function snapshotSession(session: SessionInterface): {
+    readonly id: string;
+    readonly data: Record<string, unknown>;
+};
+
 /**
  * One access-log-style entry `createTelemetry` records after a response
  * settles — the access-log/timing seam's payload shape.

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

@@ -1,8 +1,13 @@
 import { ConnectionInfo } from '@orkestrel/server';
 import { CookieOptions } from '@orkestrel/server';
 import { Encoding } from '@orkestrel/server';
+import { Guard } from '@orkestrel/contract';
+import { JSONShape } from '@orkestrel/contract';
 import { MiddlewareContext } from '@orkestrel/server';
 import { MiddlewareHandler } from '@orkestrel/server';
+import { NumberShape } from '@orkestrel/contract';
+import { StringShape } from '@orkestrel/contract';
+import { TableInterface } from '@orkestrel/database';
 import { TokenSecret } from '@orkestrel/server';
 
 /**
@@ -37,6 +42,19 @@ export declare interface BearerState {
     token?: string;
 }
 
+/**
+ * The body state slice `createBody` stashes.
+ *
+ * @remarks
+ * `body` holds the same value the cached `context.body()` resolved to
+ * (`undefined` when the request declared no body, or a body `createBody`
+ * did not reject) — a mid-handler read without a second `context.body()`
+ * await.
+ */
+export declare interface BodyState {
+    body?: unknown;
+}
+
 /**
  * Options for `createBoundary` — the outermost error-rendering battery.
  *
@@ -254,9 +272,10 @@ export declare function createBearer<TState extends BearerState>(options: Bearer
 
 /**
  * The body-driving battery — eagerly awaits the cached `context.body()` so
- * its throws (or a malformed-JSON `undefined`) surface before the handler runs.
+ * its throws (or a malformed-JSON `undefined`) surface before the handler
+ * runs, and stashes the resolved value onto {@link BodyState.body}.
  *
- * @typeParam TState - The consumer's opaque per-request state type
+ * @typeParam TState - The consumer's opaque per-request state type, must carry {@link BodyState}
  * @returns A `MiddlewareHandler<TState>`
  * @throws {HTTPError} `400` when the request declares `application/json` and the body resolves `undefined`
  *
@@ -264,14 +283,16 @@ export declare function createBearer<TState extends BearerState>(options: Bearer
  * 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).
+ * `createBodyParser` surface, which configured them itself). `state.body` is
+ * stashed from the SAME awaited call the 400 check reads — `context.body()`
+ * is never invoked twice.
  *
  * @example
  * ```ts
  * const body = createBody()
  * ```
  */
-export declare function createBody<TState>(): MiddlewareHandler<TState>;
+export declare function createBody<TState extends BodyState = BodyState>(): MiddlewareHandler<TState>;
 
 /**
  * The outermost error-rendering battery — catches a downstream throw and
@@ -351,6 +372,32 @@ 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} —
+ * the durable counterpart to `createMemorySessionStore`, over a caller-opened
+ * `@orkestrel/database` table (declare it with {@link sessionColumns}).
+ *
+ * @typeParam S - The session data payload 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
+ * @returns A {@link SessionStoreInterface}
+ *
+ * @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.
+ *
+ * @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>;
+
 /**
  * The application-level per-request deadline battery.
  *
@@ -532,6 +579,49 @@ export declare interface CSRFState {
     csrf?: string;
 }
 
+/**
+ * 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
+ *
+ * @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
+ * 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
+ * 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
+ * `ttl`/`lifetime` elapses on a later `get`.
+ *
+ * @example
+ * ```ts
+ * const store = new DatabaseSessionStore(table, isSession, { ttl: 60_000 })
+ * await store.set('abc', 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;
+    });
+    get(id: string, now: number): Promise<S | undefined>;
+    set(id: string, session: S, now: number): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
 /**
  * Options for `createDeadline` — the application-level per-request deadline.
  *
@@ -695,6 +785,22 @@ export declare interface ETagOptions {
     readonly weak?: boolean;
 }
 
+/**
+ * Scope a battery to run everywhere EXCEPT a set of exact pathnames — there
+ * it steps aside via `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`
+ * @param handler - The battery to run when `paths` does not match
+ * @returns A `MiddlewareHandler<TState>`
+ *
+ * @example
+ * ```ts
+ * const scoped = except('/health', createTelemetry({ record }))
+ * ```
+ */
+export declare function except<TState>(paths: string | readonly string[], handler: MiddlewareHandler<TState>): MiddlewareHandler<TState>;
+
 /**
  * Options for `createForwarded` — the trusted-proxy client-IP resolver.
  *
@@ -812,7 +918,10 @@ 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`.
+ * 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}
@@ -820,6 +929,7 @@ export declare function isPreflight(method: string, headers: Headers): boolean;
  * @example
  * ```ts
  * isSession({ id: 'a', data: new Map() }) // true
+ * isSession(new Session('a')) // true
  * ```
  */
 export declare function isSession(value: unknown): value is SessionInterface;
@@ -1007,6 +1117,22 @@ export declare interface MultipartState {
     multipart?: MultipartBody;
 }
 
+/**
+ * Scope a battery to run ONLY on a set of exact pathnames — elsewhere it
+ * steps aside via `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`
+ * @param handler - The battery to run when `paths` matches
+ * @returns A `MiddlewareHandler<TState>`
+ *
+ * @example
+ * ```ts
+ * const scoped = only('/admin', createBearer({ secret }))
+ * ```
+ */
+export declare function only<TState>(paths: string | readonly string[], handler: MiddlewareHandler<TState>): MiddlewareHandler<TState>;
+
 /**
  * Rebuild a `Response` around a replacement body while preserving its
  * status/statusText — the buffered-response reconstruction shared by the
@@ -1099,6 +1225,21 @@ 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
  * policy, or `false` to disable the feature entirely.
@@ -1170,6 +1311,31 @@ export declare class Session implements SessionInterface {
     constructor(id: string);
 }
 
+/**
+ * The `@orkestrel/database` column shape for a {@link 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
+ * them as integers, so `DatabaseSessionStore`'s `now` clock must yield
+ * integer milliseconds (`Date.now()`, the implicit default `createSession`
+ * clock). A fractional clock (`performance.now()`) fails the write with a
+ * validation error; `MemorySessionStore` carries no such column shape and
+ * accepts a fractional clock without complaint.
+ *
+ * @example
+ * ```ts
+ * const db = createDatabase({ driver, tables: { sessions: sessionColumns } })
+ * ```
+ */
+export declare const sessionColumns: {
+    id: StringShape;
+    session: JSONShape;
+    lastSeen: NumberShape;
+    createdAt: NumberShape;
+};
+
 /**
  * The mid-handler control handle `createSession` stashes alongside the
  * session itself — the OWASP anti-fixation / logout primitives.
@@ -1185,6 +1351,28 @@ export declare interface SessionControlInterface {
     destroy(): void;
 }
 
+/**
+ * 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 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
+ *
+ * @example
+ * ```ts
+ * sessionExpired({ lastSeen: 0, createdAt: 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;
+
 /**
  * A server-managed session's public surface — an id and its mutable data bag.
  *
@@ -1241,6 +1429,18 @@ export declare interface SessionOptions<S, TState = unknown> {
     readonly clock?: () => number;
 }
 
+/**
+ * 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 {
+    readonly id: string;
+    readonly session: unknown;
+    readonly lastSeen: number;
+    readonly createdAt: number;
+}
+
 /**
  * The session state slice `createSession` stashes.
  *
@@ -1290,6 +1490,30 @@ export declare interface SessionTransport {
     clear(response: Response): void;
 }
 
+/**
+ * Snapshot a session's `data` Map 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`
+ *
+ * @remarks
+ * `data` 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
+ * polluting the shared prototype).
+ *
+ * @example
+ * ```ts
+ * snapshotSession(session) // { id: 'abc', data: { userId: 'u_1' } }
+ * ```
+ */
+export declare function snapshotSession(session: SessionInterface): {
+    readonly id: string;
+    readonly data: Record<string, unknown>;
+};
+
 /**
  * One access-log-style entry `createTelemetry` records after a response
  * settles — the access-log/timing seam's payload shape.