@fuzdev/fuz_app 0.55.0 → 0.57.0

package/dist/auth/{permit_offer_queries.js → role_grant_offer_queries.js}

@@ -1,9 +1,9 @@
 /**
- * Permit offer database queries.
+ * Role grant offer database queries.
  *
- * Covers the offer side of the consentful-permits flow: create (with
+ * Covers the offer side of the consentful-role-grants flow: create (with
  * re-offer upsert), decline, retract, list, find-pending, sweep-expired,
- * and the atomic `query_accept_offer` that bridges offer → permit.
+ * and the atomic `query_accept_offer` that bridges offer → role_grant.
  *
  * IDOR guards are expressed in each helper's signature — decline/accept
  * require the recipient's `to_account_id`, retract requires the grantor's
@@ -12,18 +12,18 @@
  * @module
  */
 import { assert_row } from '../db/assert_row.js';
-import { PERMIT_OFFER_SCOPE_SENTINEL_UUID, } from './permit_offer_schema.js';
+import { ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN, ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID, } from './role_grant_offer_schema.js';
 import { query_audit_log } from './audit_log_queries.js';
 /**
  * Error thrown by offer-lifecycle queries when the offer is in a non-pending
  * state (accepted / declined / retracted / superseded) and therefore not
- * actionable. Distinct from `PermitOfferExpiredError` — expiry has its own
+ * actionable. Distinct from `RoleGrantOfferExpiredError` — expiry has its own
  * user-facing story ("ask the grantor to re-send") so it travels separately.
  */
