@fuzdev/fuz_app 0.117.1 → 0.119.0

package/dist/actions/CLAUDE.md

@@ -234,6 +234,12 @@ e.g. when consumers like zzz throw their own `ThrownJsonrpcError`)
 preserves code + data verbatim. Generic throws become `internal_error` 500;
 message is the raw error under `DEV`, "internal server error" otherwise.
 
+A result `c.json` cannot serialize (a `bigint`, a cycle) answers the same
+`internal_error` 500 rather than throwing. By then `perform_action` has
+committed, and a throw would have the route wrapper
+(`dispatch_with_post_commit_rollback`) discard the handler's
+`post_commit_effects` — the connection closes of a revocation that did land.
+
 ### Per-request handler shape
 
 Unified across HTTP RPC + WS via `ActionContext`:
@@ -348,16 +354,19 @@ and `allow_fallback: boolean` (default `true`). Explicit
 
 ### WS close codes (`actions/transports.ts`)
 
-- `WS_CLOSE_SESSION_REVOKED = 4001` — server revoked auth; client enters permanent `revoked` state, no reconnect.
+- `WS_CLOSE_SESSION_REVOKED = 4001` — server revoked auth (reason `WS_CLOSE_SESSION_REVOKED_REASON`, `Session revoked`); client enters permanent `revoked` state, no reconnect. Also the close for an upgrade refused at admission because its credential was revoked mid-upgrade — indistinguishable on the wire by design.
 - `WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT = 4002` — client observed receive-silence past its receive timeout (`resolve_heartbeat_receive_timeout`).
 - `WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT = 4003` — server observed receive-silence past `DEFAULT_SERVER_HEARTBEAT_TIMEOUT` (60s).
+- `WS_CLOSE_CONNECTION_LIMIT = 4004` — server closed this socket to admit a newer one on the same account, past the per-account connection cap (reason `connection limit`). Not a revocation: the client stays `closed` with `superseded` set and no reconnect, until `connect()` is called. Twin of the Rust spine's constant.
 - `WS_CLOSE_MESSAGE_TOO_BIG = 1009` — server received a message over its `max_message_bytes` cap (RFC 6455 "Message Too Big").
+- `WS_CLOSE_POLICY_VIOLATION = 1008` — a socket sent too much while it was still opening (before admission and `on_socket_open` completed): past `MAX_PRE_ADMISSION_FRAMES` frames or the `PRE_ADMISSION_QUEUE_BYTES_FACTOR` byte budget.
+- `WS_CLOSE_INTERNAL_ERROR = 1011` — the admission credential re-check itself failed (reason `internal error`), `on_socket_open` threw (reason `socket bootstrap failed`), or the socket's connection was removed from the transport without a close (reason `connection unregistered`). Not a revocation: the client reconnects under its ordinary backoff. Twin of the Rust spine's constant.
 
 ### Transport modules
 
 - `actions/transports_http.ts` — `frontend_http_rpc`; thin `fetch` adapter, POST default, GET on `has_side_effects(method) === false`.
 - `actions/transports_ws.ts` — `frontend_websocket_rpc`; thin adapter over `WebsocketRpcConnection` (default impl: `FrontendWebsocketClient`). Answers inbound server→client requests: a built-in `peer_ping_responder` for `peer/ping` (zero-wiring liveness), any other request routed through `peer.receive` with the response sent back over the socket (the frontend half of the ActionPeer receive loop).
-- `actions/transports_ws_backend.ts` — `backend_websocket_rpc`; server-side WS with session tracking; satisfies `FilterableBroadcastTransport`. Server→client requests via `request_connection` (correlation registry in `actions/peer_request.ts`).
+- `actions/transports_ws_backend.ts` — `backend_websocket_rpc`; server-side WS with session tracking, two-phase registration (`register_pending` / `admit`), and the per-account cap; satisfies `FilterableBroadcastTransport`. Server→client requests via `request_connection` (correlation registry in `actions/peer_request.ts`).
 
 `FrontendHttpTransport` on non-OK HTTP returns the body as-is when it's a
 JSON-RPC error response for the request (same `id` compared as strings since GET sends it as a query param, or `null`) — the
