@fuzdev/fuz_app 0.117.1 → 0.119.0

package/dist/server/app_server.d.ts

@@ -26,7 +26,8 @@ import { type RouteSpec } from '../http/route_spec.js';
 import type { MiddlewareSpec } from '../http/middleware_spec.js';
 import { type BootstrapStatus } from '../auth/bootstrap_routes.js';
 import type { WsEndpointSpec } from '../actions/ws_endpoint_spec.js';
-import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
+import type { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
+import { type AuthCleanupScheduleOptions } from '../auth/cleanup.js';
 /**
  * Context passed to `on_effect_error` when a pending effect rejects.
  */
@@ -185,12 +186,13 @@ export interface AppServerOptions {
      *
      * When truthy, creates an `AuditLogSse` instance internally, registers the SSE
      * listener via `backend.deps.audit.add_listener` (composing with the
-     * consumer's `on_audit_event` callback rather than rebuilding `AppDeps`), and
-     * auto-includes `audit_log_event_specs` in the surface. The result is exposed
-     * on `AppServerContext` (for route factories) and `AppServer` (for the caller),
-     * always typed as `AuditLogSse | null` — when this option is set, the field
-     * is non-null. Use `require_audit_sse(ctx)` to assert the invariant in
-     * route factories that depend on it.
+     * consumer's `on_audit_event` callback rather than rebuilding `AppDeps`),
+     * adds its registry to `backend.deps.connection_closer` so revocations close
+     * its streams, and auto-includes `audit_log_event_specs` in the surface. The
+     * result is exposed on `AppServerContext` (for route factories) and
+     * `AppServer` (for the caller), always typed as `AuditLogSse | null` — when
+     * this option is set, the field is non-null. Use `require_audit_sse(ctx)` to
+     * assert the invariant in route factories that depend on it.
      *
      * Pass `true` for defaults (admin role), or `{role: 'custom'}` for a custom role.
      * Omit to wire audit SSE manually.
@@ -198,6 +200,28 @@ export interface AppServerOptions {
     audit_log_sse?: true | {
         role?: string;
     };
+    /**
+     * Schedule the auth cleanup beside the server: `start_auth_cleanup` over
+     * `backend.deps` — a pass as assembly finishes, then one per interval —
+     * stopped by `AppServer.close`. Each pass deletes expired sessions and
+     * closes the connections they opened through `deps.connection_closer`
+     * (every WebSocket transport and audit stream this server mounts), and
+     * audits each newly expired role_grant offer once.
+     *
+     * **Off by default; a production server should turn it on.** Without it
+     * nothing sweeps: expired session rows accumulate, a WebSocket or audit
+     * stream outlives the expiry of the session it opened on until it
+     * disconnects, and an offer's expiry is never audited. With it, a
+     * connection outlives its session's expiry by at most one interval. The
+     * Rust spine's servers all schedule the twin (`spawn_auth_cleanup`).
+     *
+     * Pass `true` for the default interval
+     * (`DEFAULT_AUTH_CLEANUP_INTERVAL_MS`), or `{interval_ms}` for another.
+     * Leave it off in an in-process test harness — a background pass deletes
+     * rows and writes audit rows mid-test — and in a process that runs
+     * `run_auth_cleanup` on a schedule of its own.
+     */
+    auth_cleanup?: boolean | AuthCleanupScheduleOptions;
     /** SSE event specs for surface generation. Defaults to `[]` (no SSE events). */
     event_specs?: Array<EventSpec>;
     /**
@@ -245,13 +269,17 @@ export interface AppServerOptions {
      * Duplicate `path` values across two `WsEndpointSpec`s throw at
      * mount time (Hono would silently shadow them otherwise).
      *
+     * Every mounted transport is added to `deps.connection_closer`, so
+     * the revocation handlers' post-commit closes reach its sockets —
+     * unconditionally, since those closes are what ends a revoked
+     * credential's connections.
+     *
      * Each spec's `auth_guard?` defaults to `true` — the factory
-     * composes `create_ws_auth_guard` + `create_ws_logout_closer`
-     * against the mounted transport and registers them via
-     * `deps.audit.add_listener`. Wiring is deduped by transport
-     * **reference identity** so two specs sharing one
-     * `BackendWebsocketTransport` instance get a single pair of
-     * listeners; wrapped / proxied transports dedupe as separate
+     * registers `create_ws_auth_guard` against the mounted transport via
+     * `deps.audit.add_listener`, repeating the close on the audit row.
+     * Wiring is deduped by transport **reference identity** so two specs
+     * sharing one `BackendWebsocketTransport` instance get a single
+     * listener; wrapped / proxied transports dedupe as separate
      * entries (set `auth_guard: false` on duplicates and compose
      * against the underlying transport once).
      */
@@ -320,7 +348,12 @@ export interface AppServer {
      * Empty when no `ws_endpoints` were mounted.
      */
     ws_endpoints: Readonly<Record<string, BackendWebsocketTransport>>;
-    /** Close the database connection. Propagated from `AppBackend`. */
+    /**
+     * Shut the server's resources down: stop the auth cleanup schedule when
+     * the `auth_cleanup` option started one — waiting for a pass in progress —
+     * then close the database connection (`AppBackend.close`). That wait has
+     * no bound of its own; a shutdown with a deadline races it.
+     */
     close: () => Promise<void>;
 }
 /**
@@ -354,12 +387,19 @@ export declare const DEFAULT_MAX_BODY_SIZE: number;
  * pass `migration_namespaces` to `create_app_backend`.
  *
  * When `audit_log_sse` is set, the SSE registry's listener is registered via
- * `backend.deps.audit.add_listener` — no shallow-copy of `AppDeps`. The
+ * `backend.deps.audit.add_listener` — no shallow-copy of `AppDeps`. That
+ * registry and every WebSocket transport mounted from `ws_endpoints` are added
+ * to `backend.deps.connection_closer`, so the revocation handlers built from
+ * `ctx.deps` close their connections with no further wiring. The
  * `audit_sse` field on the returned `AppServer` (and the
  * `AppServerContext` passed to `create_route_specs`) is non-null in that
  * case; consumers can call `require_audit_sse(ctx)` / `require_audit_sse(server)`
  * to assert the invariant.
  *
+ * When `auth_cleanup` is set, the auth cleanup schedule starts as the last
+ * step of assembly — so an assembly that throws leaves no schedule running —
+ * and the returned `close` stops it before closing the database.
+ *
  * @returns assembled Hono app, backend, surface build, and bootstrap status
  */
 export declare const create_app_server: (options: AppServerOptions) => Promise<AppServer>;

package/dist/server/app_server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app_server.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app_server.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_server.ts"],"names":[],"mappings":"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"}

package/dist/server/app_server.js

@@ -32,8 +32,8 @@ import { create_fuz_authorization_handler } from '../auth/request_context.js';
 import { ERROR_PAYLOAD_TOO_LARGE } from '../http/error_schemas.js';
 import { create_rpc_endpoint } from '../actions/action_rpc.js';
 import { register_ws_endpoint } from '../actions/register_ws_endpoint.js';
-import { create_ws_auth_guard, create_ws_logout_closer } from '../actions/transports_ws_auth_guard.js';
-import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
+import { create_ws_auth_guard } from '../actions/transports_ws_auth_guard.js';
+import { start_auth_cleanup } from '../auth/cleanup.js';
 /**
  * Assert that `audit_sse` was wired by `create_app_server` and return it
  * as a non-null `AuditLogSse`. Throws a labelled error when the
@@ -68,12 +68,19 @@ export const DEFAULT_MAX_BODY_SIZE = 1024 * 1024;
  * pass `migration_namespaces` to `create_app_backend`.
  *
  * When `audit_log_sse` is set, the SSE registry's listener is registered via
- * `backend.deps.audit.add_listener` — no shallow-copy of `AppDeps`. The
+ * `backend.deps.audit.add_listener` — no shallow-copy of `AppDeps`. That
+ * registry and every WebSocket transport mounted from `ws_endpoints` are added
+ * to `backend.deps.connection_closer`, so the revocation handlers built from
+ * `ctx.deps` close their connections with no further wiring. The
  * `audit_sse` field on the returned `AppServer` (and the
  * `AppServerContext` passed to `create_route_specs`) is non-null in that
  * case; consumers can call `require_audit_sse(ctx)` / `require_audit_sse(server)`
  * to assert the invariant.
  *
+ * When `auth_cleanup` is set, the auth cleanup schedule starts as the last
+ * step of assembly — so an assembly that throws leaves no schedule running —
+ * and the returned `close` stops it before closing the database.
+ *
  * @returns assembled Hono app, backend, surface build, and bootstrap status
  */
 export const create_app_server = async (options) => {
@@ -106,11 +113,13 @@ export const create_app_server = async (options) => {
         : options.action_account_rate_limiter;
     // Factory-managed audit SSE — registers a listener on the bound emitter
     // so SSE fan-out runs alongside the consumer's `on_audit_event`
-    // without rebuilding `AppDeps`.
+    // without rebuilding `AppDeps`, and adds the registry to the backend's
+    // closer so revocations close its streams.
     const audit_sse = options.audit_log_sse
         ? create_audit_log_sse({
             log,
-            role: typeof options.audit_log_sse === 'object' ? options.audit_log_sse.role : undefined
+            role: typeof options.audit_log_sse === 'object' ? options.audit_log_sse.role : undefined,
+            connection_closer: deps.connection_closer
         })
         : null;
     if (audit_sse) {
@@ -281,7 +290,10 @@ export const create_app_server = async (options) => {
     // committed transaction). Both queues drain here, after the handler
     // (and any wrapping `db.transaction`) returns. In test mode both are
     // awaited before the response returns; in production, eager-queue
-    // rejections are reported via `on_effect_error`.
+    // rejections are reported via `on_effect_error`. Either way the
+    // deferred thunks are invoked without waiting for the eager writes to
+    // settle — a revocation's connection close must not sit behind a slow
+    // audit INSERT.
     app.use('*', async (c, next) => {
         c.set('pending_effects', []);
         c.set('post_commit_effects', []);
@@ -293,8 +305,11 @@ export const create_app_server = async (options) => {
             const deferred = c.var.post_commit_effects;
             if (eager.length || deferred.length) {
                 if (options.await_pending_effects) {
+                    // run the deferred thunks before awaiting the eager writes,
+                    // so neither mode holds them behind a write
+                    const deferred_flush = flush_post_commit_effects(deferred, log);
                     await flush_pending_effects(eager, log);
-                    await flush_post_commit_effects(deferred, log);
+                    await deferred_flush;
                 }
                 else {
                     const error_ctx = { method: c.req.method, path: c.req.path };
@@ -348,7 +363,7 @@ export const create_app_server = async (options) => {
         }
         const seen_paths = new Set();
         // Dedupe `auth_guard` wiring by transport reference — two specs
-        // sharing one transport instance get a single pair of listeners,
+        // sharing one transport instance get a single listener,
         // otherwise revocation events would fire `close_sockets_for_*`
         // twice per event (idempotent on the transport but log-spammy).
         // Cross-spec OR-semantics: any spec with `auth_guard !== false`
@@ -364,15 +379,17 @@ export const create_app_server = async (options) => {
                 throw new Error(`create_app_server: ws_endpoints path collides with a GET RouteSpec: ${endpoint.path}`);
             }
             seen_paths.add(endpoint.path);
-            const endpoint_transport = endpoint.transport ?? new BackendWebsocketTransport();
-            register_ws_endpoint({
+            const { transport: endpoint_transport } = register_ws_endpoint({
                 app,
                 path: endpoint.path,
                 upgradeWebSocket: options.upgradeWebSocket,
                 allowed_origins: endpoint.allowed_origins,
                 db: deps.db,
                 actions: endpoint.actions,
-                transport: endpoint_transport,
+                transport: endpoint.transport,
+                // every revocation handler's close reaches this transport
+                connection_closer: deps.connection_closer,
+                max_connections_per_account: endpoint.max_connections_per_account,
                 heartbeat: endpoint.heartbeat,
                 artificial_delay: endpoint.artificial_delay,
                 max_message_bytes: endpoint.max_message_bytes,
@@ -387,7 +404,6 @@ export const create_app_server = async (options) => {
             if (endpoint.auth_guard !== false && !guarded_transports.has(endpoint_transport)) {
                 guarded_transports.add(endpoint_transport);
                 deps.audit.add_listener(create_ws_auth_guard(endpoint_transport, log));
-                deps.audit.add_listener(create_ws_logout_closer(endpoint_transport, log));
             }
             if (endpoint.extra_audit_handlers?.length) {
                 for (const handler of endpoint.extra_audit_handlers) {
@@ -407,6 +423,12 @@ export const create_app_server = async (options) => {
             app.use('/*', mw);
         }
     }
+    // Auth cleanup — opt-in, and last: nothing after it can throw, so a failed
+    // assembly never leaves a schedule running. Its closes go through
+    // `deps.connection_closer`, which the mounts above have filled.
+    const auth_cleanup = options.auth_cleanup
+        ? start_auth_cleanup(deps, options.auth_cleanup === true ? undefined : options.auth_cleanup)
+        : null;
     return {
         app,
         surface_spec,
@@ -414,6 +436,12 @@ export const create_app_server = async (options) => {
         migration_results: backend.migration_results,
         audit_sse,
         ws_endpoints: mounted_ws_endpoints,
-        close: backend.close
+        close: auth_cleanup
+            ? async () => {
+                // the schedule first, so a pass in progress finishes on a live pool
+                await auth_cleanup.stop();
+                await backend.close();
+            }
+            : backend.close
     };
 };

package/dist/testing/CLAUDE.md

@@ -31,10 +31,10 @@ time (never runtime), where a throwing guard would break `vite build`.
 - `create_stub_db()` — real `Db` whose `client.query` yields `{rows: []}` and `transaction(fn)` synchronously calls `fn(inner_stub_db)`. Safe for `apply_route_specs`'s declarative transaction wrapper.
 - `stub_handler()` — fresh `Response('stub')`.
 - `stub_mw` — pass-through middleware (`async (_c, next) => next()`).
-- `stub_app_deps` — frozen `AppDeps`, every capability throwing, `audit` a no-op `AuditEmitter` from `create_test_audit_emitter`.
-- `create_stub_app_deps()` — factory: fresh `AppDeps` with no-op keyring/password/`delete_file`, a `read_secure_file` that throws ENOENT (the no-token-file state), a `create_noop_stub` DB, silent `Logger`, no-op `audit`.
+- `stub_app_deps` — frozen `AppDeps`, every capability throwing, `audit` a no-op `AuditEmitter` from `create_test_audit_emitter`, `connection_closer` an empty `RealtimeCloser`.
+- `create_stub_app_deps()` — factory: fresh `AppDeps` with no-op keyring/password/`delete_file`, a `read_secure_file` that throws ENOENT (the no-token-file state), a `create_noop_stub` DB, silent `Logger`, no-op `audit`, an empty `connection_closer`.
 - `create_test_audit_emitter()` — no-op `AuditEmitter`; `emit` / `emit_role_grant_target` no-op, `emit_pool` resolves immediately, `notify` no-op, `add_listener` throws (use `create_recording_audit_emitter` for a listener-accepting emitter), `listener_count` returns 0.
-- `create_stub_audit_sse()` — no-op `AuditLogSse` for surface-test wiring without booting real SSE. `subscribe` returns a no-op cleanup; `on_audit_event` no-op; `registry` is a fresh `SubscriberRegistry` (live `.size` / `.close_*` for registry-state tests, isolated per call). For real SSE plumbing build via `create_audit_log_sse` against `create_test_app`.
+- `create_stub_audit_sse()` — no-op `AuditLogSse` for surface-test wiring without booting real SSE. `on_audit_event` no-op (nothing is broadcast); `registry` is a fresh `SubscriberRegistry` (live `.count` / `.close_*` for registry-state tests, isolated per call). For real SSE plumbing build via `create_audit_log_sse` against `create_test_app`.
 - `create_stub_api_middleware({include_daemon_token?})` — stub `MiddlewareSpec[]` matching `create_auth_middleware_specs`'s output (origin/session/request_context/bearer_auth, optional daemon_token) for surface generation without booting real auth. See `auth/CLAUDE.md` §Middleware for the real stack.
 - `create_stub_app_server_context(session_options)` — stub `AppServerContext`; rate limiters null, `bootstrap_status.available: false`, `app_settings.open_signup: false`.
 - `create_test_app_surface_spec(options)` — builds an `AppSurfaceSpec` mirroring `create_app_server`'s route assembly (consumer routes + stub middleware + surface generation). `CreateTestAppSurfaceSpecOptions`: `session_options`, `create_route_specs`, `env_schema?`, `event_specs?`, `rpc_endpoints?`, `ws_endpoints?`, `transform_middleware?`, `bootstrap?`. Bootstrap is opt-in (symmetric with `create_app_server` — omit to skip; pass the same value as prod to mount routes at `bootstrap.route_prefix ?? '/api/account'`). Single source of truth for attack-surface tests — track `create_app_server` wiring changes here.
@@ -100,16 +100,14 @@ mismatch.
 ### `audit_drift_guard.ts` — audit-emission validation
 
 - `install_audit_drift_guard()` — `beforeEach` resets + `afterEach` zero-checks `audit_metadata_validation_failures` + `audit_unknown_event_type_failures` counters from `auth/audit_log_queries.ts`. Call once at the top of any `describe_db` block firing audit emits — production validation is fail-open, so without this any regression shipping a typo'd `event_type` or undeclared metadata field is silent. Pair with `await_pending_effects: true` (the `create_test_app` default) so fire-and-forget audit writes complete by response time.
-- `create_emit_ordering_audit_factory<E>(seq_ref, events_ref, build_inner)` — returns an `AuditFactory` wrapping `build_inner({db, log})` so every `emit` pushes `{kind: 'emit', at: seq.value++}` into a shared sequence + events array. Pass through `create_test_app({audit_factory: …})` — the test backend invokes it with its `{db, log}` and lands the wrapped emitter on `deps.audit`. Generic `E extends {kind: string; at: number}` so the events array typechecks against the caller's own `close` / custom marker shape. Pair with `create_recording_closer(seq_ref)` for close-vs-emit ordering tests. Scope is `emit` only — `emit_role_grant_target`, `emit_pool`, `notify` forward to the inner emitter unwrapped.
-- `AuditEmitMarker` — `{kind: 'emit'; at: number}`, the marker type pushed.
 - `create_recording_audit_emitter(calls_ref?)` — no-op `AuditEmitter` pushing every `emit` and `emit_pool` call into `calls`. Pass `calls_ref` to write into a caller-owned array; omit to let the helper allocate. Returns `{emitter, calls}` — destructure `emitter` as the `audit` dep and read `calls` to assert. Replaces per-file capturing emitters previously duplicated across `password_change.test.ts`, `audit_log.test.ts`, etc.
 - `RecordingAuditEmitter` — `{emitter: AuditEmitter; calls: Array<AuditLogInput>}`.
 
 ### `connection_closer_helpers.ts` — `ConnectionCloser` test doubles
 
-- `create_recording_closer(seq_ref?)` — `{closer, calls}`; every method on `closer` records `{method, id, at}` into `calls`. Pass `seq_ref` to share the sequence counter with `create_emit_ordering_audit_factory` so close + emit markers compose for ordering tests.
-- `assert_close_call(call, method, id)` — pins `{method, id}` on a recorded close call without baking in the `at: N` sequence number. Use at every "did the closer fire?" site; reserve `at: N` assertions for the dedicated ordering test paired with the capture helper.
-- `RecordedClose` — `{method: 'session' | 'token' | 'account', id, at}`.
+- `create_recording_closer()` — `{closer, calls}`; every method on `closer` records `{method, id}` into `calls` and closes nothing. To see a handler's closes, add it to the backend's closer (`ctx.deps.connection_closer.add(closer)`) or build the factory's deps with it. The closes are queued post-commit, so they have run by the time a `create_test_app` response is in hand (`await_pending_effects: true` flushes both queues).
+- `assert_close_call(call, method, id)` — pins `{method, id}` on a recorded close call; handles the missing-element case.
+- `RecordedClose` — `{method: 'session' | 'token' | 'account', id}`.
 - `RecordingCloser` — `{closer, calls}`.
 
 ## Database — `db.ts`
@@ -171,7 +169,7 @@ pre-keeper, lock unflipped), use `create_test_app_for_bootstrap` — pair with
 Types:
 
 - `TestAppServer extends AppBackend` — adds `account`, `actor`, `api_token`, `session_cookie`, `keyring`, `cleanup()`.
-- `TestAppServerOptions` — `session_options` (required), optional `db`, `db_type`, `migration_namespaces`, `password`, `username`, `password_value`, `roles`, `audit_factory`. `migration_namespaces` runs extra namespaces after auth in the auto-created PGlite (mirrors `create_app_backend`); mutually exclusive with `db` (caller-migrated) — passing both throws. The optional `audit_factory` defaults to `default_audit_factory` (no-listener `create_audit_emitter` over the test backend's `{db, log}`); pass a custom factory to compose `on_audit_event` / `audit_log_config`, wrap with `emit_decorator` (via `create_emit_ordering_audit_factory`), or otherwise replace the emitter. Mirrors `CreateAppBackendOptions` end-to-end — the previous `on_audit_event` / `audit_log_config` sugar was removed alongside the production rename.
+- `TestAppServerOptions` — `session_options` (required), optional `db`, `db_type`, `migration_namespaces`, `password`, `username`, `password_value`, `roles`, `audit_factory`. `migration_namespaces` runs extra namespaces after auth in the auto-created PGlite (mirrors `create_app_backend`); mutually exclusive with `db` (caller-migrated) — passing both throws. The optional `audit_factory` defaults to `default_audit_factory` (no-listener `create_audit_emitter` over the test backend's `{db, log}`); pass a custom factory to compose `on_audit_event` / `audit_log_config`, instrument `emit` with `emit_decorator`, or otherwise replace the emitter. Mirrors `CreateAppBackendOptions` end-to-end — the previous `on_audit_event` / `audit_log_config` sugar was removed alongside the production rename.
 - `CreateTestAppOptions extends TestAppServerOptions` — adds `create_route_specs` (required), `rpc_endpoints?: RpcEndpointsSuiteOption` (top-level only — single source of truth, symmetric with the suite-level option), `bootstrap?: BootstrapServerOptions` (top-level only — same precedent as `rpc_endpoints`), and `app_options?: SuiteAppOptions` (`Partial<AppServerOptions>` excluding the five fields the helper manages: `backend`, `session_options`, `create_route_specs`, `rpc_endpoints`, `bootstrap`).
 - `TestAccount` — `{account, actor, session_cookie, api_token, create_session_headers, create_bearer_headers}`.
 - `TestApp` — `{app, backend, surface_spec, surface, route_specs, create_session_headers, create_bearer_headers, create_daemon_token_headers, create_account, cleanup}`.
@@ -186,6 +184,11 @@ state (no rotation, keeper already set),
 the response returns so tests can assert on side effects inline), and silent
 logger. Override via `app_options`.
 
+`auth_cleanup` is left at its default, **off**, here and in
+`create_test_app_for_bootstrap`: a background pass would delete rows and
+write audit rows mid-test. A suite that opts in through `app_options` has the
+schedule stopped by `cleanup()`, which is the assembled server's `close`.
+
 A fresh Hono app is created on every call because middleware closures bind
 to the server's deps (db, keyring). Hono assembly is cheap (~10–50ms);
 PGlite WASM caching in `db.ts` is where the real savings are.
@@ -515,13 +518,14 @@ bootstrapped keeper) based on `method.auth`; keeper uses the daemon token.
 Per SSE route: open stream with matching auth, assert the
 `SSE_CONNECTED_COMMENT` comment, fire a consumer-supplied `trigger()`,
 validate the next `data:` frame as `{method, params}` against declared
-`EventSpec`s, then (by default) fire `POST /api/account/sessions/revoke-all`
-and assert the stream closes within 2s.
+`EventSpec`s, then (by default) dispatch the `account_session_revoke_all` RPC
+method and assert the stream closes within 2s.
 
 `SseRouteTestSpec` per route: `{path, trigger, event_specs?, assert_closes_on_revoke?}`.
-Pass `on_audit_event` on the suite options to wire a close-on-revoke guard
-(e.g. via `create_sse_auth_guard`) for consumer SSE registries — without it,
-the revoke assertion hangs because the guard never fires.
+A consumer registry closes on the revoke when its route joined it to the
+backend's closer (`ctx.deps.connection_closer.add(create_sse_connection_closer(registry))`)
+or when the suite's `on_audit_event` option wires a guard (e.g. `create_sse_auth_guard`); with
+neither, the revoke assertion fails.
 
 Frame reading is delegated to the shared `create_sse_frame_reader`
 (`transports/sse_frame_reader.ts`) — `\n\n` framing, a 2s per-read timeout
@@ -539,12 +543,12 @@ skipped (the Node test runtime has no `@hono/node-ws` adapter).
 
 Three layers:
 
-1. **Primitives** — `create_fake_ws()`, `create_fake_hono_context(opts)`, `create_stub_upgrade()`, `MinimalActionEnvironment`, `dispatch_ws_message(on_message, event, ws)`.
-2. **Harness** — `create_ws_test_harness({actions, transport?, heartbeat?, log?, on_socket_open?, on_socket_close?})` → `WsTestHarness`. `connect(identity?)` is async and resolves after `on_socket_open` completes, so broadcasts sent immediately after `await harness.connect()` reach the client. The harness threads its own `create_stub_db()` into the dispatcher's `db` slot so handlers declaring `side_effects: true` execute under the same transaction wrap they would in production (the stub's `transaction(fn)` synchronously calls `fn(stub_db)`); domain deps reach handlers via factory closures, the same way HTTP RPC factories already wire them. Audit fan-out runs through whatever `audit` emitter the consumer supplied to its action factory closure (typically `create_test_audit_emitter()` for unit harnesses).
+1. **Primitives** — `create_fake_ws()`, `create_fake_hono_context(opts)`, `create_stub_upgrade()`, `MinimalActionEnvironment`, `dispatch_ws_message(on_message, event, ws)`. The fake context sets the keys the production auth middleware sets — `AUTH_SESSION_TOKEN_HASH_KEY` included, as `hash_session_token(auth_session_id)` — because the dispatcher reads the credential through `get_resolved_auth(c)`; a hand-built upgrade context must do the same.
+2. **Harness** — `create_ws_test_harness({actions, transport?, heartbeat?, log?, on_socket_open?, on_socket_close?})` → `WsTestHarness`. `connect(identity?)` is async and resolves after the connection is admitted and `on_socket_open` completes, so broadcasts sent immediately after `await harness.connect()` reach the client. The harness pre-bakes its `RequestContext` (`TEST_CONTEXT_PRESET_KEY`), which also skips the admission credential re-read — there are no session or token rows behind a harness identity — so tests of the re-read itself drive `register_action_ws` with a real database and no preset (`src/test/actions/register_action_ws.admission.db.test.ts`). The harness threads its own `create_stub_db()` into the dispatcher's `db` slot so handlers declaring `side_effects: true` execute under the same transaction wrap they would in production (the stub's `transaction(fn)` synchronously calls `fn(stub_db)`); domain deps reach handlers via factory closures, the same way HTTP RPC factories already wire them. Audit fan-out runs through whatever `audit` emitter the consumer supplied to its action factory closure (typically `create_test_audit_emitter()` for unit harnesses).
 3. **Round-trip helpers** — predicates + wire-frame types live in `transports/ws_client.ts` (shared with the cross-process `ws_transport.ts` impl): `is_notification(method)`, `is_notification_with<P>(method, match)` (type-guard combinator — narrows `wait_for` return type), `is_response_for(id)`, `JsonrpcNotificationFrame<P>` / `JsonrpcSuccessResponseFrame<R>` / `JsonrpcErrorResponseFrame<D>` (typed wire-frame shapes distinct from the runtime Zod schemas in `http/jsonrpc.ts` — generic over `params` / `result` / `data` so tests narrow without casts). `build_broadcast_api<TApi>({harness, specs})` (in `ws_round_trip.ts`) wires a typed broadcast API against the harness transport.
 
 `WsClient` (in `transports/ws_client.ts`):
-`{send, request<R>, close, messages, wait_for, wait_for_close, close_code}`.
+`{send, request<R>, close, messages, wait_for, wait_for_close, close_code, close_reason}`.
 The harness's `connect()` returns this shape; the cross-process
 `create_ws_transport` in `transports/ws_transport.ts` implements the same
 interface so assertion helpers and suite bodies work against either impl.
@@ -553,7 +557,9 @@ socket within the timeout, `false` on timeout (and `true` immediately when
 already closed) — the signal for server-initiated close (e.g. an auth-guard
 revocation), distinct from client-initiated `close()`. Mirrors the SSE frame
 reader's `wait_for_close`. `close_code` is the connection's close code once
-closed (`1006` for a drop without a close frame), `null` while open.
+closed (`1006` for a drop without a close frame), `null` while open;
+`close_reason` is the text sent with it (empty when the close carried none),
+`null` while open.
 `request` throws with code + message + data on error frames (so asserting `result.foo` on a
 failed request surfaces the real cause, not a `Cannot read property 'foo'
 of undefined`). `wait_for(predicate, timeout_ms?)` checks already-received
@@ -915,9 +921,10 @@ source of truth for wire-shape conformance.
 - `testing/cross_backend/capabilities.ts` — `BackendCapabilities` vocabulary
   (the **gating** flags `ws` / `sse` / `cell_crud` / `cell_relations` /
   `cell_gated_create` / `account_lifecycle` / `fact_serving` / `ready` /
-  `account_status` / `oversized_reject_closes_connection` / `peer_request` —
+  `account_status` / `oversized_reject_closes_connection` / `peer_request` /
+  `ws_handshake_pipelining` / `ws_account_actions` / `ws_self_revocation_reply` —
   each has a `test_if`
-  reader; `peer_request` (server-initiated requests — the ActionPeer
+  reader (`ws_self_revocation_reply` forks one case's assertion instead); `peer_request` (server-initiated requests — the ActionPeer
   `peer/ping` round-trip) is `true` for both the Rust spine and the TS spine
   (`BackendWebsocketTransport.request_connection`); `ts_default_capabilities`
   keeps it `false` like sse/ready until a backend wires the `peer/ping` HTTP +
@@ -962,6 +969,17 @@ source of truth for wire-shape conformance.
   smuggling probe (`true` Node/Deno/Rust — they close on an oversized reject;
   `false` Bun — `Bun.serve` drains + keepalives but frames correctly, so the
   suite's no-desync half still runs).
+  `ws_handshake_pipelining` gates the WS round-trip suite's
+  frames-with-the-handshake case (`true` Node/Deno/Rust — frames written in the
+  same TCP write as the upgrade request reach the socket; `false` Bun, whose
+  HTTP parser answers such a request `400`, and `false` in-process, where there
+  is no socket to write raw bytes to).
+  `ws_account_actions` gates the WS round-trip suite's self-revocation case
+  (the WS endpoint mounts the account actions — `true` on fuz_app's own spine
+  presets, `false` in the family defaults), and `ws_self_revocation_reply`
+  says what that case requires: the reply ahead of the close (`true`, the TS
+  family) or the close alone (`false`, the Rust family, whose socket loop
+  drops the response once the connection is closed — a recorded divergence).
 
 ### `cross_backend/standard.ts` — `describe_standard_cross_process_tests`
 
@@ -1084,20 +1102,32 @@ base_url, ws_path, origin?, rpc_path?, max_message_bytes?})` opens a live
 `WebSocket` via `create_ws_transport` (the `ws` npm package) and asserts
 cases against the upgrade stack `register_ws_endpoint` wires (origin →
 `require_auth` → dispatch): authed upgrade round-trips `heartbeat`,
+requests sent the moment the socket opens are all answered (both spines admit a
+connection only after re-reading its credential; frames that arrive first wait
+for that, they are not dropped) — and, gated on
+`capabilities.ws_handshake_pipelining`, the same with the ordering forced:
+frames written in the same TCP write as the upgrade request (`connect_raw_ws`)
+are all answered,
 `heartbeat` admits only the parameterless shapes (a declared param →
 `invalid_params`), a message past `max_message_bytes` (default
 `DEFAULT_WS_MAX_MESSAGE_BYTES`) closes with `WS_CLOSE_MESSAGE_TOO_BIG`,
 anonymous upgrade refused, disallowed-origin upgrade refused, and — gated on
 `rpc_path` — a live socket drops when the account's sessions are revoked
-mid-connection (`account_session_revoke_all` over the keeper session channel
-emits `session_revoke_all`, which `create_ws_auth_guard` closes on; asserted
-via `WsClient.wait_for_close`). Per-connection auth is enforced **at upgrade
+mid-connection (`account_session_revoke_all` over the keeper session channel;
+asserted via `WsClient.wait_for_close`) and when its account is deleted
+(`account_delete` by the keeper, also gated on
+`capabilities.account_lifecycle`; the close code is
+`WS_CLOSE_SESSION_REVOKED`). Per-connection auth is enforced **at upgrade
 time**, so the negative upgrade cases assert the upgrade itself rejects, not
-a per-message error; the close-on-revoke case proves the audit-fed guard is
-the revocation seam for an already-open socket, since per-message dispatch
-never re-checks credential validity. Omit `rpc_path` to skip the close case
-(consumers without the standard account actions on their RPC endpoint).
-**Consumer-agnostic** — it drives only the `heartbeat` protocol action
+a per-message error; the close cases prove a revocation closes an
+already-open socket, since per-message dispatch never re-checks credential
+validity. Omit `rpc_path` to skip the close cases (consumers without the
+standard account and admin actions on their RPC endpoint). One case is gated
+on `capabilities.ws_account_actions` (the WS endpoint mounts the account
+actions): a socket that revokes its own sessions over that socket is closed
+with `WS_CLOSE_SESSION_REVOKED`, and — where the backend declares
+`capabilities.ws_self_revocation_reply` — reads the reply first.
+Otherwise **consumer-agnostic** — it drives only the `heartbeat` protocol action
 (guaranteed on every WS endpoint by `assert_ws_endpoints_include_protocol_actions`),
 so it validates the transport without touching domain WS methods. Gated on
 `capabilities.ws`; cross-process only (needs a real bound socket — wire from
@@ -1114,7 +1144,9 @@ the seven server-initiated notifications (`received` → recipient,
 superseded sibling's grantor on **both** the accept- and revoke-cascade paths).
 `describe_role_grant_offer_notification_ws_tests({setup_test, capabilities,
 base_url, ws_path})` opens the affected counterparty's socket
-(`create_ws_transport`), drives the lifecycle RPC over `fixture.transport`, then
+(`create_admitted_ws_transport` — a targeted notification reaches only an
+admitted connection, and the handshake alone doesn't say it is one), drives the
+lifecycle RPC over `fixture.transport`, then
 strict-parses the delivered frame against its canonical params schema from
 `auth/role_grant_offer_notifications.ts` (the guard against serialization drift —
 field / null / datetime / the flat revoke shape / the supersede `reason` +
@@ -1159,6 +1191,48 @@ action (manifest-excluded), so parity is behavioral here, not via the manifest
 gate. Cross-process only; fuz_app's own wiring is
 `src/test/cross_backend/peer_ping_ws.cross.test.ts`.
 
+### `cross_backend/ws_connection_cap.ts` — `describe_ws_connection_cap_cross_tests`
+
+Real-upgrade parity for the **per-account WebSocket connection cap** — the
+evict-oldest policy both spines apply (`BackendWebsocketTransport`'s
+`max_connections_per_account`, the Rust `fuz_realtime` `ConnectionRegistry`).
+The close code, its reason, and which socket closes are wire contract — a
+client reads `WS_CLOSE_CONNECTION_LIMIT` as "superseded, don't reconnect" — so
+this is the pin that runs on both.
+`describe_ws_connection_cap_cross_tests({setup_test, capabilities, base_url,
+ws_path, origin?, max_connections_per_account?})` opens every socket with the
+fresh-per-test keeper's session cookies (one account), each answering a
+`heartbeat` before the next opens (`create_admitted_ws_transport`) so the
+backend registered them in order and
+"oldest" names the same socket on both spines. Cases: one connection past the
+cap closes exactly the oldest with `WS_CLOSE_CONNECTION_LIMIT` + reason
+`connection limit` while every other socket, the newest included, keeps
+dispatching — and the session then upgrades again (a revoked session couldn't),
+superseding the next-oldest; and a socket held open while a cap's worth of
+others open and close in sequence is never evicted (a backend that leaks closed
+connections in its registry counts them toward the cap, which is what this
+catches). `max_connections_per_account` defaults to
+`DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT`, the cap both spines apply unless
+overridden; pass the consumer's value when it sets one, `null` (cap disabled)
+to skip. **Consumer-agnostic** like the WS round-trip suite (`heartbeat` only).
+A separate call rather than more cases on that suite because each case opens
+more than a cap's worth of real sockets. Gated on `capabilities.ws`;
+cross-process only. fuz_app's own wiring is
+`src/test/cross_backend/ws_connection_cap.cross.test.ts`.
+
+### `cross_backend/session_cap.ts` — `describe_session_cap_cross_tests`
+
+Parity for the per-account session cap over real HTTP: logging in past
+`max_sessions` (default `DEFAULT_MAX_SESSIONS`) never refuses a login and
+evicts the oldest session.
+`describe_session_cap_cross_tests({setup_test, max_sessions?, login_path?,
+status_path?, ws?})` — pass `ws` (`{base_url, ws_path, origin?}`) to also
+assert that the evicted session's socket is closed with
+`WS_CLOSE_SESSION_REVOKED` once the evicting login commits; omitted, that case
+is skipped, so a caller passes it only for a backend with `capabilities.ws`.
+Cross-process only. fuz_app's own wiring is
+`src/test/cross_backend/session_cap.cross.test.ts`.
+
 ### `cross_backend/sse_round_trip.ts` — `describe_cross_process_sse_tests`
 
 Cross-process counterpart to the in-process `sse_round_trip.ts` harness —
@@ -1167,23 +1241,26 @@ endpoint via `create_sse_transport` (built-in `fetch` + `TextDecoder`, no
 dep), threading the fresh-per-test keeper's session cookie. Kept a separate
 call (not folded into `describe_standard_cross_process_tests`) for the same
 reason the WS suite is — it needs raw `base_url` / `sse_path` the standard
-bundle doesn't carry. Up to three cases, mirroring the in-process audit-log
-self-test: the stream emits the `: connected` comment; a minted secondary's
-sessions are revoked over the keeper's admin channel (`admin_session_revoke_all`),
+bundle doesn't carry. The cases mirror the in-process audit-log self-test:
+the stream emits the `: connected` comment; a minted secondary's sessions are
+revoked over the keeper's admin channel (`admin_session_revoke_all`),
 broadcasting one `session_revoke_all` audit `data:` frame **without** closing
 the keeper's stream (target ≠ subscriber — secondary minted before the stream
-opens so its `create_account` audit events stay off it); and the subscriber's
-_own_ sessions are revoked (`account_session_revoke_all`) so the audit guard
-drops the live stream (asserted via `SseTransport.wait_for_close`). The
-data-frame + close cases gate on `rpc_path` (they drive the standard
-account/admin actions); all cases gate on `capabilities.sse`. Cross-process
-only — wire from a `*.cross.test.ts`. fuz*app's own wiring is
-`src/test/cross_backend/sse.cross.test.ts`; only the TS spines advertise
-`sse` (they wire `audit_log_sse`), so the Rust `spine_stub` cases `.skip`.
-That file also registers one `xfail_until` (only when `sse: false`) asserting
-the stream \_can't* open on a spine without SSE — a self-cleaning tripwire for
-the spine that should grow it, distinct from the consumer-legit capability
-skip the shared suite emits.
+opens so its `create_account` audit events stay off it); the subscriber's
+_own_ sessions are revoked, all of them (`account_session_revoke_all`, the
+account-wide close) and then just the one (`account_session_revoke`, the
+session-scoped close), each dropping the live stream (asserted via
+`SseTransport.wait_for_close`); the keeper soft-deletes a second admin whose
+stream is open (`account_delete`, also gated on
+`capabilities.account_lifecycle`), dropping it; and one stream past the per-session cap
+(`max_per_scope`, default `AUDIT_LOG_SSE_MAX_PER_SCOPE`; `null` skips) on one
+session closes the oldest and leaves the rest open. The data-frame + close
+cases gate on `rpc_path` (they drive the standard account/admin actions); all
+cases gate on `capabilities.sse`. Cross-process only — wire from a
+`*.cross.test.ts`. fuz_app's own wiring is
+`src/test/cross_backend/sse.cross.test.ts`, which runs on every backend — the
+TS spines wire `audit_log_sse` and the Rust `spine_stub` serves the same
+stream.
 
 ### `cross_backend/cell_crud.ts` + `cell_relations.ts` + `cell_gated_create.ts` — cell parity suites
 
@@ -1292,7 +1369,8 @@ are `src/test/auth/cell_crud_parity.db.test.ts`
   transport carries the keeper session cookie in its jar after this call
   resolves.
 - `testing/transports/ws_client.ts` — shared `WsClient` interface (`send` /
-  `request` / `close` / `messages` / `wait_for` / `wait_for_close` / `close_code`),
+  `request` / `close` / `messages` / `wait_for` / `wait_for_close` / `close_code` /
+  `close_reason`),
   wire-frame types, and
   predicates (`is_notification`, `is_response_for`, ...). Both in-process
   (`ws_round_trip.ts`) and cross-process (`ws_transport.ts`) impls satisfy
@@ -1309,6 +1387,20 @@ are `src/test/auth/cell_crud_parity.db.test.ts`
   Threads the keeper cookie onto the upgrade so per-action auth succeeds on
   the first message. `on_request` (attached at construction, before the upgrade
   completes) answers server-initiated requests via the shared `deliver_inbound`.
+  An open socket is not yet an *admitted* connection — both spines answer the
+  handshake, then re-read the credential, then admit, and deliver no
+  server-initiated message until then. `create_admitted_ws_transport(options)`
+  opens and round-trips `heartbeat` (response id `WS_ADMISSION_PROBE_ID`) so the
+  connection is admitted when it resolves; suites that wait for a push, or need
+  connections registered in a known order, open through it.
+- `testing/transports/ws_raw_client.ts` — `connect_raw_ws({port, hostname?, path, headers?, pipelined?})`
+  → `RawWsClient` (`{frames, send_text, wait_for, destroy}`), a WebSocket client
+  over a raw `node:net` socket for the two things a client library can't do:
+  **withhold the close frame** (it never answers one) and put frames in the
+  server's hands **with the handshake** (`pipelined` — written in the same TCP
+  write as the upgrade request, so before the connection can have been
+  admitted). Small unfragmented text frames only. Helpers `is_raw_ws_close`,
+  `raw_ws_close_code`, `RAW_WS_OPCODE_TEXT` / `_CLOSE`.
 - `testing/transports/sse_frame_reader.ts` — `create_sse_frame_reader(reader, default_timeout_ms?)`,
   the transport-agnostic SSE framing core over a
   `ReadableStreamDefaultReader<Uint8Array>`: `\n\n` framing, per-read timeout,
@@ -1658,7 +1750,7 @@ re-roll the serve / daemon-info / WS-attach / drain boilerplate:
 - `testing/cross_backend/full_spine_mount.ts` — `build_full_spine_rpc_actions(deps, options)` / `full_spine_rpc_endpoints(ctx, options)` — the **full** live RPC mount: the declared bundle **plus** the off-declared-surface families the binary live-mounts (`_testing_*` backdoors, the cell verb set, the opt-in `actor_lookup` / `actor_search` resolvers). Single-sources what was an inline assembly in `testing_spine_server.ts`, so the binary and the `spine_method_coverage` reconciliation test build the same list. Also `$lib`-free.
 - `testing/cross_backend/ts_spine_backend_config.ts` — `ts_spine_node_backend_config()` / `ts_spine_deno_backend_config()` / `ts_spine_bun_backend_config()` presets (in-memory PGlite, no external infra), the TS analog of `rust_spine_stub_backend_config()`.
 
-fuz_app's own binary wiring (`src/test/cross_backend/testing_spine_server{,_node,_deno,_bun}.ts`) is the worked example: ~one `build_app` over `create_app_backend` + `create_app_server` + `full_spine_rpc_endpoints` + a WS mount, reusing `default_spine_surface`. The `_node`/`_deno`/`_bun` entries differ only in which adapter they wire — `build_spine_app` is runtime-agnostic.
+fuz_app's own binary wiring (`src/test/cross_backend/testing_spine_server{,_node,_deno,_bun}.ts`) is the worked example: ~one `build_app` over `create_app_backend` + `create_app_server` + `full_spine_rpc_endpoints` + a WS mount, reusing `default_spine_surface`. The `_node`/`_deno`/`_bun` entries differ only in which adapter they wire — `build_spine_app` is runtime-agnostic. It leaves `create_app_server`'s `auth_cleanup` off, as the Rust `testing_spine_stub` leaves its twin unscheduled: a background pass would delete rows and write audit rows under a running suite. A consumer's cross-process test binary may schedule it when nothing its suites seed is already expired (the conformance table's `expired_session` principal seeds a backdated session row); an in-process harness leaves it off.
 
 ### Live-method coverage reconciliation — `method_coverage.ts`
 
@@ -1687,8 +1779,8 @@ no-DB reconciliation test `spine_method_coverage.test.ts`, which enumerates
 The in-process `ws_round_trip` harness stays (it drives the dispatcher
 against a fake upgrade, no wire), but the real-upgrade coverage now lives in
 the cross-process `cross_backend/ws_round_trip.ts` suite below — including
-close-on-revoke (`WsClient.wait_for_close` asserts the audit-guard drops a
-live socket on `session_revoke_all`).
+close-on-revoke (`WsClient.wait_for_close` asserts a live socket is dropped
+once `account_session_revoke_all` commits).
 
 `audit_completeness` is in-process by design (FK-structural introspection
 beyond the `audit_log_list` RPC reads — structurally in-process).