-export class PermitOfferAlreadyTerminalError extends Error {
+export class RoleGrantOfferAlreadyTerminalError extends Error {
     constructor(offer_id) {
         super(`Offer ${offer_id} is already in a terminal state`);
-        this.name = 'PermitOfferAlreadyTerminalError';
+        this.name = 'RoleGrantOfferAlreadyTerminalError';
     }
 }
 /**
@@ -32,10 +32,10 @@ export class PermitOfferAlreadyTerminalError extends Error {
  * must not be accepted, even in the race window between expiry and the
  * sweep stamping the audit event.
  */
-export class PermitOfferExpiredError extends Error {
+export class RoleGrantOfferExpiredError extends Error {
     constructor(offer_id) {
         super(`Offer ${offer_id} has expired`);
-        this.name = 'PermitOfferExpiredError';
+        this.name = 'RoleGrantOfferExpiredError';
     }
 }
 /**
@@ -44,14 +44,14 @@ export class PermitOfferExpiredError extends Error {
  * (IDOR guard) — the standard 404-over-403 pattern that avoids disclosing
  * whether an offer id exists.
  */
-export class PermitOfferNotFoundError extends Error {
+export class RoleGrantOfferNotFoundError extends Error {
     constructor(offer_id) {
         super(`Offer ${offer_id} not found`);
-        this.name = 'PermitOfferNotFoundError';
+        this.name = 'RoleGrantOfferNotFoundError';
     }
 }
 /**
- * Error thrown when a grantor attempts to offer a permit to their own account.
+ * Error thrown when a grantor attempts to offer a role_grant to their own account.
  *
  * Enforced via a single SELECT on the grantor's `actor.account_id` (rather
  * than via a CHECK constraint or a denormalized column). Resolving from the
@@ -59,40 +59,40 @@ export class PermitOfferNotFoundError extends Error {
  * recipient account may host many actors, but the grantor → account binding
  * remains 1:1 by definition of `actor`.
  */
-export class PermitOfferSelfTargetError extends Error {
+export class RoleGrantOfferSelfTargetError extends Error {
     constructor() {
-        super('Cannot offer a permit to your own account');
-        this.name = 'PermitOfferSelfTargetError';
+        super('Cannot offer a role_grant to your own account');
+        this.name = 'RoleGrantOfferSelfTargetError';
     }
 }
 /**
  * Error thrown when an actor-targeted offer is being accepted by an actor
- * other than `offer.to_actor_id`. Distinct from `PermitOfferNotFoundError`
+ * other than `offer.to_actor_id`. Distinct from `RoleGrantOfferNotFoundError`
  * (the IDOR mask): once an offer has been resolved to the recipient account,
  * a wrong-actor accept on a same-account actor is a contract violation, not
  * a privacy boundary — surface a specific error so the client UI can
  * distinguish "this offer isn't for you" from "no such offer".
  */
-export class PermitOfferActorMismatchError extends Error {
+export class RoleGrantOfferActorMismatchError extends Error {
     constructor(offer_id) {
         super(`Offer ${offer_id} is targeted to a different actor on this account`);
-        this.name = 'PermitOfferActorMismatchError';
+        this.name = 'RoleGrantOfferActorMismatchError';
     }
 }
 /**
- * Error thrown when `query_permit_offer_create` is called with a
+ * Error thrown when `query_role_grant_offer_create` is called with a
  * `to_actor_id` that does not exist or does not belong to `to_account_id`.
  * Surfaces the actor↔account binding mismatch at the boundary instead of
  * letting the FK silently disagree with the recipient field.
  */
-export class PermitOfferActorAccountMismatchError extends Error {
+export class RoleGrantOfferActorAccountMismatchError extends Error {
     constructor() {
         super('to_actor_id does not belong to to_account_id');
-        this.name = 'PermitOfferActorAccountMismatchError';
+        this.name = 'RoleGrantOfferActorAccountMismatchError';
     }
 }
 /**
- * Create a new permit offer, or refresh an existing pending offer for the
+ * Create a new role_grant offer, or refresh an existing pending offer for the
  * same `(to_account_id, role, scope_id, from_actor_id)` tuple.
  *
  * Re-offer semantics: a second call by the same grantor with the same
@@ -104,7 +104,7 @@ export class PermitOfferActorAccountMismatchError extends Error {
  * a distinct row — multiple pending grantors coexist. After a terminal
  * state, a re-offer is a fresh INSERT.
  *
- * Self-offer rejection: throws `PermitOfferSelfTargetError` if the offering
+ * Self-offer rejection: throws `RoleGrantOfferSelfTargetError` if the offering
  * actor belongs to the recipient account.
  *
  * Actor-targeted offers: when `to_actor_id` is supplied,
@@ -113,11 +113,11 @@ export class PermitOfferActorAccountMismatchError extends Error {
  * `target_actor_id` null even when the recipient binding is known at
  * offer time. The actor↔account binding is verified here in one SELECT.
  *
- * @mutates `permit_offer` table - inserts a new offer or upserts the matching pending row
- * @throws PermitOfferSelfTargetError if the offering actor belongs to `to_account_id`
- * @throws PermitOfferActorAccountMismatchError if `to_actor_id` is set but does not belong to `to_account_id`
+ * @mutates `role_grant_offer` table - inserts a new offer or upserts the matching pending row
+ * @throws RoleGrantOfferSelfTargetError if the offering actor belongs to `to_account_id`
+ * @throws RoleGrantOfferActorAccountMismatchError if `to_actor_id` is set but does not belong to `to_account_id`
  */
-export const query_permit_offer_create = async (deps, input) => {
+export const query_role_grant_offer_create = async (deps, input) => {
     // Self-target check resolves the **grantor** actor's account and
     // compares against to_account_id. This is multi-actor-correct:
     // a single account may host many actors, and self-target means
@@ -129,18 +129,24 @@ export const query_permit_offer_create = async (deps, input) => {
     // actor wasn't the offering one.)
     const grantor = await deps.db.query_one(`SELECT account_id FROM actor WHERE id = $1`, [input.from_actor_id]);
     if (grantor && grantor.account_id === input.to_account_id) {
-        throw new PermitOfferSelfTargetError();
+        throw new RoleGrantOfferSelfTargetError();
     }
     if (input.to_actor_id != null) {
         const target = await deps.db.query_one(`SELECT account_id FROM actor WHERE id = $1`, [input.to_actor_id]);
         if (!target || target.account_id !== input.to_account_id) {
-            throw new PermitOfferActorAccountMismatchError();
+            throw new RoleGrantOfferActorAccountMismatchError();
         }
     }
-    const row = await deps.db.query_one(`INSERT INTO permit_offer
-			 (from_actor_id, to_account_id, to_actor_id, role, scope_id, message, expires_at)
-		 VALUES ($1, $2, $3, $4, $5, $6, $7)
-		 ON CONFLICT (to_account_id, role, COALESCE(scope_id, '${PERMIT_OFFER_SCOPE_SENTINEL_UUID}'::uuid), from_actor_id)
+    const row = await deps.db.query_one(`INSERT INTO role_grant_offer
+			 (from_actor_id, to_account_id, to_actor_id, role, scope_kind, scope_id, message, expires_at)
+		 VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+		 ON CONFLICT (
+		   to_account_id,
+		   role,
+		   COALESCE(scope_kind, '${ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN}'),
+		   COALESCE(scope_id, '${ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID}'::uuid),
+		   from_actor_id
+		 )
 		   WHERE accepted_at IS NULL AND declined_at IS NULL AND retracted_at IS NULL AND superseded_at IS NULL
 		 DO UPDATE SET
 			 to_actor_id = EXCLUDED.to_actor_id,
@@ -151,18 +157,19 @@ export const query_permit_offer_create = async (deps, input) => {
         input.to_account_id,
         input.to_actor_id ?? null,
         input.role,
+        input.scope_kind ?? null,
         input.scope_id ?? null,
         input.message ?? null,
         input.expires_at.toISOString(),
     ]);
-    return assert_row(row, 'INSERT INTO permit_offer');
+    return assert_row(row, 'INSERT INTO role_grant_offer');
 };
 /**
  * Mark an offer declined.
  *
  * Guarded by `to_account_id` (IDOR). Returns `null` if the offer does not
  * exist or belongs to a different account. Throws
- * `PermitOfferAlreadyTerminalError` if the offer exists for the caller but
+ * `RoleGrantOfferAlreadyTerminalError` if the offer exists for the caller but
  * is already in a terminal state.
  *
  * Returns the declined offer with the grantor's `from_account_id` joined
@@ -171,12 +178,12 @@ export const query_permit_offer_create = async (deps, input) => {
  * grantor account), satisfying the "both populated → same account"
  * invariant the audit-log column comments describe.
  *
- * @mutates `permit_offer` row - sets `declined_at` and `decline_reason`
- * @throws PermitOfferAlreadyTerminalError if the offer is already accepted, declined, retracted, or superseded
+ * @mutates `role_grant_offer` row - sets `declined_at` and `decline_reason`
+ * @throws RoleGrantOfferAlreadyTerminalError if the offer is already accepted, declined, retracted, or superseded
  */
-export const query_permit_offer_decline = async (deps, offer_id, to_account_id, reason) => {
+export const query_role_grant_offer_decline = async (deps, offer_id, to_account_id, reason) => {
     const updated = await deps.db.query_one(`WITH updated AS (
-			UPDATE permit_offer
+			UPDATE role_grant_offer
 			SET declined_at = NOW(), decline_reason = $3
 			WHERE id = $1
 			  AND to_account_id = $2
@@ -198,14 +205,14 @@ export const query_permit_offer_decline = async (deps, offer_id, to_account_id,
  *
  * Guarded by `from_actor_id` (IDOR). Returns `null` if the offer does not
  * exist or was issued by a different actor. Throws
- * `PermitOfferAlreadyTerminalError` if the offer exists for this grantor
+ * `RoleGrantOfferAlreadyTerminalError` 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
+ * @mutates `role_grant_offer` row - sets `retracted_at`
+ * @throws RoleGrantOfferAlreadyTerminalError 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
+export const query_role_grant_offer_retract = async (deps, offer_id, from_actor_id) => {
+    const updated = await deps.db.query_one(`UPDATE role_grant_offer
 		 SET retracted_at = NOW()
 		 WHERE id = $1
 		   AND from_actor_id = $2
@@ -231,11 +238,11 @@ const resolve_terminal_or_missing = async (deps, offer_id, scope) => {
         conditions.push(`from_actor_id = $${idx++}`);
         params.push(scope.from_actor_id);
     }
-    const row = await deps.db.query_one(`SELECT * FROM permit_offer WHERE ${conditions.join(' AND ')}`, params);
+    const row = await deps.db.query_one(`SELECT * FROM role_grant_offer WHERE ${conditions.join(' AND ')}`, params);
     if (!row)
         return null;
     if (row.accepted_at || row.declined_at || row.retracted_at || row.superseded_at) {
-        throw new PermitOfferAlreadyTerminalError(offer_id);
+        throw new RoleGrantOfferAlreadyTerminalError(offer_id);
     }
     return null;
 };
@@ -244,10 +251,10 @@ 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_permit_offer_sweep_expired`) handles audit tombstoning.
+ * sweep (`query_role_grant_offer_sweep_expired`) handles audit tombstoning.
  */
-export const query_permit_offer_list = async (deps, to_account_id) => {
-    return deps.db.query(`SELECT * FROM permit_offer
+export const query_role_grant_offer_list = async (deps, to_account_id) => {
+    return deps.db.query(`SELECT * FROM role_grant_offer
 		 WHERE to_account_id = $1
 		   AND accepted_at IS NULL
 		   AND declined_at IS NULL
@@ -261,8 +268,8 @@ export const query_permit_offer_list = async (deps, to_account_id) => {
  *
  * Includes terminal offers — used by the grantor-side admin / history view.
  */
-export const query_permit_offer_history_for_account = async (deps, account_id, limit = 100, offset = 0) => {
-    return deps.db.query(`SELECT o.* FROM permit_offer o
+export const query_role_grant_offer_history_for_account = async (deps, account_id, limit = 100, offset = 0) => {
+    return deps.db.query(`SELECT o.* FROM role_grant_offer o
 		 LEFT JOIN actor a ON a.id = o.from_actor_id
 		 WHERE o.to_account_id = $1 OR a.account_id = $1
 		 ORDER BY o.created_at DESC
@@ -272,8 +279,8 @@ export const query_permit_offer_history_for_account = async (deps, account_id, l
  * Look up a pending offer by id. Returns `null` if the offer is terminal,
  * expired (server-side filter), or missing.
  */
-export const query_permit_offer_find_pending = async (deps, offer_id) => {
-    const row = await deps.db.query_one(`SELECT * FROM permit_offer
+export const query_role_grant_offer_find_pending = async (deps, offer_id) => {
+    const row = await deps.db.query_one(`SELECT * FROM role_grant_offer
 		 WHERE id = $1
 		   AND accepted_at IS NULL
 		   AND declined_at IS NULL
@@ -285,13 +292,13 @@ export const query_permit_offer_find_pending = async (deps, offer_id) => {
 /**
  * Return pending offers whose `expires_at` has passed.
  *
- * Callers fire `permit_offer_expire` audit events for each row. The schema
+ * 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 `permit_offer_expire` audit event
+ * idempotency (e.g. check whether a `role_grant_offer_expire` audit event
  * already exists for the offer id).
  */
-export const query_permit_offer_sweep_expired = async (deps) => {
-    return deps.db.query(`SELECT * FROM permit_offer
+export const query_role_grant_offer_sweep_expired = async (deps) => {
+    return deps.db.query(`SELECT * FROM role_grant_offer
 		 WHERE accepted_at IS NULL
 		   AND declined_at IS NULL
 		   AND retracted_at IS NULL
@@ -300,35 +307,35 @@ export const query_permit_offer_sweep_expired = async (deps) => {
 		 ORDER BY expires_at ASC`);
 };
 /**
- * Accept an offer atomically: mark accepted, insert the permit, stamp
- * `resulting_permit_id`, supersede sibling pending offers for the same
- * `(to_account, role, scope)`, and emit `permit_offer_accept` +
- * `permit_grant` + one `permit_offer_supersede` per sibling. Must run
+ * Accept an offer atomically: mark accepted, insert the role_grant, stamp
+ * `resulting_role_grant_id`, supersede sibling pending offers for the same
+ * `(to_account, role, scope)`, and emit `role_grant_offer_accept` +
+ * `role_grant_create` + one `role_grant_offer_supersede` per sibling. Must run
  * inside a transaction — the caller's route spec should declare
  * `transaction: true` (or wrap explicitly).
  *
  * Idempotent on race: if a second concurrent call observes the offer
- * already accepted, returns the existing permit rather than creating a
+ * already accepted, returns the existing role_grant rather than creating a
  * duplicate or throwing.
  *
  * Error map:
- * - `PermitOfferNotFoundError` — offer does not exist, or belongs to a
+ * - `RoleGrantOfferNotFoundError` — offer does not exist, or belongs to a
  *   different recipient (IDOR guard). The offer row is untouched.
- * - `PermitOfferAlreadyTerminalError` — offer is declined, retracted, or
+ * - `RoleGrantOfferAlreadyTerminalError` — offer is declined, retracted, or
  *   superseded.
- * - `PermitOfferExpiredError` — offer is pending but past `expires_at`.
+ * - `RoleGrantOfferExpiredError` — offer is pending but past `expires_at`.
  *
  * 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.
+ * accepted even if the resulting role_grant 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`
+ * @mutates `role_grant_offer` row - stamps `accepted_at` and `resulting_role_grant_id`
+ * @mutates `role_grant` table - inserts the resulting role_grant (idempotent on race)
+ * @mutates `role_grant_offer` siblings - stamps `superseded_at` on every other pending offer for the tuple
+ * @mutates `audit_log` table - emits `role_grant_offer_accept` + `role_grant_create` + one `role_grant_offer_supersede` per sibling
+ * @throws RoleGrantOfferNotFoundError if the offer is missing or belongs to another recipient
+ * @throws RoleGrantOfferAlreadyTerminalError if the offer is declined, retracted, or superseded
+ * @throws RoleGrantOfferExpiredError if the offer is pending but past `expires_at`
  * @throws Error if the accepting `actor_id` does not belong to `to_account_id`, or invariant assertions fail
  */
 export const query_accept_offer = async (deps, input) => {
@@ -336,31 +343,31 @@ export const query_accept_offer = async (deps, input) => {
     // Claim the offer with a row-level lock. Subsequent concurrent callers
     // block on the lock until this transaction commits/rolls back; after commit
     // they see the new state (accepted or terminal) and branch idempotently.
-    // We defer writing `accepted_at` until the permit row exists — the
-    // `permit_offer_permit_iff_accepted` CHECK constraint demands both be set
+    // We defer writing `accepted_at` until the role_grant row exists — the
+    // `role_grant_offer_role_grant_iff_accepted` CHECK constraint demands both be set
     // (or neither) at row-visibility time.
-    const locked = await deps.db.query_one(`SELECT * FROM permit_offer
+    const locked = await deps.db.query_one(`SELECT * FROM role_grant_offer
 		 WHERE id = $1 AND to_account_id = $2
 		 FOR UPDATE`, [offer_id, to_account_id]);
     if (!locked) {
-        throw new PermitOfferNotFoundError(offer_id);
+        throw new RoleGrantOfferNotFoundError(offer_id);
     }
     if (locked.accepted_at) {
-        // Race winner already committed; return the pre-existing permit.
-        // `permit_offer_permit_iff_accepted` CHECK guarantees resulting_permit_id is non-null.
-        const permit = assert_row(await deps.db.query_one(`SELECT * FROM permit WHERE id = $1`, [
-            locked.resulting_permit_id,
-        ]), 'resulting_permit lookup');
+        // Race winner already committed; return the pre-existing role_grant.
+        // `role_grant_offer_role_grant_iff_accepted` CHECK guarantees resulting_role_grant_id is non-null.
+        const role_grant = assert_row(await deps.db.query_one(`SELECT * FROM role_grant WHERE id = $1`, [
+            locked.resulting_role_grant_id,
+        ]), 'resulting_role_grant lookup');
         // Multi-actor guard: two actors on the same recipient account may
         // both race an account-grain offer — the loser must not silently
-        // receive the winner's permit (which would tell them "you got it"
-        // while the actor on the permit is someone else). Treat the offer
+        // receive the winner's role_grant (which would tell them "you got it"
+        // while the actor on the role_grant is someone else). Treat the offer
         // as terminal for the loser.
-        if (permit.actor_id !== actor_id) {
-            throw new PermitOfferAlreadyTerminalError(offer_id);
+        if (role_grant.actor_id !== actor_id) {
+            throw new RoleGrantOfferAlreadyTerminalError(offer_id);
         }
         return {
-            permit,
+            role_grant,
             offer: locked,
             created: false,
             superseded_offers: [],
@@ -368,13 +375,13 @@ export const query_accept_offer = async (deps, input) => {
         };
     }
     if (locked.declined_at || locked.retracted_at || locked.superseded_at) {
-        throw new PermitOfferAlreadyTerminalError(offer_id);
+        throw new RoleGrantOfferAlreadyTerminalError(offer_id);
     }
     // Expiry check AFTER the accepted-path: a validly-accepted offer past its
-    // expires_at still returns the permit idempotently. Only pending offers
+    // expires_at still returns the role_grant idempotently. Only pending offers
     // past expiry reach this branch.
     if (new Date(locked.expires_at) <= new Date()) {
-        throw new PermitOfferExpiredError(offer_id);
+        throw new RoleGrantOfferExpiredError(offer_id);
     }
     // Actor-targeted offer gate. When the offer is account-grain
     // (`to_actor_id IS NULL`) any actor on `to_account_id` may accept and
@@ -385,7 +392,7 @@ export const query_accept_offer = async (deps, input) => {
     //
     // Ordering contract: this check fires *before* the cross-account
     // `actor_check` SELECT below. A wrong-actor accept on an actor-grain
-    // offer surfaces as `PermitOfferActorMismatchError` regardless of
+    // offer surfaces as `RoleGrantOfferActorMismatchError` regardless of
     // whether the supplied `actor_id` belongs to `to_account_id` — the
     // actor-grain binding is the tighter constraint and dominates. The
     // cross-account `Error` only fires for account-grain offers (or
@@ -393,42 +400,48 @@ export const query_accept_offer = async (deps, input) => {
     // the actor turns out not to be on the account, which is unreachable
     // under the FK invariant but stays as defense-in-depth).
     if (locked.to_actor_id != null && locked.to_actor_id !== actor_id) {
-        throw new PermitOfferActorMismatchError(offer_id);
+        throw new RoleGrantOfferActorMismatchError(offer_id);
     }
     // Verify the accepting actor belongs to the recipient account.
     // Defense-in-depth: the action handler passes `auth.actor.id` which is
     // already session-bound, but enforcing the invariant here protects
     // direct callers (tests, future consumers) from cross-account binding
-    // bugs that would silently grant a permit to the wrong actor.
+    // bugs that would silently grant a role_grant to the wrong actor.
     const actor_check = await deps.db.query_one(`SELECT id FROM actor WHERE id = $1 AND account_id = $2`, [actor_id, to_account_id]);
     if (!actor_check) {
         throw new Error(`Accepting actor ${actor_id} does not belong to account ${to_account_id} (offer ${offer_id})`);
     }
-    // Insert the permit. Uses the normal grant idempotency — if another
-    // code path already granted the same (actor, role, scope), reuse it.
-    const granted_permit = await deps.db.query_one(`INSERT INTO permit (actor_id, role, scope_id, granted_by, source_offer_id)
-		 VALUES ($1, $2, $3, $4, $5)
-		 ON CONFLICT (actor_id, role, COALESCE(scope_id, '${PERMIT_OFFER_SCOPE_SENTINEL_UUID}'::uuid))
+    // Insert the role_grant. Uses the normal grant idempotency — if another
+    // code path already granted the same (actor, role, scope_kind, scope), reuse it.
+    const granted_role_grant = await deps.db.query_one(`INSERT INTO role_grant (actor_id, role, scope_kind, scope_id, granted_by, source_offer_id)
+		 VALUES ($1, $2, $3, $4, $5, $6)
+		 ON CONFLICT (
+		   actor_id,
+		   role,
+		   COALESCE(scope_kind, '${ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN}'),
+		   COALESCE(scope_id, '${ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID}'::uuid)
+		 )
 		   WHERE revoked_at IS NULL
 		 DO NOTHING
-		 RETURNING *`, [actor_id, locked.role, locked.scope_id, locked.from_actor_id, locked.id]);
-    let permit;
-    if (granted_permit) {
-        permit = granted_permit;
+		 RETURNING *`, [actor_id, locked.role, locked.scope_kind, locked.scope_id, locked.from_actor_id, locked.id]);
+    let role_grant;
+    if (granted_role_grant) {
+        role_grant = granted_role_grant;
     }
     else {
-        const existing = await deps.db.query_one(`SELECT * FROM permit
+        const existing = await deps.db.query_one(`SELECT * FROM role_grant
 			 WHERE actor_id = $1
 			   AND role = $2
-			   AND scope_id IS NOT DISTINCT FROM $3
-			   AND revoked_at IS NULL`, [actor_id, locked.role, locked.scope_id]);
-        permit = assert_row(existing, 'query_accept_offer idempotent permit lookup');
+			   AND scope_kind IS NOT DISTINCT FROM $3
+			   AND scope_id IS NOT DISTINCT FROM $4
+			   AND revoked_at IS NULL`, [actor_id, locked.role, locked.scope_kind, locked.scope_id]);
+        role_grant = assert_row(existing, 'query_accept_offer idempotent role_grant lookup');
     }
     // Single UPDATE sets both sides of the CHECK constraint at once.
-    const offer_accepted = await deps.db.query_one(`UPDATE permit_offer
-		 SET accepted_at = NOW(), resulting_permit_id = $2
+    const offer_accepted = await deps.db.query_one(`UPDATE role_grant_offer
+		 SET accepted_at = NOW(), resulting_role_grant_id = $2
 		 WHERE id = $1
-		 RETURNING *`, [locked.id, permit.id]);
+		 RETURNING *`, [locked.id, role_grant.id]);
     const offer = assert_row(offer_accepted, 'mark offer accepted');
     // Supersede sibling pending offers for the same (to_account, role, scope).
     // Forecloses the "accept this other sibling later to get the role back
@@ -436,7 +449,7 @@ export const query_accept_offer = async (deps, input) => {
     // is obsoleted by the accept. CTE joins `actor` to surface each sibling's
     // grantor `account_id` for the caller's notification fan-out.
     const superseded = await deps.db.query(`WITH updated AS (
-			UPDATE permit_offer
+			UPDATE role_grant_offer
 			SET superseded_at = NOW()
 			WHERE to_account_id = $1
 			  AND role = $2
@@ -451,13 +464,13 @@ export const query_accept_offer = async (deps, input) => {
 		SELECT u.*, grantor.account_id AS from_account_id
 		FROM updated u
 		JOIN actor grantor ON grantor.id = u.from_actor_id`, [to_account_id, offer.role, offer.scope_id, offer.id]);
-    // Emit audit events in-transaction (atomic with the permit insert).
-    // `RETURNING *` after the SET guarantees `offer.resulting_permit_id === permit.id`.
+    // Emit audit events in-transaction (atomic with the role_grant insert).
+    // `RETURNING *` after the SET guarantees `offer.resulting_role_grant_id === role_grant.id`.
     // Accept binds the actor deterministically — populate both target
-    // columns to mirror `permit_grant` (the in-tx pair) so forensic
+    // columns to mirror `role_grant_create` (the in-tx pair) so forensic
     // queries don't have to split between the two events.
     const offer_accept_event = await query_audit_log(deps, {
-        event_type: 'permit_offer_accept',
+        event_type: 'role_grant_offer_accept',
         actor_id,
         account_id: to_account_id,
         target_account_id: to_account_id,
@@ -465,18 +478,18 @@ export const query_accept_offer = async (deps, input) => {
         ip: ip ?? null,
         metadata: {
             offer_id: offer.id,
-            permit_id: permit.id,
+            role_grant_id: role_grant.id,
             role: offer.role,
             scope_id: offer.scope_id,
         },
     });
-    // `permit_grant` is the canonical actor-bound-subject event — the
-    // permit just bound to this actor. On self-accept the actor and the
+    // `role_grant_create` is the canonical actor-bound-subject event — the
+    // role_grant just bound to this actor. On self-accept the actor and the
     // target are the same identity; on admin direct-grant (separate code
     // path) they differ. Either way `target_actor_id` carries the
     // grantee for actor-grain forensics.
-    const permit_grant_event = await query_audit_log(deps, {
-        event_type: 'permit_grant',
+    const role_grant_create_event = await query_audit_log(deps, {
+        event_type: 'role_grant_create',
         actor_id,
         account_id: to_account_id,
         target_account_id: to_account_id,
@@ -484,7 +497,7 @@ export const query_accept_offer = async (deps, input) => {
         ip: ip ?? null,
         metadata: {
             role: offer.role,
-            permit_id: permit.id,
+            role_grant_id: role_grant.id,
             scope_id: offer.scope_id,
             source_offer_id: offer.id,
         },
@@ -495,7 +508,7 @@ export const query_accept_offer = async (deps, input) => {
         // when the sibling was actor-targeted, account-grain (null) when it
         // was account-level.
         supersede_events.push(await query_audit_log(deps, {
-            event_type: 'permit_offer_supersede',
+            event_type: 'role_grant_offer_supersede',
             actor_id,
             account_id: to_account_id,
             target_account_id: to_account_id,
@@ -511,10 +524,10 @@ export const query_accept_offer = async (deps, input) => {
         }));
     }
     return {
-        permit,
+        role_grant,
         offer,
         created: true,
         superseded_offers: superseded,
-        audit_events: [offer_accept_event, permit_grant_event, ...supersede_events],
+        audit_events: [offer_accept_event, role_grant_create_event, ...supersede_events],
     };
 };