@@ -390,22 +399,90 @@ client; `null` skips the client-side measurement.
 
 ### `BackendWebsocketTransport` — server-side WS state
 
-Three aligned maps keyed by `connection_id` (branded `Uuid`):
-
-- `#connections: Map<Uuid, WSContext>` — id → socket
-- `#connection_ids: WeakMap<WSContext, Uuid>` — socket → id (reverse)
-- `#connection_identities: Map<Uuid, ConnectionIdentity>` — id → `{token_hash, account_id, api_token_id}` (session sets `token_hash`, bearer sets `api_token_id`, daemon-token sets both null)
+One map keyed by `connection_id` (branded `Uuid`), in registration order:
+`#connections: Map<Uuid, ConnectionEntry>`, each entry `{ws, identity,
+admitted, abort_controller}`. `identity` is the `ConnectionIdentity`
+`{token_hash, account_id, api_token_id}` (session sets `token_hash`, bearer
+sets `api_token_id`, daemon-token sets both null).
+
+The id is the connection's only handle — `register_pending` / `add_connection`
+return it and `admit` / `remove_connection` / `is_registered` take it. There is
+no socket → id lookup: a runtime adapter may hand each socket event its own
+`WSContext` (`hono/bun` builds one per event), so the object a close event
+carries can't identify the connection. `register_action_ws` captures the id on
+open and removes by it.
+
+**Two-phase registration.** An upgrade resolves its credential before the
+socket exists, and a revocation closes only the connections *registered* under
+what it revoked — so a one-step registration leaves a window in which a
+revocation closes nothing and the socket is then admitted on a dead credential.
+The transport splits registration to close it (the twin of the Rust
+`fuz_realtime` `ConnectionRegistry`, same method names):
+
+- `register_pending(ws, token_hash, account_id, api_token_id?, abort_controller?)`
+  inserts the entry **un-admitted**. Every `close_sockets_for_*` matches it
+  from that instant. Otherwise it is inert: no `send` broadcast,
+  `broadcast_filtered` (the predicate never sees it), `send_to_account`, or
+  `request_connection` (`connection_gone`) reaches it; `get_connection_count`,
+  `is_ready`, and `is_registered` don't see it
+  (`get_pending_connection_count` does); the cap neither counts nor evicts it.
+- the caller re-reads the credential (`revalidate_resolved_auth`).
+- `admit(connection_id)` returns `false` when the entry is gone — a revocation
+  closed it while pending — and evicts nothing; otherwise it enforces the cap
+  (counting admitted connections only) and marks the entry admitted.
+
+Nothing is queued for a pending entry, so a server-initiated message sent
+between the handshake and admission is not delivered — the same as one sent
+before the handshake. `add_connection` is the one-step form (register and admit
+together) for a connection with nothing revocable behind it: tests and
+harnesses that register a socket directly. An upgrade that authenticated a session or token
+uses the two-phase form.
+
+**Abort at close time.** The `abort_controller` passed at registration is the
+socket's per-connection controller. The transport aborts it when it closes the
+connection — a revocation or a cap eviction — so in-flight handlers see
+`signal.aborted` at once, not when the close handshake lands.
+`remove_connection` only removes: it neither closes nor aborts.
+
+**Per-account connection cap.** `new BackendWebsocketTransport({max_connections_per_account})`
+— default `DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT` (50), `null` disables, anything
+but a positive integer throws. The policy is **evict-oldest**: admission always
+admits the new connection, first closing the account's oldest admitted ones
+(registration order) with `WS_CLOSE_CONNECTION_LIMIT` so the account never
+holds more than the cap. It keys on `account_id` across every credential type —
+session, bearer, and daemon-token connections all count, none exempt. Refusing
+the newcomer instead would let half-open sockets lock a user out with their
+own dead connections, and let a stolen credential hold every slot ahead of the
+real user. The check runs at **admission** (`admit`, or `add_connection`),
+which `register_action_ws` reaches in `onOpen` — after every upgrade gate
+(origin, auth, token scope, role) and the credential re-read — so a refused or
+just-revoked request never closes someone's socket. An evicted connection
+leaves the transport's map at once — no broadcast or peer request reaches it,
+its pending peer requests drain as `connection_gone`, it stops counting toward
+the cap, its controller is aborted, and `register_action_ws` dispatches nothing
+more on it — while the socket itself is only closed once the close handshake
+completes. Its `on_socket_close` fires when the close lands, and the
+`remove_connection` before it is a no-op. An eviction logs
+`ws: connection cap closed oldest` at
+info with `{account_id, closed, max}` (the Rust spine's line) through the
+transport's `log` (a `[ws]` logger when unset, `null` silences;
+`register_action_ws` passes its own to the transport it creates). The cap is per transport:
+endpoints sharing one transport share one count per account. The twin of the
+Rust `fuz_realtime` `ConnectionRegistry`'s cap — same default, same policy,
+same close code and reason — pinned on both by the
+`describe_ws_connection_cap_cross_tests` suite.
 
 Targeted closure (all return socket count closed, use
-`WS_CLOSE_SESSION_REVOKED`):
+`WS_CLOSE_SESSION_REVOKED`, match pending and admitted entries alike, and abort
+each closed connection's controller):
 
 - `close_sockets_for_session(token_hash)`
 - `close_sockets_for_token(api_token_id)`
 - `close_sockets_for_account(account_id)` — coarse, covers session + bearer + daemon-token
 
