@fuzdev/fuz_app 0.114.0 → 0.116.0

package/dist/auth/role_grant_offer_queries.js

@@ -16,6 +16,7 @@ import { columns_sql, qualify_columns } from '../db/sql_columns.js';
 import { ROLE_GRANT_OFFER_COLUMNS, role_grant_offer_expr, ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN, ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID, ROLE_GRANT_OFFER_WITH_GRANTOR_SELECT } from './role_grant_offer_ddl.js';
 import { query_create_role_grant, query_role_grant_by_id } from './role_grant_queries.js';
 import { query_audit_log } from './audit_log_queries.js';
+import { is_builtin_role, ROLE_ADMIN, ROLE_KEEPER } from './role_schema.js';
 /**
  * Error thrown by offer-lifecycle queries when the offer is in a non-pending
  * state (accepted / declined / retracted / superseded) and therefore not
@@ -81,6 +82,22 @@ export class RoleGrantOfferActorMismatchError extends Error {
         this.name = 'RoleGrantOfferActorMismatchError';
     }
 }
+/**
+ * Error thrown by `query_accept_offer` when the offer confers a builtin role
+ * (`admin` / `keeper`) that this accept must not mint — `refusal` names the
+ * rule. Carries the locked (still pending, untouched) offer so the caller can
+ * audit the refusal with the offer's role and scope.
+ */
+export class RoleGrantOfferBuiltinRefusedError extends Error {
+    offer;
+    refusal;
+    constructor(offer, refusal) {
+        super(`Offer ${offer.id} is refused: ${refusal}`);
+        this.name = 'RoleGrantOfferBuiltinRefusedError';
+        this.offer = offer;
+        this.refusal = refusal;
+    }
+}
 /**
  * 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`.
@@ -307,6 +324,35 @@ export const query_role_grant_offer_sweep_expired = async (deps) => {
 		   AND expires_at <= NOW()
 		 ORDER BY role_grant_offer.expires_at ASC`);
 };
+/**
+ * Whether `grantor_actor_id` holds an active **global** `admin` on an active
+ * actor of an active account — the authority a builtin-role offer needs at the
+ * moment its grant is minted.
+ *
+ * A locking read: `FOR SHARE OF rg` takes a share lock on the grant row that
+ * admits, so a concurrent revoke (an `UPDATE` of that row) is strictly ordered
+ * against this accept — it either commits first, and the recheck of the locked
+ * row sees `revoked_at` set and excludes it, or it waits for this transaction
+ * to commit the grant it authorized. A plain `EXISTS` could read the grant as
+ * active while a revoke commits in between. The actor and account tombstones
+ * are read but not locked — ordering a delete racing an accept isn't worth
+ * locking two more tables. Twin of the Rust `grantor_holds_global_admin`.
+ */
+const query_grantor_holds_global_admin = async (deps, grantor_actor_id) => {
+    const row = await deps.db.query_one(`SELECT 1 AS held FROM role_grant rg
+		 JOIN actor act ON act.id = rg.actor_id
+		 JOIN account a ON a.id = act.account_id
+		 WHERE rg.actor_id = $1
+		   AND rg.role = $2
+		   AND rg.scope_id IS NULL
+		   AND rg.revoked_at IS NULL
+		   AND (rg.expires_at IS NULL OR rg.expires_at > NOW())
+		   AND act.deleted_at IS NULL
+		   AND a.deleted_at IS NULL
+		 LIMIT 1
+		 FOR SHARE OF rg`, [grantor_actor_id, ROLE_ADMIN]);
+    return row != null;
+};
 /**
  * Accept an offer atomically: mark accepted, insert the role_grant, stamp
  * `resulting_role_grant_id`, supersede sibling pending offers for the same
@@ -325,6 +371,11 @@ export const query_role_grant_offer_sweep_expired = async (deps) => {
  * - `RoleGrantOfferAlreadyTerminalError` — offer is declined, retracted, or
  *   superseded.
  * - `RoleGrantOfferExpiredError` — offer is pending but past `expires_at`.
+ * - `RoleGrantOfferActorMismatchError` — actor-targeted offer, different actor.
+ * - `RoleGrantOfferBuiltinRefusedError` — a builtin-role offer that must not
+ *   mint: `keeper` at all, a builtin bound to a scope, or one whose grantor no
+ *   longer holds an active global `admin` (read under `FOR SHARE`). The offer
+ *   stays pending.
  *
  * 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
@@ -337,6 +388,8 @@ export const query_role_grant_offer_sweep_expired = async (deps) => {
  * @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 RoleGrantOfferActorMismatchError if the offer is actor-targeted to a different actor
+ * @throws RoleGrantOfferBuiltinRefusedError if a builtin-role offer must not mint (see `BuiltinOfferRefusal`)
  * @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) => {
@@ -413,6 +466,29 @@ export const query_accept_offer = async (deps, input) => {
     if (locked.to_actor_id != null && locked.to_actor_id !== actor_id) {
         throw new RoleGrantOfferActorMismatchError(offer_id);
     }
+    // Builtin-role offers — checked here, the chokepoint where an offer turns
+    // into a `role_grant`, so a direct caller of this query can't skip them. No
+    // current grant path creates a refused shape, but a pending row can still
+    // carry one (a direct `query_role_grant_offer_create`, or an offer made under
+    // a since-closed path).
+    if (is_builtin_role(locked.role)) {
+        let refusal = null;
+        if (locked.role === ROLE_KEEPER) {
+            // `keeper` is bootstrap-only — never conferred through an offer, even
+            // from a global admin.
+            refusal = 'bootstrap_only';
+        }
+        else if (locked.scope_id !== null) {
+            // Builtin roles are global-only.
+            refusal = 'scoped';
+        }
+        else if (!(await query_grantor_holds_global_admin(deps, locked.from_actor_id))) {
+            refusal = 'grantor_not_authorized';
+        }
+        if (refusal !== null) {
+            throw new RoleGrantOfferBuiltinRefusedError(locked, refusal);
+        }
+    }
     // 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

package/dist/auth/role_schema.d.ts

@@ -39,6 +39,18 @@ export declare const BuiltinRole: z.ZodEnum<{
     keeper: "keeper";
 }>;
 export type BuiltinRole = z.infer<typeof BuiltinRole>;
+/**
+ * Whether `name` is a builtin role (`keeper` / `admin`).
+ *
+ * Builtin roles are **global-only**: no grant path binds one to a scope
+ * (`role_grant_assign`, `role_grant_offer_create`, and
+ * `role_grant_offer_accept` refuse it), and every gate that reads one checks
+ * the global grant, so a scoped builtin row confers nothing.
+ *
+ * @param name - the role name to check
+ * @returns `true` for `keeper` or `admin`
+ */
+export declare const is_builtin_role: (name: string) => name is BuiltinRole;
 /**
  * Configuration for a role.
  *

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;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEN,KAAK,0BAA0B,EAC/B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAGN,KAAK,qBAAqB,EAC1B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,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,iEAAiE;AACjE,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;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,QAAQ;IACxB,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAClD;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/C;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAuBnE,CAAC;AAEH,iGAAiG;AACjG,MAAM,WAAW,uBAAuB;IACvC,uGAAuG;IACvG,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;IAC9C,+FAA+F;IAC/F,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,oFAAoF;IACpF,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAChC,0GAA0G;IAC1G,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,yEAAyE;IACzE,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CAC1C;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,kBAAkB,GAC9B,gBAAgB,aAAa,CAAC,QAAQ,CAAC,EACvC,UAAS,uBAA4B,KACnC,gBA2CF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC/B,YAAY,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,MAAM,MAAM,EACZ,YAAY,MAAM,KAChB,OAGF,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,0BAA0B,GACtC,YAAY,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,YAAY,MAAM,KAChB,KAAK,CAAC,MAAM,CAMd,CAAC"}
+{"version":3,"file":"role_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEN,KAAK,0BAA0B,EAC/B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAGN,KAAK,qBAAqB,EAC1B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,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,iEAAiE;AACjE,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;AAEtD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,IAAI,IAAI,WACX,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,QAAQ;IACxB,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAClD;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/C;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAuBnE,CAAC;AAEH,iGAAiG;AACjG,MAAM,WAAW,uBAAuB;IACvC,uGAAuG;IACvG,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;IAC9C,+FAA+F;IAC/F,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,oFAAoF;IACpF,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAChC,0GAA0G;IAC1G,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,yEAAyE;IACzE,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CAC1C;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,kBAAkB,GAC9B,gBAAgB,aAAa,CAAC,QAAQ,CAAC,EACvC,UAAS,uBAA4B,KACnC,gBA2CF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC/B,YAAY,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,MAAM,MAAM,EACZ,YAAY,MAAM,KAChB,OAGF,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,0BAA0B,GACtC,YAAY,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,YAAY,MAAM,KAChB,KAAK,CAAC,MAAM,CAMd,CAAC"}

package/dist/auth/role_schema.js

@@ -36,6 +36,18 @@ export const ROLE_ADMIN = 'admin';
 export const BUILTIN_ROLES = [ROLE_KEEPER, ROLE_ADMIN];
 /** Zod schema for builtin roles only. */
 export const BuiltinRole = z.enum(BUILTIN_ROLES);
