@fuzdev/fuz_app 0.117.1 → 0.118.0

package/dist/auth/CLAUDE.md

@@ -125,7 +125,7 @@ its registered listeners + optional `AuditLogConfig`. Six methods:
 
 - `emit(ctx, input)` — fire-and-forget pool write, pushes to `ctx.pending_effects`
 - `emit_role_grant_target(ctx, auth, input)` — lifts `actor_id` / `account_id` / `ip` boilerplate for role-grant-shape events
-- `emit_pool(input)` — awaitable pool write for code paths without `pending_effects` (cleanup sweeps)
+- `emit_pool(input)` — awaitable pool write for code paths without `pending_effects` (ad-hoc maintenance scripts; not for success audits paired with a mutation — those write in-tx and `notify` post-commit)
 - `notify(event)` — fan out an already-written row to listeners (used by in-tx audit batches like `query_accept_offer.audit_events`)
 - `add_listener(listener)` — append-only listener registration (twin of Rust `fuz_auth` `AuditEmitter::add_listener`)
 - `listener_count()` — registered-listener count, for tests / diagnostics
@@ -843,11 +843,24 @@ drops the hand-maintained method-name mappings:
 
 `auth/cleanup.ts` — `run_auth_cleanup(deps)` runs every sweep (expired
 sessions + expired offers) and returns counts. Re-throws sweep errors so the
-caller's scheduler can log/alert. Idempotency: audit log has no tombstone on
-`role_grant_offer_expire`, so concurrent runs double-audit — deploy a single
-scheduled invocation per instance. Expired offer rows are preserved (audit
+caller's scheduler can log/alert. Expired offer rows are preserved (audit
 value for the history view).
 
+**Idempotency.** `cleanup_expired_role_grant_offers` runs one transaction:
+`query_role_grant_offer_sweep_expired` claims the expired pending offers not
+yet audited by stamping `role_grant_offer.expire_audited_at` (`UPDATE …
+RETURNING`), and each claimed row's `role_grant_offer_expire` audit row is
+inserted in the same transaction; events fan out via `audit.notify` after the
+commit. Each expiry is audited exactly once — a second run finds nothing, and
+concurrent runs claim disjoint rows (a row another sweep holds blocks on its
+row lock, then fails the re-checked stamp). A failed audit insert rolls the
+stamps back and the next run retries, so the offer sweep can throw. The stamp
+is not a lifecycle state (outside the terminal CHECK and the pending
+predicate) and stays off the wire (`to_role_grant_offer_json` drops it); the
+create upsert's re-offer clears it, so a refreshed offer's own expiry is
+audited too. The `role_grant_offer_expire_sweep` partial index serves the
+claim. Twin of the Rust `fuz_auth::auth_cleanup` module.
+
 `AuthCleanupDeps` requires `audit: AuditEmitter` — production wiring always
 has a bound emitter; tests pass `create_test_audit_emitter()` from
 `testing/stubs.ts`.

package/dist/auth/audit_emitter.d.ts

@@ -22,12 +22,13 @@
  *   `actor_id` / `account_id` / `ip` boilerplate every role-grant-shape audit
  *   site repeated. Delegates to `emit`.
  * - `emit_pool(input)` — awaitable pool write for code paths without a
- *   `pending_effects` queue (cleanup sweeps, ad-hoc maintenance scripts).
- *   Same write-then-notify semantics as `emit`, just synchronous-with-await.
+ *   `pending_effects` queue (ad-hoc maintenance scripts). Same
+ *   write-then-notify semantics as `emit`, just synchronous-with-await.
  * - `notify(event)` — fan out an already-written audit row (e.g. rows
  *   returned by `query_accept_offer` that were inserted in-transaction by
- *   the query layer). Runs every registered listener; per-listener throws
- *   are isolated.
+ *   the query layer, or the offer-expiry rows `auth/cleanup.ts` writes in
+ *   its sweep transaction). Runs every registered listener; per-listener
+ *   throws are isolated.
  *
  * Listeners are a documented registration seam — `create_app_server`
  * registers additional listeners via `add_listener` after the backend is