-Fan-out: `send(notification)` broadcasts to every connection;
-`broadcast_filtered(message, predicate)` runs per-connection ACL predicate
-over `ConnectionIdentity`; `send_to_account` wraps `broadcast_filtered` and
+Fan-out, to admitted connections only: `send(notification)` broadcasts to every
+connection; `broadcast_filtered(message, predicate)` runs per-connection ACL
+predicate over `ConnectionIdentity`; `send_to_account` wraps `broadcast_filtered` and
 structurally satisfies `NotificationSender` (see `auth/CLAUDE.md` §WS
 notifications). `send(request)` is a misuse (a request has no single
 broadcast target) and returns an error envelope.
@@ -434,60 +511,101 @@ Return values are bookkeeping, not delivery receipts — `0` means no live
 sockets, non-zero means `ws.send` did not throw. Durable delivery requires
 persistence + rehydration by the consumer.
 
-## WS auth guard (`actions/transports_ws_auth_guard.ts`)
-
-Closes WS sockets on audit revoke events — per-message dispatch doesn't
-re-check session/token validity, so this guard is the revocation seam for
-open connections.
-
-`create_ws_auth_guard(transport, log)` returns an `on_audit_event` callback.
-For standard WS endpoints mounted via `AppServerOptions.ws_endpoints`,
-`create_app_server` registers this guard via `backend.deps.audit.add_listener`
-automatically (per `WsEndpointSpec.auth_guard`). For custom wiring, register
-inside the consumer's `audit_factory` body.
-
-`ws_disconnect_event_types` (ReadonlySet): `session_revoke`, `token_revoke`,
-`session_revoke_all`, `token_revoke_all`, `password_change`.
-`role_grant_revoke` is intentionally **omitted** — the WS transport doesn't
-track per-connection role requirements, so role-scoped disconnection would
-require either closing all sockets (too aggressive) or new per-connection
-role tracking (out of scope). Consumers that need it compose their own
-callback.
-
-`outcome === 'failure'` events are ignored — they carry attacker-controlled
-identifiers. Reacting to them would let an authenticated caller close
-another user's socket by guessing a session hash or token id.
-
-`create_ws_logout_closer(transport, log)` is the sibling helper for
-user-initiated `logout` events — kept separate because
-`ws_disconnect_event_types` deliberately omits `logout` (admin-initiated
-revocations use `session_revoke`, while `logout` is the user-initiated
-case). Closes via `close_sockets_for_account(event.account_id)`.
-
 ## Connection closer (`actions/connection_closer.ts`)
 
-Narrow structural capability for handler-side eager WS socket closure on
-revocation — belt+suspenders layer that complements the audit-listener
-guards above.
+A WebSocket and an SSE stream are authorized once, at open, so a revocation
+takes effect on an open connection only when something closes it.
+`ConnectionCloser` is that capability — the twin of the Rust spine's
+`SocketRevoker`:
 
 ```ts
 interface ConnectionCloser {
 	close_sockets_for_session: (session_token_hash: string) => number;
 	close_sockets_for_token: (api_token_id: string) => number;
-	close_sockets_for_account: (account_id: string) => number;
+	close_sockets_for_account: (account_id: Uuid) => number;
 }
 ```
 
