@fuzdev/fuz_app 0.101.1 → 0.102.0

package/dist/auth/CLAUDE.md

@@ -436,7 +436,7 @@ are excluded.
   records, regardless of outcome. Default
   `default_action_account_rate_limit` is 1200/15min per actor.
 
-### Admin actions — fourteen specs
+### Admin actions
 
 `create_admin_actions(deps, options?)` in `auth/admin_actions.ts`.
 
@@ -501,7 +501,7 @@ visibility — `target_account_id` is null (FK rejects missing ids), and the
 probed id is preserved under `metadata.attempted_account_id`. Every gated
 event additionally records `credential_type` in metadata (defense in depth).
 
-### Role-grant-offer actions — seven specs
+### Role-grant-offer actions
 
 `create_role_grant_offer_actions(deps, options?)` in
 `auth/role_grant_offer_actions.ts`.
@@ -525,19 +525,22 @@ event additionally records `credential_type` in metadata (defense in depth).
 - `role_grant_offer_list_action_spec` — input `{account_id?}`; output `{offers}`.
 - `role_grant_offer_history_action_spec` — input `{account_id?, limit?, offset?}`; output `{offers}`.
 - `role_grant_revoke_action_spec` — input `{actor_id, role_grant_id, reason?}`; output `{ok, revoked}`.