@@ -119,10 +120,14 @@ export interface AuditEmitter {
      * Awaitable pool write for code paths without a `pending_effects` queue.
      *
      * Same write-then-notify semantics as `emit`. Errors are logged and
-     * swallowed (resolved void), so callers can sequence sweeps with
-     * `await audit.emit_pool(...)` without try/catch boilerplate. The
-     * primary user is `auth/cleanup.ts` — sweeps have no per-request
-     * `pending_effects` to attach to.
+     * swallowed (resolved void), so callers can sequence writes with
+     * `await audit.emit_pool(...)` without try/catch boilerplate.
+     *
+     * Not for a success audit paired with a state mutation: the pool write
+     * can't roll back with the state, and a swallowed error leaves the
+     * mutation unaudited. Write those in the mutation's transaction
+     * (`query_audit_log` against the tx) and `notify` after the commit — the
+     * shape `auth/cleanup.ts`'s offer sweep and `query_accept_offer` use.
      *
      * @mutates `audit_log` table - inserts the row via the captured pool
      */

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

@@ -1 +1 @@
-{"version":3,"file":"audit_emitter.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,mBAAmB;IACnC,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACrE,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAChF;;;;;;;OAOG;IACH,sBAAsB,CAAC,CAAC,SAAS,MAAM,EACtC,GAAG,EAAE,yBAAyB,EAC9B,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE;QACN,UAAU,EAAE,CAAC,CAAC;QACd,iBAAiB,EAAE,IAAI,GAAG,IAAI,CAAC;QAC/B,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;QAC7B,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACvC,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;KAChC,GACC,IAAI,CAAC;IACR;;;;;;;;;;OAUG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACnC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI,CAAC;IAC7D,+EAA+E;IAC/E,cAAc,IAAI,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,SAAS,MAAM,EAC1C,GAAG,EAAE,mBAAmB,EACxB,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,KACnB,IAAI,CAAC;AAEV;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,WAAW,CAAC;AAEhE,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACzC,oDAAoD;IACpD,EAAE,EAAE,EAAE,CAAC;IACP,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,cAAc,CAAC;IAClC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,yBAAyB,KAAG,YAuFzE,CAAC"}
+{"version":3,"file":"audit_emitter.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/audit_emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,mBAAmB;IACnC,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACrE,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAChF;;;;;;;OAOG;IACH,sBAAsB,CAAC,CAAC,SAAS,MAAM,EACtC,GAAG,EAAE,yBAAyB,EAC9B,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE;QACN,UAAU,EAAE,CAAC,CAAC;QACd,iBAAiB,EAAE,IAAI,GAAG,IAAI,CAAC;QAC/B,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;QAC7B,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACvC,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;KAChC,GACC,IAAI,CAAC;IACR;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACnC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI,CAAC;IAC7D,+EAA+E;IAC/E,cAAc,IAAI,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,SAAS,MAAM,EAC1C,GAAG,EAAE,mBAAmB,EACxB,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,KACnB,IAAI,CAAC;AAEV;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,WAAW,CAAC;AAEhE,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACzC,oDAAoD;IACpD,EAAE,EAAE,EAAE,CAAC;IACP,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,cAAc,CAAC;IAClC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,yBAAyB,KAAG,YAuFzE,CAAC"}

package/dist/auth/audit_emitter.js

@@ -22,12 +22,13 @@
  *   `actor_id` / `account_id` / `ip` boilerplate every role-grant-shape audit
  *   site repeated. Delegates to `emit`.
  * - `emit_pool(input)` — awaitable pool write for code paths without a
- *   `pending_effects` queue (cleanup sweeps, ad-hoc maintenance scripts).
- *   Same write-then-notify semantics as `emit`, just synchronous-with-await.
+ *   `pending_effects` queue (ad-hoc maintenance scripts). Same
+ *   write-then-notify semantics as `emit`, just synchronous-with-await.
  * - `notify(event)` — fan out an already-written audit row (e.g. rows
  *   returned by `query_accept_offer` that were inserted in-transaction by
- *   the query layer). Runs every registered listener; per-listener throws
- *   are isolated.
+ *   the query layer, or the offer-expiry rows `auth/cleanup.ts` writes in
+ *   its sweep transaction). Runs every registered listener; per-listener
+ *   throws are isolated.
  *
  * Listeners are a documented registration seam — `create_app_server`
  * registers additional listeners via `add_listener` after the backend is

package/dist/auth/bootstrap_account.d.ts