-`BackendWebsocketTransport` satisfies this structurally — consumers pass
-the transport instance directly (same shape as `NotificationSender`). Wired
-into `AccountRouteOptions.connection_closer` (logout / password),
-`AccountActionOptions.connection_closer` (session/token revoke), and
-`AdminActionOptions.connection_closer` (admin revoke-all). Each handler
-calls the appropriate `close_sockets_for_*` synchronously **before** the
-audit emit so revocation lands even on audit INSERT failure. Failure
-outcomes (`revoked: false`, 404 not-found) skip the eager close — mirrors
-the listener's `outcome === 'failure'` guard so attacker-guessable ids can
-never target arbitrary sockets.
+`BackendWebsocketTransport` satisfies it structurally;
+`create_sse_connection_closer(registry)` (`realtime/sse_auth_guard.ts`) adapts
+a `SubscriberRegistry`. Closing is idempotent and synchronous.
+
+**Every revocation closes after its commit.** A handler never calls a closer
+inline: it calls `queue_connection_close(ctx, deps.connection_closer, target)`,
+which puts the close on the request's post-commit queue (`emit_after_commit`).
+The close runs once the handler's transaction has committed and is discarded
+when the handler throws — a rolled-back revocation closes nothing. `target` is
+a `ConnectionCloseTarget` (`{kind: 'session', session_token_hash}` /
+`{kind: 'token', api_token_id}` / `{kind: 'account', account_id}`);
+`close_connections(closer, target)` is the immediate form the queue runs. Twin
+of `queue_socket_close` / `SocketCloseTarget`.
+
+The order is load-bearing for admission: a connection registers, then re-reads
+its credential, so a close that missed the registration must belong to a
+revocation the re-read can see — true only if the close came after the commit
+(../../../docs/security.md §Closing on Revocation).
+
+The close does not depend on the audit write, which is pool-routed and
+fail-open. Failure outcomes (`revoked: false`, a 404) queue no close — they
+carry caller-supplied ids.
+
+**One closer for every transport.** `create_realtime_closer()` returns a
+`RealtimeCloser` — a `ConnectionCloser` plus `add(closer)` (idempotent by
+reference) — whose every close fans out to each member and returns the sum.
+`create_app_backend` puts one on `AppDeps.connection_closer`; `create_app_server`
+adds each mounted WS transport and the audit stream registry. Twin of
+`RealtimeRevoker`. A member that throws does not stop the fan-out — every
+member is called, then the first error is thrown for the caller to log;
+`BackendWebsocketTransport` and `SubscriberRegistry.close_by_identity` treat a
+throwing socket or stream the same way. `noop_connection_closer` is a `ConnectionCloser` that closes
+nothing, for hand-built action-factory deps on a backend with no
+live-connection surface.
+
+It is required where it is read, so it can't be forgotten:
+`RevokingActionFactoryDeps.connection_closer` (`create_account_actions`,
+`create_admin_actions`, `create_standard_rpc_actions`), `AppDeps` /
+`RouteFactoryDeps` (`create_account_route_specs`),
+`AuthCleanupDeps.connection_closer` (the auth cleanup's session sweep closes
+the connections of each expired session it deletes — `auth/CLAUDE.md`
+§Cleanup), and the
+`connection_closer: RealtimeCloser | null` option of `register_action_ws` /
+`register_ws_endpoint` / `create_audit_log_sse`, which add their transport to it
+(`null` is the explicit opt-out).
+
+## WS auth guard (`actions/transports_ws_auth_guard.ts`)
+
+The audit-listener half of revocation: `create_ws_auth_guard(closer, log)`
+returns an `on_audit_event` callback that repeats a revocation's close when its
+audit row is announced. It covers a revocation emitted by code that holds no
+closer; for the builtin handlers it is a repeat of the close they already
+queued. A success row is announced only after its request's transaction commits
+(`auth/CLAUDE.md` §Audit emitter), so the guard's close is post-commit too. Its
+closes reach a connection still pending admission.
+
+`closer` is any `ConnectionCloser` — a `BackendWebsocketTransport`, or a
+`RealtimeCloser` to cover every transport from one listener. For standard WS
+endpoints mounted via `AppServerOptions.ws_endpoints`, `create_app_server`
+registers the guard via `backend.deps.audit.add_listener` automatically (per
+`WsEndpointSpec.auth_guard`). For custom wiring, register inside the consumer's
+`audit_factory` body.
+
+It dispatches on the `RevocationScope` each event declares in
+`audit_event_revocation_scopes` (`auth/audit_log_schema.ts`), the table the SSE
+guard reads too — one declaration, so the two can't drift:
+
+- `session` (`session_revoke`) → `close_sockets_for_session(metadata.session_id)`
+- `token` (`token_revoke`) → `close_sockets_for_token(metadata.token_id)`
+- `account` (`session_revoke_all`, `token_revoke_all`, `password_change`,
+  `logout`, `account_delete`, `account_purge`) →
+  `close_sockets_for_account(target_account_id ?? account_id)`
+- `role` (`role_grant_revoke`) → nothing, deliberately: per-message dispatch
+  re-authorizes, so the next message is refused. The SSE guard closes here.
+- `none` → nothing — every other event, and any event type fuz_app doesn't
+  define
+
+`outcome === 'failure'` events are ignored — they carry attacker-controlled
+identifiers. Reacting to them would let an authenticated caller close
+another user's socket by guessing a session hash or token id.
 
 ## WebSocket dispatch — three layered entry points
 
