@fuzdev/fuz_app 0.50.0 → 0.52.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,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/account_routes.d.ts

@@ -4,7 +4,7 @@
  * Returns `RouteSpec[]` — caller applies them to Hono via `apply_route_specs`.
  *
  * Four REST flows remain here; each has a concrete reason to stay REST
- * rather than moving to `account_actions.ts`:
+ * rather than moving to `auth/account_actions.ts`:
  *
  * - `POST /login` — issues a signed `Set-Cookie` and pre-handler rate-limits
  *   by IP + per-canonical-account before password hashing.
@@ -15,7 +15,7 @@
  *   callers should use the `account_verify` RPC action for the typed payload.
  *
  * Session listing/revocation and API token CRUD are on the RPC endpoint —
- * see `account_actions.ts`. Signup is in `signup_routes.ts`. Defaults are
+ * see `auth/account_actions.ts`. Signup is in `auth/signup_routes.ts`. Defaults are
  * closed/safe: accounts are created through bootstrap, admin action, or
  * invite.
  *
@@ -184,7 +184,7 @@ export type PasswordChangeOutput = z.infer<typeof PasswordChangeOutput>;
  *
  * The returned specs cover the three flows that stay REST after the RPC
  * migration (login, logout, password change). Self-service session/token
- * management and verify are on `account_actions.ts`.
+ * management and verify are on `auth/account_actions.ts`.
  *
  * @param deps - stateless capabilities (keyring, password, log)
  * @param options - per-factory configuration (session_options, ip_rate_limiter, login_account_rate_limiter)

package/dist/auth/account_routes.js

@@ -4,7 +4,7 @@
  * Returns `RouteSpec[]` — caller applies them to Hono via `apply_route_specs`.
  *
  * Four REST flows remain here; each has a concrete reason to stay REST
- * rather than moving to `account_actions.ts`:
+ * rather than moving to `auth/account_actions.ts`:
  *
  * - `POST /login` — issues a signed `Set-Cookie` and pre-handler rate-limits
  *   by IP + per-canonical-account before password hashing.
@@ -15,7 +15,7 @@
  *   callers should use the `account_verify` RPC action for the typed payload.
  *
  * Session listing/revocation and API token CRUD are on the RPC endpoint —
- * see `account_actions.ts`. Signup is in `signup_routes.ts`. Defaults are
+ * see `auth/account_actions.ts`. Signup is in `auth/signup_routes.ts`. Defaults are
  * closed/safe: accounts are created through bootstrap, admin action, or
  * invite.
  *
@@ -167,7 +167,7 @@ export const PasswordChangeOutput = z.strictObject({
  *
  * The returned specs cover the three flows that stay REST after the RPC
  * migration (login, logout, password change). Self-service session/token
- * management and verify are on `account_actions.ts`.
+ * management and verify are on `auth/account_actions.ts`.
  *
  * @param deps - stateless capabilities (keyring, password, log)
  * @param options - per-factory configuration (session_options, ip_rate_limiter, login_account_rate_limiter)

package/dist/auth/account_schema.d.ts

@@ -4,7 +4,7 @@
  * Defines the runtime types for the fuz identity system:
  * `Account`, `Actor`, `Permit`, `AuthSession`, and `ApiToken`.
  *
- * DDL lives in `ddl.ts`; role system in `role_schema.ts`.
+ * DDL lives in `auth/ddl.ts`; role system in `auth/role_schema.ts`.
  * See docs/identity.md for design rationale.
  *
  * @module

package/dist/auth/account_schema.js

@@ -4,7 +4,7 @@
  * Defines the runtime types for the fuz identity system:
  * `Account`, `Actor`, `Permit`, `AuthSession`, and `ApiToken`.
  *
- * DDL lives in `ddl.ts`; role system in `role_schema.ts`.
+ * DDL lives in `auth/ddl.ts`; role system in `auth/role_schema.ts`.
  * See docs/identity.md for design rationale.
  *
  * @module

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.d.ts

@@ -4,7 +4,7 @@
  * Tokens use the format `secret_fuz_token_<base64url>` and are stored
  * as blake3 hashes. These are pure cryptographic operations with no
  * framework dependency — the bearer auth middleware that validates
- * tokens lives in `bearer_auth.ts`.
+ * tokens lives in `auth/bearer_auth.ts`.
  *
  * @module
  */

package/dist/auth/api_token.js

@@ -4,7 +4,7 @@
  * Tokens use the format `secret_fuz_token_<base64url>` and are stored
  * as blake3 hashes. These are pure cryptographic operations with no
  * framework dependency — the bearer auth middleware that validates
- * tokens lives in `bearer_auth.ts`.
+ * tokens lives in `auth/bearer_auth.ts`.
  *
  * @module
  */

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"}

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,9 @@ 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
+ * @throws Error if the INSERT does not return a row (failed `assert_row` invariant)
  */
 export declare const query_audit_log: <T extends string>(deps: QueryDeps, input: AuditLogInput<T>, config?: AuditLogConfig) => Promise<AuditLogEvent>;
 /**
@@ -77,6 +80,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 +106,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;;;;;;;;;;;;;;;;GAgBG;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,9 @@ 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
+ * @throws Error if the INSERT does not return a row (failed `assert_row` invariant)
  */
 export const query_audit_log = async (deps, input, config = BUILTIN_AUDIT_LOG_CONFIG) => {
     if (!config.event_types.includes(input.event_type)) {
@@ -204,6 +207,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 +224,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

@@ -2,7 +2,7 @@
  * Audit log SSE stream route.
  *
  * The two list-reads (`audit_log_list`, `audit_log_permit_history`) moved to
- * RPC in `admin_actions.ts`, and the admin session listing 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
  * stay on REST. The event payload broadcast on the stream surfaces via

package/dist/auth/audit_log_routes.js

@@ -2,7 +2,7 @@
  * Audit log SSE stream route.
  *
  * The two list-reads (`audit_log_list`, `audit_log_permit_history`) moved to
- * RPC in `admin_actions.ts`, and the admin session listing 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
  * stay on REST. The event payload broadcast on the stream surfaces via

package/dist/auth/audit_log_schema.d.ts

@@ -242,7 +242,7 @@ export interface CreateAuditLogConfigOptions {
      *
      * Collisions with builtin event-type strings throw at construction.
      * Schemas are run via `safeParse` at insert time; mismatches log + count
-     * but never throw (fail-open — see the drift counters in `audit_log_queries.ts`).
+     * but never throw (fail-open — see the drift counters in `auth/audit_log_queries.ts`).
      */
     extra_events?: Readonly<Record<string, z.ZodType | null>>;
 }
@@ -255,6 +255,8 @@ export interface CreateAuditLogConfigOptions {
  * Call once at startup; pass the result to consumer-emitted
  * `audit_log_fire_and_forget` calls. Builtin handlers omit the argument and
  * pick up `BUILTIN_AUDIT_LOG_CONFIG`.
+ *
+ * @throws Error when an `extra_events` key collides with a builtin event type or fails `AuditEventTypeName` format validation
  */
 export declare const create_audit_log_config: (options?: CreateAuditLogConfigOptions) => AuditLogConfig;
 /** Default page size for audit log listings. */

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

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