@fuzdev/fuz_app 0.51.0 → 0.53.0

package/dist/auth/permit_offer_queries.d.ts

@@ -66,6 +66,9 @@ 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`
  */
 export declare const query_permit_offer_create: (deps: QueryDeps, input: CreatePermitOfferInput) => Promise<PermitOffer>;
 /**
@@ -75,6 +78,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 +90,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 +169,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;;;;;;;;;;;;;;;;GAgBG;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,9 @@ 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`
  */
 export const query_permit_offer_create = async (deps, input) => {
     const actor = await query_actor_by_account(deps, input.to_account_id);
@@ -108,6 +111,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 +136,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 +257,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,7 @@ 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)`
  */
 export declare const query_grant_permit: (deps: QueryDeps, input: GrantPermitInput) => Promise<Permit>;
 /**
@@ -79,6 +80,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 +160,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 +203,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":"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"}
+{"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,7 @@ 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)`
  */
 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 +87,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 +202,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 +256,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/self_service_role_actions.d.ts

@@ -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

@@ -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,8 @@ 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)
  */
 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;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,GACzC,SAAS,gCAAgC,KACvC,OAAO,CAAC,IAAI,CAad,CAAC"}

package/dist/auth/session_lifecycle.js

@@ -12,6 +12,8 @@ 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)
  */
 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

@@ -28,6 +28,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;;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;;;;;;;;;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

@@ -44,6 +44,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>;
 /**
@@ -60,6 +62,8 @@ export declare const query_session_touch: (deps: QueryDeps, token_hash: string)
  * 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);
@@ -80,6 +82,8 @@ export const query_session_touch = async (deps, token_hash) => {
  * 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/cli/config.d.ts

@@ -37,12 +37,11 @@ export declare const load_config: <T>(runtime: Pick<FsReadDeps, "stat" | "read_t
 /**
  * Save CLI configuration to a JSON file.
  *
- * Creates parent directories if they don't exist.
- *
  * @param runtime - runtime with file write capability
  * @param path - path to the config JSON file
  * @param dir - directory containing the config file (created if missing)
  * @param config - configuration to save
+ * @mutates filesystem - creates `dir` (recursive) and writes JSON to `path`
  */
 export declare const save_config: <T>(runtime: Pick<FsWriteDeps, "mkdir" | "write_text_file">, path: string, dir: string, config: T) => Promise<void>;
 //# sourceMappingURL=config.d.ts.map

package/dist/cli/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,IAGtF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,IAG1F,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EAClC,SAAS,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAAG,OAAO,EAC9D,MAAM,MAAM,EACZ,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAClB,OAAO,CAAC,CAAC,GAAG,IAAI,CAoBlB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EAClC,SAAS,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,CAAC,EACvD,MAAM,MAAM,EACZ,KAAK,MAAM,EACX,QAAQ,CAAC,KACP,OAAO,CAAC,IAAI,CAOd,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,IAGtF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,IAG1F,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EAClC,SAAS,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAAG,OAAO,EAC9D,MAAM,MAAM,EACZ,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAClB,OAAO,CAAC,CAAC,GAAG,IAAI,CAoBlB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EAClC,SAAS,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,CAAC,EACvD,MAAM,MAAM,EACZ,KAAK,MAAM,EACX,QAAQ,CAAC,KACP,OAAO,CAAC,IAAI,CAOd,CAAC"}

package/dist/cli/config.js