+- `role_grant_assign_action_spec` — admin-only immediate conferral (no consent step); input `{to_account_id, to_actor_id?, role, scope_id?}`; output `{ok, role_grant_id}`. Runs the same admin-grant-path gate as offer-create, resolves the target actor (named `to_actor_id` ∈ the account's active actors, else its sole active actor — multi-actor → `invalid_params`, actorless → 404), writes via the idempotent `query_create_role_grant` (`scope_kind` stays null), and emits a `role_grant_create` audit row. No WS notification in v1. Reasons: `ERROR_ROLE_NOT_WEB_GRANTABLE`, `ERROR_ROLE_GRANT_OFFER_ACTOR_ACCOUNT_MISMATCH`.
 
 Every input carries `acting?: ActingActor` (registry-time invariant 2).
 `role_grant_revoke` keys on **`actor_id`**, not `account_id` — role_grants
 are actor-scoped and deriving actor from account collapses under multi-actor
 accounts.
 
-`role_grant_offer_create` runs the **admin-grant-path gate first** (offered
+`role_grant_offer_create` runs the **admin-grantability gate first** (offered
 role's `RoleSpec.grant_paths` must include `'admin'`), then the
-`RoleGrantOfferCreateAuthorize` callback. Default: caller holds the offered
-role globally. Pre-built `authorize_admin_or_holder` admits any admin and
-otherwise falls back to the default — drop into `create_role_grant_offer_actions({authorize: authorize_admin_or_holder})`
-or `create_standard_rpc_actions` for "admins offer anything; users offer
-what they hold."
+`RoleGrantOfferCreateAuthorize` callback. **Default `default_authorize`: the
+caller must hold a _global_ `admin` grant** — conferral is admin-only, with no
+holder-propagation (holding the offered role confers no power to offer it). The
+global check (`has_scoped_role(_, ROLE_ADMIN, null)`) stops a scoped `admin`
+escalating into global authority over the offer surface. A consumer needing
+scope-aware delegation (e.g. a classroom teacher offering within their own
+scope) supplies a custom `authorize` callback.
 
 Error reasons (`as const` literals):
 
@@ -589,7 +592,7 @@ Options: `roles?: RoleSchemaResult` (drives admin-grant-path lookup),
 `default_ttl_ms?` (defaults to `ROLE_GRANT_OFFER_DEFAULT_TTL_MS` = 30 days),
 `authorize?: RoleGrantOfferCreateAuthorize`.
 
-### Account actions — seven self-service specs
+### Account actions — self-service
 
 `create_account_actions(deps, options?)` in `auth/account_actions.ts`.
 
@@ -625,8 +628,8 @@ arbitrary sockets.
 `create_standard_rpc_actions(deps, options)` in `auth/standard_rpc_actions.ts`
 spreads `create_admin_actions`, `create_role_grant_offer_actions`, and
 `create_account_actions` into a single `Array<RpcAction>` — the canonical
-fuz_app "standard" surface (28 actions: 14 admin + 7 role-grant-offer + 7
-account; the two app-settings methods are always wired). Frontend mirror is
+fuz_app "standard" surface (admin + role-grant-offer + account; the two
+app-settings methods are always wired). Frontend mirror is
 `all_standard_action_specs` in `auth/standard_action_specs.ts`.
 
 Option routing — `roles` is shared between admin + role-grant-offer;

package/dist/auth/role_grant_offer_action_specs.d.ts

@@ -1,6 +1,7 @@
 /**
  * Role grant offer RPC action specs — declarative contract for the
- * consentful-role-grants surface (offer lifecycle + admin revoke).
+ * consentful-role-grants surface (offer lifecycle + admin revoke + the
+ * immediate admin-only `role_grant_assign`).
  *
  * Import this module for the specs, Input/Output schemas, `ERROR_ROLE_GRANT_OFFER_*`
  * reason constants, and the `all_role_grant_offer_action_specs` registry.
@@ -209,6 +210,27 @@ export declare const RoleGrantRevokeOutput: z.ZodObject<{
     revoked: z.ZodLiteral<true>;
 }, z.core.$strict>;
 export type RoleGrantRevokeOutput = z.infer<typeof RoleGrantRevokeOutput>;
+/**
+ * Input for `role_grant_assign` — the immediate admin-only conferral path, the
+ * consent-free sibling of `role_grant_offer_create`. An admin assigns a
+ * role_grant straight onto the target actor; there is no offer for a grantee to
+ * accept. No `message` (no offer to carry it on) and no `scope_kind` (`scope_id`
+ * alone is the v1 scope discriminator — the grant row's `scope_kind` stays null).
+ */
+export declare const RoleGrantAssignInput: z.ZodObject<{
+    to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    to_actor_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+    role: z.ZodString;
+    scope_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+    acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+}, z.core.$strict>;
+export type RoleGrantAssignInput = z.infer<typeof RoleGrantAssignInput>;
+/** Output for `role_grant_assign`. */
+export declare const RoleGrantAssignOutput: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    role_grant_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+}, z.core.$strict>;
+export type RoleGrantAssignOutput = z.infer<typeof RoleGrantAssignOutput>;
 /**
  * `rate_limit: 'account'` throttles offer-spam at the authenticated
  * grantor and bounds the account-existence oracle on `to_account_id` —
@@ -447,10 +469,41 @@ export declare const role_grant_revoke_action_spec: {
     error_reasons: ("role_not_web_grantable" | "role_grant_not_found")[];
     rate_limit: "account";
 };
+/**
+ * `rate_limit: 'account'` bounds admin-side burn of `role_grant_assign` — the
+ * action is admin-gated and audit-trailed, but the per-account cap matches
+ * `role_grant_revoke` so a single admin script can't churn grants in a loop.
+ */
+export declare const role_grant_assign_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "required";
+        roles: string[];
+    };
+    side_effects: true;
+    input: z.ZodObject<{
+        to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        to_actor_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+        role: z.ZodString;
+        scope_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+        acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+        role_grant_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+    error_reasons: ("role_not_web_grantable" | "role_grant_offer_actor_account_mismatch")[];
+    rate_limit: "account";
+};
 /**
  * All role-grant-offer action specs — a codegen-ready registry. Consumers spread
- * this into their own action-spec array to include offer lifecycle + revoke
- * methods in a typed client surface.
+ * this into their own action-spec array to include offer lifecycle + revoke +
+ * assign methods in a typed client surface.
  */
 export declare const all_role_grant_offer_action_specs: Array<RequestResponseActionSpec>;
 //# sourceMappingURL=role_grant_offer_action_specs.d.ts.map

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

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

package/dist/auth/role_grant_offer_action_specs.js

@@ -1,6 +1,7 @@
 /**
  * Role grant offer RPC action specs — declarative contract for the
- * consentful-role-grants surface (offer lifecycle + admin revoke).
+ * consentful-role-grants surface (offer lifecycle + admin revoke + the
+ * immediate admin-only `role_grant_assign`).
  *
  * Import this module for the specs, Input/Output schemas, `ERROR_ROLE_GRANT_OFFER_*`
  * reason constants, and the `all_role_grant_offer_action_specs` registry.
@@ -156,6 +157,31 @@ export const RoleGrantRevokeOutput = z.strictObject({
     ok: z.literal(true),
     revoked: z.literal(true),
 });
+/**
+ * Input for `role_grant_assign` — the immediate admin-only conferral path, the
+ * consent-free sibling of `role_grant_offer_create`. An admin assigns a
+ * role_grant straight onto the target actor; there is no offer for a grantee to
+ * accept. No `message` (no offer to carry it on) and no `scope_kind` (`scope_id`
+ * alone is the v1 scope discriminator — the grant row's `scope_kind` stays null).
+ */
+export const RoleGrantAssignInput = z.strictObject({
+    to_account_id: Uuid.meta({ description: 'Account id of the grantee.' }),
+    to_actor_id: Uuid.nullish().meta({
+        description: "Optional actor-grain target on the grantee account. When set, must belong to `to_account_id`. Omit to resolve the account's sole active actor — a multi-actor account must name one.",
+    }),
+    role: RoleName.meta({
+        description: "Role to assign. Must be admin-grantable (its `grant_paths` includes `'admin'`).",
+    }),
+    scope_id: Uuid.nullish().meta({
+        description: 'Scope id for resource-scoped grants. `null` for a global role_grant.',
+    }),
+    acting: ActingActor,
+});
+/** Output for `role_grant_assign`. */
+export const RoleGrantAssignOutput = z.strictObject({
+    ok: z.literal(true),
+    role_grant_id: Uuid,
+});
 // -- Action specs -----------------------------------------------------------
 /**
  * `rate_limit: 'account'` throttles offer-spam at the authenticated
@@ -267,10 +293,28 @@ export const role_grant_revoke_action_spec = {
     error_reasons: [ERROR_ROLE_GRANT_NOT_FOUND, ERROR_ROLE_NOT_WEB_GRANTABLE],
     rate_limit: 'account',
 };
+/**
+ * `rate_limit: 'account'` bounds admin-side burn of `role_grant_assign` — the
+ * action is admin-gated and audit-trailed, but the per-account cap matches
+ * `role_grant_revoke` so a single admin script can't churn grants in a loop.
+ */
+export const role_grant_assign_action_spec = {
+    method: 'role_grant_assign',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required', roles: ['admin'] },
+    side_effects: true,
+    input: RoleGrantAssignInput,
+    output: RoleGrantAssignOutput,
+    async: true,
+    description: "Immediately assign a role_grant to a target account — admin-only, no consent step (the capability-unlock UX). The role's `grant_paths` must include `'admin'`. Idempotent: re-assigning an active grant returns it. Emits a role_grant_create audit event.",
+    error_reasons: [ERROR_ROLE_NOT_WEB_GRANTABLE, ERROR_ROLE_GRANT_OFFER_ACTOR_ACCOUNT_MISMATCH],
+    rate_limit: 'account',
+};
 /**
  * All role-grant-offer action specs — a codegen-ready registry. Consumers spread
- * this into their own action-spec array to include offer lifecycle + revoke
- * methods in a typed client surface.
+ * this into their own action-spec array to include offer lifecycle + revoke +
+ * assign methods in a typed client surface.
  */
 export const all_role_grant_offer_action_specs = [
     role_grant_offer_create_action_spec,
@@ -280,4 +324,5 @@ export const all_role_grant_offer_action_specs = [
     role_grant_offer_list_action_spec,
     role_grant_offer_history_action_spec,
     role_grant_revoke_action_spec,
+    role_grant_assign_action_spec,
 ];

package/dist/auth/role_grant_offer_actions.d.ts

@@ -1,8 +1,9 @@
 /**
  * Role grant offer RPC action handlers — the consentful-role-grants action surface.
  *
- * Seven actions: six offer-lifecycle methods (create / accept / decline /
- * retract / list / history) plus `role_grant_revoke` (admin-only). All mount
+ * Eight actions: six offer-lifecycle methods (create / accept / decline /
+ * retract / list / history) plus `role_grant_revoke` and `role_grant_assign`
+ * (both admin-only). All mount
  * on a consumer's JSON-RPC endpoint via `create_rpc_endpoint`. The action
  * specs themselves live in `auth/role_grant_offer_action_specs.ts`. Mutations
  * declare `side_effects: true` so the RPC dispatcher wraps the handler in
@@ -23,6 +24,10 @@
  *   dispatcher rejects non-admin callers before the handler runs.
  *   The admin-grant-path gate prevents revoking keeper / daemon-scoped
  *   roles via this surface. Keys on `actor_id` to survive multi-actor accounts.
+ * - `role_grant_assign` — spec-level `auth: {role: 'admin'}`; the immediate
+ *   consent-free conferral path. The admin-grant-path gate prevents assigning
+ *   keeper / daemon-scoped roles via this surface. No holder-propagation — only
+ *   admins confer (see participation-gates.md Decision 7).
  *
  * Audit events are emitted in-transaction by the query layer (atomic with
  * the role_grant write on accept/revoke) or by the handler via the bound
@@ -76,23 +81,8 @@ export interface RoleGrantOfferActionOptions {
     authorize?: RoleGrantOfferCreateAuthorize;
 }
 /**
- * Authorization callback that admits any admin and otherwise falls back to
- * the symmetric default (caller must hold the offered role globally).
- *
- * The admin-grant-path filter in `create_handler` runs **before** the
- * `authorize` callback, so this never sees roles whose `grant_paths`
- * omits `'admin'`. Drop into
- * `create_role_grant_offer_actions({authorize: authorize_admin_or_holder})`
- * (or any factory that forwards `authorize`, e.g. `create_standard_rpc_actions`)
- * for the common "admins offer anything; users offer what they hold"
- * pattern. Scope-aware policies (e.g. classroom_teacher offering
- * classroom_student in their own scope) wrap this and short-circuit `true`
- * before delegating.
- */
-export declare const authorize_admin_or_holder: RoleGrantOfferCreateAuthorize;
-/**
- * Create the seven role-grant-offer RPC actions (six offer-lifecycle methods
- * plus `role_grant_revoke`).
+ * Create the eight role-grant-offer RPC actions (six offer-lifecycle methods
+ * plus `role_grant_revoke` and the immediate `role_grant_assign`).
  *
  * @param deps - `RouteFactoryDeps` (`log`, `audit`, …) plus optional `notification_sender` for WS fan-out — when absent, WS fan-out is silently skipped (DB-only side effects still happen). Consumers wiring `BackendWebsocketTransport` assign its instance directly (the transport's `send_to_account` signature accepts the broader `JsonrpcMessageFromServerToClient`, which is contravariantly compatible)
  * @param options - role schema, default TTL, authorization override

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

@@ -1 +1 @@
-{"version":3,"file":"role_grant_offer_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_grant_offer_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAGN,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAIN,KAAK,gBAAgB,EACrB,MAAM,kBAAkB,CAAC;AA0B1B,OAAO,EAA4C,KAAK,cAAc,EAAC,MAAM,sBAAsB,CAAC;AACpG,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAEhD,OAAO,EAON,KAAK,kBAAkB,EACvB,MAAM,qCAAqC,CAAC;AAiC7C;;;;;;;;GAQG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAC3C,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAC,EACrE,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,EACnC,GAAG,EAAE,aAAa,KACd,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,qDAAqD;AACrD,MAAM,WAAW,2BAA2B;IAC3C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,6BAA6B,CAAC;CAC1C;AA6BD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,EAAE,6BAavC,CAAC;AAIF;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,OAAO,CAAC,GAAG;IAC/C,mBAAmB,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAChD,EACD,UAAS,2BAAgC,KACvC,KAAK,CAAC,SAAS,CAodjB,CAAC"}
+{"version":3,"file":"role_grant_offer_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_grant_offer_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,OAAO,EAGN,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAIN,KAAK,gBAAgB,EACrB,MAAM,kBAAkB,CAAC;AA2B1B,OAAO,EAA4C,KAAK,cAAc,EAAC,MAAM,sBAAsB,CAAC;AACpG,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAEhD,OAAO,EAON,KAAK,kBAAkB,EACvB,MAAM,qCAAqC,CAAC;AAoC7C;;;;;;;;GAQG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAC3C,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAC,EACrE,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,EACnC,GAAG,EAAE,aAAa,KACd,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,qDAAqD;AACrD,MAAM,WAAW,2BAA2B;IAC3C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,6BAA6B,CAAC;CAC1C;AAgCD;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,OAAO,CAAC,GAAG;IAC/C,mBAAmB,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAChD,EACD,UAAS,2BAAgC,KACvC,KAAK,CAAC,SAAS,CAkiBjB,CAAC"}

package/dist/auth/role_grant_offer_actions.js

@@ -1,8 +1,9 @@
 /**
  * Role grant offer RPC action handlers — the consentful-role-grants action surface.
  *
- * Seven actions: six offer-lifecycle methods (create / accept / decline /
- * retract / list / history) plus `role_grant_revoke` (admin-only). All mount
+ * Eight actions: six offer-lifecycle methods (create / accept / decline /
+ * retract / list / history) plus `role_grant_revoke` and `role_grant_assign`
+ * (both admin-only). All mount
  * on a consumer's JSON-RPC endpoint via `create_rpc_endpoint`. The action
  * specs themselves live in `auth/role_grant_offer_action_specs.ts`. Mutations
  * declare `side_effects: true` so the RPC dispatcher wraps the handler in
@@ -23,6 +24,10 @@
  *   dispatcher rejects non-admin callers before the handler runs.
  *   The admin-grant-path gate prevents revoking keeper / daemon-scoped
  *   roles via this surface. Keys on `actor_id` to survive multi-actor accounts.
+ * - `role_grant_assign` — spec-level `auth: {role: 'admin'}`; the immediate
+ *   consent-free conferral path. The admin-grant-path gate prevents assigning
+ *   keeper / daemon-scoped roles via this surface. No holder-propagation — only
+ *   admins confer (see participation-gates.md Decision 7).
  *
  * Audit events are emitted in-transaction by the query layer (atomic with
  * the role_grant write on accept/revoke) or by the handler via the bound
@@ -44,12 +49,12 @@ import { builtin_role_specs_by_name, ROLE_ADMIN, role_has_grant_path, } from './
 import { GRANT_PATH_ADMIN } from './grant_path_schema.js';
 import { ROLE_GRANT_OFFER_DEFAULT_TTL_MS, to_role_grant_offer_json, } from './role_grant_offer_schema.js';
 import { query_role_grant_offer_create, query_role_grant_offer_decline, query_role_grant_offer_retract, query_role_grant_offer_list, query_role_grant_offer_history_for_account, query_accept_offer, RoleGrantOfferActorAccountMismatchError, RoleGrantOfferActorMismatchError, RoleGrantOfferAlreadyTerminalError, RoleGrantOfferExpiredError, RoleGrantOfferNotFoundError, RoleGrantOfferSelfTargetError, } from './role_grant_offer_queries.js';
-import { query_role_grant_find_active_role_for_actor, query_revoke_role_grant, } from './role_grant_queries.js';
-import { query_actor_by_id } from './account_queries.js';
+import { query_create_role_grant, query_role_grant_find_active_role_for_actor, query_revoke_role_grant, } from './role_grant_queries.js';
+import { query_actor_by_id, query_active_actors_by_account } from './account_queries.js';
 import { has_scoped_role } from './request_context.js';
 import { build_role_grant_offer_accepted_notification, build_role_grant_offer_declined_notification, build_role_grant_offer_received_notification, build_role_grant_offer_retracted_notification, build_role_grant_offer_supersede_notification, build_role_grant_revoke_notification, } from './role_grant_offer_notifications.js';
 import { ERROR_ROLE_GRANT_NOT_FOUND, ERROR_ROLE_NOT_WEB_GRANTABLE } from '../http/error_schemas.js';
-import { ERROR_ROLE_GRANT_OFFER_ACTOR_ACCOUNT_MISMATCH, ERROR_ROLE_GRANT_OFFER_ACTOR_MISMATCH, ERROR_ROLE_GRANT_OFFER_EXPIRED, ERROR_ROLE_GRANT_OFFER_NOT_AUTHORIZED, ERROR_ROLE_GRANT_OFFER_NOT_FOUND, ERROR_ROLE_GRANT_OFFER_ROLE_NOT_GRANTABLE, ERROR_ROLE_GRANT_OFFER_SELF_TARGET, ERROR_ROLE_GRANT_OFFER_TERMINAL, role_grant_offer_create_action_spec, role_grant_offer_accept_action_spec, role_grant_offer_decline_action_spec, role_grant_offer_retract_action_spec, role_grant_offer_list_action_spec, role_grant_offer_history_action_spec, role_grant_revoke_action_spec, } from './role_grant_offer_action_specs.js';
+import { ERROR_ROLE_GRANT_OFFER_ACTOR_ACCOUNT_MISMATCH, ERROR_ROLE_GRANT_OFFER_ACTOR_MISMATCH, ERROR_ROLE_GRANT_OFFER_EXPIRED, ERROR_ROLE_GRANT_OFFER_NOT_AUTHORIZED, ERROR_ROLE_GRANT_OFFER_NOT_FOUND, ERROR_ROLE_GRANT_OFFER_ROLE_NOT_GRANTABLE, ERROR_ROLE_GRANT_OFFER_SELF_TARGET, ERROR_ROLE_GRANT_OFFER_TERMINAL, role_grant_offer_create_action_spec, role_grant_offer_accept_action_spec, role_grant_offer_decline_action_spec, role_grant_offer_retract_action_spec, role_grant_offer_list_action_spec, role_grant_offer_history_action_spec, role_grant_revoke_action_spec, role_grant_assign_action_spec, } from './role_grant_offer_action_specs.js';
 // -- Helpers ----------------------------------------------------------------
 /**
  * Fan out a batch of pre-written audit rows to the bound emitter's
@@ -67,40 +72,18 @@ const fan_out_audit_events = (events, audit) => {
     }
 };
 // eslint-disable-next-line @typescript-eslint/require-await
-const default_authorize = async (auth, input, _deps, _ctx) => {
-    // Caller must hold an active role_grant for the offered role. Global (no scope)
-    // check — the scope-aware "only in this classroom" policy is consumer-level.
-    // Reads from the in-memory `auth.role_grants` snapshot loaded once per request
-    // by `create_request_context_middleware`; no DB roundtrip needed.
-    return has_scoped_role(auth, input.role, null);
-};
-/**
- * Authorization callback that admits any admin and otherwise falls back to
- * the symmetric default (caller must hold the offered role globally).
- *
- * The admin-grant-path filter in `create_handler` runs **before** the
- * `authorize` callback, so this never sees roles whose `grant_paths`
- * omits `'admin'`. Drop into
- * `create_role_grant_offer_actions({authorize: authorize_admin_or_holder})`
- * (or any factory that forwards `authorize`, e.g. `create_standard_rpc_actions`)
- * for the common "admins offer anything; users offer what they hold"
- * pattern. Scope-aware policies (e.g. classroom_teacher offering
- * classroom_student in their own scope) wrap this and short-circuit `true`
- * before delegating.
- */
-export const authorize_admin_or_holder = async (auth, input, _deps, _ctx) => {
-    // Admin bypass keys on **global** admin role_grants only — `has_scoped_role(_, _, null)`
-    // rejects scoped admin role_grants. Without this, a `{role: 'admin', scope_id: scope_X}`
-    // role_grant would let the holder offer any admin-grant-path role without holding it
-    // themselves, escalating scoped admin to global authority over the offer surface.
-    if (has_scoped_role(auth, ROLE_ADMIN, null))
-        return true;
-    return has_scoped_role(auth, input.role, null);
+const default_authorize = async (auth, _input, _deps, _ctx) => {
+    // Admin-only conferral: the caller must hold a *global* `admin` grant. Holding
+    // the offered role itself confers no power to offer it (no holder-propagation —
+    // see participation-gates.md Decision 6). The global check (scope_id null) stops
+    // a scoped `admin` escalating into global authority over the offer surface.
+    // Reads the in-memory `auth.role_grants` snapshot; no DB roundtrip.
+    return has_scoped_role(auth, ROLE_ADMIN, null);
 };
 // -- Action factory ---------------------------------------------------------
 /**
- * Create the seven role-grant-offer RPC actions (six offer-lifecycle methods
- * plus `role_grant_revoke`).
+ * Create the eight role-grant-offer RPC actions (six offer-lifecycle methods
+ * plus `role_grant_revoke` and the immediate `role_grant_assign`).
  *
  * @param deps - `RouteFactoryDeps` (`log`, `audit`, …) plus optional `notification_sender` for WS fan-out — when absent, WS fan-out is silently skipped (DB-only side effects still happen). Consumers wiring `BackendWebsocketTransport` assign its instance directly (the transport's `send_to_account` signature accepts the broader `JsonrpcMessageFromServerToClient`, which is contravariantly compatible)
  * @param options - role schema, default TTL, authorization override
@@ -464,6 +447,77 @@ export const create_role_grant_offer_actions = (deps, options = {}) => {
         }
         return { ok: true, revoked: true };
     };
+    // The immediate admin-only conferral path — the consent-free sibling of
+    // `role_grant_offer_create`. Admin-gated at the dispatcher (`roles:
+    // ['admin']`), it re-checks admin-grantability (so keeper / CLI-only roles
+    // can't be web-assigned), resolves the target actor, writes the idempotent
+    // grant, and emits a `role_grant_create` audit row — the same event the
+    // offer-accept and self-service paths emit. No WS notification in v1 (the
+    // grantee picks the capability up on its next authenticated request).
+    const assign_handler = async (input, ctx) => {
+        const auth = ctx.auth;
+        // Admin-grant-path gate — the same registry check the offer/revoke gates
+        // use; keeper / daemon-scoped roles stay CLI-only. Denial is
+        // forensic-audited (`role_grant_id` omitted — no grant was created).
+        if (!role_has_grant_path(role_specs, input.role, GRANT_PATH_ADMIN)) {
+            audit.emit_role_grant_target(ctx, auth, {
+                event_type: 'role_grant_create',
+                outcome: 'failure',
+                target_account_id: input.to_account_id,
+                target_actor_id: input.to_actor_id ?? null,
+                metadata: { role: input.role, scope_id: input.scope_id ?? null },
+            });
+            throw jsonrpc_errors.forbidden('role not web-grantable', {
+                reason: ERROR_ROLE_NOT_WEB_GRANTABLE,
+            });
+        }
+        // Resolve the grant's target actor. A supplied `to_actor_id` must be an
+        // active actor of `to_account_id`; otherwise the account's sole active
+        // actor is used (a multi-actor account must name one). A missing /
+        // actorless account 404-masks. Inlined (not a helper) so the
+        // actor-account-mismatch throw stays in the handler body the
+        // error_reasons drift scan reads.
+        const actors = await query_active_actors_by_account(ctx, input.to_account_id);
+        let target_actor_id;
+        if (input.to_actor_id != null) {
+            if (!actors.some((a) => a.id === input.to_actor_id)) {
+                throw jsonrpc_errors.invalid_params('to_actor_id does not belong to to_account_id', {
+                    reason: ERROR_ROLE_GRANT_OFFER_ACTOR_ACCOUNT_MISMATCH,
+                });
+            }
+            target_actor_id = input.to_actor_id;
+        }
+        else if (actors.length === 1) {
+            target_actor_id = actors[0].id;
+        }
+        else if (actors.length === 0) {
+            throw jsonrpc_errors.not_found('account');
+        }
+        else {
+            throw jsonrpc_errors.invalid_params('to_actor_id is required for a multi-actor account');
+        }
+        // Idempotent write — re-assigning an already-held grant returns the
+        // existing row. `scope_kind` stays null: `scope_id` alone is the v1
+        // discriminator. `granted_by` is the assigning admin.
+        const grant = await query_create_role_grant(ctx, {
+            actor_id: target_actor_id,
+            role: input.role,
+            scope_kind: null,
+            scope_id: input.scope_id ?? null,
+            granted_by: auth.actor.id,
+        });
+        audit.emit_role_grant_target(ctx, auth, {
+            event_type: 'role_grant_create',
+            target_account_id: input.to_account_id,
+            target_actor_id,
+            metadata: {
+                role: grant.role,
+                role_grant_id: grant.id,
+                scope_id: grant.scope_id,
+            },
+        });
+        return { ok: true, role_grant_id: grant.id };
+    };
     return [
         rpc_action(role_grant_offer_create_action_spec, create_handler),
         rpc_action(role_grant_offer_accept_action_spec, accept_handler),
@@ -472,5 +526,6 @@ export const create_role_grant_offer_actions = (deps, options = {}) => {
         rpc_action(role_grant_offer_list_action_spec, list_handler),
         rpc_action(role_grant_offer_history_action_spec, history_handler),
         rpc_action(role_grant_revoke_action_spec, revoke_handler),
+        rpc_action(role_grant_assign_action_spec, assign_handler),
     ];
 };

package/dist/testing/CLAUDE.md

@@ -1452,6 +1452,44 @@ The in-process counterparts already exist (`describe_rate_limiting_tests` plus t
 proxy middleware tests), so there's no in-process leg. `npm run test:cross:security`.
 Cited property: `docs/security.md` §"Rate Limiting" + §"Trusted Proxy / Client IP".
 
+### Role-gated participation parity — `cross_backend/role_grant_participation.ts`
+
+The role-gated-participation capstone — TS↔Rust agreement that an **app-defined
+role is conferred identically** on both spines. A `participant`
+(`grant_paths: ['admin']`) app-role is registered on both spines (`spine_roles`
+in `default_spine_surface.ts` + the Rust `testing_spine_stub`'s `RoleRegistry`
+and `known_roles`); the cross legs prove the three conferral properties agree.
+
+**Declarative-max, imperative-as-escape-hatch.** The single-request matrix is
+declarative (`conformance_participation_cases.ts`, run via
+`describe_conformance_table_tests`): **(a) grantability** —
+`role_grant_assign` of `participant` passes the admin-grant-path gate and dies
+_past_ it (404, nonexistent account) while a non-grantable role (`keeper`,
+unregistered) is refused _at_ it (403 `role_not_web_grantable`), and the
+`role_grant_offer_create` grant-path gate matches (403
+`role_grant_offer_role_not_grantable`); **(b) admin-only conferral** — a
+non-admin _holder_ of `participant` (and a fresh non-admin) can't offer it (403
+`role_grant_offer_not_authorized` — no holder-propagation); **(c)
+`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`).
+
+`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**
+`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`.
+
+Both legs run in-process (`conformance_participation.db.test.ts`, plain
+`gro test`) and cross-process (`conformance_participation.cross.test.ts`, TS
+node/deno/bun + Rust stub). Landing the TS `role_grant_assign` action also turned
+the `cross_backend_parity` action-manifest gate green (it was Rust-only before).
+Cited property: `docs/identity.md` + the role-gated-participation design
+(admin-only conferral, immediate assign).
+
 ### Building a TS test-server binary — `testing_server_core.ts` + adapters
 
 The reusable shape for standing up a **spawnable TS** cross-process test

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

@@ -36,11 +36,15 @@ import type { AppServerContext } from '../../server/app_server_context.js';
  */
 export declare const spine_session_options: SessionOptions<string>;
 /**
- * The spine's closed role registry: built-ins plus `SPINE_CELL_EDITOR_ROLE`.
- * Threaded into the cell spec set's role-validity gate; the Rust stub mirrors
- * the same membership. When the spine grows additional grantable roles,
- * thread their registry through `create_role_schema` here so the admin suite
- * picks up grant-path coverage.
+ * The spine's closed role registry: built-ins plus two app roles —
+ * `SPINE_CELL_EDITOR_ROLE` (no grant path; the role-shaped-`cell_grant`
+ * suite's bootstrap-seeded role) and `SPINE_PARTICIPANT_ROLE`
+ * (`grant_paths: ['admin']`; the role-gated-participation suite's
+ * admin-grantable role). Threaded into the cell spec set's role-validity gate
+ * **and** the auth grantability gates; the Rust stub mirrors the same
+ * membership in both its `RoleRegistry` and `known_roles`. The `participant`
+ * entry also gives the admin suite real app-role grant-path coverage
+ * (`admin_account_list.grantable_roles` carries it on both spines).
  */
 export declare const spine_roles: RoleSchemaResult;
 /** Options for {@link spine_rpc_endpoints}. */

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

@@ -1 +1 @@
-{"version":3,"file":"default_spine_surface.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_spine_surface.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAIpD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,8CAA8C,CAAC;AACrF,OAAO,EAAqB,KAAK,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAwB,KAAK,cAAc,EAAC,MAAM,8BAA8B,CAAC;AAIxF,OAAO,EAAqB,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAC,cAAc,EAAE,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,oCAAoC,CAAC;AAczE;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,MAAM,CAAwC,CAAC;AAElG;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,gBAExB,CAAC;AAEH,+CAA+C;AAC/C,MAAM,WAAW,wBAAwB;IACxC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACzD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,gBAAgB,EACrB,UAAU,wBAAwB,KAChC,KAAK,CAAC,eAAe,CAQvB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,KAAK,gBAAgB,KAAG,KAAK,CAAC,SAAS,CA+B/E,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,GAAI,MAAM,MAAM,KAAG,SAC6B,CAAC;AAE3F;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAO,cAM1C,CAAC"}
+{"version":3,"file":"default_spine_surface.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_spine_surface.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAIpD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,8CAA8C,CAAC;AACrF,OAAO,EAAqB,KAAK,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AAEpF,OAAO,EAAwB,KAAK,cAAc,EAAC,MAAM,8BAA8B,CAAC;AAIxF,OAAO,EAAqB,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAC,cAAc,EAAE,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,oCAAoC,CAAC;AAezE;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,MAAM,CAAwC,CAAC;AAElG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,EAAE,gBAGxB,CAAC;AAEH,+CAA+C;AAC/C,MAAM,WAAW,wBAAwB;IACxC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACzD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,gBAAgB,EACrB,UAAU,wBAAwB,KAChC,KAAK,CAAC,eAAe,CAQvB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,KAAK,gBAAgB,KAAG,KAAK,CAAC,SAAS,CA+B/E,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,GAAI,MAAM,MAAM,KAAG,SAC6B,CAAC;AAE3F;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAO,cAM1C,CAAC"}

package/dist/testing/cross_backend/default_spine_surface.js

@@ -2,6 +2,7 @@ import '../assert_dev_env.js';
 import { create_account_route_specs } from '../../auth/account_routes.js';
 import { create_audit_log_route_specs } from '../../auth/audit_log_routes.js';
 import { create_role_schema } from '../../auth/role_schema.js';
+import { GRANT_PATH_ADMIN } from '../../auth/grant_path_schema.js';
 import { create_session_config } from '../../auth/session_cookie.js';
 import { create_signup_route_specs } from '../../auth/signup_routes.js';
 import { create_standard_rpc_actions } from '../../auth/standard_rpc_actions.js';
@@ -13,21 +14,26 @@ import { create_test_app_surface_spec } from '../stubs.js';
 // without dragging this module's eager in-process route handlers
 // (→ `session_middleware` → `hono/cookie`). Import only the constants this
 // module uses internally; callers that need a bare constant reach for the leaf.
-import { SPINE_CELL_EDITOR_ROLE, SPINE_EXPECTED_SCHEMA_URL, SPINE_RPC_PATH, } from './spine_surface_constants.js';
+import { SPINE_CELL_EDITOR_ROLE, SPINE_EXPECTED_SCHEMA_URL, SPINE_PARTICIPANT_ROLE, SPINE_RPC_PATH, } from './spine_surface_constants.js';
 /**
  * Session config — cookie name matches the binary's issued session cookie
  * (`fuz_session`) so cookie-attribute assertions + jar extraction line up.
  */
 export const spine_session_options = create_session_config('fuz_session');
 /**
- * The spine's closed role registry: built-ins plus `SPINE_CELL_EDITOR_ROLE`.
- * Threaded into the cell spec set's role-validity gate; the Rust stub mirrors
- * the same membership. When the spine grows additional grantable roles,
- * thread their registry through `create_role_schema` here so the admin suite
- * picks up grant-path coverage.
+ * The spine's closed role registry: built-ins plus two app roles —
+ * `SPINE_CELL_EDITOR_ROLE` (no grant path; the role-shaped-`cell_grant`
+ * suite's bootstrap-seeded role) and `SPINE_PARTICIPANT_ROLE`
+ * (`grant_paths: ['admin']`; the role-gated-participation suite's
+ * admin-grantable role). Threaded into the cell spec set's role-validity gate
+ * **and** the auth grantability gates; the Rust stub mirrors the same
+ * membership in both its `RoleRegistry` and `known_roles`. The `participant`
+ * entry also gives the admin suite real app-role grant-path coverage
+ * (`admin_account_list.grantable_roles` carries it on both spines).
  */
 export const spine_roles = create_role_schema([
     { name: SPINE_CELL_EDITOR_ROLE, grant_paths: [] },
+    { name: SPINE_PARTICIPANT_ROLE, grant_paths: [GRANT_PATH_ADMIN] },
 ]);
 /**
  * Factory-form RPC endpoints over the per-test `ctx.deps`. `create_app_server`

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

@@ -0,0 +1,11 @@
+import '../assert_dev_env.js';
+import type { SetupTest } from './setup.js';
+/** Options for the role-gated-participation success-path parity suite. */
+export interface RoleGrantParticipationCrossTestOptions {
+    /** Per-test fixture producer (in-process or cross-process). */
+    readonly setup_test: SetupTest;
+    /** RPC endpoint path. Default `/api/rpc`. */
+    readonly rpc_path?: string;
+}
+export declare const describe_role_grant_participation_cross_tests: (options: RoleGrantParticipationCrossTestOptions) => void;
+//# sourceMappingURL=role_grant_participation.d.ts.map

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

@@ -0,0 +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,EAAC,SAAS,EAAC,MAAM,YAAY,CAAC;AAE1C,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,IA+EF,CAAC"}

package/dist/testing/cross_backend/role_grant_participation.js

@@ -0,0 +1,73 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-backend parity suite for **role-gated participation conferral — the
+ * success paths**. The imperative escape hatch beneath the declarative
+ * `conformance_participation_cases.ts`: the multi-step flows that need a real
+ * recipient account (so a static conformance row can't express them) — an
+ * admin assigns the `participant` app-role, and an admin offers it through the
+ * consent flow and the recipient accepts.
+ *
+ * Proves the two conferral *write* paths agree on both spines (TS spine binary
+ * + Rust `testing_spine_stub`):
+ *
+ * - **immediate assign** — `role_grant_assign` of the admin-grantable
+ *   `participant` role lands a grant and returns `{ok, role_grant_id}`;
+ *   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.
+ *
+ * The single-request gate/denial matrix (grantability refusal, admin-only
+ * conferral, dispatcher admin gate, auth) lives in the declarative table
+ * (`conformance_participation_cases.ts`) — keep new single-request assertions
+ * there; this suite is only for flows the table cannot carry.
+ *
+ * The `participant` role is registered admin-grantable on both spines
+ * (`spine_roles` / the Rust stub's `RoleRegistry`), so the suite is ungated;
+ * every spine mounts the standard RPC surface it drives.
+ *
+ * `$lib`-free by contract (relative specifiers only), like the sibling
+ * cross-backend suites.
+ *
+ * @module
+ */
+import { describe, test, assert } from 'vitest';
+import { rpc_call } from '../rpc_helpers.js';
+import { SPINE_PARTICIPANT_ROLE, SPINE_RPC_PATH } from './spine_surface_constants.js';
+export const describe_role_grant_participation_cross_tests = (options) => {
+    const { setup_test } = options;
+    const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
+    const rpc = (transport, method, params, headers) => rpc_call({ app: transport, path: rpc_path, method, params, headers });
+    describe('role-gated participation conferral (success paths)', () => {
+        test('admin assigns the participant app-role to a fresh account (idempotent)', async () => {
+            const fixture = await setup_test();
+            const recipient = await fixture.create_account({ username: 'participation_assignee' });
+            // The keeper holds ROLE_ADMIN (seeded via extra_keeper_roles), so it
+            // clears the dispatcher admin gate; `participant` is admin-grantable, so
+            // it clears the grant-path gate; the recipient is single-actor, so the
+            // target actor resolves without `to_actor_id`.
+            const first = await rpc(fixture.transport, 'role_grant_assign', { to_account_id: recipient.account.id, role: SPINE_PARTICIPANT_ROLE }, fixture.create_session_headers());
+            assert.ok(first.ok, `assign must succeed: ${JSON.stringify(first)}`);
+            const assigned = first.result;
+            assert.strictEqual(assigned.ok, true);
+            assert.ok(typeof assigned.role_grant_id === 'string' && assigned.role_grant_id.length > 0, 'assign returns the new role_grant id');
+            // Idempotent — re-assigning the active grant returns the existing id.
+            const second = await rpc(fixture.transport, 'role_grant_assign', { to_account_id: recipient.account.id, role: SPINE_PARTICIPANT_ROLE }, fixture.create_session_headers());
+            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 offers the participant app-role and the recipient accepts', async () => {
+            const fixture = await setup_test();
+            const recipient = await fixture.create_account({ username: 'participation_offeree' });
+            // Admin-only conferral via the consent flow: the keeper (admin) offers
+            // the app-role, proving the widened grant-path gate admits it through
+            // the offer path too.
+            const created = await rpc(fixture.transport, 'role_grant_offer_create', { to_account_id: recipient.account.id, role: SPINE_PARTICIPANT_ROLE }, fixture.create_session_headers());
+            assert.ok(created.ok, `offer create must succeed: ${JSON.stringify(created)}`);
+            const offer_id = created.result.offer.id;
+            // The recipient accepts → a role_grant lands.
+            const accepted = await rpc(fixture.fresh_transport(), 'role_grant_offer_accept', { offer_id }, recipient.create_session_headers());
+            assert.ok(accepted.ok, `accept must succeed: ${JSON.stringify(accepted)}`);
+            assert.ok(typeof accepted.result.role_grant_id === 'string', 'accept lands a role_grant for the app-role');
+        });
+    });
+};

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

@@ -32,6 +32,18 @@ export declare const SPINE_SSE_PATH = "/api/admin/audit/stream";
  * Rust `testing_spine_stub`'s `known_roles` (cross-language test contract).
  */
 export declare const SPINE_CELL_EDITOR_ROLE = "cell_editor";
+/**
+ * Admin-grantable app role the role-gated-participation cross suite exercises.
+ * Registered with `grant_paths: ['admin']` so it enters the admin grant flow —
+ * the cross-backend proof that an app-defined role is conferrable (offer /
+ * `role_grant_assign`) admin-only on **both** spines. Must match the
+ * `participant` entry in the Rust `testing_spine_stub`'s `RoleRegistry`
+ * **and** its `known_roles` (the registry feeds the cell vocabulary too) — a
+ * cross-language test contract. Distinct from `SPINE_CELL_EDITOR_ROLE`
+ * (no grant path): this one is the *grantable* role, that one is the
+ * bootstrap-seed-only cell role.
+ */
+export declare const SPINE_PARTICIPANT_ROLE = "participant";
 /**
  * Committed expected-schema fixture for the spine `/ready` deploy gate — the
  * column map a fresh full spine bootstrap (auth + cell + cell_history + fact)

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

@@ -1 +1 @@
-{"version":3,"file":"spine_surface_constants.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/spine_surface_constants.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;GAcG;AAEH,iEAAiE;AACjE,eAAO,MAAM,cAAc,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,4BAA4B,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,EAAE,GAAwD,CAAC"}
+{"version":3,"file":"spine_surface_constants.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/spine_surface_constants.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;GAcG;AAEH,iEAAiE;AACjE,eAAO,MAAM,cAAc,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,4BAA4B,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,EAAE,GAAwD,CAAC"}

package/dist/testing/cross_backend/spine_surface_constants.js

@@ -32,6 +32,18 @@ export const SPINE_SSE_PATH = '/api/admin/audit/stream';
  * Rust `testing_spine_stub`'s `known_roles` (cross-language test contract).
  */
 export const SPINE_CELL_EDITOR_ROLE = 'cell_editor';
+/**
+ * Admin-grantable app role the role-gated-participation cross suite exercises.
+ * Registered with `grant_paths: ['admin']` so it enters the admin grant flow —
+ * the cross-backend proof that an app-defined role is conferrable (offer /
+ * `role_grant_assign`) admin-only on **both** spines. Must match the
+ * `participant` entry in the Rust `testing_spine_stub`'s `RoleRegistry`
+ * **and** its `known_roles` (the registry feeds the cell vocabulary too) — a
+ * cross-language test contract. Distinct from `SPINE_CELL_EDITOR_ROLE`
+ * (no grant path): this one is the *grantable* role, that one is the
+ * bootstrap-seed-only cell role.
+ */
+export const SPINE_PARTICIPANT_ROLE = 'participant';
 /**
  * Committed expected-schema fixture for the spine `/ready` deploy gate — the
  * column map a fresh full spine bootstrap (auth + cell + cell_history + fact)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.101.1",
+  "version": "0.102.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",