+/**
+ * Whether `name` is a builtin role (`keeper` / `admin`).
+ *
+ * Builtin roles are **global-only**: no grant path binds one to a scope
+ * (`role_grant_assign`, `role_grant_offer_create`, and
+ * `role_grant_offer_accept` refuse it), and every gate that reads one checks
+ * the global grant, so a scoped builtin row confers nothing.
+ *
+ * @param name - the role name to check
+ * @returns `true` for `keeper` or `admin`
+ */
+export const is_builtin_role = (name) => name === ROLE_KEEPER || name === ROLE_ADMIN;
 /**
  * Builtin role specs, keyed by role name. Not overridable by consumers
  * — read once at startup by `create_role_schema` and the action

package/dist/auth/self_service_role_actions.d.ts

@@ -39,6 +39,19 @@
 import { type RpcAction } from '../actions/action_rpc.js';
 import { type RoleSchemaResult } from './role_schema.js';
 import type { ActionFactoryDeps } from './deps.js';
+/**
+ * Validate a deployment's self-service eligible-role set at construction.
+ *
+ * Refuses a builtin role (`admin` / `keeper`) — self-toggling one would hand
+ * any account instance-wide authority, so no eligible set may name it — and a
+ * name outside the `RoleName` grammar. The same fail-loud-at-boot shape as
+ * `create_role_schema`, which refuses a builtin name where only app roles
+ * belong. Twin of the Rust `validate_self_service_eligible_roles`.
+ *
+ * @param roles - the eligible role names
+ * @throws Error on a builtin role or a name outside the role grammar
+ */
+export declare const validate_self_service_eligible_roles: (roles: Iterable<string>) => void;
 /** Options for `create_self_service_role_actions`. */
 export interface SelfServiceRoleActionsOptions {
     /**
@@ -70,6 +83,7 @@ export interface SelfServiceRoleActionsOptions {
  * @param options - optional eligible-role override plus optional role schema for default-eligibility derivation
  * @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_specs`
+ * @throws Error at factory time if the eligible set names a builtin role or an invalid role name
  */
 export declare const create_self_service_role_actions: (deps: ActionFactoryDeps, 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE/F,OAAO,EAGN,KAAK,gBAAgB,EACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAWnD,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC7C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,iBAAiB,EACvB,UAAS,6BAAkC,KACzC,KAAK,CAAC,SAAS,CA2HjB,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE/F,OAAO,EAKN,KAAK,gBAAgB,EACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAWnD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oCAAoC,GAAI,OAAO,QAAQ,CAAC,MAAM,CAAC,KAAG,IAW9E,CAAC;AAEF,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC7C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,iBAAiB,EACvB,UAAS,6BAAkC,KACzC,KAAK,CAAC,SAAS,CA6HjB,CAAC"}

package/dist/auth/self_service_role_actions.js

@@ -38,12 +38,34 @@
  */
 import { rpc_action } from '../actions/action_rpc.js';
 import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
-import { builtin_role_specs_by_name, list_roles_with_grant_path } from './role_schema.js';
+import { builtin_role_specs_by_name, is_builtin_role, list_roles_with_grant_path, RoleName } from './role_schema.js';
 import { GRANT_PATH_SELF_SERVICE } from './grant_path_schema.js';
 import { query_create_role_grant, query_revoke_role_grant } from './role_grant_queries.js';
 import { is_role_grant_active } from './account_schema.js';
 import { has_scoped_role } from './request_context.js';
 import { ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE, self_service_role_set_action_spec } from './self_service_role_action_specs.js';
+/**
+ * Validate a deployment's self-service eligible-role set at construction.
+ *
+ * Refuses a builtin role (`admin` / `keeper`) — self-toggling one would hand
+ * any account instance-wide authority, so no eligible set may name it — and a
+ * name outside the `RoleName` grammar. The same fail-loud-at-boot shape as
+ * `create_role_schema`, which refuses a builtin name where only app roles
+ * belong. Twin of the Rust `validate_self_service_eligible_roles`.
+ *
+ * @param roles - the eligible role names
+ * @throws Error on a builtin role or a name outside the role grammar
+ */
+export const validate_self_service_eligible_roles = (roles) => {
+    for (const role of roles) {
+        if (is_builtin_role(role)) {
+            throw new Error(`self-service eligible role "${role}" is a builtin role — builtin roles are never self-service`);
+        }
+        if (!RoleName.safeParse(role).success) {
+            throw new Error(`self-service eligible role "${role}" is not a valid role name`);
+        }
+    }
+};
 /**
  * Build the unified self-service role toggle RPC action.
  *
@@ -53,12 +75,14 @@ import { ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE, self_service_role_set_action_spec
  * @param options - optional eligible-role override plus optional role schema for default-eligibility derivation
  * @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_specs`
+ * @throws Error at factory time if the eligible set names a builtin role or an invalid role name
  */
 export const create_self_service_role_actions = (deps, options = {}) => {
     const role_specs = options.roles?.role_specs ?? builtin_role_specs_by_name;
     const eligible = options.eligible_roles
         ? new Set(options.eligible_roles)
         : new Set(list_roles_with_grant_path(role_specs, GRANT_PATH_SELF_SERVICE));
+    validate_self_service_eligible_roles(eligible);
     if (options.eligible_roles && options.roles) {
         for (const r of eligible) {
             if (!role_specs.has(r)) {

package/dist/server/serve_fact_route.d.ts

@@ -138,7 +138,9 @@ export declare const create_serve_cell_fact_route_spec: (options: CreateServeFac
  * Auth is `{account: 'required', actor: 'required', roles: ['admin']}` —
  * the dispatcher's authorization phase resolves the acting actor and the
  * post-authorization guard enforces the admin role before the handler runs.
- * The handler re-checks `has_role(_, admin)` as defense-in-depth so a future
+ * The handler re-checks the **global** admin grant
+ * (`has_scoped_role(_, admin, null)`, the auth phase's own reading) as
+ * defense-in-depth so a future
  * mounting/auth-shape regression fails closed rather than serving by bare
  * hash to a non-admin.
  */

package/dist/server/serve_fact_route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAetD,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAkEjD,MAAM,WAAW,+BAA+B;IAC/C;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;CACZ;AAgHD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,+BAA+B,KACtC,SAgDF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SA0CF,CAAC"}
+{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAetD,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAkEjD,MAAM,WAAW,+BAA+B;IAC/C;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;CACZ;AAgHD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,+BAA+B,KACtC,SAgDF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SA2CF,CAAC"}

package/dist/server/serve_fact_route.js

@@ -93,7 +93,7 @@ import { join } from 'node:path';
 import { FactHashSchema } from '@fuzdev/fuz_util/hash_schemas.ts';
 import { Uuid } from '@fuzdev/fuz_util/id.ts';
 import { z } from 'zod';
-import { build_request_context, get_request_context, has_role } from '../auth/request_context.js';
+import { build_request_context, get_request_context, has_scoped_role } from '../auth/request_context.js';
 import { ROLE_ADMIN } from '../auth/role_schema.js';
 import { ActingActor } from '../http/auth_shape.js';
 import { ACCOUNT_ID_KEY } from '../hono_context.js';
@@ -315,7 +315,9 @@ export const create_serve_cell_fact_route_spec = (options) => {
  * Auth is `{account: 'required', actor: 'required', roles: ['admin']}` —
  * the dispatcher's authorization phase resolves the acting actor and the
  * post-authorization guard enforces the admin role before the handler runs.
- * The handler re-checks `has_role(_, admin)` as defense-in-depth so a future
+ * The handler re-checks the **global** admin grant
+ * (`has_scoped_role(_, admin, null)`, the auth phase's own reading) as
+ * defense-in-depth so a future
  * mounting/auth-shape regression fails closed rather than serving by bare
  * hash to a non-admin.
  */
@@ -351,8 +353,9 @@ export const create_serve_fact_route_spec = (options) => {
             const { hash } = get_route_params(c);
             // Defense-in-depth: the auth phase already gated this on the admin
             // role, but re-check the resolved context so a mounting/auth-shape
-            // regression fails closed instead of serving by bare hash.
-            if (!has_role(get_request_context(c), ROLE_ADMIN)) {
+            // regression fails closed instead of serving by bare hash. Global
+            // grant only — a scoped `admin` row must not read every fact.
+            if (!has_scoped_role(get_request_context(c), ROLE_ADMIN, null)) {
                 return c.body(null, 404);
             }
             return serve_fact_bytes(c, route, hash, config);

package/dist/testing/CLAUDE.md

@@ -1237,8 +1237,11 @@ the option type states whether the bundle is read.
   (gate on `capabilities.cell_gated_create`, **cross-only**) — the parent-aware
   cell-creation authorizer (`CellCreateAuthorize`, **directory model**) +
   the `cell_moderate` verb parity proofs. Both spines mount the same
-  `test_cell_gated_create_authorize` policy: a `kind: 'space'` **root** is
-  admin-only (a non-admin → **403** `cell_create_forbidden`); a **contribution**
+  `test_cell_gated_create_authorize` policy (its admin bypass and `min_role`
+  read the **global** grant): a `kind: 'space'` **root** is
+  admin-only (a non-admin → **403** `cell_create_forbidden`, and the same for a
+  non-admin `cell_clone` of a viewable space — clone runs the authorizer for
+  every cell it writes); a **contribution**
   under a space is gated by the root's `data.policy[kind] = {min_role,
 moderation_required}`, with `moderation` set per the verdict (`pending`+private
   vs `approved`+author-visibility); a **hidden** parent **404**-masks vs a
@@ -1619,12 +1622,17 @@ non-admin _holder_ of `participant` (and a fresh non-admin) can't offer it (403
 `role_grant_assign` is admin-only** — non-admin holder / fresh → 403
 `insufficient_permissions` (dispatcher gate), anon → 401; plus the
 `to_actor_id`-must-belong-to-`to_account_id` resolution arm (400
-`role_grant_offer_actor_account_mismatch`).
+`role_grant_offer_actor_account_mismatch`); **(d) builtin roles are
+global-only** — an unpaired `scope_kind` / `scope_id` → 400 on assign + offer,
+a scoped `admin` → 400 `role_grant_builtin_scoped` on assign + offer, a builtin
+offer from a non-global-admin → 403 `role_grant_offer_not_authorized`.
 
 `describe_role_grant_participation_cross_tests` (this module) is the **imperative
 escape hatch** for the multi-step success paths a static row can't express (they
 need a real recipient): admin **assigns** `participant` to a fresh account
-(`{ok, role_grant_id}` + idempotent re-assign), and admin **offers**
+(`{ok, role_grant_id}` + idempotent re-assign), admin **assigns** a scoped
+`participant` whose `scope_kind` + `scope_id` round-trip through
+`admin_account_list` (distinct from the global grant), and admin **offers**
 `participant` → recipient **accepts** → a role_grant lands. The `role_holder`
 principal is seeded via `extra_accounts: [{username, roles: ['participant']}]`
 (bootstrap-cradle direct grant) and named through `principals.role_holder`.

package/dist/testing/cross_backend/cell_gated_create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cell_gated_create.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/cell_gated_create.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAiD9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAkB1E,eAAO,MAAM,sCAAsC,GAClD,SAAS,uCAAuC,KAC9C,IAwPF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,kCAAkC,GAC9C,SAAS,uCAAuC,KAC9C,IAwHF,CAAC"}
+{"version":3,"file":"cell_gated_create.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/cell_gated_create.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAyD9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAkB1E,eAAO,MAAM,sCAAsC,GAClD,SAAS,uCAAuC,KAC9C,IAwPF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,kCAAkC,GAC9C,SAAS,uCAAuC,KAC9C,IAyKF,CAAC"}

package/dist/testing/cross_backend/cell_gated_create.js

@@ -30,6 +30,9 @@ import '../assert_dev_env.js';
  *   **private** space the caller can't view → **404** `cell_not_found` (the
  *   parent is masked); under a **public** space → **403** (you see it, you
  *   can't contribute).
+ * - **clone is no side door** — `cell_clone` runs the authorizer for every cell
+ *   it writes as a parentless create, so a non-admin clone of a viewable
+ *   `space` root → **403** `cell_create_forbidden`; admin → succeeds.
  *
  * Gated on `capabilities.cell_gated_create` — `true` only on the reference
  * spine binaries that mount the policy, so it skips for generic consumers and
@@ -41,7 +44,8 @@ import '../assert_dev_env.js';
  * @module
  */
 import { describe, assert } from 'vitest';
-import { CellCreateOutput, CellModerateOutput } from '../../auth/cell_action_specs.js';
+import { CellCloneOutput, CellCreateOutput, CellModerateOutput } from '../../auth/cell_action_specs.js';
+import { JSONRPC_ERROR_CODES } from '../../http/jsonrpc_errors.js';
 import { test_if } from './capabilities.js';
 import { cross_rpc_call, error_reason, expect_output } from './cell_cross_helpers.js';
 import { SPINE_RPC_PATH } from './spine_surface_constants.js';
@@ -211,4 +215,22 @@ export const describe_cell_moderate_cross_tests = (options) => {
             assert.strictEqual(moderated.cell.visibility, 'private', 'rejection leaves the post private');
         });
     });
+    describe('cell_clone runs the creation authorizer (parity)', () => {
+        test_if(capabilities.cell_gated_create, 'a non-admin clone of a viewable `space` root → 403, admin clone succeeds', async () => {
+            const fixture = await setup_test();
+            const space = expect_output(await cross_rpc_call(fixture.transport, rpc_path, 'cell_create', { kind: SPACE_CELL_KIND, data: SPACE_POLICY, visibility: 'public' }, fixture.create_session_headers()), CellCreateOutput);
+            // Every cell a clone writes is a parentless create of the source's
+            // kind, gated like `cell_create` — so a caller denied a `space` root
+            // can't clone one they can see into one they own.
+            const stranger = await fixture.create_account({ username: 'clone_stranger' });
+            const denied = await cross_rpc_call(fixture.transport, rpc_path, 'cell_clone', { source_id: space.cell.id }, stranger.create_session_headers());
+            assert.ok(!denied.ok, 'a non-admin must not clone a space root');
+            assert.strictEqual(denied.error?.code, JSONRPC_ERROR_CODES.forbidden, 'a 403');
+            assert.strictEqual(error_reason(denied), 'cell_create_forbidden');
+            const cloned = expect_output(await cross_rpc_call(fixture.transport, rpc_path, 'cell_clone', { source_id: space.cell.id }, fixture.create_session_headers()), CellCloneOutput);
+            assert.strictEqual(cloned.cell.kind, SPACE_CELL_KIND, 'the admin clones the space');
+            assert.notStrictEqual(cloned.cell.id, space.cell.id);
+            assert.strictEqual(cloned.cell.moderation, null, 'a clone stamps no moderation');
+        });
+    });
 };

package/dist/testing/cross_backend/role_grant_participation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role_grant_participation.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/role_grant_participation.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAsC9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,0EAA0E;AAC1E,MAAM,WAAW,sCAAsC;IACtD,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,6CAA6C,GACzD,SAAS,sCAAsC,KAC7C,IAgFF,CAAC"}
+{"version":3,"file":"role_grant_participation.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/role_grant_participation.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAyC9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,0EAA0E;AAC1E,MAAM,WAAW,sCAAsC;IACtD,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,6CAA6C,GACzD,SAAS,sCAAsC,KAC7C,IA8IF,CAAC"}

package/dist/testing/cross_backend/role_grant_participation.js

@@ -15,6 +15,9 @@ import '../assert_dev_env.js';
  *   re-assigning the active grant is idempotent (same id).
  * - **consent flow** — `role_grant_offer_create` of `participant` (admin-only)
  *   → the recipient `role_grant_offer_accept`s → a role_grant lands.
+ * - **scoped assign** — `role_grant_assign` of `participant` with a paired
+ *   `scope_kind` + `scope_id` lands a scoped grant carrying both, read back
+ *   through `admin_account_list`, distinct from the global grant.
  *
  * The single-request gate/denial matrix (grantability refusal, admin-only
  * conferral, dispatcher admin gate, auth) lives in the declarative table
@@ -55,6 +58,37 @@ export const describe_role_grant_participation_cross_tests = (options) => {
             assert.ok(second.ok, `re-assign must succeed: ${JSON.stringify(second)}`);
             assert.strictEqual(second.result.role_grant_id, assigned.role_grant_id, 're-assigning an active grant returns the existing role_grant id');
         });
+        test('admin assigns a scoped participant grant that round-trips scope_kind', async () => {
+            const fixture = await setup_test();
+            const recipient = await fixture.create_account({ username: 'participation_scoped' });
+            const scope_id = '33333333-3333-4333-8333-333333333333';
+            const scoped = await rpc(fixture.transport, 'role_grant_assign', {
+                to_account_id: recipient.account.id,
+                role: SPINE_PARTICIPANT_ROLE,
+                scope_kind: 'space',
+                scope_id
+            }, fixture.create_session_headers());
+            assert.ok(scoped.ok, `scoped assign must succeed: ${JSON.stringify(scoped)}`);
+            const scoped_id = scoped.result.role_grant_id;
+            const global = await rpc(fixture.transport, 'role_grant_assign', { to_account_id: recipient.account.id, role: SPINE_PARTICIPANT_ROLE }, fixture.create_session_headers());
+            assert.ok(global.ok, `global assign must succeed: ${JSON.stringify(global)}`);
+            const global_id = global.result.role_grant_id;
+            assert.notStrictEqual(global_id, scoped_id, 'the global grant is a distinct row');
+            const listed = await rpc(fixture.transport, 'admin_account_list', {}, fixture.create_session_headers());
+            assert.ok(listed.ok, `admin_account_list must succeed: ${JSON.stringify(listed)}`);
+            const entry = listed.result.accounts.find((a) => a.account.id === recipient.account.id);
+            assert.ok(entry, 'the recipient is listed');
+            const by_id = new Map(entry.role_grants.map((g) => [g.id, g]));
+            const scoped_row = by_id.get(scoped_id);
+            assert.ok(scoped_row, 'the scoped grant is listed');
+            assert.strictEqual(scoped_row.role, SPINE_PARTICIPANT_ROLE);
+            assert.strictEqual(scoped_row.scope_kind, 'space', 'scope_kind round-trips');
+            assert.strictEqual(scoped_row.scope_id, scope_id, 'scope_id round-trips');
+            const global_row = by_id.get(global_id);
+            assert.ok(global_row, 'the global grant is listed');
+            assert.strictEqual(global_row.scope_kind, null);
+            assert.strictEqual(global_row.scope_id, null);
+        });
         test('admin offers the participant app-role and the recipient accepts', async () => {
             const fixture = await setup_test();
             const recipient = await fixture.create_account({ username: 'participation_offeree' });

package/dist/testing/cross_backend/rust_spine_stub_backend_config.d.ts

@@ -2,6 +2,14 @@ import '../assert_dev_env.js';
 import type { BackendConfig } from './backend_config.js';
 /** Env var naming the prebuilt `testing_spine_stub` binary. Required when `binary_path` is omitted. */
 export declare const RUST_SPINE_STUB_BIN_ENV = "FUZ_TESTING_RUST_SPINE_STUB_BIN";
+/**
+ * Env var overriding the stub's Postgres URL when `database_url` is omitted —
+ * e.g. a scratch cluster on a spare port, keeping the run off the machine's
+ * default server. Pair it with the libpq `PGHOST` / `PGPORT` the runner's
+ * idempotent `createdb` reads, so the database it ensures is the one the URL
+ * names.
+ */
+export declare const RUST_SPINE_STUB_DATABASE_URL_ENV = "FUZ_TESTING_RUST_SPINE_STUB_DATABASE_URL";
 /**
  * Env var the stub reads for the absolute path of the committed
  * `expected_schema.json` its `/ready` gate introspects against. Pointed at the
@@ -16,7 +24,10 @@ export declare const RUST_SPINE_STUB_DEFAULT_DATABASE_URL = "postgres://localhos
 export interface SpineStubBackendConfigOptions {
     /** Listening port. Default `RUST_SPINE_STUB_DEFAULT_PORT`. */
     readonly port?: number;
-    /** Postgres connection URL. Default `RUST_SPINE_STUB_DEFAULT_DATABASE_URL`. */
+    /**
+     * Postgres connection URL. Default `$FUZ_TESTING_RUST_SPINE_STUB_DATABASE_URL`,
+     * then `RUST_SPINE_STUB_DEFAULT_DATABASE_URL`.
+     */
     readonly database_url?: string;
     /**
      * Prebuilt binary path. Overrides the `FUZ_TESTING_RUST_SPINE_STUB_BIN` env

package/dist/testing/cross_backend/rust_spine_stub_backend_config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rust_spine_stub_backend_config.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/rust_spine_stub_backend_config.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AASzD,uGAAuG;AACvG,eAAO,MAAM,uBAAuB,oCAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,wCAAwC,6CAA6C,CAAC;AAkBnG,kGAAkG;AAClG,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,0FAA0F;AAC1F,eAAO,MAAM,oCAAoC,sDACG,CAAC;AAErD,MAAM,WAAW,6BAA6B;IAC7C,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,GAC1C,UAAS,6BAAkC,KACzC,aAiDF,CAAC"}
+{"version":3,"file":"rust_spine_stub_backend_config.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/rust_spine_stub_backend_config.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA0C9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AASzD,uGAAuG;AACvG,eAAO,MAAM,uBAAuB,oCAAoC,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,6CAA6C,CAAC;AAE3F;;;;;GAKG;AACH,eAAO,MAAM,wCAAwC,6CAA6C,CAAC;AAkBnG,kGAAkG;AAClG,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,0FAA0F;AAC1F,eAAO,MAAM,oCAAoC,sDACG,CAAC;AAErD,MAAM,WAAW,6BAA6B;IAC7C,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,GAC1C,UAAS,6BAAkC,KACzC,aAkDF,CAAC"}

package/dist/testing/cross_backend/rust_spine_stub_backend_config.js

@@ -25,6 +25,9 @@ import '../assert_dev_env.js';
  * createdb fuz_app_test_rust_spine_stub 2>/dev/null || true
  * ```
  *
+ * `FUZ_TESTING_RUST_SPINE_STUB_DATABASE_URL` points the stub at another
+ * server (e.g. a scratch cluster on a spare port).
+ *
  * The binary self-wipes the auth-namespace schema on every boot
  * (`FUZ_TESTING_RESET_DB_ON_STARTUP=true`, set by the Rust-family builder),
  * so no manual `DROP TABLE` between sessions is needed; per-test reset is
@@ -39,6 +42,14 @@ import { SPINE_EXPECTED_SCHEMA_URL } from './spine_surface_constants.js';
 import { LOGIN_RATE_LIMIT_ENABLED_ENV, make_default_rust_backend_config, rust_default_capabilities } from './default_backend_configs.js';
 /** Env var naming the prebuilt `testing_spine_stub` binary. Required when `binary_path` is omitted. */
 export const RUST_SPINE_STUB_BIN_ENV = 'FUZ_TESTING_RUST_SPINE_STUB_BIN';
+/**
+ * Env var overriding the stub's Postgres URL when `database_url` is omitted —
+ * e.g. a scratch cluster on a spare port, keeping the run off the machine's
+ * default server. Pair it with the libpq `PGHOST` / `PGPORT` the runner's
+ * idempotent `createdb` reads, so the database it ensures is the one the URL
+ * names.
+ */
+export const RUST_SPINE_STUB_DATABASE_URL_ENV = 'FUZ_TESTING_RUST_SPINE_STUB_DATABASE_URL';
 /**
  * Env var the stub reads for the absolute path of the committed
  * `expected_schema.json` its `/ready` gate introspects against. Pointed at the
@@ -77,7 +88,8 @@ export const RUST_SPINE_STUB_DEFAULT_DATABASE_URL = 'postgres://localhost/fuz_ap
  * @throws Error when no binary path is available.
  */
 export const rust_spine_stub_backend_config = (options = {}) => {
-    const { port = RUST_SPINE_STUB_DEFAULT_PORT, database_url = RUST_SPINE_STUB_DEFAULT_DATABASE_URL, binary_path = process.env[RUST_SPINE_STUB_BIN_ENV], enable_login_rate_limit, trusted_proxies } = options;
+    const { port = RUST_SPINE_STUB_DEFAULT_PORT, database_url = process.env[RUST_SPINE_STUB_DATABASE_URL_ENV] ||
+        RUST_SPINE_STUB_DEFAULT_DATABASE_URL, binary_path = process.env[RUST_SPINE_STUB_BIN_ENV], enable_login_rate_limit, trusted_proxies } = options;
     if (!binary_path) {
         throw new Error(`rust_spine_stub_backend_config: no binary path — set ${RUST_SPINE_STUB_BIN_ENV} to a prebuilt ` +
             '`testing_spine_stub` binary (build it with `cargo build -p testing_spine_stub --release`) ' +

package/dist/testing/cross_backend/test_cell_gated_create_authorize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test_cell_gated_create_authorize.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/test_cell_gated_create_authorize.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA+B9B,OAAO,KAAK,EACX,mBAAmB,EAGnB,MAAM,4BAA4B,CAAC;AAGpC,8EAA8E;AAC9E,eAAO,MAAM,eAAe,UAAU,CAAC;AAEvC;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,gBAAyB,CAAC;AAEzD,yFAAyF;AACzF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAYD;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,EAAE,mBAoB9C,CAAC"}
+{"version":3,"file":"test_cell_gated_create_authorize.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/test_cell_gated_create_authorize.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA+B9B,OAAO,KAAK,EACX,mBAAmB,EAGnB,MAAM,4BAA4B,CAAC;AAGpC,8EAA8E;AAC9E,eAAO,MAAM,eAAe,UAAU,CAAC;AAEvC;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,gBAAyB,CAAC;AAEzD,yFAAyF;AACzF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAYD;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,EAAE,mBAsB9C,CAAC"}

package/dist/testing/cross_backend/test_cell_gated_create_authorize.js

@@ -6,15 +6,15 @@ import '../assert_dev_env.js';
  * the parent-aware cell-creation authorizer agrees TS↔Rust. The twin of the
  * Rust `TestCellGatedCreateAuthorize`, **directory model**.
  *
- * Admin bypasses everything (`{allow: true, moderation_required: false}`). For
- * a non-admin:
+ * A **global** admin bypasses everything (`{allow: true, moderation_required:
+ * false}`) — a scoped `admin` row is no admin here. For anyone else:
  *
  * - **Root creation** (`root_id` null): `kind: 'space'` is admin-only (denied);
  *   every other parentless kind stays open, so the plain-create `cell_crud` /
  *   `cell_relations` suites are unaffected.
  * - **Contribution** (`root_id` set): the governing root's
  *   `data.policy[kind] = {min_role?, moderation_required?}` decides — a missing
- *   entry denies, a present `min_role` the actor lacks denies, and otherwise it
+ *   entry denies, a present `min_role` the actor lacks globally denies, and otherwise it
  *   admits with the entry's `moderation_required` folded into the verdict. The
  *   root's `data` arrives in `input.root_data` (the handler read it in-tx), so
  *   the predicate is **pure** — no DB read of its own (which also dodges the
@@ -25,7 +25,7 @@ import '../assert_dev_env.js';
  *
  * @module
  */
-import { has_role } from '../../auth/request_context.js';
+import { has_scoped_role } from '../../auth/request_context.js';
 import { ROLE_ADMIN } from '../../auth/role_schema.js';
 import { SPINE_PARTICIPANT_ROLE } from './spine_surface_constants.js';
 /** The admin-only root kind the test policy gates (talk's `space` analog). */
@@ -54,8 +54,9 @@ const get_contribution_rule = (data, kind) => {
  * handler). Byte-equivalent with the Rust `TestCellGatedCreateAuthorize`.
  */
 export const test_cell_gated_create_authorize = (auth, input) => {
-    // Admin bypass — admins create roots + any kind, live immediately.
-    if (has_role(auth, ROLE_ADMIN))
+    // Admin bypass — admins create roots + any kind, live immediately. The
+    // global grant only: a scoped `admin` row bypasses nothing.
+    if (has_scoped_role(auth, ROLE_ADMIN, null))
         return { allow: true, moderation_required: false };
     // Root creation (no governing root): `space` is admin-only; other parentless
     // kinds stay open (the plain-create suites).
@@ -68,7 +69,8 @@ export const test_cell_gated_create_authorize = (auth, input) => {
     const rule = get_contribution_rule(input.root_data, input.kind ?? '');
     if (!rule)
         return { allow: false };
-    const admitted = rule.min_role === undefined || has_role(auth, rule.min_role);
+    // `min_role` names no scope, so only the global grant satisfies it.
+    const admitted = rule.min_role === undefined || has_scoped_role(auth, rule.min_role, null);
     return admitted
         ? { allow: true, moderation_required: rule.moderation_required ?? false }
         : { allow: false };

package/dist/testing/entities.d.ts

@@ -1,7 +1,7 @@
 import './assert_dev_env.js';
 import type { Account, Actor, RoleGrant } from '../auth/account_schema.js';
 import type { AuditLogEvent } from '../auth/audit_log_schema.js';
-import type { RequestContext } from '../auth/request_context.js';
+import type { RequestActorContext } from '../auth/request_context.js';
 /** Override type for `create_test_account` — id-like fields accept plain `string`. */
 export type TestAccountOverrides = Partial<Omit<Account, 'id' | 'created_by' | 'updated_by'>> & {
     id?: string;
@@ -30,8 +30,11 @@ export type TestRoleGrantOverrides = Partial<Omit<RoleGrant, 'id' | 'actor_id' |
 };
 /** Create a test `RoleGrant` with sensible defaults. */
 export declare const create_test_role_grant: (overrides?: TestRoleGrantOverrides) => RoleGrant;
-/** Create a test `RequestContext` with role_grants from partial overrides. */
-export declare const create_test_context: (role_grants?: Array<TestRoleGrantOverrides>) => RequestContext;
+/**
+ * Create a test `RequestActorContext` (a `RequestContext` with a resolved
+ * actor) with role_grants from partial overrides.
+ */
+export declare const create_test_context: (role_grants?: Array<TestRoleGrantOverrides>) => RequestActorContext;
 /** Override type for `create_test_audit_event` — id-like fields accept plain `string`. */
 export type TestAuditEventOverrides = Partial<Omit<AuditLogEvent, 'id' | 'actor_id' | 'account_id' | 'target_account_id' | 'target_actor_id'>> & {
     id?: string;

package/dist/testing/entities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entities.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/entities.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAiB7B,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,sFAAsF;AACtF,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,YAAY,GAAG,YAAY,CAAC,CAAC,GAAG;IAC/F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,GAAI,YAAY,oBAAoB,KAAG,OAarE,CAAC;AAEH,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,YAAY,GAAG,YAAY,CAAC,CAAC,GAAG;IAC3F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,GAAI,YAAY,kBAAkB,KAAG,KAUjE,CAAC;AAEH,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAC3C,IAAI,CACH,SAAS,EACT,IAAI,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,iBAAiB,CAC/F,CACD,GAAG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,sBAAsB,GAAI,YAAY,sBAAsB,KAAG,SAgB3E,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,GAC/B,cAAa,KAAK,CAAC,sBAAsB,CAAQ,KAC/C,cAID,CAAC;AAEH,0FAA0F;AAC1F,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAC5C,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,UAAU,GAAG,YAAY,GAAG,mBAAmB,GAAG,iBAAiB,CAAC,CAC/F,GAAG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,GAAI,YAAY,uBAAuB,KAAG,aAa5E,CAAC"}
+{"version":3,"file":"entities.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/entities.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAiB7B,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,sFAAsF;AACtF,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,YAAY,GAAG,YAAY,CAAC,CAAC,GAAG;IAC/F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,GAAI,YAAY,oBAAoB,KAAG,OAarE,CAAC;AAEH,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,YAAY,GAAG,YAAY,CAAC,CAAC,GAAG;IAC3F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,GAAI,YAAY,kBAAkB,KAAG,KAUjE,CAAC;AAEH,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAC3C,IAAI,CACH,SAAS,EACT,IAAI,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,iBAAiB,CAC/F,CACD,GAAG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,sBAAsB,GAAI,YAAY,sBAAsB,KAAG,SAgB3E,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAC/B,cAAa,KAAK,CAAC,sBAAsB,CAAQ,KAC/C,mBAID,CAAC;AAEH,0FAA0F;AAC1F,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAC5C,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,UAAU,GAAG,YAAY,GAAG,mBAAmB,GAAG,iBAAiB,CAAC,CAC/F,GAAG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,GAAI,YAAY,uBAAuB,KAAG,aAa5E,CAAC"}

package/dist/testing/entities.js

@@ -44,7 +44,10 @@ export const create_test_role_grant = (overrides) => {
     };
     return overrides ? { ...base, ...overrides } : base;
 };
-/** Create a test `RequestContext` with role_grants from partial overrides. */
+/**
+ * Create a test `RequestActorContext` (a `RequestContext` with a resolved
+ * actor) with role_grants from partial overrides.
+ */
 export const create_test_context = (role_grants = [{}]) => ({
     account: create_test_account(),
     actor: create_test_actor(),