@@ -508,10 +626,19 @@ but `upgradeWebSocket` is missing. A factory returning `[]` does NOT trip
 the check, so feature-flag gated WS surfaces stay safe.
 
 `WsEndpointSpec` fields: `path`, `allowed_origins`, `actions`,
-`required_roles?`, `transport?`, `heartbeat?`, `artificial_delay?`, `max_message_bytes?`,
+`required_roles?`, `transport?`, `max_connections_per_account?`, `heartbeat?`,
+`artificial_delay?`, `max_message_bytes?`,
 `on_socket_open?`, `on_socket_close?`, `auth_guard?` (default `true`,
 deduped by reference identity via `WeakSet<BackendWebsocketTransport>`),
-`extra_audit_handlers?`.
+`extra_audit_handlers?`. Every mounted transport is added to
+`deps.connection_closer`, whatever `auth_guard` says — the flag opts out of
+the audit listener, not of the handlers' closes.
+
+`max_connections_per_account` sets the per-account connection cap on the
+transport the mount creates (`RegisterActionWsOptions` carries the same field).
+It throws alongside `transport` — a supplied transport carries its own cap, set
+where it was constructed, and an option that silently did nothing would read as
+enforced.
 
 Mounted transport reachable at `app_server.ws_endpoints[path]`
 (`Readonly<Record<string, BackendWebsocketTransport>>`). Duplicate paths
@@ -542,7 +669,8 @@ Composes the standard upgrade stack:
 5. Delegates to `register_action_ws`
 
 Extends `RegisterActionWsOptions` with `allowed_origins` and optional
-`required_roles`. Returns `{transport}`. Most consumers reach for
+`required_roles`, and inherits its required `connection_closer`. Returns
+`{transport}`. Most consumers reach for
 `ws_endpoints` above; this is the entry test harnesses use when they need
 the upgrade stack without `create_app_server`'s full assembly.
 
@@ -558,14 +686,79 @@ HTTP RPC also calls. `register_action_ws` owns only WS-specific concerns:
 - **Cancel-notification interception** — `{request_id → AbortController}` map; aborts the matching pending controller before the cancel bubbles past the dispatcher
 - **Socket-scoped notify** — `(method, params) => ws.send(notification)`, threaded into `perform_action` as `notify`
 - **Composed abort signal** — `AbortSignal.any([socket_close, per_request_cancel])`, threaded as `signal`
