@fuzdev/fuz_app 0.51.0 → 0.52.0

package/dist/actions/transports.js

@@ -25,7 +25,10 @@ export class Transports {
      */
     allow_fallback = true; // TODO allow registering transports with a priority level so this can be customized
     /**
-     * Registers a transport.
+     * Registers a transport. The first transport registered also becomes the current.
+     *
+     * @mutates this - inserts into `#transport_by_name`; sets `#current_transport`
+     *   if no current is set
      */
     register_transport(transport) {
         this.#transport_by_name.set(transport.transport_name, transport); // TODO maybe ensure unregistering of any previous transport?
@@ -34,6 +37,12 @@ export class Transports {
             this.#current_transport = transport;
         }
     }
+    /**
+     * Switch the current transport selection by name.
+     *
+     * @mutates this - sets `#current_transport`
+     * @throws Error if no transport with `transport_name` has been registered
+     */
     set_current_transport(transport_name) {
         const transport = this.#transport_by_name.get(transport_name);
         if (!transport)
@@ -42,9 +51,9 @@ export class Transports {
     }
     /**
      * Gets either the current transport or the first ready transport
-     * depending on `allow_fallback`, or throws an error.
+     * depending on `allow_fallback`.
      * @param transport_name - optional transport to use instead of the current
-     * @throws when no transport available or ready
+     * @returns the resolved transport, or `null` when none is ready
      */
     get_transport(transport_name) {
         return this.allow_fallback
@@ -68,9 +77,9 @@ export class Transports {
         return this.#transport_by_name.get(transport_name) ?? null;
     }
     /**
-     * Gets the specified transport, defaulting to the current, or throws an error.
+     * Gets the specified transport, defaulting to the current.
      * @param transport_name - optional transport type to use instead of the current
-     * @throws when no transport available or ready
+     * @returns the resolved transport when ready, else `null`
      */
     #get_exact(transport_name) {
         const transport = transport_name
@@ -82,9 +91,9 @@ export class Transports {
         return null;
     }
     /**
-     * Gets the appropriate transport or throws an error.
+     * Gets the appropriate transport.
      * @param transport_name - optional transport type or array of types to use instead of the current
-     * @throws when no transport available or ready
+     * @returns the first ready transport (specified → current → any), or `null`
      */
     #get_first_ready(transport_name) {
         // First try the specified transport(s) if provided

package/dist/actions/transports_http.d.ts

@@ -5,6 +5,13 @@
  */
 import type { JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
 import type { Transport, TransportSendOptions } from './transports.js';
+/**
+ * Thin `fetch` adapter for the JSON-RPC endpoint. POST by default; GET when
+ * the optional `has_side_effects(method)` callback returns `false` for the
+ * method (matches `create_rpc_endpoint`'s GET convention). On non-OK HTTP
+ * responses, synthesizes a JSON-RPC error envelope via
+ * `http_status_to_jsonrpc_error_code`. Always reports ready.
+ */
 export declare class FrontendHttpTransport implements Transport {
     #private;
     readonly transport_name: "frontend_http_rpc";

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

@@ -1 +1 @@
-{"version":3,"file":"transports_http.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,SAAS,EAAE,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAErE,qBAAa,qBAAsB,YAAW,SAAS;;IACtD,QAAQ,CAAC,cAAc,EAAG,mBAAmB,CAAU;gBAOtD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO;IAOzC,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAyEvC,QAAQ,IAAI,OAAO;CAGnB"}
+{"version":3,"file":"transports_http.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,SAAS,EAAE,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAErE;;;;;;GAMG;AACH,qBAAa,qBAAsB,YAAW,SAAS;;IACtD,QAAQ,CAAC,cAAc,EAAG,mBAAmB,CAAU;gBAOtD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO;IAOzC,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAyEvC,QAAQ,IAAI,OAAO;CAGnB"}

package/dist/actions/transports_http.js

@@ -6,6 +6,13 @@
 import { DEV } from 'esm-env';
 import { ThrownJsonrpcError, jsonrpc_error_messages, http_status_to_jsonrpc_error_code, UNKNOWN_ERROR_MESSAGE, } from '../http/jsonrpc_errors.js';
 import { create_jsonrpc_error_response, to_jsonrpc_message_id, is_jsonrpc_error_response, } from '../http/jsonrpc_helpers.js';
+/**
+ * Thin `fetch` adapter for the JSON-RPC endpoint. POST by default; GET when
+ * the optional `has_side_effects(method)` callback returns `false` for the
+ * method (matches `create_rpc_endpoint`'s GET convention). On non-OK HTTP
+ * responses, synthesizes a JSON-RPC error envelope via
+ * `http_status_to_jsonrpc_error_code`. Always reports ready.
+ */
 export class FrontendHttpTransport {
     transport_name = 'frontend_http_rpc';
     #url;

package/dist/actions/transports_ws.d.ts

@@ -41,6 +41,12 @@ export interface WebsocketRpcConnection extends WebsocketConnection {
         id?: JsonrpcRequestId;
     }) => Promise<unknown>;
 }
+/**
+ * Thin adapter over `WebsocketRpcConnection` (canonical implementation:
+ * `FrontendWebsocketClient`). Routes inbound server-pushed requests and
+ * notifications into the supplied `receive` callback; responses are owned
+ * by the connection's own `request()` pending map and are ignored here.
+ */
 export declare class FrontendWebsocketTransport implements Transport {
     #private;
     readonly transport_name: "frontend_websocket_rpc";
@@ -48,6 +54,13 @@ export declare class FrontendWebsocketTransport implements Transport {
     send(message: JsonrpcRequest, options?: TransportSendOptions): Promise<JsonrpcResponseOrError>;
     send(message: JsonrpcNotification, options?: TransportSendOptions): Promise<JsonrpcErrorResponse | null>;
     is_ready(): boolean;
+    /**
+     * Detach the inbound message and error handlers registered on the
+     * connection. Idempotent — subsequent calls no-op. Does not close the
+     * underlying connection (that lifecycle is owned by the caller).
+     *
+     * @mutates this - clears the two stored unsubscribe references after invoking them
+     */
     dispose(): void;
 }
 //# sourceMappingURL=transports_ws.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"transports_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,SAAS,EAAE,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAIrE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAC5E,iBAAiB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACnE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IAClE,OAAO,EAAE,CACR,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE;QAAC,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,EAAE,CAAC,EAAE,gBAAgB,CAAA;KAAC,KACpE,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAED,qBAAa,0BAA2B,YAAW,SAAS;;IAC3D,QAAQ,CAAC,cAAc,EAAG,wBAAwB,CAAU;gBAOhD,UAAU,EAAE,sBAAsB,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC;IAyBtF,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA4DvC,QAAQ,IAAI,OAAO;IAInB,OAAO,IAAI,IAAI;CAUf"}
+{"version":3,"file":"transports_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,SAAS,EAAE,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAIrE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAC5E,iBAAiB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACnE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IAClE,OAAO,EAAE,CACR,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE;QAAC,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,EAAE,CAAC,EAAE,gBAAgB,CAAA;KAAC,KACpE,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,YAAW,SAAS;;IAC3D,QAAQ,CAAC,cAAc,EAAG,wBAAwB,CAAU;gBAOhD,UAAU,EAAE,sBAAsB,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC;IAyBtF,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA4DvC,QAAQ,IAAI,OAAO;IAInB;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;CAUf"}

package/dist/actions/transports_ws.js

@@ -13,6 +13,12 @@
  */
 import { ThrownJsonrpcError, jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
 import { is_jsonrpc_notification, is_jsonrpc_request, to_jsonrpc_message_id, to_jsonrpc_result, create_jsonrpc_response, create_jsonrpc_error_response, } from '../http/jsonrpc_helpers.js';
+/**
+ * Thin adapter over `WebsocketRpcConnection` (canonical implementation:
+ * `FrontendWebsocketClient`). Routes inbound server-pushed requests and
+ * notifications into the supplied `receive` callback; responses are owned
+ * by the connection's own `request()` pending map and are ignored here.
+ */
 export class FrontendWebsocketTransport {
     transport_name = 'frontend_websocket_rpc';
     #connection;
@@ -86,6 +92,13 @@ export class FrontendWebsocketTransport {
     is_ready() {
         return this.#connection.connected;
     }
+    /**
+     * Detach the inbound message and error handlers registered on the
+     * connection. Idempotent — subsequent calls no-op. Does not close the
+     * underlying connection (that lifecycle is owned by the caller).
+     *
+     * @mutates this - clears the two stored unsubscribe references after invoking them
+     */
     dispose() {
         if (this.#remove_message_handler) {
             this.#remove_message_handler();

package/dist/actions/transports_ws_auth_guard.d.ts

@@ -47,7 +47,9 @@ export declare const WS_DISCONNECT_EVENT_TYPES: ReadonlySet<string>;
  *
  * @param transport - the backend WebSocket transport to guard
  * @param log - logger for disconnect events (info level on non-zero closures)
- * @returns an `on_audit_event` callback suitable for `CreateAppBackendOptions`
+ * @returns an `on_audit_event` callback suitable for `CreateAppBackendOptions`.
+ *   The returned callback mutates `transport` (closing matching sockets via
+ *   `close_sockets_for_session` / `_token` / `_account`) on every relevant event.
  */
 export declare const create_ws_auth_guard: (transport: BackendWebsocketTransport, log: Logger) => AuditEventHandler;
 /**
@@ -78,7 +80,9 @@ export declare const create_ws_auth_guard: (transport: BackendWebsocketTransport
  *
  * @param transport - the backend WebSocket transport to guard
  * @param log - logger for disconnect events (info level on non-zero closures)
- * @returns an `on_audit_event` callback wireable alongside `create_ws_auth_guard`
+ * @returns an `on_audit_event` callback wireable alongside `create_ws_auth_guard`.
+ *   The returned callback mutates `transport` via `close_sockets_for_account`
+ *   on every successful `logout` event with a non-empty `account_id`.
  */
 export declare const create_ws_logout_closer: (transport: BackendWebsocketTransport, log: Logger) => AuditEventHandler;
 //# sourceMappingURL=transports_ws_auth_guard.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"transports_ws_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,4BAA4B,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAMxD,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAChC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBA6CF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,uBAAuB,GACnC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBAaF,CAAC"}
+{"version":3,"file":"transports_ws_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,4BAA4B,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAMxD,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAChC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBA6CF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,uBAAuB,GACnC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBAaF,CAAC"}

package/dist/actions/transports_ws_auth_guard.js

@@ -40,7 +40,9 @@ export const WS_DISCONNECT_EVENT_TYPES = new Set([
  *
  * @param transport - the backend WebSocket transport to guard
  * @param log - logger for disconnect events (info level on non-zero closures)
- * @returns an `on_audit_event` callback suitable for `CreateAppBackendOptions`
+ * @returns an `on_audit_event` callback suitable for `CreateAppBackendOptions`.
+ *   The returned callback mutates `transport` (closing matching sockets via
+ *   `close_sockets_for_session` / `_token` / `_account`) on every relevant event.
  */
 export const create_ws_auth_guard = (transport, log) => {
     return (event) => {
@@ -112,7 +114,9 @@ export const create_ws_auth_guard = (transport, log) => {
  *
  * @param transport - the backend WebSocket transport to guard
  * @param log - logger for disconnect events (info level on non-zero closures)
- * @returns an `on_audit_event` callback wireable alongside `create_ws_auth_guard`
+ * @returns an `on_audit_event` callback wireable alongside `create_ws_auth_guard`.
+ *   The returned callback mutates `transport` via `close_sockets_for_account`
+ *   on every successful `logout` event with a non-empty `account_id`.
  */
 export const create_ws_logout_closer = (transport, log) => {
     return (event) => {

package/dist/actions/transports_ws_backend.d.ts

@@ -44,28 +44,39 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
     /**
      * Add a new WebSocket connection with auth info.
      * Session connections pass a token hash for targeted revocation.
-     * Bearer token connections (api_token) pass the `api_token.id` so the
+     * Bearer token connections (`api_token`) pass the `api_token.id` so the
      * socket can be closed when that specific token is revoked without
      * tearing down the account's other sockets. Daemon-token connections
      * pass `null` for both — they're only reachable via
      * `close_sockets_for_account`.
+     *
+     * @returns the freshly assigned `connection_id` (branded `Uuid`)
+     * @mutates this - inserts into `#connections`, `#connection_ids`, and
+     *   `#connection_identities`
      */
     add_connection(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null): Uuid;
     /**
      * Remove a WebSocket connection and its auth tracking data.
      * Idempotent — safe to call after revocation has already cleaned up.
+     *
+     * @mutates this - deletes the connection's entries from `#connections`,
+     *   `#connection_ids`, and `#connection_identities`
      */
     remove_connection(ws: WSContext): void;
     /**
      * Close all sockets associated with a specific session token hash.
      *
      * @returns the number of sockets closed
+     * @mutates this - removes matching connections from internal maps and
+     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_session(token_hash: string): number;
     /**
      * Close all sockets associated with a specific account.
      *
      * @returns the number of sockets closed
+     * @mutates this - removes matching connections from internal maps and
+     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_account(account_id: Uuid): number;
     /**
@@ -76,6 +87,8 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      * tokens' sockets.
      *
      * @returns the number of sockets closed
+     * @mutates this - removes matching connections from internal maps and
+     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_token(api_token_id: string): number;
     send(message: JsonrpcRequest, options?: TransportSendOptions): Promise<JsonrpcResponseOrError>;

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

@@ -1 +1 @@
-{"version":3,"file":"transports_ws_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_backend.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AACvC,OAAO,EAAc,KAAK,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAE9D,OAAO,KAAK,EAEX,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EAA2B,KAAK,SAAS,EAAE,KAAK,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAIpG;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,UAAU,EAAE,IAAI,CAAC;IACjB,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA6B,SAAQ,SAAS;IAC9D,kBAAkB,EAAE,CACnB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,KAChD,MAAM,CAAC;CACZ;AAED,qDAAqD;AACrD,eAAO,MAAM,iCAAiC,GAC7C,WAAW,SAAS,KAClB,SAAS,IAAI,4BAEqE,CAAC;AAEtF,qBAAa,yBAA0B,YAAW,4BAA4B;;IAC7E,QAAQ,CAAC,cAAc,EAAG,uBAAuB,CAAU;IAY3D;;;;;;;;OAQG;IACH,cAAc,CACb,EAAE,EAAE,SAAS,EACb,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,IAAI,EAChB,YAAY,GAAE,MAAM,GAAG,IAAW,GAChC,IAAI;IAQP;;;OAGG;IACH,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IA0BtC;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIrD;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM;IAInD;;;;;;;;OAQG;IACH,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAsB/C,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA6CvC;;;;;;;;;OASG;IACH,kBAAkB,CACjB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,GAClD,MAAM;IAoBT;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,gCAAgC,GAAG,MAAM;IAIpF,QAAQ,IAAI,OAAO;IAInB;;;;;;;OAOG;IACH,oBAAoB,IAAI,MAAM;CAG9B"}
+{"version":3,"file":"transports_ws_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_backend.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AACvC,OAAO,EAAc,KAAK,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAE9D,OAAO,KAAK,EAEX,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EAA2B,KAAK,SAAS,EAAE,KAAK,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAIpG;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,UAAU,EAAE,IAAI,CAAC;IACjB,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA6B,SAAQ,SAAS;IAC9D,kBAAkB,EAAE,CACnB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,KAChD,MAAM,CAAC;CACZ;AAED,qDAAqD;AACrD,eAAO,MAAM,iCAAiC,GAC7C,WAAW,SAAS,KAClB,SAAS,IAAI,4BAEqE,CAAC;AAEtF,qBAAa,yBAA0B,YAAW,4BAA4B;;IAC7E,QAAQ,CAAC,cAAc,EAAG,uBAAuB,CAAU;IAY3D;;;;;;;;;;;;OAYG;IACH,cAAc,CACb,EAAE,EAAE,SAAS,EACb,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,IAAI,EAChB,YAAY,GAAE,MAAM,GAAG,IAAW,GAChC,IAAI;IAQP;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IA0BtC;;;;;;OAMG;IACH,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIrD;;;;;;OAMG;IACH,yBAAyB,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM;IAInD;;;;;;;;;;OAUG;IACH,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAsB/C,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA6CvC;;;;;;;;;OASG;IACH,kBAAkB,CACjB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,GAClD,MAAM;IAoBT;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,gCAAgC,GAAG,MAAM;IAIpF,QAAQ,IAAI,OAAO;IAInB;;;;;;;OAOG;IACH,oBAAoB,IAAI,MAAM;CAG9B"}

package/dist/actions/transports_ws_backend.js

@@ -23,11 +23,15 @@ export class BackendWebsocketTransport {
     /**
      * Add a new WebSocket connection with auth info.
      * Session connections pass a token hash for targeted revocation.
-     * Bearer token connections (api_token) pass the `api_token.id` so the
+     * Bearer token connections (`api_token`) pass the `api_token.id` so the
      * socket can be closed when that specific token is revoked without
      * tearing down the account's other sockets. Daemon-token connections
      * pass `null` for both — they're only reachable via
      * `close_sockets_for_account`.
+     *
+     * @returns the freshly assigned `connection_id` (branded `Uuid`)
+     * @mutates this - inserts into `#connections`, `#connection_ids`, and
+     *   `#connection_identities`
      */
     add_connection(ws, token_hash, account_id, api_token_id = null) {
         const connection_id = create_uuid();
@@ -39,6 +43,9 @@ export class BackendWebsocketTransport {
     /**
      * Remove a WebSocket connection and its auth tracking data.
      * Idempotent — safe to call after revocation has already cleaned up.
+     *
+     * @mutates this - deletes the connection's entries from `#connections`,
+     *   `#connection_ids`, and `#connection_identities`
      */
     remove_connection(ws) {
         const connection_id = this.#connection_ids.get(ws);
@@ -68,6 +75,8 @@ export class BackendWebsocketTransport {
      * Close all sockets associated with a specific session token hash.
      *
      * @returns the number of sockets closed
+     * @mutates this - removes matching connections from internal maps and
+     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_session(token_hash) {
         return this.#close_where((id) => id.token_hash === token_hash);
@@ -76,6 +85,8 @@ export class BackendWebsocketTransport {
      * Close all sockets associated with a specific account.
      *
      * @returns the number of sockets closed
+     * @mutates this - removes matching connections from internal maps and
+     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_account(account_id) {
         return this.#close_where((id) => id.account_id === account_id);
@@ -88,6 +99,8 @@ export class BackendWebsocketTransport {
      * tokens' sockets.
      *
      * @returns the number of sockets closed
+     * @mutates this - removes matching connections from internal maps and
+     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_token(api_token_id) {
         return this.#close_where((id) => id.api_token_id === api_token_id);

package/dist/auth/CLAUDE.md

@@ -157,10 +157,39 @@ Separated from runtime types to isolate DDL concerns. Consumed by
 
 ### Audit log (`audit_log_schema.ts`)
 
-- `AUDIT_EVENT_TYPES` — 21 events covering auth + permit + offer + invite +
-  settings mutations. Offer lifecycle: `permit_offer_create` / `_accept` /
-  `_decline` / `_retract` / `_expire` / `_supersede`.
-- `AuditEventType` (Zod enum), `AuditOutcome` (`'success' | 'failure'`).
+#### Audit event types
+
+`AUDIT_EVENT_TYPES` — 21 events covering auth + permit + offer + invite +
+settings mutations. Offer lifecycle: `permit_offer_create` / `_accept` /
+`_decline` / `_retract` / `_expire` / `_supersede`. `AuditEventType` is the
+Zod enum; `AuditOutcome` is `'success' | 'failure'`.
+
+| Event type               |
+| ------------------------ |
+| `login`                  |
+| `logout`                 |
+| `bootstrap`              |
+| `signup`                 |
+| `password_change`        |
+| `session_revoke`         |
+| `session_revoke_all`     |
+| `token_create`           |
+| `token_revoke`           |
+| `token_revoke_all`       |
+| `permit_grant`           |
+| `permit_revoke`          |
+| `permit_offer_create`    |
+| `permit_offer_accept`    |
+| `permit_offer_decline`   |
+| `permit_offer_retract`   |
+| `permit_offer_expire`    |
+| `permit_offer_supersede` |
+| `invite_create`          |
+| `invite_delete`          |
+| `app_settings_update`    |
+
+#### Metadata schemas
+
 - `AUDIT_METADATA_SCHEMAS` — per-type `z.looseObject`. Notable shapes:
   - `permit_grant` — `scope_id`, optional `permit_id` (failed grants
     omit — `web_grantable` denial never produces a row), optional
@@ -957,6 +986,13 @@ Plus re-uses from `../http/error_schemas.ts`: `ERROR_PERMIT_NOT_FOUND`,
 `ERROR_ROLE_NOT_WEB_GRANTABLE`, `ERROR_INSUFFICIENT_PERMISSIONS`,
 `ERROR_ACCOUNT_NOT_FOUND`.
 
+Each spec declares the reason codes its handler may surface (see
+`../actions/CLAUDE.md` §Action specs for the field semantics). Only
+domain reasons returned via `error.data.reason` are listed; standard
+transport errors (validation, auth, rate-limit) stay implicit. Drift
+between declared reasons and handler throws is caught by
+`../../test/auth/permit_offer_actions.error_reasons.test.ts`.
+
 Failure-outcome audit events emitted (success and failure rows both carry
 `ip: ctx.client_ip` — uniform with the admin and self-service surfaces):
 

package/dist/auth/account_queries.d.ts

@@ -14,6 +14,8 @@ import { type Account, type Actor, type CreateAccountInput, type AdminAccountEnt
  * @param deps - query dependencies
  * @param input - the account fields
  * @returns the created account
+ * @mutates `account` table - inserts the new row
+ * @throws Error if the INSERT does not return a row (failed `assert_row` invariant)
  */
 export declare const query_create_account: (deps: QueryDeps, input: CreateAccountInput) => Promise<Account>;
 /**
@@ -42,10 +44,14 @@ export declare const query_account_by_email: (deps: QueryDeps, email: string) =>
 export declare const query_account_by_username_or_email: (deps: QueryDeps, input: string) => Promise<Account | undefined>;
 /**
  * Update the password hash for an account.
+ *
+ * @mutates `account` row - updates `password_hash`, `updated_at`, and `updated_by`
  */
 export declare const query_update_account_password: (deps: QueryDeps, id: string, password_hash: string, updated_by: string | null) => Promise<void>;
 /**
  * Delete an account. Cascades to actors, permits, sessions, and tokens.
+ *
+ * @mutates `account` table and downstream FK rows - DELETE cascades through actors/permits/sessions/tokens
  */
 export declare const query_delete_account: (deps: QueryDeps, id: string) => Promise<boolean>;
 /**
@@ -59,6 +65,8 @@ export declare const query_account_has_any: (deps: QueryDeps) => Promise<boolean
  * @param account_id - the owning account
  * @param name - display name (defaults to account username)
  * @returns the created actor
+ * @mutates `actor` table - inserts the new row
+ * @throws Error if the INSERT does not return a row (failed `assert_row` invariant)
  */
 export declare const query_create_actor: (deps: QueryDeps, account_id: string, name: string) => Promise<Actor>;
 /**
@@ -79,6 +87,8 @@ export declare const query_actor_by_id: (deps: QueryDeps, id: string) => Promise
  * @param deps - query dependencies
  * @param input - the account fields
  * @returns the created account and actor
+ * @mutates `account` and `actor` tables - inserts one row in each
+ * @throws Error if either INSERT does not return a row
  */
 export declare const query_create_account_with_actor: (deps: QueryDeps, input: CreateAccountInput) => Promise<{
     account: Account;

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

@@ -1 +1 @@
-{"version":3,"file":"account_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAEN,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,OAAO,kBAAkB,KACvB,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,OAAO,GAAG,SAAS,CAE7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,OAAO,GAAG,SAAS,CAI7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAI7B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAS7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,IAAI,MAAM,EACV,eAAe,MAAM,EACrB,YAAY,MAAM,GAAG,IAAI,KACvB,OAAO,CAAC,IAAI,CAKd,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAU,MAAM,SAAS,EAAE,IAAI,MAAM,KAAG,OAAO,CAAC,OAAO,CAKvF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,OAAO,CAK5E,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,MAAM,MAAM,KACV,OAAO,CAAC,KAAK,CAMf,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,KAAK,GAAG,SAAS,CAE3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,KAAK,GAAG,SAAS,CAE3B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,SAAS,EACf,OAAO,kBAAkB,KACvB,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAC,CAI1C,CAAC;AAyBF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,SAAS,KACb,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,CA+EtC,CAAC"}
+{"version":3,"file":"account_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAEN,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,OAAO,kBAAkB,KACvB,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,OAAO,GAAG,SAAS,CAE7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,OAAO,GAAG,SAAS,CAI7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAI7B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAS7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,IAAI,MAAM,EACV,eAAe,MAAM,EACrB,YAAY,MAAM,GAAG,IAAI,KACvB,OAAO,CAAC,IAAI,CAKd,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAU,MAAM,SAAS,EAAE,IAAI,MAAM,KAAG,OAAO,CAAC,OAAO,CAKvF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,OAAO,CAK5E,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,MAAM,MAAM,KACV,OAAO,CAAC,KAAK,CAMf,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,KAAK,GAAG,SAAS,CAE3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,KAAK,GAAG,SAAS,CAE3B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,SAAS,EACf,OAAO,kBAAkB,KACvB,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAC,CAI1C,CAAC;AAyBF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,SAAS,KACb,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,CA+EtC,CAAC"}

package/dist/auth/account_queries.js

@@ -14,6 +14,8 @@ import { to_admin_account, } from './account_schema.js';
  * @param deps - query dependencies
  * @param input - the account fields
  * @returns the created account
+ * @mutates `account` table - inserts the new row
+ * @throws Error if the INSERT does not return a row (failed `assert_row` invariant)
  */
 export const query_create_account = async (deps, input) => {
     const row = await deps.db.query_one(`INSERT INTO account (username, password_hash, email)
@@ -62,12 +64,16 @@ export const query_account_by_username_or_email = async (deps, input) => {
 };
 /**
  * Update the password hash for an account.
+ *
+ * @mutates `account` row - updates `password_hash`, `updated_at`, and `updated_by`
  */
 export const query_update_account_password = async (deps, id, password_hash, updated_by) => {
     await deps.db.query(`UPDATE account SET password_hash = $1, updated_at = NOW(), updated_by = $2 WHERE id = $3`, [password_hash, updated_by ?? null, id]);
 };
 /**
  * Delete an account. Cascades to actors, permits, sessions, and tokens.
+ *
+ * @mutates `account` table and downstream FK rows - DELETE cascades through actors/permits/sessions/tokens
  */
 export const query_delete_account = async (deps, id) => {
     const rows = await deps.db.query(`DELETE FROM account WHERE id = $1 RETURNING id`, [
@@ -89,6 +95,8 @@ export const query_account_has_any = async (deps) => {
  * @param account_id - the owning account
  * @param name - display name (defaults to account username)
  * @returns the created actor
+ * @mutates `actor` table - inserts the new row
+ * @throws Error if the INSERT does not return a row (failed `assert_row` invariant)
  */
 export const query_create_actor = async (deps, account_id, name) => {
     const row = await deps.db.query_one(`INSERT INTO actor (account_id, name) VALUES ($1, $2) RETURNING *`, [account_id, name]);
@@ -116,6 +124,8 @@ export const query_actor_by_id = async (deps, id) => {
  * @param deps - query dependencies
  * @param input - the account fields
  * @returns the created account and actor
+ * @mutates `account` and `actor` tables - inserts one row in each
+ * @throws Error if either INSERT does not return a row
  */
 export const query_create_account_with_actor = async (deps, input) => {
     const account = await query_create_account(deps, input);

package/dist/auth/admin_actions.d.ts

@@ -65,6 +65,7 @@ export type AdminActionDeps = Pick<RouteFactoryDeps, 'log' | 'on_audit_event' |
  * @param deps - `AdminActionDeps` slice of `AppDeps` (`log`, `on_audit_event`, optional `audit_log_config`)
  * @param options - role schema for `grantable_roles` derivation
  * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
+ * @mutates `options.app_settings` ref - `app_settings_update` writes `open_signup`, `updated_at`, and `updated_by` so signup middleware reads without a DB round trip
  */
 export declare const create_admin_actions: (deps: AdminActionDeps, options?: AdminActionOptions) => Array<RpcAction>;
 //# sourceMappingURL=admin_actions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"admin_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/admin_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExF,OAAO,EAAuB,KAAK,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAuB7E,OAAO,EAAC,KAAK,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAK1D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AA8ChD,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAAC,CAAC;AAEpG;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,eAAe,EACrB,UAAS,kBAAuB,KAC9B,KAAK,CAAC,SAAS,CAmSjB,CAAC"}
+{"version":3,"file":"admin_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/admin_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExF,OAAO,EAAuB,KAAK,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAuB7E,OAAO,EAAC,KAAK,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAK1D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AA8ChD,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAAC,CAAC;AAEpG;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,eAAe,EACrB,UAAS,kBAAuB,KAC9B,KAAK,CAAC,SAAS,CAmSjB,CAAC"}

package/dist/auth/admin_actions.js

@@ -47,6 +47,7 @@ import { admin_account_list_action_spec, admin_session_list_action_spec, admin_s
  * @param deps - `AdminActionDeps` slice of `AppDeps` (`log`, `on_audit_event`, optional `audit_log_config`)
  * @param options - role schema for `grantable_roles` derivation
  * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
+ * @mutates `options.app_settings` ref - `app_settings_update` writes `open_signup`, `updated_at`, and `updated_by` so signup middleware reads without a DB round trip
  */
 export const create_admin_actions = (deps, options = {}) => {
     const role_options = options.roles?.role_options ?? BUILTIN_ROLE_OPTIONS;

package/dist/auth/api_token_queries.d.ts

@@ -20,6 +20,8 @@ export interface ApiTokenQueryDeps extends QueryDeps {
  * @param token_hash - blake3 hash of the raw token
  * @param expires_at - optional expiration
  * @returns the stored token record
+ * @mutates `api_token` table - inserts the new row keyed by `id`
+ * @throws Error if the INSERT does not return a row (failed `assert_row` invariant)
  */
 export declare const query_create_api_token: (deps: QueryDeps, id: string, account_id: string, name: string, token_hash: string, expires_at?: Date | null) => Promise<ApiToken>;
 /**
@@ -34,6 +36,8 @@ export declare const query_create_api_token: (deps: QueryDeps, id: string, accou
  * @param ip - the client IP address (for audit)
  * @param pending_effects - optional array to register the usage-tracking effect for later awaiting
  * @returns the token record if valid, or `undefined`
+ * @mutates `api_token` row - fire-and-forget UPDATE of `last_used_at` / `last_used_ip` on a valid token
+ * @mutates `pending_effects` - pushes the in-flight tracking promise when provided
  */
 export declare const query_validate_api_token: (deps: ApiTokenQueryDeps, raw_token: string, ip: string | undefined, pending_effects: Array<Promise<void>> | undefined) => Promise<ApiToken | undefined>;
 /**
@@ -42,6 +46,7 @@ export declare const query_validate_api_token: (deps: ApiTokenQueryDeps, raw_tok
  * @param deps - query dependencies
  * @param account_id - the account whose tokens to revoke
  * @returns the number of tokens revoked
+ * @mutates `api_token` table - deletes every row for `account_id`
  */
 export declare const query_revoke_all_api_tokens_for_account: (deps: QueryDeps, account_id: string) => Promise<number>;
 /**
@@ -53,6 +58,7 @@ export declare const query_revoke_all_api_tokens_for_account: (deps: QueryDeps,
  * @param id - the public token id
  * @param account_id - the account that must own the token
  * @returns `true` if a token was revoked, `false` if not found or wrong account
+ * @mutates `api_token` table - deletes the row when account ownership matches
  */
 export declare const query_revoke_api_token_for_account: (deps: QueryDeps, id: string, account_id: string) => Promise<boolean>;
 /**
@@ -75,6 +81,7 @@ export declare const query_api_token_list_for_account: (deps: QueryDeps, account
  * @param account_id - the account to enforce the limit for
  * @param max_tokens - maximum number of tokens to keep
  * @returns the number of tokens evicted
+ * @mutates `api_token` table - deletes the oldest rows past the cap
  */
 export declare const query_api_token_enforce_limit: (deps: QueryDeps, account_id: string, max_tokens: number) => Promise<number>;
 //# sourceMappingURL=api_token_queries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"api_token_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/api_token_queries.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,qBAAqB,CAAC;AAGlD,yEAAyE;AACzE,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IACnD,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,IAAI,MAAM,EACV,YAAY,MAAM,EAClB,MAAM,MAAM,EACZ,YAAY,MAAM,EAClB,aAAa,IAAI,GAAG,IAAI,KACtB,OAAO,CAAC,QAAQ,CAQlB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,iBAAiB,EACvB,WAAW,MAAM,EACjB,IAAI,MAAM,GAAG,SAAS,EACtB,iBAAiB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,KAC/C,OAAO,CAAC,QAAQ,GAAG,SAAS,CAuB9B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,IAAI,MAAM,EACV,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAMjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAM7C,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAYhB,CAAC"}
+{"version":3,"file":"api_token_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/api_token_queries.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,qBAAqB,CAAC;AAGlD,yEAAyE;AACzE,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IACnD,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,IAAI,MAAM,EACV,YAAY,MAAM,EAClB,MAAM,MAAM,EACZ,YAAY,MAAM,EAClB,aAAa,IAAI,GAAG,IAAI,KACtB,OAAO,CAAC,QAAQ,CAQlB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,iBAAiB,EACvB,WAAW,MAAM,EACjB,IAAI,MAAM,GAAG,SAAS,EACtB,iBAAiB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,KAC/C,OAAO,CAAC,QAAQ,GAAG,SAAS,CAuB9B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,IAAI,MAAM,EACV,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAMjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAM7C,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAYhB,CAAC"}

package/dist/auth/api_token_queries.js

@@ -15,6 +15,8 @@ import { hash_api_token } from './api_token.js';
  * @param token_hash - blake3 hash of the raw token
  * @param expires_at - optional expiration
  * @returns the stored token record
+ * @mutates `api_token` table - inserts the new row keyed by `id`
+ * @throws Error if the INSERT does not return a row (failed `assert_row` invariant)
  */
 export const query_create_api_token = async (deps, id, account_id, name, token_hash, expires_at) => {
     const row = await deps.db.query_one(`INSERT INTO api_token (id, account_id, name, token_hash, expires_at)
@@ -34,6 +36,8 @@ export const query_create_api_token = async (deps, id, account_id, name, token_h
  * @param ip - the client IP address (for audit)
  * @param pending_effects - optional array to register the usage-tracking effect for later awaiting
  * @returns the token record if valid, or `undefined`
+ * @mutates `api_token` row - fire-and-forget UPDATE of `last_used_at` / `last_used_ip` on a valid token
+ * @mutates `pending_effects` - pushes the in-flight tracking promise when provided
  */
 export const query_validate_api_token = async (deps, raw_token, ip, pending_effects) => {
     const token_hash = hash_api_token(raw_token);
@@ -61,6 +65,7 @@ export const query_validate_api_token = async (deps, raw_token, ip, pending_effe
  * @param deps - query dependencies
  * @param account_id - the account whose tokens to revoke
  * @returns the number of tokens revoked
+ * @mutates `api_token` table - deletes every row for `account_id`
  */
 export const query_revoke_all_api_tokens_for_account = async (deps, account_id) => {
     const rows = await deps.db.query(`DELETE FROM api_token WHERE account_id = $1 RETURNING id`, [account_id]);
@@ -75,6 +80,7 @@ export const query_revoke_all_api_tokens_for_account = async (deps, account_id)
  * @param id - the public token id
  * @param account_id - the account that must own the token
  * @returns `true` if a token was revoked, `false` if not found or wrong account
+ * @mutates `api_token` table - deletes the row when account ownership matches
  */
 export const query_revoke_api_token_for_account = async (deps, id, account_id) => {
     const rows = await deps.db.query(`DELETE FROM api_token WHERE id = $1 AND account_id = $2 RETURNING id`, [id, account_id]);
@@ -103,6 +109,7 @@ export const query_api_token_list_for_account = async (deps, account_id) => {
  * @param account_id - the account to enforce the limit for
  * @param max_tokens - maximum number of tokens to keep
  * @returns the number of tokens evicted
+ * @mutates `api_token` table - deletes the oldest rows past the cap
  */
 export const query_api_token_enforce_limit = async (deps, account_id, max_tokens) => {
     const rows = await deps.db.query(`DELETE FROM api_token

package/dist/auth/app_settings_queries.d.ts

@@ -12,6 +12,7 @@ import type { AppSettings, AppSettingsWithUsernameJson } from './app_settings_sc
  *
  * @param deps - query dependencies
  * @returns the app settings row
+ * @throws Error if the singleton `app_settings` row is missing (migration drift — should not occur in practice)
  */
 export declare const query_app_settings_load: (deps: QueryDeps) => Promise<AppSettings>;
 /**
@@ -19,6 +20,7 @@ export declare const query_app_settings_load: (deps: QueryDeps) => Promise<AppSe
  *
  * @param deps - query dependencies
  * @returns the app settings with `updated_by_username`
+ * @throws Error if the singleton `app_settings` row is missing
  */
 export declare const query_app_settings_load_with_username: (deps: QueryDeps) => Promise<AppSettingsWithUsernameJson>;
 /**
@@ -28,6 +30,8 @@ export declare const query_app_settings_load_with_username: (deps: QueryDeps) =>
  * @param open_signup - new value for the open_signup toggle
  * @param actor_id - the actor making the change
  * @returns the updated app settings row
+ * @mutates `app_settings` row - sets `open_signup`, `updated_at`, and `updated_by`
+ * @throws Error if the singleton `app_settings` row is missing
  */
 export declare const query_app_settings_update: (deps: QueryDeps, open_signup: boolean, actor_id: string) => Promise<AppSettings>;
 //# sourceMappingURL=app_settings_queries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"app_settings_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/app_settings_queries.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,WAAW,EAAE,2BAA2B,EAAC,MAAM,0BAA0B,CAAC;AAEvF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,WAAW,CAQlF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,SAAS,KACb,OAAO,CAAC,2BAA2B,CAWrC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,aAAa,OAAO,EACpB,UAAU,MAAM,KACd,OAAO,CAAC,WAAW,CASrB,CAAC"}
+{"version":3,"file":"app_settings_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/app_settings_queries.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,WAAW,EAAE,2BAA2B,EAAC,MAAM,0BAA0B,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,WAAW,CAQlF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,SAAS,KACb,OAAO,CAAC,2BAA2B,CAWrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,aAAa,OAAO,EACpB,UAAU,MAAM,KACd,OAAO,CAAC,WAAW,CASrB,CAAC"}