@@ -53,8 +53,9 @@ export interface BootstrapAccountDeps {
     token_path: string;
     /**
      * Hardened secret-file read (see `FsSecureReadDeps.read_secure_file`) —
-     * the token mints the keeper account, so a symlinked, group/other-readable,
-     * or oversized file must refuse rather than be honored. Throws on refusal;
+     * the token mints the keeper account, so a symlinked, non-regular,
+     * group/other-readable, or oversized file must refuse rather than be
+     * honored. Throws on refusal;
      * every throw reads as `TOKEN_FILE_MISSING` upstream.
      */
     read_secure_file: (path: string) => Promise<Uint8Array>;

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

@@ -1 +1 @@
-{"version":3,"file":"bootstrap_account.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/bootstrap_account.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EACN,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGrE,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEtC,gDAAgD;AAChD,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,6DAA6D;AAC7D,MAAM,WAAW,uBAAuB;IACvC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,CAAC;IACrD,wFAAwF;IACxF,kBAAkB,EAAE,OAAO,CAAC;CAC5B;AAED,gCAAgC;AAChC,MAAM,MAAM,uBAAuB,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,0BAA0B,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GACpE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,wBAAwB,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GAClE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,mBAAmB,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC;AAEjE,qFAAqF;AACrF,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,GAAG,uBAAuB,CAAC;AAEvF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,EAAE,CAAC;IACP,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IACxD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,6EAA6E;IAC7E,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;IAClD,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,oBAAoB,EAC1B,gBAAgB,MAAM,EACtB,OAAO,qBAAqB,KAC1B,OAAO,CAAC,sBAAsB,CA2EhC,CAAC"}
+{"version":3,"file":"bootstrap_account.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/bootstrap_account.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EACN,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGrE,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEtC,gDAAgD;AAChD,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,6DAA6D;AAC7D,MAAM,WAAW,uBAAuB;IACvC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,CAAC;IACrD,wFAAwF;IACxF,kBAAkB,EAAE,OAAO,CAAC;CAC5B;AAED,gCAAgC;AAChC,MAAM,MAAM,uBAAuB,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,0BAA0B,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GACpE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,wBAAwB,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GAClE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,mBAAmB,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC;AAEjE,qFAAqF;AACrF,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,GAAG,uBAAuB,CAAC;AAEvF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,EAAE,CAAC;IACP,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IACxD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,6EAA6E;IAC7E,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;IAClD,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,oBAAoB,EAC1B,gBAAgB,MAAM,EACtB,OAAO,qBAAqB,KAC1B,OAAO,CAAC,sBAAsB,CA2EhC,CAAC"}

package/dist/auth/bootstrap_account.js

@@ -36,9 +36,9 @@ import { query_create_role_grant } from './role_grant_queries.js';
 export const bootstrap_account = async (deps, provided_token, input) => {
     const { db, token_path, read_secure_file, delete_file, password, log } = deps;
     // 1. Read and verify token (non-destructive, before transaction). The
-    // secure read fails loud on a symlink / permissive mode / oversized file —
-    // every refusal masks as the same TOKEN_FILE_MISSING the wire always
-    // carried, with the specific reason logged for the operator.
+    // secure read fails loud on a symlink / non-regular file / permissive mode /
+    // oversized file — every refusal masks as the same TOKEN_FILE_MISSING the
+    // wire always carried, with the specific reason logged for the operator.
     let expected_token;
     try {
         expected_token = new TextDecoder().decode(await read_secure_file(token_path)).trim();

package/dist/auth/cleanup.d.ts

@@ -11,10 +11,13 @@
  * `role_grant_offer_expire` audit emission and is the piece most likely to be
  * reused in a consumer's bespoke scheduler.
  *
- * Idempotency: the audit log has no tombstone on `role_grant_offer_expire`, so
- * concurrent sweep runs double-audit. The expected deployment pattern is a
- * single scheduled invocation per instance — matching
- * `query_session_cleanup_expired`.
+ * Idempotency: the offer sweep claims each expired offer by stamping
+ * `role_grant_offer.expire_audited_at` in the same transaction as its
+ * `role_grant_offer_expire` audit row, so every expiry is audited exactly
+ * once — a second run finds nothing, and concurrent runs claim disjoint rows
+ * (row locks serialize them on the re-checked stamp). A failed audit insert
+ * rolls the stamps back with it and the next run retries. A re-offer clears
+ * the stamp, so the refreshed offer's own expiry is audited too.
  *
  * @module
  */
@@ -25,11 +28,12 @@ import type { AuditEmitter } from './audit_emitter.js';
 export interface AuthCleanupDeps extends QueryDeps {
     log: Logger;
     /**
-     * Bound audit emitter. `cleanup_expired_role_grant_offers` writes via
-     * `audit.emit_pool` (the captured pool + config + listener chain), so
-     * one slot covers both row persistence and SSE/WS fan-out. Required —
-     * production wiring always has a bound emitter on `AppDeps.audit`, and
-     * tests that need a no-op pass `create_test_audit_emitter()`.
+     * Bound audit emitter. `cleanup_expired_role_grant_offers` writes its audit
+     * rows in its own transaction and fans each one out through `audit.notify`
+     * after the commit, so listeners never see an event that rolled back.
+     * Required — production wiring always has a bound emitter on
+     * `AppDeps.audit`, and tests that need a no-op pass
+     * `create_test_audit_emitter()`.
      */
     audit: AuditEmitter;
 }
@@ -42,15 +46,24 @@ export interface AuthCleanupResult {
 }
 /**
  * Sweep expired role_grant offers and emit one `role_grant_offer_expire` audit
- * event per row.
+ * event per newly expired row.
  *
- * Returns the count of offers audit-stamped. The offer rows themselves are
+ * One transaction: `query_role_grant_offer_sweep_expired` claims the expired,
+ * not-yet-audited offers (stamping `expire_audited_at`) and each claimed row's
+ * audit row is inserted beside it. After the commit, each event fans out
+ * through `deps.audit.notify` — per-listener throws are isolated there, so one
+ * bad listener never starves the rest. Twin of the Rust
+ * `cleanup_expired_role_grant_offers`.
+ *
+ * Returns the count of offers audited. The offer rows themselves are
  * preserved — offers carry audit value for the history view even after
  * expiry, and accepted rows are the provenance for the resulting role_grant
  * (deleting expired rows would not threaten that, but keeping them uniform
  * with the retention policy for terminal rows is simpler).
  *
+ * @mutates `role_grant_offer` rows - stamps `expire_audited_at` on each swept offer
  * @mutates `audit_log` table - inserts one `role_grant_offer_expire` row per swept offer
+ * @throws Error if the claim or an audit insert fails — the transaction rolls back, so no offer is stamped and the next run retries
  */
 export declare const cleanup_expired_role_grant_offers: (deps: AuthCleanupDeps) => Promise<number>;
 /**
@@ -64,6 +77,7 @@ export declare const cleanup_expired_role_grant_offers: (deps: AuthCleanupDeps)
  * directly if you need finer error isolation.
  *
  * @mutates `auth_session` table - deletes expired sessions
+ * @mutates `role_grant_offer` rows - stamps `expire_audited_at` on expired offers
  * @mutates `audit_log` table - emits `role_grant_offer_expire` rows for expired offers
  * @throws Error re-thrown from any sweep that fails (no per-sweep isolation here)
  */

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

@@ -1 +1 @@
-{"version":3,"file":"cleanup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,4CAA4C;AAC5C,MAAM,WAAW,eAAgB,SAAQ,SAAS;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,KAAK,EAAE,YAAY,CAAC;CACpB;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IACjC,8CAA8C;IAC9C,gBAAgB,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAAU,MAAM,eAAe,KAAG,OAAO,CAAC,MAAM,CAuB7F,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAAU,MAAM,eAAe,KAAG,OAAO,CAAC,iBAAiB,CAIvF,CAAC"}
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,4CAA4C;AAC5C,MAAM,WAAW,eAAgB,SAAQ,SAAS;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,KAAK,EAAE,YAAY,CAAC;CACpB;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IACjC,8CAA8C;IAC9C,gBAAgB,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iCAAiC,GAAU,MAAM,eAAe,KAAG,OAAO,CAAC,MAAM,CAgC7F,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,GAAU,MAAM,eAAe,KAAG,OAAO,CAAC,iBAAiB,CAIvF,CAAC"}

package/dist/auth/cleanup.js

@@ -11,50 +11,68 @@
  * `role_grant_offer_expire` audit emission and is the piece most likely to be
  * reused in a consumer's bespoke scheduler.
  *
- * Idempotency: the audit log has no tombstone on `role_grant_offer_expire`, so
- * concurrent sweep runs double-audit. The expected deployment pattern is a
- * single scheduled invocation per instance — matching
- * `query_session_cleanup_expired`.
+ * Idempotency: the offer sweep claims each expired offer by stamping
+ * `role_grant_offer.expire_audited_at` in the same transaction as its
+ * `role_grant_offer_expire` audit row, so every expiry is audited exactly
+ * once — a second run finds nothing, and concurrent runs claim disjoint rows
+ * (row locks serialize them on the re-checked stamp). A failed audit insert
+ * rolls the stamps back with it and the next run retries. A re-offer clears
+ * the stamp, so the refreshed offer's own expiry is audited too.
  *
  * @module
  */
 import { query_session_cleanup_expired } from './session_queries.js';
 import { query_role_grant_offer_sweep_expired } from './role_grant_offer_queries.js';
+import { query_audit_log } from './audit_log_queries.js';
 /**
  * Sweep expired role_grant offers and emit one `role_grant_offer_expire` audit
- * event per row.
+ * event per newly expired row.
  *
- * Returns the count of offers audit-stamped. The offer rows themselves are
+ * One transaction: `query_role_grant_offer_sweep_expired` claims the expired,
+ * not-yet-audited offers (stamping `expire_audited_at`) and each claimed row's
+ * audit row is inserted beside it. After the commit, each event fans out
+ * through `deps.audit.notify` — per-listener throws are isolated there, so one
+ * bad listener never starves the rest. Twin of the Rust
+ * `cleanup_expired_role_grant_offers`.
+ *
+ * Returns the count of offers audited. The offer rows themselves are
  * preserved — offers carry audit value for the history view even after
  * expiry, and accepted rows are the provenance for the resulting role_grant
  * (deleting expired rows would not threaten that, but keeping them uniform
  * with the retention policy for terminal rows is simpler).
  *
+ * @mutates `role_grant_offer` rows - stamps `expire_audited_at` on each swept offer
  * @mutates `audit_log` table - inserts one `role_grant_offer_expire` row per swept offer
+ * @throws Error if the claim or an audit insert fails — the transaction rolls back, so no offer is stamped and the next run retries
  */
 export const cleanup_expired_role_grant_offers = async (deps) => {
-    const expired = await query_role_grant_offer_sweep_expired(deps);
-    for (const offer of expired) {
-        // `role_grant_offer_expire` populates `target_actor_id` only when the
-        // offer was actor-targeted (`to_actor_id` set at create time).
-        // Account-grain offers (no `to_actor_id`) never bound to a
-        // specific actor and leave the field null.
-        // `emit_pool` swallows + logs both write errors and per-listener
-        // throws, so a single bad row never starves the rest of the sweep.
-        await deps.audit.emit_pool({
-            event_type: 'role_grant_offer_expire',
-            actor_id: offer.from_actor_id,
-            target_account_id: offer.to_account_id,
-            target_actor_id: offer.to_actor_id,
-            ip: null,
-            metadata: {
-                offer_id: offer.id,
-                role: offer.role,
-                scope_id: offer.scope_id
-            }
-        });
-    }
-    return expired.length;
+    const events = await deps.db.transaction(async (tx) => {
+        const expired = await query_role_grant_offer_sweep_expired({ db: tx });
+        const written = [];
+        for (const offer of expired) {
+            // `role_grant_offer_expire` populates `target_actor_id` only when the
+            // offer was actor-targeted (`to_actor_id` set at create time).
+            // Account-grain offers (no `to_actor_id`) never bound to a
+            // specific actor and leave the field null. No request is behind a
+            // sweep, so `ip` stays null.
+            written.push(await query_audit_log({ db: tx }, {
+                event_type: 'role_grant_offer_expire',
+                actor_id: offer.from_actor_id,
+                target_account_id: offer.to_account_id,
+                target_actor_id: offer.to_actor_id,
+                ip: null,
+                metadata: {
+                    offer_id: offer.id,
+                    role: offer.role,
+                    scope_id: offer.scope_id
+                }
+            }));
+        }
+        return written;
+    });
+    for (const event of events)
+        deps.audit.notify(event);
+    return events.length;
 };
 /**
  * Run every auth cleanup sweep — expired sessions and expired role_grant
@@ -67,6 +85,7 @@ export const cleanup_expired_role_grant_offers = async (deps) => {
  * directly if you need finer error isolation.
  *
  * @mutates `auth_session` table - deletes expired sessions
+ * @mutates `role_grant_offer` rows - stamps `expire_audited_at` on expired offers
  * @mutates `audit_log` table - emits `role_grant_offer_expire` rows for expired offers
  * @throws Error re-thrown from any sweep that fails (no per-sweep isolation here)
  */

package/dist/auth/deps.d.ts

@@ -24,7 +24,7 @@ export interface AppDeps {
      * Hardened secret-file read — used for the bootstrap token (the file that
      * mints the keeper account). Production wiring passes the runtime's
      * `read_secure_file` (`FsSecureReadDeps`), which rejects symlinks,
-     * group/other-accessible modes, and oversized files; both the boot-time
+     * non-regular files, group/other-accessible modes, and oversized files; both the boot-time
      * availability probe and the request-time read go through this one
      * capability so the probe can never be laxer than the read it gates.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AA+BH,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtE,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,EAAE,aAAa,CAAC,MAAM,CAA8B,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CA6K5C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AA+BH,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtE,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,EAAE,aAAa,CAAC,MAAM,CAA8B,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CA0M5C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}

package/dist/auth/migrations.js

@@ -237,6 +237,33 @@ export const auth_migrations = [
         up: async (db) => {
             await db.query('ALTER TABLE auth_session DROP COLUMN IF EXISTS last_seen_at');
         }
+    },
+    // The expiry-audit stamp that makes the offer sweep idempotent.
+    //
+    // An expired pending offer has no terminal state — expiry is computed from
+    // `expires_at`, never written — so without a stamp every
+    // `cleanup_expired_role_grant_offers` run re-audited every expired offer.
+    // The sweep now claims rows by setting `expire_audited_at` in the same
+    // transaction as their `role_grant_offer_expire` audit rows, so each expiry
+    // is audited exactly once and concurrent sweeps claim disjoint rows.
+    //
+    // Not a lifecycle state: the column stays out of the
+    // `role_grant_offer_single_terminal` CHECK and the pending predicate, and
+    // off the wire. A re-offer of a stamped row clears it (the create upsert),
+    // so the refreshed offer's own expiry is audited too. The partial index
+    // serves exactly the sweep's claim predicate.
+    {
+        name: 'role_grant_offer_expire_audited_at',
+        up: async (db) => {
+            await db.query('ALTER TABLE role_grant_offer ADD COLUMN IF NOT EXISTS expire_audited_at TIMESTAMPTZ NULL');
+            await db.query(`CREATE INDEX IF NOT EXISTS role_grant_offer_expire_sweep
+  ON role_grant_offer (expires_at)
+  WHERE accepted_at IS NULL
+    AND declined_at IS NULL
+    AND retracted_at IS NULL
+    AND superseded_at IS NULL
+    AND expire_audited_at IS NULL`);
+        }
     }
 ];
 /** Pre-composed migration namespace for auth tables. */

package/dist/auth/role_grant_offer_ddl.d.ts

@@ -27,13 +27,15 @@ export declare const ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN = "GLOBAL";
  * The full `role_grant_offer` column set, named explicitly so a row read
  * fails loud on schema drift (see `ACCOUNT_COLUMNS` in
  * `auth/account_queries.ts` for the outage class). Column order follows
- * `RoleGrantOffer` and `ROLE_GRANT_OFFER_SCHEMA` below.
+ * `RoleGrantOffer` and `ROLE_GRANT_OFFER_SCHEMA` below, with
+ * `expire_audited_at` last — the appended `role_grant_offer_expire_audited_at`
+ * migration adds it after the frozen `CREATE TABLE`.
  *
  * Lives here rather than in `auth/role_grant_offer_queries.ts` because two
  * query modules project this table — see the placement rule in
  * `db/sql_columns.ts`.
  */
-export declare const ROLE_GRANT_OFFER_COLUMNS: readonly ["id", "from_actor_id", "to_account_id", "to_actor_id", "role", "scope_kind", "scope_id", "message", "created_at", "expires_at", "accepted_at", "declined_at", "decline_reason", "retracted_at", "superseded_at", "resulting_role_grant_id"];
+export declare const ROLE_GRANT_OFFER_COLUMNS: readonly ["id", "from_actor_id", "to_account_id", "to_actor_id", "role", "scope_kind", "scope_id", "message", "created_at", "expires_at", "accepted_at", "declined_at", "decline_reason", "retracted_at", "superseded_at", "resulting_role_grant_id", "expire_audited_at"];
 /**
  * The `role_grant_offer` timestamp override, by row qualifier (`''` bare,
  * `o` for the history JOIN, `u` for the `updated` CTE's outer select). Lives

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

@@ -1 +1 @@
-{"version":3,"file":"role_grant_offer_ddl.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_grant_offer_ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,mHAAmH;AACnH,eAAO,MAAM,oCAAoC,yCAAyC,CAAC;AAE3F;;;;;GAKG;AACH,eAAO,MAAM,wCAAwC,WAAW,CAAC;AAEjE;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,uPAiBmB,CAAC;AAEzD;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,8DAOhC,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,oCAAoC,QAMI,CAAC;AAEtD,eAAO,MAAM,uBAAuB,qzCAkClC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qCAAqC,2XAYpB,CAAC;AAE/B,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,kOAMX,CAAC"}
+{"version":3,"file":"role_grant_offer_ddl.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_grant_offer_ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,mHAAmH;AACnH,eAAO,MAAM,oCAAoC,yCAAyC,CAAC;AAE3F;;;;;GAKG;AACH,eAAO,MAAM,wCAAwC,WAAW,CAAC;AAEjE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,4QAkBmB,CAAC;AAEzD;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,8DAQhC,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,oCAAoC,QAMI,CAAC;AAKtD,eAAO,MAAM,uBAAuB,qzCAkClC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qCAAqC,2XAYpB,CAAC;AAE/B,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,kOAMX,CAAC"}

package/dist/auth/role_grant_offer_ddl.js

@@ -28,7 +28,9 @@ export const ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN = 'GLOBAL';
  * The full `role_grant_offer` column set, named explicitly so a row read
  * fails loud on schema drift (see `ACCOUNT_COLUMNS` in
  * `auth/account_queries.ts` for the outage class). Column order follows
- * `RoleGrantOffer` and `ROLE_GRANT_OFFER_SCHEMA` below.
+ * `RoleGrantOffer` and `ROLE_GRANT_OFFER_SCHEMA` below, with
+ * `expire_audited_at` last — the appended `role_grant_offer_expire_audited_at`
+ * migration adds it after the frozen `CREATE TABLE`.
  *
  * Lives here rather than in `auth/role_grant_offer_queries.ts` because two
  * query modules project this table — see the placement rule in
@@ -50,7 +52,8 @@ export const ROLE_GRANT_OFFER_COLUMNS = [
     'decline_reason',
     'retracted_at',
     'superseded_at',
-    'resulting_role_grant_id'
+    'resulting_role_grant_id',
+    'expire_audited_at'
 ];
 /**
  * The `role_grant_offer` timestamp override, by row qualifier (`''` bare,
@@ -68,7 +71,8 @@ export const role_grant_offer_expr = iso8601_timestamp_expr(ROLE_GRANT_OFFER_COL
     'accepted_at',
     'declined_at',
     'retracted_at',
-    'superseded_at'
+    'superseded_at',
+    'expire_audited_at'
 ]);
 /**
  * Outer `SELECT` over an `updated` CTE of `role_grant_offer` rows, joining
@@ -81,6 +85,9 @@ export const role_grant_offer_expr = iso8601_timestamp_expr(ROLE_GRANT_OFFER_COL
 export const ROLE_GRANT_OFFER_WITH_GRANTOR_SELECT = `SELECT ${qualify_columns(ROLE_GRANT_OFFER_COLUMNS, 'u', role_grant_offer_expr('u'))}, grantor.account_id AS from_account_id
 		FROM updated u
 		JOIN actor grantor ON grantor.id = u.from_actor_id`;
+// Frozen v1 body — `expire_audited_at` is added by the appended
+// `role_grant_offer_expire_audited_at` migration (with its partial sweep
+// index), so a fresh bootstrap and an old deployed DB converge on one shape.
 export const ROLE_GRANT_OFFER_SCHEMA = `
 CREATE TABLE IF NOT EXISTS role_grant_offer (
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

package/dist/auth/role_grant_offer_queries.d.ts

@@ -112,7 +112,9 @@ export declare class RoleGrantOfferActorAccountMismatchError extends Error {
  * `(to_account, role, scope)` while pending upserts the existing row,
  * refreshing `message` and `expires_at` (and `to_actor_id` — supplying
  * a different `to_actor_id` on re-offer narrows the existing row to the
- * named actor; supplying null widens it back to account-grain). A
+ * named actor; supplying null widens it back to account-grain) and clearing
+ * `expire_audited_at`, so a re-offer of an expired, already-audited row gets
+ * its own `role_grant_offer_expire` when the refreshed expiry passes. A
  * different grantor offering the same `(to_account, role, scope)` creates
  * a distinct row — multiple pending grantors coexist. After a terminal
  * state, a re-offer is a fresh INSERT.
@@ -176,7 +178,7 @@ export declare const query_role_grant_offer_retract: (deps: QueryDeps, offer_id:
  *
  * Expired offers are filtered server-side (`expires_at > NOW()`) so the
  * inbox never surfaces a row that can no longer be accepted. The periodic
- * sweep (`query_role_grant_offer_sweep_expired`) handles audit tombstoning.
+ * sweep (`query_role_grant_offer_sweep_expired`) audits each expiry once.
  */
 export declare const query_role_grant_offer_list: (deps: QueryDeps, to_account_id: string) => Promise<Array<RoleGrantOffer>>;
 /**
@@ -191,12 +193,19 @@ export declare const query_role_grant_offer_history_for_account: (deps: QueryDep
  */
 export declare const query_role_grant_offer_find_pending: (deps: QueryDeps, offer_id: string) => Promise<RoleGrantOffer | null>;
 /**
- * Return pending offers whose `expires_at` has passed.
+ * Claim the pending offers whose `expires_at` has passed and whose expiry has
+ * not been audited yet, stamping `expire_audited_at` on each, and return them
+ * soonest-expiry first.
  *
- * Callers fire `role_grant_offer_expire` audit events for each row. The schema
- * does not tombstone the row, so callers are responsible for their own
- * idempotency (e.g. check whether a `role_grant_offer_expire` audit event
- * already exists for the offer id).
+ * The stamp is the sweep's idempotency: a claimed row never matches again, so
+ * each expiry is audited exactly once. It must share a transaction with the
+ * caller's `role_grant_offer_expire` audit inserts — committed together, or
+ * rolled back together so the next sweep retries. Concurrent sweeps claim
+ * disjoint rows: a row another sweep has stamped but not committed blocks on
+ * its row lock, then fails the re-checked `expire_audited_at IS NULL`.
+ * `cleanup_expired_role_grant_offers` is the caller.
+ *
+ * @mutates `role_grant_offer` rows - stamps `expire_audited_at` on each claimed row
  */
 export declare const query_role_grant_offer_sweep_expired: (deps: QueryDeps) => Promise<Array<RoleGrantOffer>>;
 /** Input for `query_accept_offer`. */

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

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

package/dist/auth/role_grant_offer_queries.js

@@ -118,7 +118,9 @@ export class RoleGrantOfferActorAccountMismatchError extends Error {
  * `(to_account, role, scope)` while pending upserts the existing row,
  * refreshing `message` and `expires_at` (and `to_actor_id` — supplying
  * a different `to_actor_id` on re-offer narrows the existing row to the
- * named actor; supplying null widens it back to account-grain). A
+ * named actor; supplying null widens it back to account-grain) and clearing
+ * `expire_audited_at`, so a re-offer of an expired, already-audited row gets
+ * its own `role_grant_offer_expire` when the refreshed expiry passes. A
  * different grantor offering the same `(to_account, role, scope)` creates
  * a distinct row — multiple pending grantors coexist. After a terminal
  * state, a re-offer is a fresh INSERT.
@@ -170,7 +172,8 @@ export const query_role_grant_offer_create = async (deps, input) => {
 		 DO UPDATE SET
 			 to_actor_id = EXCLUDED.to_actor_id,
 			 message = EXCLUDED.message,
-			 expires_at = EXCLUDED.expires_at
+			 expires_at = EXCLUDED.expires_at,
+			 expire_audited_at = NULL
 		 RETURNING ${columns_sql(ROLE_GRANT_OFFER_COLUMNS, role_grant_offer_expr(''))}`, [
         input.from_actor_id,
         input.to_account_id,
@@ -269,7 +272,7 @@ const resolve_terminal_or_missing = async (deps, offer_id, scope) => {
  *
  * Expired offers are filtered server-side (`expires_at > NOW()`) so the
  * inbox never surfaces a row that can no longer be accepted. The periodic
- * sweep (`query_role_grant_offer_sweep_expired`) handles audit tombstoning.
+ * sweep (`query_role_grant_offer_sweep_expired`) audits each expiry once.
  */
 export const query_role_grant_offer_list = async (deps, to_account_id) => {
     return deps.db.query(`SELECT ${columns_sql(ROLE_GRANT_OFFER_COLUMNS, role_grant_offer_expr(''))} FROM role_grant_offer
@@ -308,21 +311,36 @@ export const query_role_grant_offer_find_pending = async (deps, offer_id) => {
     return row ?? null;
 };
 /**
- * Return pending offers whose `expires_at` has passed.
+ * Claim the pending offers whose `expires_at` has passed and whose expiry has
+ * not been audited yet, stamping `expire_audited_at` on each, and return them
+ * soonest-expiry first.
  *
- * Callers fire `role_grant_offer_expire` audit events for each row. The schema
- * does not tombstone the row, so callers are responsible for their own
- * idempotency (e.g. check whether a `role_grant_offer_expire` audit event
- * already exists for the offer id).
+ * The stamp is the sweep's idempotency: a claimed row never matches again, so
+ * each expiry is audited exactly once. It must share a transaction with the
+ * caller's `role_grant_offer_expire` audit inserts — committed together, or
+ * rolled back together so the next sweep retries. Concurrent sweeps claim
+ * disjoint rows: a row another sweep has stamped but not committed blocks on
+ * its row lock, then fails the re-checked `expire_audited_at IS NULL`.
+ * `cleanup_expired_role_grant_offers` is the caller.
+ *
+ * @mutates `role_grant_offer` rows - stamps `expire_audited_at` on each claimed row
  */
 export const query_role_grant_offer_sweep_expired = async (deps) => {
-    return deps.db.query(`SELECT ${columns_sql(ROLE_GRANT_OFFER_COLUMNS, role_grant_offer_expr(''))} FROM role_grant_offer
-		 WHERE accepted_at IS NULL
-		   AND declined_at IS NULL
-		   AND retracted_at IS NULL
-		   AND superseded_at IS NULL
-		   AND expires_at <= NOW()
-		 ORDER BY role_grant_offer.expires_at ASC`);
+    return deps.db.query(`WITH claimed AS (
+			UPDATE role_grant_offer
+			SET expire_audited_at = NOW()
+			WHERE accepted_at IS NULL
+			  AND declined_at IS NULL
+			  AND retracted_at IS NULL
+			  AND superseded_at IS NULL
+			  AND expires_at <= NOW()
+			  AND expire_audited_at IS NULL
+			-- raw columns; the outer select formats them
+			RETURNING ${columns_sql(ROLE_GRANT_OFFER_COLUMNS)}
+		)
+		SELECT ${qualify_columns(ROLE_GRANT_OFFER_COLUMNS, 'c', role_grant_offer_expr('c'))}
+		FROM claimed c
+		ORDER BY c.expires_at ASC, c.id ASC`);
 };
 /**
  * Whether `grantor_actor_id` holds an active **global** `admin` on an active

package/dist/auth/role_grant_offer_schema.d.ts

@@ -60,6 +60,15 @@ export interface RoleGrantOffer {
      */
     superseded_at: string | null;
     resulting_role_grant_id: Uuid | null;
+    /**
+     * When the expiry sweep audited this offer's `role_grant_offer_expire` —
+     * the claim stamp `query_role_grant_offer_sweep_expired` sets in the same
+     * transaction as the audit row, so each expiry is audited once. Not a
+     * lifecycle state (an expired offer is still pending by the terminal
+     * columns) and server-only: `to_role_grant_offer_json` drops it, and the
+     * strict `RoleGrantOfferJson` would reject it. A re-offer clears it.
+     */
+    expire_audited_at: string | null;
 }
 /**
  * A superseded offer row annotated with the grantor's `account_id`.