-- **Connection lifecycle** — `transport.add_connection` / `remove_connection`, `on_socket_open` / `_close` hooks, server heartbeat
+- **Connection lifecycle** — admission (`transport.register_pending` → credential re-read → `transport.admit`, which enforces the per-account connection cap) / `remove_connection`, `on_socket_open` / `_close` hooks, server heartbeat
+- **The inbound gate** — frames queue until the socket is admitted and `on_socket_open` has completed; frames on a socket the server closed are dropped
+
+**Admission.** `onOpen` registers the connection pending (synchronously, with
+the socket's `AbortController`), re-reads the credential captured at upgrade
+(`revalidate_resolved_auth({db}, resolved)` — session row / token row / account
+row, no touch; `resolved` is `get_resolved_auth(c)`, the one derivation the
+audit stream shares, read off the keys the auth middleware set), then
+`transport.admit`s. A dead credential, or a pending entry a revocation closed
+meanwhile, closes the socket with `WS_CLOSE_SESSION_REVOKED` and the reason a
+revoked socket gets; a re-check that throws closes it with
+`WS_CLOSE_INTERNAL_ERROR` (`internal error`) — fail closed, never admitted
+unchecked. A refused socket gets nothing else written to it, evicts nothing,
+and runs neither lifecycle hook. An upgrade with no resolved credential on its
+context, or one on another account than its request context, throws before the
+socket exists. The test-preset escape hatch
+(`TEST_CONTEXT_PRESET_KEY`) skips the re-read — a pre-baked credential has no
+rows behind it — so `create_ws_test_harness` admits synchronously. Admission
+leaves no interleaving that admits a revoked credential, because every
+revocation closes only after its commit — see
+../../../docs/security.md §Connection Admission and §Closing on Revocation.
+
+`connection_closer: RealtimeCloser | null` is a required option: the endpoint's
+transport is added to it, so the revocation handlers' post-commit closes reach
+the sockets opened here. `null` is for a transport no revocation has to reach
+(a harness driving the dispatcher directly).
+
+Because `onOpen` awaits, an adapter can deliver `onMessage` before admission
+(`@hono/node-ws` doesn't await `onOpen` at all). Those frames are **queued, not
+dispatched** — nothing runs on a credential that has not been re-read — and
+dispatch in arrival order, back to back, once the socket is admitted and
+`on_socket_open` has completed; a refusal drops them unread. The Rust spine
+gets the same ordering from starting its read loop at admission, with the
+kernel socket buffer as the queue; here the queue is in memory, bounded by
+count (`MAX_PRE_ADMISSION_FRAMES`, 256) and by bytes
+(`PRE_ADMISSION_QUEUE_BYTES_FACTOR`, 4, times the endpoint's
+`max_message_bytes`) — the frame that would pass either closes the socket with
+`WS_CLOSE_POLICY_VIOLATION` (reason `WS_CLOSE_PRE_ADMISSION_OVERFLOW_REASON`).
+The byte budget is what bounds memory: pending sockets are not capped per
+account. A consumer that raises the client's durable queue above the frame cap
+makes a full reopen flush overflow it. The `onMessage` call for a queued frame
+returns a promise that settles when the frame was dispatched or dropped.
+
+The queue holds **every** inbound frame, replies to server-initiated requests
+included — so an `on_socket_open` hook that awaits
+`transport.request_connection` on its own connection gets no reply until it
+returns (it times out); start such a request without awaiting it.
+
+**A server-closed socket dispatches nothing.** An adapter can keep delivering
+frames after the server calls `ws.close(…)`, until the close handshake
+completes — `@hono/node-ws` does, for up to the `ws` close timeout when the
+client withholds its close frame. So every server-side close removes the
+connection from the transport and aborts the socket's controller **at close
+time**: the transport does both for a revocation or a cap eviction, and
+`register_action_ws`'s `end_socket` does both for a heartbeat timeout, an
+oversized message, a failed `on_socket_open`, and a refused admission.
+`onMessage` then drops any frame whose socket has ended — no dispatch, no
+error reply. A connection the transport no longer holds though nothing closed
+its socket (a bare `transport.remove_connection`; `transport.is_registered` is
+the twin of the Rust `is_registered`) is ended on its next frame with
+`WS_CLOSE_INTERNAL_ERROR` (`connection unregistered`), so it can't linger as a
+socket that reads everything, answers nothing, and — being chatty — is never
+reaped by the heartbeat. Only a frame that is queued or dispatched counts as
+heartbeat activity.
 
 **Per-message authorization phase.** `perform_action` calls
 `apply_authorization_phase` per-message (HTTP and WS uniformly). Role grant
 changes during a connection lifetime are picked up on the next message —
 no in-place refresh, no socket-close on `role_grant_revoke`. Authentication
-invalidation (`session_revoke`, `password_change`, `token_revoke_all`)
-still closes the socket via `create_ws_auth_guard`.
+invalidation (a session or token revoke, `password_change`, a logout, an
+account delete, a cap eviction) still closes the socket — the revoking
+handler through `connection_closer`, `create_ws_auth_guard` again on the
+audit row.
 
 Per-message side-effect queues: `pending_effects` (eager) drains via
 `flush_pending_effects`; `post_commit_effects` (deferred — pushed by
@@ -573,26 +766,46 @@ handlers via `emit_after_commit`) drains via `flush_post_commit_effects`.
 Both flush in the same `try/finally` that releases the request controller,
 so fire-and-forget audit / notification effects pushed by the handler
 complete (or reject visibly) before the next message dispatches. The
+deferred thunks are invoked first and the eager writes awaited after, so a
+revocation's close never waits on a slow audit INSERT — held behind one, the
+socket would stay open on a credential already committed gone and dispatch its
+next frame. The
 deferred queue is **discarded on rollback** before it reaches that flush (a
 rolled-back message fires no post-commit effect). See `http/CLAUDE.md`
 §Pending Effects.
 
+**Reply before flush.** The response is sent before either queue flushes. A
+handler that revokes the credential its own socket runs on queues a close of
+that socket on `post_commit_effects`, so the caller reads its reply and then the
+`WS_CLOSE_SESSION_REVOKED` close — flushing first would strand it without an
+answer. (The Rust spine does flush first, and drops the response: a divergence
+the cross-backend WS suite records as `capabilities.ws_self_revocation_reply`.)
+
 **Lifecycle hooks.** `on_socket_open({ws, connection_id, identity, notify, signal})`
-fires after `transport.add_connection` but before the first message;
-awaited; throws log + close with `1011 'socket bootstrap failed'`.
-`on_socket_close({ws, connection_id, identity})` fires before
-`transport.remove_connection` so `identity` is still readable. Errors
-logged and swallowed.
+fires once the connection is admitted and before the first message dispatches
+(frames sent meanwhile wait); awaited; throws log + an `internal_error` frame +
+close with `WS_CLOSE_INTERNAL_ERROR` `'socket bootstrap failed'`, unregistering
+the connection.
+`on_socket_close({ws, connection_id, identity})` fires — only for a socket that
+was admitted — after
+`transport.remove_connection(connection_id)` — a slow hook never holds a dead
+entry that broadcasts still target and the per-account cap still counts.
+`connection_id` and `identity` are the values captured at open, so the hook
+reads them the same way after a client close, a revocation, or a connection-cap
+eviction; its `ws` is the close event's context, which on some adapters is not
+the object `on_socket_open` received. Errors logged and swallowed.
 
 **Server-side heartbeat** (`heartbeat?: boolean | ServerHeartbeatOptions`):
 default-on, 60s silence timeout. Any inbound message resets
-`last_receive_time` — chatty clients never trip it. First timeout window
-after open is exempt (cold-start grace). Tick interval is `timeout / 2`,
-so event-loop blockage pauses the timer itself.
+`last_receive_time` — chatty clients never trip it. The timer starts at
+admission, and the first timeout window after it is exempt (cold-start grace).
+Tick interval is `timeout / 2`, so event-loop blockage pauses the timer itself.
+A timeout unregisters the connection and aborts its signal along with the
+`WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT` close.
 
 Two abort signals composed via `AbortSignal.any`:
 
-- `socket_abort_controller` — per-socket, fires on close. Drives every handler's `ctx.signal`.
+- `socket_abort_controller` — per-socket, fires when the socket ends: at the server's close (revocation, cap eviction, heartbeat timeout, …) or the client's. Registered with the transport, which aborts it on the closes it makes. Drives every handler's `ctx.signal`.
 - `pending_controllers: Map<JsonrpcRequestId, AbortController>` — per-request. Registered before dispatch, cleared in `finally` so late cancels for a completed id (or a reused id) can't null-abort the wrong handler. Unknown cancels no-op.
 
 ## Protocol actions (`actions/protocol.ts`)
@@ -684,8 +897,21 @@ recent frame each way — every frame, including heartbeats and the responses
 `request` consumes — for diagnostics UI.
 
 Reconnect policy (exponential backoff): `delay = DEFAULT_RECONNECT_DELAY * DEFAULT_BACKOFF_FACTOR ** (attempts-1)`,
-capped at `DEFAULT_RECONNECT_DELAY_MAX`. `WS_CLOSE_SESSION_REVOKED` is
-**terminal** — sets `#revoked = true`, no reconnect loop on 401.
+capped at `DEFAULT_RECONNECT_DELAY_MAX`. Two close codes never reconnect:
+
+- `WS_CLOSE_SESSION_REVOKED` is **terminal** — sets `revoked`, no reconnect
+  loop on 401, and `connect()` becomes a no-op. Pending and queued requests
+  reject `unauthenticated`.
+- `WS_CLOSE_CONNECTION_LIMIT` is **closed until the user acts** — sets
+  `superseded` (reactive), status `closed`, no reconnect scheduled: the server
+  closed this socket to admit a newer one on the same account, and
+  reconnecting would close that one in turn, so clients past the cap would
+  close each other in a loop. The credential is still good, so `revoked` stays
+  `false` and an explicit `connect()` reopens and clears `superseded`. Pending
+  and queued requests reject `service_unavailable`; requests made while
+  superseded buffer in the durable queue like any call on a closed client. UI
+  reads `superseded` to say why the connection is closed and offer the
+  reconnect.
 
 Live policy swaps (behave like constructor — whole policy atomic, missing
 fields fall back to defaults, not "keep current"): `set_reconnect`,
@@ -693,7 +919,9 @@ fields fall back to defaults, not "keep current"): `set_reconnect`,
 
 `SocketStatus = 'initial' | 'connecting' | 'connected' | 'reconnecting' | 'closed'`.
 `socket_status_to_async_status(status, revoked)` collapses to fuz_util's
-4-way `AsyncStatus`.
+4-way `AsyncStatus`: `closed` reads `failure` when revoked and `initial`
+otherwise — a `superseded` close included, since the client is not trying and
+`connect()` reopens it.
 
 ## RPC client (`actions/rpc_client.ts`)
 

package/dist/actions/action_rpc.d.ts.map

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

package/dist/actions/action_rpc.js

@@ -133,6 +133,10 @@ export const create_rpc_endpoint = (options) => {
      * 3. Hand off to `perform_action` for the post-parse pipeline.
      * 4. Bind the result to `c.json` — `'ok'` returns the result envelope,
      *    `'error'` returns the error envelope at the `result.status` HTTP code.
+     *    A result that cannot be serialized answers `internal_error` rather
+     *    than throwing: `perform_action` has already committed, and a throw
+     *    here would have the route wrapper discard the post-commit effects
+     *    the handler queued — a revocation's connection closes among them.
      *
      * @param restrict_to_reads - `true` for GET (rejects `side_effects: true` actions)
      */
@@ -186,7 +190,18 @@ export const create_rpc_endpoint = (options) => {
             // is verified by `jsonrpc_error_code_to_http_status`).
             return c.json(envelope, result.status);
         }
-        return c.json(envelope);
+        try {
+            return c.json(envelope);
+        }
+        catch (err) {
+            // The handler's output is not JSON (a `bigint`, a cycle). Its
+            // transaction has committed, so this must not propagate: the route
+            // wrapper reads a throw as a rollback and discards
+            // `post_commit_effects`, which would drop the closes of a
+            // revocation that did land.
+            log.error(`action result is not serializable: ${method_name}`, err);
+            return c.json(jsonrpc_error_envelope(id, jsonrpc_error_messages.internal_error(dev_only(err instanceof Error ? err.message : undefined))), jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.internal_error));
+        }
     };
     // POST handler — parse JSON-RPC envelope from body
     const post_handler = async (c, route) => {