@fuzdev/fuz_app 0.50.0 → 0.52.0

package/dist/auth/permit_offer_action_specs.js

@@ -19,6 +19,7 @@
  */
 import { z } from 'zod';
 import { Uuid } from '@fuzdev/fuz_util/id.js';
+import { ERROR_ACCOUNT_NOT_FOUND, ERROR_PERMIT_NOT_FOUND, ERROR_ROLE_NOT_WEB_GRANTABLE, } from '../http/error_schemas.js';
 import { RoleName } from './role_schema.js';
 import { PERMIT_OFFER_MESSAGE_LENGTH_MAX, PermitOfferJson } from './permit_offer_schema.js';
 import { PERMIT_REVOKED_REASON_LENGTH_MAX } from './account_schema.js';
@@ -133,6 +134,11 @@ export const permit_offer_create_action_spec = {
     output: PermitOfferCreateOutput,
     async: true,
     description: 'Offer a permit to another account. Grantor must hold the offered role (or pass a consumer authorize callback); role must be web_grantable.',
+    error_reasons: [
+        ERROR_OFFER_SELF_TARGET,
+        ERROR_OFFER_ROLE_NOT_GRANTABLE,
+        ERROR_OFFER_NOT_AUTHORIZED,
+    ],
 };
 export const permit_offer_accept_action_spec = {
     method: 'permit_offer_accept',
@@ -144,6 +150,7 @@ export const permit_offer_accept_action_spec = {
     output: PermitOfferAcceptOutput,
     async: true,
     description: 'Accept an offer. Atomically marks the offer accepted, inserts the permit, and supersedes sibling pending offers for the same (account, role, scope).',
+    error_reasons: [ERROR_OFFER_NOT_FOUND, ERROR_OFFER_TERMINAL, ERROR_OFFER_EXPIRED],
 };
 export const permit_offer_decline_action_spec = {
     method: 'permit_offer_decline',
@@ -155,6 +162,7 @@ export const permit_offer_decline_action_spec = {
     output: PermitOfferOkOutput,
     async: true,
     description: 'Decline an offer. Recipient-only.',
+    error_reasons: [ERROR_OFFER_NOT_FOUND, ERROR_OFFER_TERMINAL],
 };
 export const permit_offer_retract_action_spec = {
     method: 'permit_offer_retract',
@@ -166,6 +174,7 @@ export const permit_offer_retract_action_spec = {
     output: PermitOfferOkOutput,
     async: true,
     description: 'Retract an offer. Grantor-only, pre-decision.',
+    error_reasons: [ERROR_OFFER_NOT_FOUND, ERROR_OFFER_TERMINAL],
 };
 export const permit_offer_list_action_spec = {
     method: 'permit_offer_list',
@@ -199,6 +208,7 @@ export const permit_revoke_action_spec = {
     output: PermitRevokeOutput,
     async: true,
     description: 'Revoke an active permit on a target actor. Admin-only. Supersedes any pending offers for the same (account, role, scope). Fires permit_revoke + permit_offer_supersede notifications.',
+    error_reasons: [ERROR_PERMIT_NOT_FOUND, ERROR_ACCOUNT_NOT_FOUND, ERROR_ROLE_NOT_WEB_GRANTABLE],
 };
 /**
  * All permit-offer action specs — a codegen-ready registry. Consumers spread

package/dist/auth/permit_offer_queries.d.ts

@@ -66,6 +66,10 @@ export declare class PermitOfferSelfTargetError extends Error {
  *
  * Self-offer rejection: throws `PermitOfferSelfTargetError` if the offering
  * actor belongs to the recipient account.
+ *
+ * @mutates `permit_offer` table - inserts a new offer or upserts the matching pending row
+ * @throws PermitOfferSelfTargetError if the offering actor belongs to `to_account_id`
+ * @throws Error if the INSERT/UPSERT does not return a row (failed `assert_row` invariant)
  */
 export declare const query_permit_offer_create: (deps: QueryDeps, input: CreatePermitOfferInput) => Promise<PermitOffer>;
 /**
@@ -75,6 +79,9 @@ export declare const query_permit_offer_create: (deps: QueryDeps, input: CreateP
  * exist or belongs to a different account. Throws
  * `PermitOfferAlreadyTerminalError` if the offer exists for the caller but
  * is already in a terminal state.
+ *
+ * @mutates `permit_offer` row - sets `declined_at` and `decline_reason`
+ * @throws PermitOfferAlreadyTerminalError if the offer is already accepted, declined, retracted, or superseded
  */
 export declare const query_permit_offer_decline: (deps: QueryDeps, offer_id: string, to_account_id: string, reason: string | null) => Promise<PermitOffer | null>;
 /**
@@ -84,6 +91,9 @@ export declare const query_permit_offer_decline: (deps: QueryDeps, offer_id: str
  * exist or was issued by a different actor. Throws
  * `PermitOfferAlreadyTerminalError` if the offer exists for this grantor
  * but is already in a terminal state.
+ *
+ * @mutates `permit_offer` row - sets `retracted_at`
+ * @throws PermitOfferAlreadyTerminalError if the offer is already accepted, declined, retracted, or superseded
  */
 export declare const query_permit_offer_retract: (deps: QueryDeps, offer_id: string, from_actor_id: string) => Promise<PermitOffer | null>;
 /**
@@ -160,6 +170,15 @@ export interface AcceptOfferResult {
  * Sibling supersede is what closes the "accept a pre-revoke sibling offer
  * to bypass a revoke" path: once A is accepted, B/C/... can no longer be
  * accepted even if the resulting permit is later revoked.
+ *
+ * @mutates `permit_offer` row - stamps `accepted_at` and `resulting_permit_id`
+ * @mutates `permit` table - inserts the resulting permit (idempotent on race)
+ * @mutates `permit_offer` siblings - stamps `superseded_at` on every other pending offer for the tuple
+ * @mutates `audit_log` table - emits `permit_offer_accept` + `permit_grant` + one `permit_offer_supersede` per sibling
+ * @throws PermitOfferNotFoundError if the offer is missing or belongs to another recipient
+ * @throws PermitOfferAlreadyTerminalError if the offer is declined, retracted, or superseded
+ * @throws PermitOfferExpiredError if the offer is pending but past `expires_at`
+ * @throws Error if the accepting account has no actor (1:1 invariant) or invariant assertions fail
  */
 export declare const query_accept_offer: (deps: QueryDeps, input: AcceptOfferInput) => Promise<AcceptOfferResult>;
 //# sourceMappingURL=permit_offer_queries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"permit_offer_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/permit_offer_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAEjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,qBAAqB,CAAC;AAEhD,OAAO,EAEN,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEzD;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;gBAC7C,QAAQ,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACrC,QAAQ,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACtC,QAAQ,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;;CAKpD;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,OAAO,sBAAsB,KAC3B,OAAO,CAAC,WAAW,CAyBrB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GACtC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,eAAe,MAAM,EACrB,QAAQ,MAAM,GAAG,IAAI,KACnB,OAAO,CAAC,WAAW,GAAG,IAAI,CAe5B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GACtC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,eAAe,MAAM,KACnB,OAAO,CAAC,WAAW,GAAG,IAAI,CAe5B,CAAC;AA8BF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,eAAe,MAAM,KACnB,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAY5B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sCAAsC,GAClD,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAW,EACX,eAAU,KACR,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAS5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,WAAW,GAAG,IAAI,CAY5B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,KACb,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAU5B,CAAC;AAEF,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAChC,QAAQ,EAAE,IAAI,CAAC;IACf,mGAAmG;IACnG,aAAa,EAAE,IAAI,CAAC;IACpB,gDAAgD;IAChD,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnB;AAED,yHAAyH;AACzH,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,4IAA4I;IAC5I,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAC1C,sLAAsL;IACtL,YAAY,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,OAAO,gBAAgB,KACrB,OAAO,CAAC,iBAAiB,CAqK3B,CAAC"}
+{"version":3,"file":"permit_offer_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/permit_offer_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAEjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,qBAAqB,CAAC;AAEhD,OAAO,EAEN,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEzD;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;gBAC7C,QAAQ,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACrC,QAAQ,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACtC,QAAQ,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;;CAKpD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,OAAO,sBAAsB,KAC3B,OAAO,CAAC,WAAW,CAyBrB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,GACtC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,eAAe,MAAM,EACrB,QAAQ,MAAM,GAAG,IAAI,KACnB,OAAO,CAAC,WAAW,GAAG,IAAI,CAe5B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,GACtC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,eAAe,MAAM,KACnB,OAAO,CAAC,WAAW,GAAG,IAAI,CAe5B,CAAC;AA8BF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,eAAe,MAAM,KACnB,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAY5B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sCAAsC,GAClD,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAW,EACX,eAAU,KACR,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAS5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,WAAW,GAAG,IAAI,CAY5B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,KACb,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAU5B,CAAC;AAEF,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAChC,QAAQ,EAAE,IAAI,CAAC;IACf,mGAAmG;IACnG,aAAa,EAAE,IAAI,CAAC;IACpB,gDAAgD;IAChD,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnB;AAED,yHAAyH;AACzH,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,4IAA4I;IAC5I,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAC1C,sLAAsL;IACtL,YAAY,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,OAAO,gBAAgB,KACrB,OAAO,CAAC,iBAAiB,CAqK3B,CAAC"}

package/dist/auth/permit_offer_queries.js

@@ -77,6 +77,10 @@ export class PermitOfferSelfTargetError extends Error {
  *
  * Self-offer rejection: throws `PermitOfferSelfTargetError` if the offering
  * actor belongs to the recipient account.
+ *
+ * @mutates `permit_offer` table - inserts a new offer or upserts the matching pending row
+ * @throws PermitOfferSelfTargetError if the offering actor belongs to `to_account_id`
+ * @throws Error if the INSERT/UPSERT does not return a row (failed `assert_row` invariant)
  */
 export const query_permit_offer_create = async (deps, input) => {
     const actor = await query_actor_by_account(deps, input.to_account_id);
@@ -108,6 +112,9 @@ export const query_permit_offer_create = async (deps, input) => {
  * exist or belongs to a different account. Throws
  * `PermitOfferAlreadyTerminalError` if the offer exists for the caller but
  * is already in a terminal state.
+ *
+ * @mutates `permit_offer` row - sets `declined_at` and `decline_reason`
+ * @throws PermitOfferAlreadyTerminalError if the offer is already accepted, declined, retracted, or superseded
  */
 export const query_permit_offer_decline = async (deps, offer_id, to_account_id, reason) => {
     const updated = await deps.db.query_one(`UPDATE permit_offer
@@ -130,6 +137,9 @@ export const query_permit_offer_decline = async (deps, offer_id, to_account_id,
  * exist or was issued by a different actor. Throws
  * `PermitOfferAlreadyTerminalError` if the offer exists for this grantor
  * but is already in a terminal state.
+ *
+ * @mutates `permit_offer` row - sets `retracted_at`
+ * @throws PermitOfferAlreadyTerminalError if the offer is already accepted, declined, retracted, or superseded
  */
 export const query_permit_offer_retract = async (deps, offer_id, from_actor_id) => {
     const updated = await deps.db.query_one(`UPDATE permit_offer
@@ -248,6 +258,15 @@ export const query_permit_offer_sweep_expired = async (deps) => {
  * Sibling supersede is what closes the "accept a pre-revoke sibling offer
  * to bypass a revoke" path: once A is accepted, B/C/... can no longer be
  * accepted even if the resulting permit is later revoked.
+ *
+ * @mutates `permit_offer` row - stamps `accepted_at` and `resulting_permit_id`
+ * @mutates `permit` table - inserts the resulting permit (idempotent on race)
+ * @mutates `permit_offer` siblings - stamps `superseded_at` on every other pending offer for the tuple
+ * @mutates `audit_log` table - emits `permit_offer_accept` + `permit_grant` + one `permit_offer_supersede` per sibling
+ * @throws PermitOfferNotFoundError if the offer is missing or belongs to another recipient
+ * @throws PermitOfferAlreadyTerminalError if the offer is declined, retracted, or superseded
+ * @throws PermitOfferExpiredError if the offer is pending but past `expires_at`
+ * @throws Error if the accepting account has no actor (1:1 invariant) or invariant assertions fail
  */
 export const query_accept_offer = async (deps, input) => {
     const { offer_id, to_account_id, ip } = input;

package/dist/auth/permit_queries.d.ts

@@ -24,6 +24,8 @@ import { type SupersededOffer } from './permit_offer_schema.js';
  * @param deps - query dependencies
  * @param input - the permit fields
  * @returns the created or existing active permit
+ * @mutates `permit` table - inserts a row when no active permit matches `(actor_id, role, scope_id)`
+ * @throws Error if the idempotent fallback `SELECT` does not return a row (failed `assert_row` invariant)
  */
 export declare const query_grant_permit: (deps: QueryDeps, input: GrantPermitInput) => Promise<Permit>;
 /**
@@ -79,6 +81,8 @@ export interface RevokePermitResult {
  * @param actor_id - the actor that must own the permit
  * @param revoked_by - the actor who revoked it (for audit trail)
  * @param reason - optional free-form reason, stamped on `permit.revoked_reason` and surfaced to the revokee notification.
+ * @mutates `permit` row - sets `revoked_at`, `revoked_by`, and `revoked_reason`
+ * @mutates `permit_offer` rows - stamps `superseded_at` on every pending sibling for the same `(account, role, scope)`
  */
 export declare const query_revoke_permit: (deps: QueryDeps, permit_id: Uuid, actor_id: Uuid, revoked_by: Uuid | null, reason?: string | null) => Promise<RevokePermitResult | null>;
 /**
@@ -157,6 +161,8 @@ export interface RevokeForScopeResult {
  * @param revoked_by - the actor performing the cascade (audit trail)
  * @param reason - optional free-form reason, stamped on `permit.revoked_reason`.
  * @returns the revoked permits (with `account_id` for fan-out) and superseded offers (with `from_account_id` for fan-out)
+ * @mutates `permit` table - sets `revoked_at`/`revoked_by`/`revoked_reason` on every active row at `scope_id`
+ * @mutates `permit_offer` table - stamps `superseded_at` on every pending row at `scope_id`
  */
 export declare const query_permit_revoke_for_scope: (deps: QueryDeps, scope_id: Uuid, revoked_by: Uuid | null, reason?: string | null) => Promise<RevokeForScopeResult>;
 /** Result of `query_permit_revoke_role` — every permit revoked plus the pending offers superseded by the bulk revoke. */
@@ -198,6 +204,8 @@ export interface RevokeRoleResult {
  * @param revoked_by - the actor who revoked it (for audit trail)
  * @param reason - optional free-form reason, stamped on `permit.revoked_reason`.
  * @returns the list of revoked permits (empty if none were active) and superseded pending offers
+ * @mutates `permit` table - sets `revoked_at`/`revoked_by`/`revoked_reason` on every active row for `(actor, role)`
+ * @mutates `permit_offer` table - stamps `superseded_at` on every matching pending offer
  */
 export declare const query_permit_revoke_role: (deps: QueryDeps, actor_id: string, role: string, revoked_by: string | null, reason?: string | null) => Promise<RevokeRoleResult>;
 //# sourceMappingURL=permit_queries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"permit_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/permit_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAEjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,MAAM,EAAE,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAElE,OAAO,EAAmC,KAAK,eAAe,EAAC,MAAM,0BAA0B,CAAC;AAEhG;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,OAAO,gBAAgB,KACrB,OAAO,CAAC,MAAM,CA4BhB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,WAAW,MAAM,EACjB,UAAU,MAAM,KACd,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAO/B,CAAC;AAEF,6GAA6G;AAC7G,MAAM,WAAW,kBAAkB;IAClC,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB;;;;;;;;OAQG;IACH,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,WAAW,IAAI,EACf,UAAU,IAAI,EACd,YAAY,IAAI,GAAG,IAAI,EACvB,SAAS,MAAM,GAAG,IAAI,KACpB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAsCnC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CASvB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,MAAM,MAAM,EACZ,WAAW,MAAM,GAAG,IAAI,KACtB,OAAO,CAAC,OAAO,CAajB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAKvB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,SAAS,EACf,MAAM,MAAM,KACV,OAAO,CAAC,MAAM,GAAG,IAAI,CAavB,CAAC;AAEF,sIAAsI;AACtI,MAAM,WAAW,oBAAoB;IACpC;;;;OAIG;IACH,OAAO,EAAE,KAAK,CAAC;QAAC,SAAS,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAC;QAAC,UAAU,EAAE,IAAI,CAAA;KAAC,CAAC,CAAC;IAClF;;;;;;;;;;OAUG;IACH,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,UAAU,IAAI,EACd,YAAY,IAAI,GAAG,IAAI,EACvB,SAAS,MAAM,GAAG,IAAI,KACpB,OAAO,CAAC,oBAAoB,CA2C9B,CAAC;AAEF,yHAAyH;AACzH,MAAM,WAAW,gBAAgB;IAChC;;;;OAIG;IACH,OAAO,EAAE,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IAC/F;;;;;OAKG;IACH,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,MAAM,MAAM,EACZ,YAAY,MAAM,GAAG,IAAI,EACzB,SAAS,MAAM,GAAG,IAAI,KACpB,OAAO,CAAC,gBAAgB,CA2C1B,CAAC"}
+{"version":3,"file":"permit_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/permit_queries.ts"],"names":[],"mappings":"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"}

package/dist/auth/permit_queries.js

@@ -22,6 +22,8 @@ import { PERMIT_OFFER_SCOPE_SENTINEL_UUID } from './permit_offer_schema.js';
  * @param deps - query dependencies
  * @param input - the permit fields
  * @returns the created or existing active permit
+ * @mutates `permit` table - inserts a row when no active permit matches `(actor_id, role, scope_id)`
+ * @throws Error if the idempotent fallback `SELECT` does not return a row (failed `assert_row` invariant)
  */
 export const query_grant_permit = async (deps, input) => {
     const inserted = await deps.db.query_one(`INSERT INTO permit (actor_id, role, scope_id, expires_at, granted_by, source_offer_id)
@@ -86,6 +88,8 @@ export const query_permit_find_active_role_for_actor = async (deps, permit_id, a
  * @param actor_id - the actor that must own the permit
  * @param revoked_by - the actor who revoked it (for audit trail)
  * @param reason - optional free-form reason, stamped on `permit.revoked_reason` and surfaced to the revokee notification.
+ * @mutates `permit` row - sets `revoked_at`, `revoked_by`, and `revoked_reason`
+ * @mutates `permit_offer` rows - stamps `superseded_at` on every pending sibling for the same `(account, role, scope)`
  */
 export const query_revoke_permit = async (deps, permit_id, actor_id, revoked_by, reason) => {
     const rows = await deps.db.query(`UPDATE permit SET revoked_at = NOW(), revoked_by = $3, revoked_reason = $4
@@ -199,6 +203,8 @@ export const query_permit_find_account_id_for_role = async (deps, role) => {
  * @param revoked_by - the actor performing the cascade (audit trail)
  * @param reason - optional free-form reason, stamped on `permit.revoked_reason`.
  * @returns the revoked permits (with `account_id` for fan-out) and superseded offers (with `from_account_id` for fan-out)
+ * @mutates `permit` table - sets `revoked_at`/`revoked_by`/`revoked_reason` on every active row at `scope_id`
+ * @mutates `permit_offer` table - stamps `superseded_at` on every pending row at `scope_id`
  */
 export const query_permit_revoke_for_scope = async (deps, scope_id, revoked_by, reason) => {
     // Revoke every active permit at the scope. CTE pulls `account_id` via a
@@ -251,6 +257,8 @@ export const query_permit_revoke_for_scope = async (deps, scope_id, revoked_by,
  * @param revoked_by - the actor who revoked it (for audit trail)
  * @param reason - optional free-form reason, stamped on `permit.revoked_reason`.
  * @returns the list of revoked permits (empty if none were active) and superseded pending offers
+ * @mutates `permit` table - sets `revoked_at`/`revoked_by`/`revoked_reason` on every active row for `(actor, role)`
+ * @mutates `permit_offer` table - stamps `superseded_at` on every matching pending offer
  */
 export const query_permit_revoke_role = async (deps, actor_id, role, revoked_by, reason) => {
     // CTE pulls the revokee's `account_id` via a join on `actor` so callers

package/dist/auth/request_context.d.ts

@@ -77,6 +77,7 @@ export declare const has_role: (ctx: RequestContext, role: string, now?: Date) =
  * @param deps - query dependencies (pool-level db for middleware)
  * @param log - the logger instance
  * @param session_context_key - the Hono context key where session middleware stored the session token
+ * @mutates Hono context - sets `REQUEST_CONTEXT_KEY`, `CREDENTIAL_TYPE_KEY`, `AUTH_SESSION_TOKEN_HASH_KEY`, and `AUTH_API_TOKEN_ID_KEY`
  */
 export declare const create_request_context_middleware: (deps: QueryDeps, log: Logger, session_context_key?: string) => MiddlewareHandler;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"request_context.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/request_context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AACrD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAC,KAAK,OAAO,EAAE,KAAK,KAAK,EAAoB,KAAK,MAAM,EAAC,MAAM,qBAAqB,CAAC;AAQ5F,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAOnD,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACvB;AAED,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,4BAA4B,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,GAAG,OAAO,KAAG,cAAc,GAAG,IAEjE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,GAAI,GAAG,OAAO,KAAG,cAMpD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,cAAc,EAAE,MAAM,MAAM,EAAE,MAAK,IAAiB,KAAG,OAChB,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iCAAiC,GAC7C,MAAM,SAAS,EACf,KAAK,MAAM,EACX,4BAAuC,KACrC,iBA6CF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,iBAM1B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,iBAW3C,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,GAC3B,KAAK,cAAc,EACnB,MAAM,SAAS,KACb,OAAO,CAAC,cAAc,CAGxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,cAAc,GAAG,IAAI,CAS/B,CAAC"}
+{"version":3,"file":"request_context.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/request_context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AACrD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAC,KAAK,OAAO,EAAE,KAAK,KAAK,EAAoB,KAAK,MAAM,EAAC,MAAM,qBAAqB,CAAC;AAQ5F,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAOnD,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACvB;AAED,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,4BAA4B,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,GAAG,OAAO,KAAG,cAAc,GAAG,IAEjE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,GAAI,GAAG,OAAO,KAAG,cAMpD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,cAAc,EAAE,MAAM,MAAM,EAAE,MAAK,IAAiB,KAAG,OAChB,CAAC;AAEtE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iCAAiC,GAC7C,MAAM,SAAS,EACf,KAAK,MAAM,EACX,4BAAuC,KACrC,iBA6CF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,iBAM1B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,iBAW3C,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,GAC3B,KAAK,cAAc,EACnB,MAAM,SAAS,KACb,OAAO,CAAC,cAAc,CAGxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,cAAc,GAAG,IAAI,CAS/B,CAAC"}

package/dist/auth/request_context.js

@@ -81,6 +81,7 @@ export const has_role = (ctx, role, now = new Date()) => ctx.permits.some((p) =>
  * @param deps - query dependencies (pool-level db for middleware)
  * @param log - the logger instance
  * @param session_context_key - the Hono context key where session middleware stored the session token
+ * @mutates Hono context - sets `REQUEST_CONTEXT_KEY`, `CREDENTIAL_TYPE_KEY`, `AUTH_SESSION_TOKEN_HASH_KEY`, and `AUTH_API_TOKEN_ID_KEY`
  */
 export const create_request_context_middleware = (deps, log, session_context_key = 'auth_session_id') => {
     return async (c, next) => {

package/dist/auth/role_schema.d.ts

@@ -64,6 +64,8 @@ export interface RoleSchemaResult {
  * @param app_roles - app-defined roles with optional config overrides
  * @returns `{Role, role_options}` — Zod schema and full config map
  *
+ * @throws Error if any `app_roles` key fails the `RoleName` regex or collides with a builtin role
+ *
  * @example
  * ```ts
  * // visiones

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

@@ -1 +1 @@
-{"version":3,"file":"role_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,0FAA0F;AAC1F,eAAO,MAAM,QAAQ,aAKnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAIhD,sFAAsF;AACtF,eAAO,MAAM,WAAW,WAAW,CAAC;AAEpC,+EAA+E;AAC/E,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC,+CAA+C;AAC/C,eAAO,MAAM,aAAa,8BAAqC,CAAC;AAEhE,yCAAyC;AACzC,eAAO,MAAM,WAAW;;;EAAwB,CAAC;AACjD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAItD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,iGAAiG;IACjG,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAG1E,CAAC;AAEH,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAChC,sGAAsG;IACtG,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,2EAA2E;IAC3E,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,EAClD,WAAW,MAAM,CAAC,CAAC,EAAE,WAAW,CAAC,KAC/B,gBAwBF,CAAC"}
+{"version":3,"file":"role_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,0FAA0F;AAC1F,eAAO,MAAM,QAAQ,aAKnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAIhD,sFAAsF;AACtF,eAAO,MAAM,WAAW,WAAW,CAAC;AAEpC,+EAA+E;AAC/E,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC,+CAA+C;AAC/C,eAAO,MAAM,aAAa,8BAAqC,CAAC;AAEhE,yCAAyC;AACzC,eAAO,MAAM,WAAW;;;EAAwB,CAAC;AACjD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAItD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,iGAAiG;IACjG,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAG1E,CAAC;AAEH,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAChC,sGAAsG;IACtG,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,2EAA2E;IAC3E,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,EAClD,WAAW,MAAM,CAAC,CAAC,EAAE,WAAW,CAAC,KAC/B,gBAwBF,CAAC"}

package/dist/auth/role_schema.js

@@ -46,6 +46,8 @@ export const BUILTIN_ROLE_OPTIONS = new Map([
  * @param app_roles - app-defined roles with optional config overrides
  * @returns `{Role, role_options}` — Zod schema and full config map
  *
+ * @throws Error if any `app_roles` key fails the `RoleName` regex or collides with a builtin role
+ *
  * @example
  * ```ts
  * // visiones

package/dist/auth/route_guards.d.ts

@@ -3,7 +3,7 @@
  *
  * Maps `RouteAuth` discriminants to auth middleware handlers.
  * Injected into `apply_route_specs` to decouple the generic HTTP
- * framework (`route_spec.ts`) from auth-specific middleware.
+ * framework (`http/route_spec.ts`) from auth-specific middleware.
  *
  * @module
  */

package/dist/auth/route_guards.js

@@ -3,7 +3,7 @@
  *
  * Maps `RouteAuth` discriminants to auth middleware handlers.
  * Injected into `apply_route_specs` to decouple the generic HTTP
- * framework (`route_spec.ts`) from auth-specific middleware.
+ * framework (`http/route_spec.ts`) from auth-specific middleware.
  *
  * @module
  */

package/dist/auth/self_service_role_action_specs.d.ts

@@ -3,7 +3,7 @@
  * and the codegen-ready registry.
  *
  * Client-safe: no query-layer or audit-write imports. Handler factory
- * lives in `self_service_role_actions.ts`.
+ * lives in `auth/self_service_role_actions.ts`.
  *
  * @module
  */

package/dist/auth/self_service_role_action_specs.js

@@ -3,7 +3,7 @@
  * and the codegen-ready registry.
  *
  * Client-safe: no query-layer or audit-write imports. Handler factory
- * lives in `self_service_role_actions.ts`.
+ * lives in `auth/self_service_role_actions.ts`.
  *
  * @module
  */

package/dist/auth/self_service_role_actions.d.ts

@@ -25,7 +25,7 @@
  * the existing `permit_offer_create({role})` precedent rather than
  * generating per-role methods.
  *
- * Specs and schemas live in `self_service_role_action_specs.ts` so
+ * Specs and schemas live in `auth/self_service_role_action_specs.ts` so
  * client-side codegen can import the surface without dragging in the
  * query layer.
  *
@@ -62,6 +62,7 @@ export type SelfServiceRoleActionDeps = Pick<RouteFactoryDeps, 'log' | 'on_audit
  * @param deps - `SelfServiceRoleActionDeps` slice of `AppDeps` (`log`, `on_audit_event`, optional `audit_log_config`)
  * @param options - eligible-role allowlist plus optional role schema for typo-checking
  * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
+ * @throws Error at factory time if any `eligible_roles` entry is missing from `options.roles.role_options`
  */
 export declare const create_self_service_role_actions: (deps: SelfServiceRoleActionDeps, options: SelfServiceRoleActionsOptions) => Array<RpcAction>;
 //# sourceMappingURL=self_service_role_actions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"self_service_role_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAgBhD,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC7C;;;;OAIG;IACH,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC3C,gBAAgB,EAChB,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAC7C,CAAC;AAOF;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,yBAAyB,EAC/B,SAAS,6BAA6B,KACpC,KAAK,CAAC,SAAS,CA4GjB,CAAC"}
+{"version":3,"file":"self_service_role_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAgBhD,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC7C;;;;OAIG;IACH,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC3C,gBAAgB,EAChB,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAC7C,CAAC;AAOF;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,yBAAyB,EAC/B,SAAS,6BAA6B,KACpC,KAAK,CAAC,SAAS,CA4GjB,CAAC"}

package/dist/auth/self_service_role_actions.js

@@ -25,7 +25,7 @@
  * the existing `permit_offer_create({role})` precedent rather than
  * generating per-role methods.
  *
- * Specs and schemas live in `self_service_role_action_specs.ts` so
+ * Specs and schemas live in `auth/self_service_role_action_specs.ts` so
  * client-side codegen can import the surface without dragging in the
  * query layer.
  *
@@ -47,6 +47,7 @@ const require_request_auth = (auth) => {
  * @param deps - `SelfServiceRoleActionDeps` slice of `AppDeps` (`log`, `on_audit_event`, optional `audit_log_config`)
  * @param options - eligible-role allowlist plus optional role schema for typo-checking
  * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
+ * @throws Error at factory time if any `eligible_roles` entry is missing from `options.roles.role_options`
  */
 export const create_self_service_role_actions = (deps, options) => {
     const eligible = new Set(options.eligible_roles);

package/dist/auth/session_lifecycle.d.ts

@@ -30,6 +30,9 @@ export interface CreateSessionAndSetCookieOptions {
  * Shared by login and bootstrap — generates a token, hashes it, persists
  * the session row, optionally enforces a per-account session limit, and
  * sets the signed cookie.
+ *
+ * @mutates `auth_session` table - inserts the new session row (and evicts older rows when `max_sessions` is set)
+ * @mutates `options.c` - writes the signed session cookie via `Set-Cookie`
  */
 export declare const create_session_and_set_cookie: (options: CreateSessionAndSetCookieOptions) => Promise<void>;
 //# sourceMappingURL=session_lifecycle.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"session_lifecycle.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_lifecycle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAElC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAC1C,OAAO,EAA8B,KAAK,cAAc,EAAC,MAAM,qBAAqB,CAAC;AASrF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAChD,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,IAAI,EAAE,SAAS,CAAC;IAChB,2CAA2C;IAC3C,CAAC,EAAE,OAAO,CAAC;IACX,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GACzC,SAAS,gCAAgC,KACvC,OAAO,CAAC,IAAI,CAad,CAAC"}
+{"version":3,"file":"session_lifecycle.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_lifecycle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAElC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAC1C,OAAO,EAA8B,KAAK,cAAc,EAAC,MAAM,qBAAqB,CAAC;AASrF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAChD,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,IAAI,EAAE,SAAS,CAAC;IAChB,2CAA2C;IAC3C,CAAC,EAAE,OAAO,CAAC;IACX,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,GACzC,SAAS,gCAAgC,KACvC,OAAO,CAAC,IAAI,CAad,CAAC"}

package/dist/auth/session_lifecycle.js

@@ -12,6 +12,9 @@ import { generate_session_token, hash_session_token, AUTH_SESSION_LIFETIME_MS, q
  * Shared by login and bootstrap — generates a token, hashes it, persists
  * the session row, optionally enforces a per-account session limit, and
  * sets the signed cookie.
+ *
+ * @mutates `auth_session` table - inserts the new session row (and evicts older rows when `max_sessions` is set)
+ * @mutates `options.c` - writes the signed session cookie via `Set-Cookie`
  */
 export const create_session_and_set_cookie = async (options) => {
     const { keyring, deps, c, account_id, session_options, max_sessions } = options;

package/dist/auth/session_middleware.d.ts

@@ -14,10 +14,14 @@ import { type SessionOptions } from './session_cookie.js';
 export declare const get_session_cookie: <T>(c: Context, options: SessionOptions<T>) => string | undefined;
 /**
  * Set the session cookie on a response.
+ *
+ * @mutates `c` - writes the `Set-Cookie` header
  */
 export declare const set_session_cookie: <T>(c: Context, value: string, options: SessionOptions<T>) => void;
 /**
  * Clear the session cookie on a response.
+ *
+ * @mutates `c` - writes a cookie-clearing `Set-Cookie` header
  */
 export declare const clear_session_cookie: <T>(c: Context, options: SessionOptions<T>) => void;
 /**
@@ -28,6 +32,7 @@ export declare const clear_session_cookie: <T>(c: Context, options: SessionOptio
  *
  * @param keyring - key ring for cookie verification
  * @param options - session configuration
+ * @mutates Hono context - sets `options.context_key` and may refresh or clear the session cookie
  */
 export declare const create_session_middleware: <TIdentity>(keyring: Keyring, options: SessionOptions<TIdentity>) => MiddlewareHandler;
 //# sourceMappingURL=session_middleware.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"session_middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_middleware.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAGrD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAC1C,OAAO,EACN,KAAK,cAAc,EAInB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EACnC,GAAG,OAAO,EACV,SAAS,cAAc,CAAC,CAAC,CAAC,KACxB,MAAM,GAAG,SAEX,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EACnC,GAAG,OAAO,EACV,OAAO,MAAM,EACb,SAAS,cAAc,CAAC,CAAC,CAAC,KACxB,IASF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,cAAc,CAAC,CAAC,CAAC,KAAG,IAMhF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,EAClD,SAAS,OAAO,EAChB,SAAS,cAAc,CAAC,SAAS,CAAC,KAChC,iBAgBF,CAAC"}
+{"version":3,"file":"session_middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_middleware.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAGrD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAC1C,OAAO,EACN,KAAK,cAAc,EAInB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EACnC,GAAG,OAAO,EACV,SAAS,cAAc,CAAC,CAAC,CAAC,KACxB,MAAM,GAAG,SAEX,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EACnC,GAAG,OAAO,EACV,OAAO,MAAM,EACb,SAAS,cAAc,CAAC,CAAC,CAAC,KACxB,IASF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,cAAc,CAAC,CAAC,CAAC,KAAG,IAMhF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,EAClD,SAAS,OAAO,EAChB,SAAS,cAAc,CAAC,SAAS,CAAC,KAChC,iBAgBF,CAAC"}

package/dist/auth/session_middleware.js

@@ -15,6 +15,8 @@ export const get_session_cookie = (c, options) => {
 };
 /**
  * Set the session cookie on a response.
+ *
+ * @mutates `c` - writes the `Set-Cookie` header
  */
 export const set_session_cookie = (c, value, options) => {
     const cookie_options = {
@@ -28,6 +30,8 @@ export const set_session_cookie = (c, value, options) => {
 };
 /**
  * Clear the session cookie on a response.
+ *
+ * @mutates `c` - writes a cookie-clearing `Set-Cookie` header
  */
 export const clear_session_cookie = (c, options) => {
     const cookie_options = {
@@ -44,6 +48,7 @@ export const clear_session_cookie = (c, options) => {
  *
  * @param keyring - key ring for cookie verification
  * @param options - session configuration
+ * @mutates Hono context - sets `options.context_key` and may refresh or clear the session cookie
  */
 export const create_session_middleware = (keyring, options) => {
     return async (c, next) => {

package/dist/auth/session_queries.d.ts

@@ -33,6 +33,7 @@ export declare const generate_session_token: () => string;
  * @param token_hash - blake3 hash of the session token (use `hash_session_token`)
  * @param account_id - the account this session belongs to
  * @param expires_at - when the session expires
+ * @mutates `auth_session` table - inserts a row keyed by `token_hash`
  */
 export declare const query_create_session: (deps: QueryDeps, token_hash: string, account_id: string, expires_at: Date) => Promise<void>;
 /**
@@ -49,6 +50,7 @@ export declare const query_session_get_valid: (deps: QueryDeps, token_hash: stri
  *
  * @param deps - query dependencies
  * @param token_hash - blake3 hash of the session token
+ * @mutates `auth_session` row - updates `last_seen_at` and conditionally `expires_at`
  */
 export declare const query_session_touch: (deps: QueryDeps, token_hash: string) => Promise<void>;
 /**
@@ -57,9 +59,11 @@ export declare const query_session_touch: (deps: QueryDeps, token_hash: string)
  * The `_unscoped` suffix is the safety signal — there is no `account_id`
  * constraint, so callers must guarantee the hash came from a trusted
  * source (the authenticated session cookie path is the only safe production
- * caller — see `account_routes.ts` `/logout`). For user-facing revocation
+ * caller — see `auth/account_routes.ts` `/logout`). For user-facing revocation
  * of a specific session by ID, use `query_session_revoke_for_account`
  * (IDOR-guarded).
+ *
+ * @mutates `auth_session` table - deletes the row keyed by `token_hash`
  */
 export declare const query_session_revoke_by_hash_unscoped: (deps: QueryDeps, token_hash: string) => Promise<void>;
 /**
@@ -71,12 +75,14 @@ export declare const query_session_revoke_by_hash_unscoped: (deps: QueryDeps, to
  * @param token_hash - blake3 hash of the session token
  * @param account_id - the account that must own the session
  * @returns `true` if a session was revoked, `false` if not found or wrong account
+ * @mutates `auth_session` table - deletes the row when account ownership matches
  */
 export declare const query_session_revoke_for_account: (deps: QueryDeps, token_hash: string, account_id: string) => Promise<boolean>;
 /**
  * Revoke all sessions for an account.
  *
  * @returns the number of sessions revoked
+ * @mutates `auth_session` table - deletes every row for `account_id`
  */
 export declare const query_session_revoke_all_for_account: (deps: QueryDeps, account_id: string) => Promise<number>;
 /**
@@ -104,6 +110,7 @@ export declare const query_session_list_for_account: (deps: QueryDeps, account_i
  * @param account_id - the account to enforce the limit for
  * @param max_sessions - maximum number of sessions to keep
  * @returns the number of sessions evicted
+ * @mutates `auth_session` table - deletes the oldest rows past the cap
  */
 export declare const query_session_enforce_limit: (deps: QueryDeps, account_id: string, max_sessions: number) => Promise<number>;
 /**
@@ -120,6 +127,7 @@ export declare const query_session_list_all_active: (deps: QueryDeps, limit?: nu
  * Delete expired sessions.
  *
  * @returns the number of sessions cleaned up
+ * @mutates `auth_session` table - deletes every row past `expires_at`
  */
 export declare const query_session_cleanup_expired: (deps: QueryDeps) => Promise<number>;
 /**
@@ -134,6 +142,7 @@ export declare const query_session_cleanup_expired: (deps: QueryDeps) => Promise
  * @param pending_effects - optional array to register the effect for later awaiting
  * @param log - the logger instance
  * @returns the settled promise (callers may ignore it — fire-and-forget semantics preserved)
+ * @mutates `pending_effects` - pushes the in-flight settled promise when provided
  */
 export declare const session_touch_fire_and_forget: (deps: QueryDeps, token_hash: string, pending_effects: Array<Promise<void>> | undefined, log: Logger) => Promise<void>;
 //# sourceMappingURL=session_queries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"session_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAErD,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,QAA2B,CAAC;AAEjE,yEAAyE;AACzE,eAAO,MAAM,gCAAgC,QAAsB,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,MAElD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAO,MAEzC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,EAClB,YAAY,IAAI,KACd,OAAO,CAAC,IAAI,CAMd,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,WAAW,GAAG,SAAS,CAKjC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAU,MAAM,SAAS,EAAE,YAAY,MAAM,KAAG,OAAO,CAAC,IAAI,CAY3F,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,IAAI,CAEd,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAMjB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAU,KACR,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAK5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAc,MAAM,KAClB,OAAO,CAAC,MAAM,CAYhB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,cAAW,KACT,OAAO,CAAC,KAAK,CAAC,WAAW,GAAG;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAAC,CASjD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,MAAM,CAKnF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,iBAAiB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EACjD,KAAK,MAAM,KACT,OAAO,CAAC,IAAI,CAMd,CAAC"}
+{"version":3,"file":"session_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAErD,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,QAA2B,CAAC;AAEjE,yEAAyE;AACzE,eAAO,MAAM,gCAAgC,QAAsB,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,MAElD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAO,MAEzC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,EAClB,YAAY,IAAI,KACd,OAAO,CAAC,IAAI,CAMd,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,WAAW,GAAG,SAAS,CAKjC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAU,MAAM,SAAS,EAAE,YAAY,MAAM,KAAG,OAAO,CAAC,IAAI,CAY3F,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,IAAI,CAEd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAMjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAU,KACR,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAK5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAc,MAAM,KAClB,OAAO,CAAC,MAAM,CAYhB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,cAAW,KACT,OAAO,CAAC,KAAK,CAAC,WAAW,GAAG;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAAC,CASjD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,MAAM,CAKnF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,iBAAiB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EACjD,KAAK,MAAM,KACT,OAAO,CAAC,IAAI,CAMd,CAAC"}

package/dist/auth/session_queries.js

@@ -36,6 +36,7 @@ export const generate_session_token = () => {
  * @param token_hash - blake3 hash of the session token (use `hash_session_token`)
  * @param account_id - the account this session belongs to
  * @param expires_at - when the session expires
+ * @mutates `auth_session` table - inserts a row keyed by `token_hash`
  */
 export const query_create_session = async (deps, token_hash, account_id, expires_at) => {
     await deps.db.query(`INSERT INTO auth_session (id, account_id, expires_at) VALUES ($1, $2, $3)`, [
@@ -60,6 +61,7 @@ export const query_session_get_valid = async (deps, token_hash) => {
  *
  * @param deps - query dependencies
  * @param token_hash - blake3 hash of the session token
+ * @mutates `auth_session` row - updates `last_seen_at` and conditionally `expires_at`
  */
 export const query_session_touch = async (deps, token_hash) => {
     const new_expires = new Date(Date.now() + AUTH_SESSION_LIFETIME_MS);
@@ -77,9 +79,11 @@ export const query_session_touch = async (deps, token_hash) => {
  * The `_unscoped` suffix is the safety signal — there is no `account_id`
  * constraint, so callers must guarantee the hash came from a trusted
  * source (the authenticated session cookie path is the only safe production
- * caller — see `account_routes.ts` `/logout`). For user-facing revocation
+ * caller — see `auth/account_routes.ts` `/logout`). For user-facing revocation
  * of a specific session by ID, use `query_session_revoke_for_account`
  * (IDOR-guarded).
+ *
+ * @mutates `auth_session` table - deletes the row keyed by `token_hash`
  */
 export const query_session_revoke_by_hash_unscoped = async (deps, token_hash) => {
     await deps.db.query(`DELETE FROM auth_session WHERE id = $1`, [token_hash]);
@@ -93,6 +97,7 @@ export const query_session_revoke_by_hash_unscoped = async (deps, token_hash) =>
  * @param token_hash - blake3 hash of the session token
  * @param account_id - the account that must own the session
  * @returns `true` if a session was revoked, `false` if not found or wrong account
+ * @mutates `auth_session` table - deletes the row when account ownership matches
  */
 export const query_session_revoke_for_account = async (deps, token_hash, account_id) => {
     const rows = await deps.db.query(`DELETE FROM auth_session WHERE id = $1 AND account_id = $2 RETURNING id`, [token_hash, account_id]);
@@ -102,6 +107,7 @@ export const query_session_revoke_for_account = async (deps, token_hash, account
  * Revoke all sessions for an account.
  *
  * @returns the number of sessions revoked
+ * @mutates `auth_session` table - deletes every row for `account_id`
  */
 export const query_session_revoke_all_for_account = async (deps, account_id) => {
     const rows = await deps.db.query(`DELETE FROM auth_session WHERE account_id = $1 RETURNING id`, [account_id]);
@@ -134,6 +140,7 @@ export const query_session_list_for_account = async (deps, account_id, limit = 5
  * @param account_id - the account to enforce the limit for
  * @param max_sessions - maximum number of sessions to keep
  * @returns the number of sessions evicted
+ * @mutates `auth_session` table - deletes the oldest rows past the cap
  */
 export const query_session_enforce_limit = async (deps, account_id, max_sessions) => {
     const rows = await deps.db.query(`DELETE FROM auth_session
@@ -163,6 +170,7 @@ export const query_session_list_all_active = async (deps, limit = 200) => {
  * Delete expired sessions.
  *
  * @returns the number of sessions cleaned up
+ * @mutates `auth_session` table - deletes every row past `expires_at`
  */
 export const query_session_cleanup_expired = async (deps) => {
     const rows = await deps.db.query(`DELETE FROM auth_session WHERE expires_at <= NOW() RETURNING id`);
@@ -180,6 +188,7 @@ export const query_session_cleanup_expired = async (deps) => {
  * @param pending_effects - optional array to register the effect for later awaiting
  * @param log - the logger instance
  * @returns the settled promise (callers may ignore it — fire-and-forget semantics preserved)
+ * @mutates `pending_effects` - pushes the in-flight settled promise when provided
  */
 export const session_touch_fire_and_forget = (deps, token_hash, pending_effects, log) => {
     const p = query_session_touch(deps, token_hash).catch((err) => {

package/dist/auth/signup_routes.d.ts

@@ -3,7 +3,7 @@
  *
  * Public endpoint that creates an account. When `open_signup` is disabled
  * (default), a matching unclaimed invite is required. When enabled, anyone
- * can sign up without an invite. Follows the `bootstrap_routes.ts` pattern.
+ * can sign up without an invite. Follows the `auth/bootstrap_routes.ts` pattern.
  *
  * @module
  */