@fuzdev/fuz_app 0.51.0 → 0.53.0

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,21 +99,17 @@ 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);
     }
-    /**
-     * Remove all tracking state for a connection.
-     */
     #cleanup_connection(connection_id, ws) {
         this.#connections.delete(connection_id);
         this.#connection_ids.delete(ws);
         this.#connection_identities.delete(connection_id);
     }
-    /**
-     * Clean up a connection and close its socket with a revocation code.
-     */
     #revoke_connection(connection_id, ws) {
         this.#cleanup_connection(connection_id, ws);
         ws.close(WS_CLOSE_SESSION_REVOKED, 'Session revoked');
@@ -122,9 +129,6 @@ export class BackendWebsocketTransport {
             return create_jsonrpc_error_response(to_jsonrpc_message_id(message), jsonrpc_error_messages.internal_error(error instanceof Error ? error.message : 'failed to broadcast notification'));
         }
     }
-    /**
-     * Broadcast a message to all connected clients.
-     */
     #broadcast(message) {
         const serialized = JSON.stringify(message);
         for (const ws of this.#connections.values()) {

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
@@ -806,7 +835,7 @@ The 2026-04-22 RPC migration moved audit-log list + permit-history reads
 (plus admin session listing) to `admin_actions.ts`. The sole remaining
 REST concern is the optional SSE stream:
 
-- **`GET /audit-log/stream`** — optional, wired only when
+- **`GET /audit/stream`** — optional, wired only when
   `AuditLogRouteOptions.stream` is passed. Streams aren't an RPC concern.
   Uses `AUTH_SESSION_TOKEN_HASH_KEY` for SSE `scope` identity (so
   `session_revoke` can close only that session's stream); `groups: [account_id]`
@@ -843,19 +872,29 @@ enforces admin before the handler runs. `permit_revoke` in
 sibling methods are authenticated-but-not-admin — the dispatcher checks
 auth per-spec, so mixed-auth endpoints compose cleanly.
 
-| Spec                                   | Side effects | Input                                                     | Output                        |
-| -------------------------------------- | ------------ | --------------------------------------------------------- | ----------------------------- |
-| `admin_account_list_action_spec`       | false        | `z.void()`                                                | `{accounts, grantable_roles}` |
-| `admin_session_list_action_spec`       | false        | `z.void()`                                                | `{sessions}`                  |
-| `admin_session_revoke_all_action_spec` | true         | `{account_id}`                                            | `{ok, count}`                 |
-| `admin_token_revoke_all_action_spec`   | true         | `{account_id}`                                            | `{ok, count}`                 |
-| `audit_log_list_action_spec`           | false        | `{event_type?, account_id?, limit?, offset?, since_seq?}` | `{events}`                    |
-| `audit_log_permit_history_action_spec` | false        | `{limit?, offset?}`                                       | `{events}`                    |
-| `invite_create_action_spec`            | true         | `{email?, username?}`                                     | `{ok, invite}`                |
-| `invite_list_action_spec`              | false        | `z.void()`                                                | `{invites}`                   |
-| `invite_delete_action_spec`            | true         | `{invite_id}`                                             | `{ok}`                        |
-| `app_settings_get_action_spec`         | false        | `z.void()`                                                | `{settings}`                  |
-| `app_settings_update_action_spec`      | true         | `{open_signup}`                                           | `{ok, settings}`              |
+| Spec                                   | Side effects | Rate limit  | Input                                                     | Output                        |
+| -------------------------------------- | ------------ | ----------- | --------------------------------------------------------- | ----------------------------- |
+| `admin_account_list_action_spec`       | false        |             | `z.void()`                                                | `{accounts, grantable_roles}` |
+| `admin_session_list_action_spec`       | false        |             | `z.void()`                                                | `{sessions}`                  |
+| `admin_session_revoke_all_action_spec` | true         | `'account'` | `{account_id}`                                            | `{ok, count}`                 |
+| `admin_token_revoke_all_action_spec`   | true         | `'account'` | `{account_id}`                                            | `{ok, count}`                 |
+| `audit_log_list_action_spec`           | false        |             | `{event_type?, account_id?, limit?, offset?, since_seq?}` | `{events}`                    |
+| `audit_log_permit_history_action_spec` | false        |             | `{limit?, offset?}`                                       | `{events}`                    |
+| `invite_create_action_spec`            | true         | `'account'` | `{email?, username?}`                                     | `{ok, invite}`                |
+| `invite_list_action_spec`              | false        |             | `z.void()`                                                | `{invites}`                   |
+| `invite_delete_action_spec`            | true         | `'account'` | `{invite_id}`                                             | `{ok}`                        |
+| `app_settings_get_action_spec`         | false        |             | `z.void()`                                                | `{settings}`                  |
+| `app_settings_update_action_spec`      | true         | `'account'` | `{open_signup}`                                           | `{ok, settings}`              |
+
+Mutating admin specs declare `rate_limit: 'account'` — keyed on the
+admin's `request_context.actor.id`. The dispatcher's per-action hook
+(shared by HTTP RPC + WS) records every invocation regardless of
+outcome so successful probes (e.g. `invite_create`'s account-existence
+oracle on the `LOWER()` lookup in `query_account_by_username/_by_email`)
+consume budget. Default `DEFAULT_ACTION_ACCOUNT_RATE_LIMIT` is 1200/15min
+per actor — permissive enough for any human admin workflow, slow enough
+that scripted oracles surface in audit. Tighten downstream via
+`AppServerOptions.action_account_rate_limiter`.
 
 `AUDIT_LOG_LIST_LIMIT_MAX = 200` — page size clamp (mirrors the former REST
 route).
@@ -957,6 +996,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,7 @@ 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
  */
 export declare const query_create_account: (deps: QueryDeps, input: CreateAccountInput) => Promise<Account>;
 /**
@@ -42,10 +43,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 +64,7 @@ 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
  */
 export declare const query_create_actor: (deps: QueryDeps, account_id: string, name: string) => Promise<Actor>;
 /**
@@ -79,6 +85,7 @@ 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
  */
 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;;;;;;;GAOG;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;;;;;;;;GAQG;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;;;;;;;;;GASG;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,7 @@ 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
  */
 export const query_create_account = async (deps, input) => {
     const row = await deps.db.query_one(`INSERT INTO account (username, password_hash, email)
@@ -62,12 +63,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 +94,7 @@ 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
  */
 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 +122,7 @@ 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
  */
 export const query_create_account_with_actor = async (deps, input) => {
     const account = await query_create_account(deps, input);

package/dist/auth/admin_action_specs.d.ts

@@ -325,6 +325,7 @@ export declare const admin_session_revoke_all_action_spec: {
     }, z.core.$strict>;
     async: true;
     description: string;
+    rate_limit: "account";
 };
 export declare const admin_token_revoke_all_action_spec: {
     method: string;
@@ -343,6 +344,7 @@ export declare const admin_token_revoke_all_action_spec: {
     }, z.core.$strict>;
     async: true;
     description: string;
+    rate_limit: "account";
 };
 export declare const audit_log_list_action_spec: {
     method: string;
@@ -445,6 +447,7 @@ export declare const invite_create_action_spec: {
     }, z.core.$strict>;
     async: true;
     description: string;
+    rate_limit: "account";
 };
 export declare const invite_list_action_spec: {
     method: string;
@@ -487,6 +490,7 @@ export declare const invite_delete_action_spec: {
     }, z.core.$strict>;
     async: true;
     description: string;
+    rate_limit: "account";
 };
 export declare const app_settings_get_action_spec: {
     method: string;
@@ -530,6 +534,7 @@ export declare const app_settings_update_action_spec: {
     }, z.core.$strict>;
     async: true;
     description: string;
+    rate_limit: "account";
 };
 /**
  * All admin action specs — a codegen-ready registry. Consumers spread this

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

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

package/dist/auth/admin_action_specs.js

@@ -177,6 +177,7 @@ export const admin_session_revoke_all_action_spec = {
     output: AdminSessionRevokeAllOutput,
     async: true,
     description: 'Revoke all sessions for an account. Admin-only.',
+    rate_limit: 'account',
 };
 export const admin_token_revoke_all_action_spec = {
     method: 'admin_token_revoke_all',
@@ -188,6 +189,7 @@ export const admin_token_revoke_all_action_spec = {
     output: AdminTokenRevokeAllOutput,
     async: true,
     description: 'Revoke all API tokens for an account. Admin-only.',
+    rate_limit: 'account',
 };
 export const audit_log_list_action_spec = {
     method: 'audit_log_list',
@@ -221,6 +223,7 @@ export const invite_create_action_spec = {
     output: InviteCreateOutput,
     async: true,
     description: 'Create an invite addressed to an email, username, or both. Admin-only.',
+    rate_limit: 'account',
 };
 export const invite_list_action_spec = {
     method: 'invite_list',
@@ -243,6 +246,7 @@ export const invite_delete_action_spec = {
     output: InviteDeleteOutput,
     async: true,
     description: 'Delete an unclaimed invite. Admin-only.',
+    rate_limit: 'account',
 };
 export const app_settings_get_action_spec = {
     method: 'app_settings_get',
@@ -265,6 +269,7 @@ export const app_settings_update_action_spec = {
     output: AppSettingsUpdateOutput,
     async: true,
     description: 'Update global app settings (currently just the open signup toggle). Admin-only.',
+    rate_limit: 'account',
 };
 /**
  * All admin action specs — a codegen-ready registry. Consumers spread this

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,7 @@ 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`
  */
 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 +35,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 +45,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 +57,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 +80,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;;;;;;;;;;;GAWG;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,7 @@ 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`
  */
 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 +35,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 +64,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 +79,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 +108,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"}

package/dist/auth/app_settings_queries.js

@@ -10,6 +10,7 @@
  *
  * @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 const query_app_settings_load = async (deps) => {
     const row = await deps.db.query_one(`SELECT open_signup, updated_at, updated_by FROM app_settings WHERE id = 1`);
@@ -23,6 +24,7 @@ export const query_app_settings_load = async (deps) => {
  *
  * @param deps - query dependencies
  * @returns the app settings with `updated_by_username`
+ * @throws Error if the singleton `app_settings` row is missing
  */
 export const query_app_settings_load_with_username = async (deps) => {
     const row = await deps.db.query_one(`SELECT s.open_signup, s.updated_at, s.updated_by, act.name AS updated_by_username
@@ -41,6 +43,8 @@ export const query_app_settings_load_with_username = async (deps) => {
  * @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 const query_app_settings_update = async (deps, open_signup, actor_id) => {
     const row = await deps.db.query_one(`UPDATE app_settings SET open_signup = $1, updated_at = NOW(), updated_by = $2 WHERE id = 1 RETURNING open_signup, updated_at, updated_by`, [open_signup, actor_id]);

package/dist/auth/audit_log_queries.d.ts

@@ -36,6 +36,8 @@ export declare const reset_audit_unknown_event_type_failures: () => void;
  * @param input - the audit event to record
  * @param config - audit-log config. Defaults to `BUILTIN_AUDIT_LOG_CONFIG`.
  * @returns the inserted audit log row
+ * @mutates `audit_log` table - inserts the new row
+ * @mutates drift counters - bumps `audit_unknown_event_type_failures` and/or `audit_metadata_validation_failures` on mismatch
  */
 export declare const query_audit_log: <T extends string>(deps: QueryDeps, input: AuditLogInput<T>, config?: AuditLogConfig) => Promise<AuditLogEvent>;
 /**
@@ -77,6 +79,7 @@ export declare const query_audit_log_list_permit_history: (deps: QueryDeps, limi
  * @param deps - query dependencies
  * @param before - delete entries created before this date
  * @returns the number of entries deleted
+ * @mutates `audit_log` table - deletes every row with `created_at < before`
  */
 export declare const query_audit_log_cleanup_before: (deps: QueryDeps, before: Date) => Promise<number>;
 /**
@@ -102,6 +105,8 @@ export type AuditLogFireAndForgetDeps = Pick<AppDeps, 'log' | 'on_audit_event' |
  * @param input - the audit event to record
  * @param deps - logger, `on_audit_event` callback, and optional `audit_log_config`
  * @returns the settled promise (callers may ignore it)
+ * @mutates `audit_log` table - inserts a row via `background_db` (independent of the request transaction)
+ * @mutates `route.pending_effects` - pushes the in-flight settled promise for test flushing
  */
 export declare const audit_log_fire_and_forget: <T extends string>(route: Pick<RouteContext, "background_db" | "pending_effects">, input: AuditLogInput<T>, deps: AuditLogFireAndForgetDeps) => Promise<void>;
 //# sourceMappingURL=audit_log_queries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"audit_log_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AACvC,OAAO,EAGN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,EAC3B,MAAM,uBAAuB,CAAC;AAa/B,iFAAiF;AACjF,eAAO,MAAM,sCAAsC,QAAO,MACvB,CAAC;AAEpC,0CAA0C;AAC1C,eAAO,MAAM,wCAAwC,QAAO,IAE3D,CAAC;AAYF,gFAAgF;AAChF,eAAO,MAAM,qCAAqC,QAAO,MACvB,CAAC;AAEnC,0CAA0C;AAC1C,eAAO,MAAM,uCAAuC,QAAO,IAE1D,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,SAAS,MAAM,EACrD,MAAM,SAAS,EACf,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,SAAQ,cAAyC,KAC/C,OAAO,CAAC,aAAa,CAmCvB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,UAAU,mBAAmB,KAC3B,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAwC9B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,GAC/C,MAAM,SAAS,EACf,UAAU,mBAAmB,KAC3B,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CA8C/C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAA+B,KAC7B,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAO9B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mCAAmC,GAC/C,MAAM,SAAS,EACf,cAA+B,EAC/B,eAAU,KACR,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAYvC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,QAAQ,IAAI,KACV,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC3C,OAAO,EACP,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAC7C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,GAAI,CAAC,SAAS,MAAM,EACzD,OAAO,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,iBAAiB,CAAC,EAC9D,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,yBAAyB,KAC7B,OAAO,CAAC,IAAI,CAed,CAAC"}
+{"version":3,"file":"audit_log_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_log_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AACvC,OAAO,EAGN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,EAC3B,MAAM,uBAAuB,CAAC;AAa/B,iFAAiF;AACjF,eAAO,MAAM,sCAAsC,QAAO,MACvB,CAAC;AAEpC,0CAA0C;AAC1C,eAAO,MAAM,wCAAwC,QAAO,IAE3D,CAAC;AAYF,gFAAgF;AAChF,eAAO,MAAM,qCAAqC,QAAO,MACvB,CAAC;AAEnC,0CAA0C;AAC1C,eAAO,MAAM,uCAAuC,QAAO,IAE1D,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,SAAS,MAAM,EACrD,MAAM,SAAS,EACf,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,SAAQ,cAAyC,KAC/C,OAAO,CAAC,aAAa,CAmCvB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,UAAU,mBAAmB,KAC3B,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAwC9B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,GAC/C,MAAM,SAAS,EACf,UAAU,mBAAmB,KAC3B,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CA8C/C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAA+B,KAC7B,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAO9B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mCAAmC,GAC/C,MAAM,SAAS,EACf,cAA+B,EAC/B,eAAU,KACR,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAYvC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,QAAQ,IAAI,KACV,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC3C,OAAO,EACP,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAC7C,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,GAAI,CAAC,SAAS,MAAM,EACzD,OAAO,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,iBAAiB,CAAC,EAC9D,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,yBAAyB,KAC7B,OAAO,CAAC,IAAI,CAed,CAAC"}

package/dist/auth/audit_log_queries.js

@@ -57,6 +57,8 @@ export const reset_audit_unknown_event_type_failures = () => {
  * @param input - the audit event to record
  * @param config - audit-log config. Defaults to `BUILTIN_AUDIT_LOG_CONFIG`.
  * @returns the inserted audit log row
+ * @mutates `audit_log` table - inserts the new row
+ * @mutates drift counters - bumps `audit_unknown_event_type_failures` and/or `audit_metadata_validation_failures` on mismatch
  */
 export const query_audit_log = async (deps, input, config = BUILTIN_AUDIT_LOG_CONFIG) => {
     if (!config.event_types.includes(input.event_type)) {
@@ -204,6 +206,7 @@ export const query_audit_log_list_permit_history = async (deps, limit = AUDIT_LO
  * @param deps - query dependencies
  * @param before - delete entries created before this date
  * @returns the number of entries deleted
+ * @mutates `audit_log` table - deletes every row with `created_at < before`
  */
 export const query_audit_log_cleanup_before = async (deps, before) => {
     const rows = await deps.db.query(`DELETE FROM audit_log WHERE created_at < $1 RETURNING id`, [before.toISOString()]);
@@ -220,6 +223,8 @@ export const query_audit_log_cleanup_before = async (deps, before) => {
  * @param input - the audit event to record
  * @param deps - logger, `on_audit_event` callback, and optional `audit_log_config`
  * @returns the settled promise (callers may ignore it)
+ * @mutates `audit_log` table - inserts a row via `background_db` (independent of the request transaction)
+ * @mutates `route.pending_effects` - pushes the in-flight settled promise for test flushing
  */
 export const audit_log_fire_and_forget = (route, input, deps) => {
     const { log, on_audit_event, audit_log_config = BUILTIN_AUDIT_LOG_CONFIG } = deps;

package/dist/auth/audit_log_routes.d.ts

@@ -4,7 +4,7 @@
  * The two list-reads (`audit_log_list`, `audit_log_permit_history`) moved to
  * RPC in `auth/admin_actions.ts`, and the admin session listing moved to
  * `admin_session_list` on the same file. What remains here is the optional
- * `GET /audit-log/stream` SSE route — streams aren't an action-kind, so they
+ * `GET /audit/stream` SSE route — streams aren't an action-kind, so they
  * stay on REST. The event payload broadcast on the stream surfaces via
  * `AUDIT_LOG_EVENT_SPECS` (one `EventSpec` per audit event type) declared
  * alongside the broadcaster in `../realtime/sse_auth_guard.ts`.
@@ -20,7 +20,7 @@ export interface AuditLogRouteOptions {
     /** Role required to access audit routes. Default `'admin'`. */
     required_role?: string;
     /**
-     * When provided, includes an SSE route at `/audit-log/stream` for realtime audit events.
+     * When provided, includes an SSE route at `/audit/stream` for realtime audit events.
      * The `subscribe` function receives the stream, channels, and the subscriber's `account_id`
      * as an identity key — enabling `close_by_identity()` for auth revocation.
      */