@fuzdev/fuz_app 0.128.0 → 0.130.0

package/dist/actions/transports_ws_backend.js

@@ -44,6 +44,21 @@
  * uses the two-phase form. The twin of the Rust `fuz_realtime`
  * `ConnectionRegistry`.
  *
+ * ## Shutdown
+ *
+ * `close_all_sockets` — the close `AppServer.close` runs — closes every
+ * connection, pending or admitted, with `WS_CLOSE_GOING_AWAY`, and leaves the
+ * transport **closing**: from then on every registration is born closed. A
+ * `register_pending` or `add_connection` inserts nothing — it aborts the
+ * caller's controller and closes the socket with `WS_CLOSE_GOING_AWAY` at once
+ * — so an upgrade still in flight when the server shuts down is closed rather
+ * than outliving it. An upgrade registered before the close-all is closed by
+ * it; one registered after is born closed; none is admitted. The flag is set
+ * in the same synchronous step that closes the live connections, so an `admit`
+ * that finds its entry gone and reads `is_closing()` sees the shutdown, never
+ * a revocation. Closing is permanent: a closed transport hosts no further
+ * connections.
+ *
  * @module
  */
 import { to_error_message } from '@fuzdev/fuz_util/error.ts';
@@ -78,6 +93,9 @@ export class BackendWebsocketTransport {
     // "oldest"). Adding a new identity scope (e.g. `device_id`) means adding a
     // field to `ConnectionIdentity`, not a parallel map.
     #connections = new Map();
+    // set once by `close_all_sockets`, never cleared — every later
+    // registration is born closed (module doc, "Shutdown")
+    #closing = false;
     // Server→client request correlation (ActionPeer). The transport owns the
     // sockets + the send; the registry owns the pending map, id allocation,
     // deadlines, and the per-connection in-flight cap (see `peer_request.ts`).
@@ -109,6 +127,11 @@ export class BackendWebsocketTransport {
      * The caller owns the entry until it is admitted: every refusal path calls
      * `remove_connection` with the returned id.
      *
+     * Once the transport is closing (`close_all_sockets`) the registration is
+     * born closed: nothing is inserted, `abort_controller` is aborted, and `ws`
+     * is closed with `WS_CLOSE_GOING_AWAY` before this returns. The id names
+     * nothing, so `admit` refuses it (module doc, "Shutdown").
+     *
      * @param ws - the socket to close on revocation
      * @param token_hash - blake3 session token hash, or `null` for non-session credentials
      * @param account_id - the authenticated account
@@ -116,9 +139,12 @@ export class BackendWebsocketTransport {
      * @param abort_controller - the socket-scoped controller to abort when the
      *   transport closes this connection (revocation or cap eviction)
      * @returns the freshly assigned `connection_id` (branded `Uuid`)
-     * @mutates this - inserts an un-admitted entry into `#connections`
+     * @mutates this - inserts an un-admitted entry into `#connections`, unless
+     *   the transport is closing
      */
     register_pending(ws, token_hash, account_id, api_token_id = null, abort_controller = null) {
+        if (this.#closing)
+            return this.#close_born_closed(ws, abort_controller);
         return this.#insert(ws, token_hash, account_id, api_token_id, abort_controller, false);
     }
     /**
@@ -174,7 +200,8 @@ export class BackendWebsocketTransport {
      * inserted. A removed connection gets no further broadcast or peer request,
      * stops counting toward the cap at once, and has its `abort_controller`
      * aborted; its socket is closed when the close handshake completes. The new
-     * connection is always admitted.
+     * connection is always admitted — unless the transport is closing: then it
+     * is born closed, as in `register_pending`, and evicts nothing.
      *
      * @returns the freshly assigned `connection_id` (branded `Uuid`)
      * @mutates this - inserts an admitted entry into `#connections`; past the
@@ -182,6 +209,8 @@ export class BackendWebsocketTransport {
      *   their `WSContext`
      */
     add_connection(ws, token_hash, account_id, api_token_id = null, abort_controller = null) {
+        if (this.#closing)
+            return this.#close_born_closed(ws, abort_controller);
         if (this.#max_connections_per_account !== null) {
             this.#evict_oldest_for_account(account_id, this.#max_connections_per_account);
         }
@@ -305,14 +334,49 @@ export class BackendWebsocketTransport {
      * revocation does, so its heartbeat timer stops and nothing more dispatches
      * on it. A socket whose `close` throws does not stop the loop.
      *
+     * Leaves the transport closing, for good: every later registration is born
+     * closed (module doc, "Shutdown"). A second call closes nothing.
+     *
      * @returns the number of sockets closed
-     * @mutates this - removes every connection, aborts its registered
-     *   controller, and closes its underlying `WSContext` with `WS_CLOSE_GOING_AWAY`
+     * @mutates this - sets the transport closing, removes every connection,
+     *   aborts its registered controller, and closes its underlying `WSContext`
+     *   with `WS_CLOSE_GOING_AWAY`
      * @throws the first error a socket's `close` threw, after every connection was attempted
      */
     close_all_sockets() {
+        // before any close, in the same synchronous step: an `admit` that finds
+        // its entry gone reads the shutdown, never a revocation — and set even
+        // when a socket's close throws
+        this.#closing = true;
         return this.#close_where(() => true, WS_CLOSE_GOING_AWAY, WS_CLOSE_GOING_AWAY_REASON);
     }
+    /**
+     * Whether `close_all_sockets` has run — the transport is shutting down and
+     * every registration from now on is born closed (module doc, "Shutdown").
+     * For telemetry and logs: `register_action_ws` reads it to say why an
+     * upgrade was refused.
+     */
+    is_closing() {
+        return this.#closing;
+    }
+    /**
+     * Close a registration that arrived after `close_all_sockets`, without
+     * inserting it. A socket whose `close` throws is logged, not thrown: the
+     * registration is refused either way, and its caller sees the aborted
+     * controller.
+     *
+     * @returns a fresh id that names no entry
+     */
+    #close_born_closed(ws, abort_controller) {
+        abort_controller?.abort();
+        try {
+            ws.close(WS_CLOSE_GOING_AWAY, WS_CLOSE_GOING_AWAY_REASON);
+        }
+        catch (error) {
+            this.#log?.error('error closing a socket registered during shutdown:', error);
+        }
+        return create_uuid();
+    }
     #cleanup_connection(connection_id) {
         this.#connections.delete(connection_id);
         // Wake any handler still awaiting a reply on this socket — the peer is

package/dist/auth/CLAUDE.md

@@ -124,7 +124,7 @@ upstream in `auth/signup_routes.ts` via `query_invite_find_unclaimed_match_for_u
 its registered listeners + optional `AuditLogConfig`. Its methods:
 
 - `emit(ctx, input)` — fire-and-forget pool write, pushes to `ctx.pending_effects`; a success row's listener fan-out goes on `ctx.post_commit_effects`
-- `emit_role_grant_target(ctx, auth, input)` — lifts `actor_id` / `account_id` / `ip` boilerplate for role-grant-shape events
+- `emit_role_grant_target(ctx, auth, input)` — lifts `actor_id` / `account_id` / `ip` boilerplate for role-grant-shape events; `input` is an `AuditEmitRoleGrantInput`
 - `emit_pool(input)` — awaitable pool write for code paths without a request context (ad-hoc maintenance scripts; not for success audits paired with a mutation — those write in-tx and `notify` post-commit). Writes, then notifies, whatever the outcome
 - `notify(event)` — fan out an already-written row to listeners (used by in-tx audit batches like `query_accept_offer.audit_events`)
 - `add_listener(listener)` — listener registration, returning a remover for that registration (idempotent; the same function registered twice is two registrations, each with its own remover). Twin of Rust `fuz_auth` `AuditEmitter::add_listener` in firing order and snapshot-at-notify

package/dist/auth/actor_lookup_action_specs.d.ts

@@ -12,7 +12,7 @@
  * Account-grain — only that the caller is signed in matters, not which
  * actor is calling, so resolution skips the actor phase. The auth gate
  * + per-account rate limit (default 1200/15min) + the
- * {@link ACTOR_LOOKUP_IDS_MAX | per-call cap} bound the batched
+ * per-call cap (`ACTOR_LOOKUP_IDS_MAX`) bound the batched
  * username-enumeration surface that the `cell_list` ↔ `actor_lookup`
  * pair would otherwise present.
  *
@@ -38,7 +38,7 @@
  * ids), bounded by:
  *
  * 1. rate-limit (per-account, see above),
- * 2. {@link ACTOR_LOOKUP_IDS_MAX} cap per call,
+ * 2. `ACTOR_LOOKUP_IDS_MAX` cap per call,
  * 3. actor-uuid intractability (122-bit random),
  * 4. hard-deleted actors are indistinguishable from never-existed (no
  *    tombstone oracle — see `auth/actor_lookup_queries.ts`).

package/dist/auth/actor_lookup_action_specs.js

@@ -12,7 +12,7 @@
  * Account-grain — only that the caller is signed in matters, not which
  * actor is calling, so resolution skips the actor phase. The auth gate
  * + per-account rate limit (default 1200/15min) + the
- * {@link ACTOR_LOOKUP_IDS_MAX | per-call cap} bound the batched
+ * per-call cap (`ACTOR_LOOKUP_IDS_MAX`) bound the batched
  * username-enumeration surface that the `cell_list` ↔ `actor_lookup`
  * pair would otherwise present.
  *
@@ -38,7 +38,7 @@
  * ids), bounded by:
  *
  * 1. rate-limit (per-account, see above),
- * 2. {@link ACTOR_LOOKUP_IDS_MAX} cap per call,
+ * 2. `ACTOR_LOOKUP_IDS_MAX` cap per call,
  * 3. actor-uuid intractability (122-bit random),
  * 4. hard-deleted actors are indistinguishable from never-existed (no
  *    tombstone oracle — see `auth/actor_lookup_queries.ts`).

package/dist/auth/audit_emitter.d.ts

@@ -102,6 +102,19 @@ export interface AuditEmitRoleGrantContext extends AuditEmitterContext {
     /** Resolved client IP from the trusted-proxy middleware — `'unknown'` if not resolved. */
     client_ip: string;
 }
+/**
+ * Input to `AuditEmitter.emit_role_grant_target` — the event fields that
+ * vary per call site; `actor_id`, `account_id`, and `ip` are lifted from
+ * the auth and request contexts.
+ */
+export interface AuditEmitRoleGrantInput<T extends string> {
+    event_type: T;
+    target_account_id: Uuid | null;
+    target_actor_id: Uuid | null;
+    metadata: AuditLogInput<T>['metadata'];
+    /** Default `'success'`, as for `emit`. */
+    outcome?: 'success' | 'failure';
+}
 /**
  * Bound audit-emit capability. Built once at backend assembly via
  * `create_audit_emitter`; lives on `AppDeps.audit` so factories never see
@@ -137,13 +150,7 @@ export interface AuditEmitter {
      * Reach for the lower-level `emit` only when the event is non-role-grant
      * shape (e.g. `app_settings_update`, bootstrap, signup).
      */
-    emit_role_grant_target<T extends string>(ctx: AuditEmitRoleGrantContext, auth: RequestActorContext, input: {
-        event_type: T;
-        target_account_id: Uuid | null;
-        target_actor_id: Uuid | null;
-        metadata: AuditLogInput<T>['metadata'];
-        outcome?: 'success' | 'failure';
-    }): void;
+    emit_role_grant_target<T extends string>(ctx: AuditEmitRoleGrantContext, auth: RequestActorContext, input: AuditEmitRoleGrantInput<T>): void;
     /**
      * Awaitable pool write for code paths without a request context.
      *

package/dist/auth/audit_emitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit_emitter.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_emitter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"audit_emitter.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAqB,KAAK,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAC5F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,mBAAoB,SAAQ,sBAAsB;IAClE,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACrE,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,MAAM;IACxD,UAAU,EAAE,CAAC,CAAC;IACd,iBAAiB,EAAE,IAAI,GAAG,IAAI,CAAC;IAC/B,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IACvC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAChF;;;;;;;OAOG;IACH,sBAAsB,CAAC,CAAC,SAAS,MAAM,EACtC,GAAG,EAAE,yBAAyB,EAC9B,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAC/B,IAAI,CAAC;IACR;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACnC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnE;;;OAGG;IACH,cAAc,IAAI,MAAM,CAAC;IACzB;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,SAAS,MAAM,EAC1C,GAAG,EAAE,mBAAmB,EACxB,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,KACnB,IAAI,CAAC;AAEV;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,WAAW,CAAC;AAEhE,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACzC,oDAAoD;IACpD,EAAE,EAAE,EAAE,CAAC;IACP,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,cAAc,CAAC;IAClC;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,yBAAyB,KAAG,YA6IzE,CAAC"}

package/dist/auth/audit_emitter.js

@@ -187,16 +187,14 @@ export const create_audit_emitter = (options) => {
     };
     const listener_count = () => listeners.length;
     // Freeze the slot layout so consumers cannot hot-patch `emit` /
-    // `emit_role_grant_target` / `emit_pool` / `notify` after construction.
-    // The previous test helper `patch_audit_emit_capture` did exactly this
-    // and only happened to work because the four slots were writable —
+    // `emit_role_grant_target` / `emit_pool` / `notify` after construction —
+    // a patched `emit` would miss role-grant-shape emits anyway, since
     // `emit_role_grant_target` calls the closed-over inner `emit`, not
-    // `this.emit`, so the patch silently bypassed role-grant-shape emits.
-    // Tests that need instrumentation pass `emit_decorator` so the wrap
-    // is captured by the closure before the freeze. The listener list stays
+    // `this.emit`. Tests that need instrumentation pass `emit_decorator` so the
+    // wrap is captured by the closure before the freeze. The listener list stays
     // closure-private; it changes only through `add_listener` and the remover
-    // it returns (`create_app_server` registers its SSE + WS listeners
-    // post-assembly, by design, and removes them on close).
+    // it returns (`create_app_server` registers its SSE + WS listeners after
+    // the emitter is built, by design, and removes them on close).
     return Object.freeze({
         emit,
         emit_role_grant_target,

package/dist/auth/audit_log_routes.d.ts

@@ -56,9 +56,13 @@ export interface AuditLogRouteOptions {
  * nothing else — to an `EventSource`, a stream closed an instant after it
  * opened (the client's reconnect is answered by the gates, with the precise
  * status). A pending registration receives no audit row, counts toward no cap,
- * and is removed when a re-read refuses the request. The twin of the Rust
- * spine's `audit_stream_router`, which registers before its role read rather
- * than repeating it.
+ * and is removed when a re-read refuses the request. Once the server is
+ * shutting down (`SubscriberRegistry` class doc, "Shutdown") the registration
+ * is born closed, the re-reads are skipped, and the answer is that same
+ * connect comment alone — as it is when the shutdown closes a registration
+ * whose re-read is in flight, even if the re-read then fails. The twin of the
+ * Rust spine's `audit_stream_router`, which registers before its role read
+ * rather than repeating it.
  *
  * @param options - optional stream wiring + role override
  * @returns the SSE route spec (when `options.stream` is provided) or an empty array

package/dist/auth/audit_log_routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit_log_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAUvD,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAU7E,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACpC,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE;QACR,QAAQ,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;QAC9C,GAAG,EAAE,MAAM,CAAC;KACZ,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,4BAA4B,GAAI,UAAU,oBAAoB,KAAG,KAAK,CAAC,SAAS,CAgF5F,CAAC"}
+{"version":3,"file":"audit_log_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAUvD,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAU7E,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACpC,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE;QACR,QAAQ,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;QAC9C,GAAG,EAAE,MAAM,CAAC;KACZ,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,4BAA4B,GAAI,UAAU,oBAAoB,KAAG,KAAK,CAAC,SAAS,CAiG5F,CAAC"}

package/dist/auth/audit_log_routes.js

@@ -42,9 +42,13 @@ import { AUDIT_LOG_CHANNEL } from '../realtime/sse_auth_guard.js';
  * nothing else — to an `EventSource`, a stream closed an instant after it
  * opened (the client's reconnect is answered by the gates, with the precise
  * status). A pending registration receives no audit row, counts toward no cap,
- * and is removed when a re-read refuses the request. The twin of the Rust
- * spine's `audit_stream_router`, which registers before its role read rather
- * than repeating it.
+ * and is removed when a re-read refuses the request. Once the server is
+ * shutting down (`SubscriberRegistry` class doc, "Shutdown") the registration
+ * is born closed, the re-reads are skipped, and the answer is that same
+ * connect comment alone — as it is when the shutdown closes a registration
+ * whose re-read is in flight, even if the re-read then fails. The twin of the
+ * Rust spine's `audit_stream_router`, which registers before its role read
+ * rather than repeating it.
  *
  * @param options - optional stream wiring + role override
  * @returns the SSE route spec (when `options.stream` is provided) or an empty array
@@ -87,34 +91,52 @@ export const create_audit_log_route_specs = (options) => {
                     // a revocation that closed before the registration is committed,
                     // so these see it. A throw here fails closed — no stream opens
                     // unchecked. Skipped under the test-preset escape hatch, whose
-                    // pre-baked context has no rows behind it to re-read.
-                    if (!c.get(TEST_CONTEXT_PRESET_KEY)) {
-                        const resolved = get_resolved_auth(c);
-                        const credential_is_live = resolved !== null && (await revalidate_resolved_auth(route, resolved));
-                        if (!credential_is_live) {
-                            log.info('audit stream: credential revoked during the request', ctx.account.id);
-                            return c.json({ error: ERROR_AUTHENTICATION_REQUIRED }, 401);
-                        }
-                        // Global grants only, like the `require_role` gate that ran in
-                        // the pipeline — a scoped grant must not open the instance-wide
-                        // stream.
-                        if (!has_scoped_role(await refresh_role_grants(ctx, route), required_role, null)) {
-                            log.info('audit stream: role revoked during the request', ctx.account.id);
-                            return c.json({ error: ERROR_INSUFFICIENT_PERMISSIONS, required_roles: [required_role] }, 403);
-                        }
+                    // pre-baked context has no rows behind it to re-read, and for a
+                    // registration born closed by the shutdown, which admission
+                    // refuses whatever they answer.
+                    if (!c.get(TEST_CONTEXT_PRESET_KEY) && !registry.closing) {
+                        const reread = async () => {
+                            const resolved = get_resolved_auth(c);
+                            const credential_is_live = resolved !== null && (await revalidate_resolved_auth(route, resolved));
+                            if (!credential_is_live) {
+                                log.info('audit stream: credential revoked during the request', ctx.account.id);
+                                return c.json({ error: ERROR_AUTHENTICATION_REQUIRED }, 401);
+                            }
+                            // Global grants only, like the `require_role` gate that ran in
+                            // the pipeline — a scoped grant must not open the instance-wide
+                            // stream.
+                            if (!has_scoped_role(await refresh_role_grants(ctx, route), required_role, null)) {
+                                log.info('audit stream: role revoked during the request', ctx.account.id);
+                                return c.json({ error: ERROR_INSUFFICIENT_PERMISSIONS, required_roles: [required_role] }, 403);
+                            }
+                            return null;
+                        };
+                        const refusal = await reread().catch((error) => {
+                            // the shutdown closed the registration and then the database
+                            // under the re-read: the answer is the shutdown's — admission
+                            // below refuses, since a closing registry admits nothing —
+                            // not a failure
+                            if (registry.closing)
+                                return null;
+                            throw error;
+                        });
+                        if (refusal)
+                            return refusal;
                     }
                     // Admit — the cap's eviction happens here, after every gate. A
-                    // registration a revocation closed while it was pending is not
-                    // admitted: the stream is closed at once, so the body is the
+                    // registration a revocation or the shutdown closed while it was
+                    // pending, or one born closed, is not admitted: the stream is
+                    // closed at once, so the body is the
                     // connect comment and nothing else, and the client reconnects
-                    // into the gates.
+                    // into the gates. The close listener goes on first: a client that
+                    // left during the re-reads gets a stream that is already closed,
+                    // whose listener runs at once and removes the registration, so
+                    // `admit` refuses it rather than evicting a live stream for it.
                     const { response, stream } = create_sse_response(c, log);
+                    stream.on_close(pending.unsubscribe);
                     admitted = registry.admit(pending, stream);
-                    if (admitted) {
-                        stream.on_close(pending.unsubscribe);
-                    }
-                    else {
-                        log.info('audit stream: closed by a revocation before admission', ctx.account.id);
+                    if (!admitted) {
+                        log.info('audit stream: closed before admission', ctx.account.id);
                         stream.close();
                     }
                     return response;

package/dist/auth/bearer_auth.d.ts

@@ -28,8 +28,9 @@ import type { QueryDeps } from '../db/query_deps.js';
  * (`invalid_token`, `account_not_found`) that could aid enumeration attacks,
  * and ensures public actions are not blocked by bad credentials.
  *
- * Rejects bearer tokens when an `Origin` or `Referer` header is present —
- * browsers must use cookie auth to reduce attack surface.
+ * Discards bearer tokens when an `Origin` or `Referer` header is present —
+ * `next()` with no identity, as for a bad token — so browsers must use cookie
+ * auth, reducing attack surface.
  * Auth scheme matching is case-insensitive per RFC 7235.
  * On success, sets `c.var.auth_account_id`, `CREDENTIAL_TYPE_KEY = 'api_token'`,
  * and `AUTH_API_TOKEN_ID_KEY`. Skips when an account is already authenticated

package/dist/auth/bearer_auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bearer_auth.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/bearer_auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAUtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,6BAA6B,GAAI,MAAM,SAAS,EAAE,KAAK,MAAM,KAAG,iBAuE5E,CAAC"}
+{"version":3,"file":"bearer_auth.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/bearer_auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAUtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,6BAA6B,GAAI,MAAM,SAAS,EAAE,KAAK,MAAM,KAAG,iBAuE5E,CAAC"}

package/dist/auth/bearer_auth.js

@@ -31,8 +31,9 @@ import { is_browser_context } from '../http/origin.js';
  * (`invalid_token`, `account_not_found`) that could aid enumeration attacks,
  * and ensures public actions are not blocked by bad credentials.
  *
- * Rejects bearer tokens when an `Origin` or `Referer` header is present —
- * browsers must use cookie auth to reduce attack surface.
+ * Discards bearer tokens when an `Origin` or `Referer` header is present —
+ * `next()` with no identity, as for a bad token — so browsers must use cookie
+ * auth, reducing attack surface.
  * Auth scheme matching is case-insensitive per RFC 7235.
  * On success, sets `c.var.auth_account_id`, `CREDENTIAL_TYPE_KEY = 'api_token'`,
  * and `AUTH_API_TOKEN_ID_KEY`. Skips when an account is already authenticated

package/dist/auth/request_context.d.ts

@@ -251,7 +251,7 @@ export declare const create_request_context_middleware: (deps: QueryDeps, sessio
  * across route-spec declarations and direct calls alike, and the twin of the
  * Rust signature. It needs no parse: the surface arm's identifier is pure label,
  * since rule 3 never asks *which* surface. And it is deliberately not narrowed
- * to the spine's four — the name decides nothing, so there is nothing for a
+ * to the spine's own — the name decides nothing, so there is nothing for a
  * closed set to protect, while a consumer surface would have nothing to pass.
  * fuz_app's own uses are pinned two ways by the surface census: the exact call
  * site, and the scan asserting every `'surface:<name>'` literal in `src/lib`

package/dist/auth/request_context.js

@@ -281,7 +281,7 @@ const token_scope_denial = (c, capability) => {
  * across route-spec declarations and direct calls alike, and the twin of the
  * Rust signature. It needs no parse: the surface arm's identifier is pure label,
  * since rule 3 never asks *which* surface. And it is deliberately not narrowed
- * to the spine's four — the name decides nothing, so there is nothing for a
+ * to the spine's own — the name decides nothing, so there is nothing for a
  * closed set to protect, while a consumer surface would have nothing to pass.
  * fuz_app's own uses are pinned two ways by the surface census: the exact call
  * site, and the scan asserting every `'surface:<name>'` literal in `src/lib`

package/dist/auth/token_scope.d.ts

@@ -106,7 +106,9 @@ export declare const token_scope_admits_method: (scope: TokenScope, method: stri
 export declare const token_scope_admits_non_rpc: (scope: TokenScope) => boolean;
 /**
  * The non-RPC surfaces the **spine itself** mounts (rule 3). Twin of the Rust
- * `TokenSurface` enum, name for name.
+ * `TokenSurface` enum, name for name, except `app_surface` — the opt-in
+ * `GET /api/surface` explorer (`server/surface_route.ts`), which only the TS
+ * spine serves.
  *
  * Not a registry a consumer registers into. `RouteAuth.required_scope` accepts
  * any well-formed `surface:<name>` (see `parse_token_scope_capability`), so a
@@ -120,7 +122,7 @@ export declare const token_scope_admits_non_rpc: (scope: TokenScope) => boolean;
  * refused, in the `required_scope` a denial reports. That is the same field
  * whose `rpc:<method>` arm has always carried arbitrary consumer method names.
  */
-export declare const TOKEN_SURFACES: readonly ["db_admin", "fact_bare", "audit_stream", "ws_upgrade"];
+export declare const TOKEN_SURFACES: readonly ["db_admin", "fact_bare", "audit_stream", "ws_upgrade", "app_surface"];
 export type TokenSurface = (typeof TOKEN_SURFACES)[number];
 /**
  * Is `value` one of the surfaces the spine mounts?

package/dist/auth/token_scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token_scope.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/token_scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAW,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU;;;;;;;;;4BAYrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;;4BAG1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,kDAAkD;AAClD,eAAO,MAAM,gBAAgB,QAAO,UAGlC,CAAC;AAEH,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,GAAI,SAAS,KAAK,CAAC,MAAM,CAAC,KAAG,UAI3D,CAAC;AAEH,qDAAqD;AACrD,eAAO,MAAM,sBAAsB,GAAI,OAAO,eAAe,KAAG,UACgB,CAAC;AAEjF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GAAI,OAAO,UAAU,EAAE,QAAQ,MAAM,KAAG,OACtB,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,0BAA0B,GAAI,OAAO,UAAU,KAAG,OAAgC,CAAC;AAEhG;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,kEAAmE,CAAC;AAC/F,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,KAAK,IAAI,YACA,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,QAAgC,CAAC;AAQtE;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GAAI,QAAQ,MAAM,KAAG,MAC3B,CAAC;AAErC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,oBAAoB,GAC/B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/F;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,4BAA4B,GAAI,OAAO,MAAM,KAAG,oBAAoB,GAAG,IAUnF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,GACzC,OAAO,UAAU,EACjB,YAAY,oBAAoB,KAC9B,OAGkC,CAAC;AAEtC;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GACnC,YAAY,MAAM,KAChB;IAAE,KAAK,EAAE,sBAAsB,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAGxD,CAAC;AAEH,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,GAAI,OAAO,UAAU,KAAG,MAGrD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,KAAG,UAAU,GAAG,IAU5D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,UAAU,KAAG,MAQzD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GAAI,OAAO,OAAO,KAAG,UAAU,GAAG,IAQtE,CAAC"}
+{"version":3,"file":"token_scope.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/token_scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAW,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU;;;;;;;;;4BAYrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;;4BAG1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,kDAAkD;AAClD,eAAO,MAAM,gBAAgB,QAAO,UAGlC,CAAC;AAEH,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,GAAI,SAAS,KAAK,CAAC,MAAM,CAAC,KAAG,UAI3D,CAAC;AAEH,qDAAqD;AACrD,eAAO,MAAM,sBAAsB,GAAI,OAAO,eAAe,KAAG,UACgB,CAAC;AAEjF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GAAI,OAAO,UAAU,EAAE,QAAQ,MAAM,KAAG,OACtB,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,0BAA0B,GAAI,OAAO,UAAU,KAAG,OAAgC,CAAC;AAEhG;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,iFAMjB,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,KAAK,IAAI,YACA,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,QAAgC,CAAC;AAQtE;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GAAI,QAAQ,MAAM,KAAG,MAC3B,CAAC;AAErC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,oBAAoB,GAC/B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/F;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,4BAA4B,GAAI,OAAO,MAAM,KAAG,oBAAoB,GAAG,IAUnF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,GACzC,OAAO,UAAU,EACjB,YAAY,oBAAoB,KAC9B,OAGkC,CAAC;AAEtC;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GACnC,YAAY,MAAM,KAChB;IAAE,KAAK,EAAE,sBAAsB,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAGxD,CAAC;AAEH,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,GAAI,OAAO,UAAU,KAAG,MAGrD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,KAAG,UAAU,GAAG,IAU5D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,UAAU,KAAG,MAQzD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GAAI,OAAO,OAAO,KAAG,UAAU,GAAG,IAQtE,CAAC"}

package/dist/auth/token_scope.js

@@ -112,7 +112,9 @@ export const token_scope_admits_method = (scope, method) => scope.kind === 'full
 export const token_scope_admits_non_rpc = (scope) => scope.kind === 'full';
 /**
  * The non-RPC surfaces the **spine itself** mounts (rule 3). Twin of the Rust
- * `TokenSurface` enum, name for name.
+ * `TokenSurface` enum, name for name, except `app_surface` — the opt-in
+ * `GET /api/surface` explorer (`server/surface_route.ts`), which only the TS
+ * spine serves.
  *
  * Not a registry a consumer registers into. `RouteAuth.required_scope` accepts
  * any well-formed `surface:<name>` (see `parse_token_scope_capability`), so a
@@ -126,7 +128,13 @@ export const token_scope_admits_non_rpc = (scope) => scope.kind === 'full';
  * refused, in the `required_scope` a denial reports. That is the same field
  * whose `rpc:<method>` arm has always carried arbitrary consumer method names.
  */
-export const TOKEN_SURFACES = ['db_admin', 'fact_bare', 'audit_stream', 'ws_upgrade'];
+export const TOKEN_SURFACES = [
+    'db_admin',
+    'fact_bare',
+    'audit_stream',
+    'ws_upgrade',
+    'app_surface'
+];
 /**
  * Is `value` one of the surfaces the spine mounts?
  *

package/dist/http/CLAUDE.md

@@ -28,7 +28,7 @@ effects, see ../../../docs/architecture.md.
 - `http/jsonrpc.ts` — JSON-RPC 2.0 envelope schemas (MCP superset), `JsonrpcErrorCode`, `_meta`.
 - `http/jsonrpc_errors.ts` — `ThrownJsonrpcError`, `jsonrpc_errors` throwers, HTTP-status mappings.
 - `http/jsonrpc_helpers.ts` — message builders, type guards, input/result normalizers.
-- `http/common_routes.ts` — health check + readiness probe (`/ready` schema-drift deploy gate) + authenticated server-status + surface route specs.
+- `http/common_routes.ts` — health check + readiness probe (`/ready` schema-drift deploy gate) + authenticated server-status route specs (the surface explorer route lives in `server/surface_route.ts`).
 - `http/db_routes.ts` — allowlist-gated keeper-only table browser route specs (`public` schema, minus the `NON_BROWSABLE_TABLES` credential floor).
 - `http/pending_effects.ts` — `emit_after_commit` + `dispatch_with_post_commit_rollback` (the shared rollback-discard wrapper both dispatch sites use) + `flush_pending_effects` + `flush_post_commit_effects` + `EmitAfterCommitContext`.
 
@@ -383,7 +383,7 @@ own by casting `as JsonrpcErrorCode`):
 - `rate_limited` (-32006, HTTP 429) — server-side policy.
 - `service_unavailable` (-32007, HTTP 503) — upstream down / maintenance.
 - `timeout` (-32008, HTTP 504) — handler exceeded time budget.
-- `queue_overflow` (-32009, HTTP 429) — **client-side** backpressure (WS reconnect queue full).
+- `queue_overflow` (-32009, HTTP 429) — backpressure: a buffer refused a new request because it was full — client-side (the WS reconnect queue) or server-side (a socket past `MAX_INBOUND_DISPATCHES_PER_CONNECTION` in-flight requests).
 - `request_cancelled` (-32010, HTTP 499) — caller-initiated cancellation (nginx "client closed").
 
 **`invalid_params` vs `validation_error`** — use `invalid_params` (standard
@@ -484,13 +484,12 @@ at send time.
 
 ## Common Routes
 
-`http/common_routes.ts` exposes four generic route-spec factories with no
+`http/common_routes.ts` exposes three generic route-spec factories with no
 auth-domain dependencies:
 
 - `create_health_route_spec()` — `GET /health`, public, returns `{status: 'ok'}`. Infrastructure endpoint for uptime monitors
-- `create_ready_route_spec({expected, log})` — `GET /ready`, public, the deploy gate. Introspects the live DB's columns (`db/schema_ready.ts`) and compares against the committed `expected` column map: `200 {ready: true}` on match, else `503 {error: 'schema_drift' | 'db_unreachable'}`. Detailed drift logs server-side only (minimal body — no schema leak, mirrors why `/api/surface` is authenticated). Throws at assembly on an empty `expected` (fail-loud). Opt-in like `/health`; pair with `load_expected_schema(url)` — loads + URL-caches a consumer's committed `expected_schema.json` and throws on an empty map
+- `create_ready_route_spec({expected, log})` — `GET /ready`, public, the deploy gate. Introspects the live DB's columns (`db/schema_ready.ts`) and compares against the committed `expected` column map: `200 {ready: true}` on match, else `503 {error: 'schema_drift' | 'db_unreachable'}`. Detailed drift logs server-side only (minimal body — no schema leak, mirrors why `/api/surface` is admin-only). Throws at assembly on an empty `expected` (fail-loud). Opt-in like `/health`; pair with `load_expected_schema(url)` — loads + URL-caches a consumer's committed `expected_schema.json` and throws on an empty map
 - `create_server_status_route_spec({version, get_uptime_ms})` — `GET /api/server/status`, authenticated, returns `{version, uptime_ms}`
-- `create_surface_route_spec({surface})` — `GET /api/surface`, authenticated, serves the `AppSurface` JSON. Authenticated because surface data reveals API structure (schemas, auth, routes)
 
 Auth-aware variants (account status, bootstrap status) live in `auth/` —
 `http/common_routes.ts` stays generic.

package/dist/http/auth_shape.d.ts

@@ -141,8 +141,9 @@ export declare const RouteAuth: z.ZodObject<{
      *
      * - `surface:<name>` — a non-RPC surface, refused to every narrowed token
      *   whatever its method list says (token scoping's rule that a narrowed
-     *   token is RPC-only). `surface:audit_stream` and `surface:fact_bare` are
-     *   the spine's; a consumer names its own without registering it.
+     *   token is RPC-only). `surface:audit_stream`, `surface:fact_bare`, and
+     *   `surface:app_surface` are the spine's route-spec ones; a consumer names
+     *   its own without registering it.
      * - `rpc:<method>` — one action method, refused unless the token lists it.
      *   What a route bridged from an `ActionSpec` declares: it carries the
      *   method's identity but never reaches the dispatcher's per-method gate.

package/dist/http/auth_shape.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth_shape.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/auth_shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,WAAW,6DAGtB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAGtD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa;;;;EAA2C,CAAC;AACtE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;IAMpB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;;kBAyCF,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAUlD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,OACA,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,KAAG,OAAgC,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,KAAG,OAAkC,CAAC;AAEnF,wEAAwE;AACxE,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,KAAG,OAA+B,CAAC;AAE/E,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,GAAI,MAAM,SAAS,KAAG,OAC3B,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,OACQ,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,SAAS,KAAG,OACwB,CAAC;AAYvF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAIhE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sCAAsC,GAClD,MAAM,SAAS,EACf,OAAO,WAAW,EAClB,SAAS,MAAM,KACb,IAmBF,CAAC"}
+{"version":3,"file":"auth_shape.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/auth_shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,WAAW,6DAGtB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAGtD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa;;;;EAA2C,CAAC;AACtE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;IAMpB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;;kBAyCF,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAUlD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,OACA,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,KAAG,OAAgC,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,KAAG,OAAkC,CAAC;AAEnF,wEAAwE;AACxE,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,KAAG,OAA+B,CAAC;AAE/E,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,GAAI,MAAM,SAAS,KAAG,OAC3B,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,OACQ,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,SAAS,KAAG,OACwB,CAAC;AAYvF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAIhE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sCAAsC,GAClD,MAAM,SAAS,EACf,OAAO,WAAW,EAClB,SAAS,MAAM,KACb,IAmBF,CAAC"}

package/dist/http/auth_shape.js

@@ -135,8 +135,9 @@ export const RouteAuth = z
      *
      * - `surface:<name>` — a non-RPC surface, refused to every narrowed token
      *   whatever its method list says (token scoping's rule that a narrowed
-     *   token is RPC-only). `surface:audit_stream` and `surface:fact_bare` are
-     *   the spine's; a consumer names its own without registering it.
+     *   token is RPC-only). `surface:audit_stream`, `surface:fact_bare`, and
+     *   `surface:app_surface` are the spine's route-spec ones; a consumer names
+     *   its own without registering it.
      * - `rpc:<method>` — one action method, refused unless the token lists it.
      *   What a route bridged from an `ActionSpec` declares: it carries the
      *   method's identity but never reaches the dispatcher's per-method gate.

package/dist/http/common_routes.d.ts

@@ -8,7 +8,6 @@
  */
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import type { RouteSpec } from './route_spec.js';
-import type { AppSurface } from './surface.js';
 import { type ExpectedSchema } from '../db/schema_ready.js';
 /**
  * Create a public health check route spec.
@@ -57,7 +56,7 @@ export interface ReadyRouteOptions {
  * else `503 {error}` (`schema_drift` when columns are missing, `db_unreachable`
  * when the introspection query throws). The detailed drift goes to the server
  * log only — the public body stays a minimal code so the endpoint doesn't leak
- * schema structure (mirrors why `/api/surface` is authenticated). A deploy poll
+ * schema structure (mirrors why `/api/surface` is admin-only). A deploy poll
  * treats `503` as a failed release and rolls back, turning a silent
  * schema-drift auth outage into a loud blocked deploy. See `db/schema_ready.ts`
  * for the column-presence rationale and `auth/migrations.ts` for the
@@ -78,16 +77,4 @@ export interface ServerStatusOptions {
  * this requires authentication.
  */
 export declare const create_server_status_route_spec: (options: ServerStatusOptions) => RouteSpec;
-/** Options for the surface explorer route. */
-export interface SurfaceRouteOptions {
-    /** The generated app surface to serve. */
-    surface: AppSurface;
-}
-/**
- * Create an authenticated route spec that serves the `AppSurface` as JSON.
- *
- * Surface data reveals API structure (routes, auth, schemas), so this
- * requires authentication like the server status route.
- */
-export declare const create_surface_route_spec: (options: SurfaceRouteOptions) => RouteSpec;
 //# sourceMappingURL=common_routes.d.ts.map

package/dist/http/common_routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/common_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAIN,KAAK,cAAc,EACnB,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAO,SAQ1C,CAAC;AAKH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,GAAG,GAAG,MAAM,KAAG,cAkBxD,CAAC;AAEF,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,QAAQ,EAAE,cAAc,CAAC;IACzB,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,iBAAiB,KAAG,SAoCpE,CAAC;AAEF,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IACnC,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,GAAI,SAAS,mBAAmB,KAAG,SAQ7E,CAAC;AAEH,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IACnC,0CAA0C;IAC1C,OAAO,EAAE,UAAU,CAAC;CACpB;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,mBAAmB,KAAG,SAWvE,CAAC"}
+{"version":3,"file":"common_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/common_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAIN,KAAK,cAAc,EACnB,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAO,SAQ1C,CAAC;AAKH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,GAAG,GAAG,MAAM,KAAG,cAkBxD,CAAC;AAEF,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,QAAQ,EAAE,cAAc,CAAC;IACzB,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,iBAAiB,KAAG,SAoCpE,CAAC;AAEF,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IACnC,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,GAAI,SAAS,mBAAmB,KAAG,SAQ7E,CAAC"}