@@ -61,12 +61,11 @@ export const load_config = async (runtime, path, schema) => {
 /**
  * Save CLI configuration to a JSON file.
  *
- * Creates parent directories if they don't exist.
- *
  * @param runtime - runtime with file write capability
  * @param path - path to the config JSON file
  * @param dir - directory containing the config file (created if missing)
  * @param config - configuration to save
+ * @mutates filesystem - creates `dir` (recursive) and writes JSON to `path`
  */
 export const save_config = async (runtime, path, dir, config) => {
     // ensure directory exists

package/dist/cli/daemon.d.ts

@@ -39,6 +39,8 @@ export declare const get_daemon_info_path: (runtime: Pick<EnvDeps, "env_get">, n
  * @param runtime - runtime with file write and env capabilities
  * @param name - application name
  * @param info - daemon info to write
+ * @mutates filesystem - creates `~/.{name}/run/` and atomically writes `daemon.json`
+ * @throws Error if `$HOME` is not set
  */
 export declare const write_daemon_info: (runtime: Pick<EnvDeps, "env_get"> & Pick<FsWriteDeps, "mkdir" | "write_text_file" | "rename">, name: string, info: DaemonInfo) => Promise<void>;
 /**
@@ -85,11 +87,14 @@ export interface StopDaemonResult {
  * Stop a running daemon by sending SIGTERM and cleaning up the PID file.
  *
  * Returns a result object instead of logging directly, separating
- * lifecycle from presentation.
+ * lifecycle from presentation. Errors removing the PID file are swallowed
+ * (the daemon's own shutdown handler may have removed it concurrently).
  *
  * @param runtime - runtime with command, file, and env capabilities
  * @param name - application name
  * @returns result describing the outcome
+ * @mutates filesystem - removes `~/.{name}/run/daemon.json` on success or when corrupt
+ * @mutates external process - sends `SIGTERM` to the daemon process via `kill`
  */
 export declare const stop_daemon: (runtime: Pick<EnvDeps, "env_get"> & Pick<FsReadDeps, "stat" | "read_text_file"> & FsRemoveDeps & CommandDeps & LogDeps, name: string) => Promise<StopDaemonResult>;
 //# sourceMappingURL=daemon.d.ts.map

package/dist/cli/daemon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daemon.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,MAAM,oBAAoB,CAAC;AAI5B;;GAEG;AACH,eAAO,MAAM,UAAU;IACtB,sBAAsB;;IAEtB,yBAAyB;;IAEzB,uCAAuC;;IAEvC,yCAAyC;;IAEzC,0CAA0C;;kBAEzC,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,MAAM,KACV,MAAM,GAAG,IAGX,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,GAAG,QAAQ,CAAC,EAC7F,MAAM,MAAM,EACZ,MAAM,UAAU,KACd,OAAO,CAAC,IAAI,CAWd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC5B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAAG,OAAO,EACzF,MAAM,MAAM,KACV,OAAO,CAAC,UAAU,GAAG,IAAI,CAwB3B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAU,SAAS,WAAW,EAAE,KAAK,MAAM,KAAG,OAAO,CAAC,OAAO,CAG1F,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,MAAM,MAAM,EACZ,aAAkB,EAClB,mBAAiB,KACf,OAAO,CAAC,OAAO,CAYjB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GACvB,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAChC,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAC3C,YAAY,GACZ,WAAW,GACX,OAAO,EACR,MAAM,MAAM,KACV,OAAO,CAAC,gBAAgB,CA2C1B,CAAC"}
+{"version":3,"file":"daemon.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,MAAM,oBAAoB,CAAC;AAI5B;;GAEG;AACH,eAAO,MAAM,UAAU;IACtB,sBAAsB;;IAEtB,yBAAyB;;IAEzB,uCAAuC;;IAEvC,yCAAyC;;IAEzC,0CAA0C;;kBAEzC,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,MAAM,KACV,MAAM,GAAG,IAGX,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,GAAG,QAAQ,CAAC,EAC7F,MAAM,MAAM,EACZ,MAAM,UAAU,KACd,OAAO,CAAC,IAAI,CAWd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC5B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAAG,OAAO,EACzF,MAAM,MAAM,KACV,OAAO,CAAC,UAAU,GAAG,IAAI,CAwB3B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAU,SAAS,WAAW,EAAE,KAAK,MAAM,KAAG,OAAO,CAAC,OAAO,CAG1F,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,MAAM,MAAM,EACZ,aAAkB,EAClB,mBAAiB,KACf,OAAO,CAAC,OAAO,CAYjB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GACvB,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAChC,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAC3C,YAAY,GACZ,WAAW,GACX,OAAO,EACR,MAAM,MAAM,KACV,OAAO,CAAC,gBAAgB,CA2C1B,CAAC"}

package/dist/cli/daemon.js

@@ -43,6 +43,8 @@ export const get_daemon_info_path = (runtime, name) => {
  * @param runtime - runtime with file write and env capabilities
  * @param name - application name
  * @param info - daemon info to write
+ * @mutates filesystem - creates `~/.{name}/run/` and atomically writes `daemon.json`
+ * @throws Error if `$HOME` is not set
  */
 export const write_daemon_info = async (runtime, name, info) => {
     const app_dir = get_app_dir(runtime, name);
@@ -126,11 +128,14 @@ export const check_daemon_health = async (deps, port, host = 'localhost', timeou
  * Stop a running daemon by sending SIGTERM and cleaning up the PID file.
  *
  * Returns a result object instead of logging directly, separating
- * lifecycle from presentation.
+ * lifecycle from presentation. Errors removing the PID file are swallowed
+ * (the daemon's own shutdown handler may have removed it concurrently).
  *
  * @param runtime - runtime with command, file, and env capabilities
  * @param name - application name
  * @returns result describing the outcome
+ * @mutates filesystem - removes `~/.{name}/run/daemon.json` on success or when corrupt
+ * @mutates external process - sends `SIGTERM` to the daemon process via `kill`
  */
 export const stop_daemon = async (runtime, name) => {
     const daemon_path = get_daemon_info_path(runtime, name);

package/dist/db/assert_row.d.ts

@@ -12,7 +12,8 @@
  *
  * @param row - the row from `query_one` (`T | undefined`) or `rows[0]` (`T | undefined`)
  * @param context - optional context for the error message (e.g. table or operation name)
- * @returns the row, guaranteed non-undefined
+ * @returns the row, guaranteed non-`undefined`
+ * @throws Error if `row` is `undefined`
  */
 export declare const assert_row: <T>(row: T | undefined, context?: string) => T;
 //# sourceMappingURL=assert_row.d.ts.map

package/dist/db/assert_row.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert_row.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/assert_row.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,KAAK,CAAC,GAAG,SAAS,EAAE,UAAU,MAAM,KAAG,CASpE,CAAC"}
+{"version":3,"file":"assert_row.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/assert_row.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,KAAK,CAAC,GAAG,SAAS,EAAE,UAAU,MAAM,KAAG,CASpE,CAAC"}

package/dist/db/assert_row.js

@@ -12,7 +12,8 @@
  *
  * @param row - the row from `query_one` (`T | undefined`) or `rows[0]` (`T | undefined`)
  * @param context - optional context for the error message (e.g. table or operation name)
- * @returns the row, guaranteed non-undefined
+ * @returns the row, guaranteed non-`undefined`
+ * @throws Error if `row` is `undefined`
  */
 export const assert_row = (row, context) => {
     if (row === undefined) {

package/dist/db/create_db.d.ts

@@ -24,7 +24,6 @@ export interface CreateDbResult {
 /**
  * Create a database connection based on a URL.
  *
- * Returns the `Db` instance, a typed `close` callback, driver type, and display name.
  * The `close` callback is bound to the actual driver — callers never need to
  * know which driver is in use.
  *
@@ -33,6 +32,9 @@ export interface CreateDbResult {
  *
  * @param database_url - connection URL (`postgres://`, `postgresql://`, `file://`, or `memory://`)
  * @returns database instance, close callback, type, and display name
+ * @throws Error if `database_url` uses an unsupported scheme. Driver
+ *   construction (`pg.Pool` or `PGlite`) may also throw on bad connection
+ *   parameters or missing peer-dependency packages.
  */
 export declare const create_db: (database_url: string) => Promise<CreateDbResult>;
 //# sourceMappingURL=create_db.d.ts.map