@fuzdev/fuz_app 0.59.0 → 0.60.0

package/dist/actions/CLAUDE.md

@@ -464,7 +464,7 @@ persistence + rehydration by the consumer.
 wireable via `CreateAppBackendOptions.on_audit_event`. Mirrors the SSE
 guard in `realtime/sse_auth_guard.ts` but targets the WS transport.
 
-`WS_DISCONNECT_EVENT_TYPES` (ReadonlySet): `session_revoke`,
+`ws_disconnect_event_types` (ReadonlySet): `session_revoke`,
 `token_revoke`, `session_revoke_all`, `token_revoke_all`, `password_change`.
 `role_grant_revoke` is intentionally **omitted** — the WS transport does not
 track per-connection role requirements, so role-scoped disconnection would
@@ -484,7 +484,7 @@ caller close another user's socket by guessing a session hash or token id.
 
 `create_ws_logout_closer(transport, log)` is the sibling helper for
 user-initiated `logout` events — kept separate because
-`WS_DISCONNECT_EVENT_TYPES` deliberately omits `logout` (admin-initiated
+`ws_disconnect_event_types` deliberately omits `logout` (admin-initiated
 revocations use `session_revoke`, while `logout` is the user-initiated
 case). Compose the two on `on_audit_event`:
 
@@ -600,9 +600,9 @@ an action through its lifecycle.
 
 - `ActionExecutor` — `'frontend' | 'backend'`
 - `ActionEventStep` — `'initial' | 'parsed' | 'handling' | 'handled' | 'failed'`
-- `ACTION_EVENT_STEP_TRANSITIONS` — valid next-steps: `initial → parsed | failed`, `parsed → handling | failed`, `handling → handled | failed`, `handled`/`failed` terminal.
-- `ACTION_EVENT_PHASE_BY_KIND` — valid phases per kind (`request_response` has 6, `remote_notification` has 2, `local_call` has 1).
-- `ACTION_EVENT_PHASE_TRANSITIONS` — chained phases: `send_request → receive_response`; `receive_request → send_response`; everything else terminal.
+- `action_event_step_transitions` — valid next-steps: `initial → parsed | failed`, `parsed → handling | failed`, `handling → handled | failed`, `handled`/`failed` terminal.
+- `action_event_phase_by_kind` — valid phases per kind (`request_response` has 6, `remote_notification` has 2, `local_call` has 1).
+- `action_event_phase_transitions` — chained phases: `send_request → receive_response`; `receive_request → send_response`; everything else terminal.
 - `ActionEventEnvironment` — `{executor, lookup_action_handler, lookup_action_spec, log?}`. The ambient registry + handler resolver for an `ActionEvent`.
 
 ### `action_event_data.ts`

package/dist/actions/action_codegen.d.ts

@@ -182,7 +182,7 @@ export declare const generate_actions_api_method_signature: (spec: ActionSpecUni
 /** Discriminator for `generate_action_method_enums` — which method-set enums to emit. */
 export type ActionMethodEnumKind = 'all' | 'request_response' | 'remote_notification' | 'local_call' | 'frontend' | 'backend' | 'frontend_handled' | 'backend_handled' | 'broadcast';
 /** Default emit set — every enum kind. */
-export declare const ACTION_METHOD_ENUM_KINDS_ALL: ReadonlySet<ActionMethodEnumKind>;
+export declare const action_method_enum_kinds_all: ReadonlySet<ActionMethodEnumKind>;
 /**
  * Resolve a per-spec identifier qualifier with the standard default-vs-callback
  * dance. When `qualify_spec` is set, returns the caller's callback verbatim

package/dist/actions/action_codegen.js

@@ -416,7 +416,7 @@ ${lines}
 export type ${name} = z.infer<typeof ${name}>;`;
 };
 /** Default emit set — every enum kind. */
-export const ACTION_METHOD_ENUM_KINDS_ALL = new Set([
+export const action_method_enum_kinds_all = new Set([
     'all',
     'request_response',
     'remote_notification',
@@ -483,7 +483,7 @@ export const resolve_spec_qualifier = (imports, options) => {
  *   `cancel` in the emitted enums. Default `false`.
  */
 export const generate_action_method_enums = (specs, imports, options) => {
-    const emit = options?.emit ?? ACTION_METHOD_ENUM_KINDS_ALL;
+    const emit = options?.emit ?? action_method_enum_kinds_all;
     const filtered = filter_protocol_actions(specs, options?.include_protocol_actions);
     const registry = new ActionRegistry([...filtered]);
     const blocks = [];

package/dist/actions/action_event_helpers.d.ts

@@ -59,20 +59,20 @@ export declare const is_notification_send_with_parsed_input: <TMethod extends st
     input: unknown;
 };
 /**
- * Validate that a step transition is legal per `ACTION_EVENT_STEP_TRANSITIONS`.
+ * Validate that a step transition is legal per `action_event_step_transitions`.
  *
  * @throws Error if `from → to` is not a permitted transition
  */
 export declare const validate_step_transition: (from: ActionEventStep, to: ActionEventStep) => void;
 /**
  * Validate that `phase` is one of the phases allowed for `kind` per
- * `ACTION_EVENT_PHASE_BY_KIND`.
+ * `action_event_phase_by_kind`.
  *
  * @throws Error if `phase` is not valid for `kind`
  */
 export declare const validate_phase_for_kind: (kind: ActionKind, phase: ActionEventPhase) => void;
 /**
- * Validate that a phase chain is legal per `ACTION_EVENT_PHASE_TRANSITIONS`.
+ * Validate that a phase chain is legal per `action_event_phase_transitions`.
  *
  * @throws Error if `from → to` is not the permitted next phase (or `from` is terminal)
  */

package/dist/actions/action_event_helpers.js

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import { ACTION_EVENT_STEP_TRANSITIONS, ACTION_EVENT_PHASE_BY_KIND, ACTION_EVENT_PHASE_TRANSITIONS, } from './action_event_types.js';
+import { action_event_step_transitions, action_event_phase_by_kind, action_event_phase_transitions, } from './action_event_types.js';
 // Type guards for action kinds
 export const is_request_response = (data) => data.kind === 'request_response';
 export const is_remote_notification = (data) => data.kind === 'remote_notification';
@@ -28,33 +28,33 @@ export const is_failed = (data) => data.step === 'failed';
 export const is_send_request_with_parsed_input = (data) => is_send_request(data) && (data.step === 'parsed' || data.step === 'handling');
 export const is_notification_send_with_parsed_input = (data) => is_notification_send(data) && (data.step === 'parsed' || data.step === 'handling');
 /**
- * Validate that a step transition is legal per `ACTION_EVENT_STEP_TRANSITIONS`.
+ * Validate that a step transition is legal per `action_event_step_transitions`.
  *
  * @throws Error if `from → to` is not a permitted transition
  */
 export const validate_step_transition = (from, to) => {
-    if (!ACTION_EVENT_STEP_TRANSITIONS[from].includes(to)) {
+    if (!action_event_step_transitions[from].includes(to)) {
         throw new Error(`Invalid step transition from '${from}' to '${to}'`);
     }
 };
 /**
  * Validate that `phase` is one of the phases allowed for `kind` per
- * `ACTION_EVENT_PHASE_BY_KIND`.
+ * `action_event_phase_by_kind`.
  *
  * @throws Error if `phase` is not valid for `kind`
  */
 export const validate_phase_for_kind = (kind, phase) => {
-    if (!ACTION_EVENT_PHASE_BY_KIND[kind].includes(phase)) {
+    if (!action_event_phase_by_kind[kind].includes(phase)) {
         throw new Error(`Invalid phase '${phase}' for ${kind} action`);
     }
 };
 /**
- * Validate that a phase chain is legal per `ACTION_EVENT_PHASE_TRANSITIONS`.
+ * Validate that a phase chain is legal per `action_event_phase_transitions`.
  *
  * @throws Error if `from → to` is not the permitted next phase (or `from` is terminal)
  */
 export const validate_phase_transition = (from, to) => {
-    const expected = ACTION_EVENT_PHASE_TRANSITIONS[from];
+    const expected = action_event_phase_transitions[from];
     if (expected !== to) {
         throw new Error(`Invalid phase transition from '${from}' to '${to}'`);
     }
@@ -79,7 +79,7 @@ export const is_action_complete = (data) => {
     if (data.step !== 'handled')
         return false;
     // Check if in terminal phase
-    const next_phase = ACTION_EVENT_PHASE_TRANSITIONS[data.phase];
+    const next_phase = action_event_phase_transitions[data.phase];
     return next_phase === null;
 };
 export const create_initial_data = (kind, phase, method, executor, input) => ({

package/dist/actions/action_event_types.d.ts

@@ -19,9 +19,9 @@ export declare const ActionEventStep: z.ZodEnum<{
     failed: "failed";
 }>;
 export type ActionEventStep = z.infer<typeof ActionEventStep>;
-export declare const ACTION_EVENT_STEP_TRANSITIONS: Record<ActionEventStep, ReadonlyArray<ActionEventStep>>;
-export declare const ACTION_EVENT_PHASE_BY_KIND: Record<ActionKind, ReadonlyArray<ActionEventPhase>>;
-export declare const ACTION_EVENT_PHASE_TRANSITIONS: Record<ActionEventPhase, ActionEventPhase | null>;
+export declare const action_event_step_transitions: Record<ActionEventStep, ReadonlyArray<ActionEventStep>>;
+export declare const action_event_phase_by_kind: Record<ActionKind, ReadonlyArray<ActionEventPhase>>;
+export declare const action_event_phase_transitions: Record<ActionEventPhase, ActionEventPhase | null>;
 export interface ActionEventEnvironment {
     readonly executor: ActionExecutor;
     lookup_action_handler: (method: string, phase: ActionEventPhase) => ((event: any) => any) | undefined;

package/dist/actions/action_event_types.js

@@ -12,14 +12,14 @@ export const ActionEventStep = z.enum(['initial', 'parsed', 'handling', 'handled
 // value types on the object literal) without narrowing lookups to literal
 // tuple types — a `satisfies` shape forces every `X[k]` reader to widen
 // back to `ReadonlyArray<V>` themselves to call `.includes(...)`.
-export const ACTION_EVENT_STEP_TRANSITIONS = {
+export const action_event_step_transitions = {
     initial: ['parsed', 'failed'],
     parsed: ['handling', 'failed'],
     handling: ['handled', 'failed'],
     handled: [],
     failed: [],
 };
-export const ACTION_EVENT_PHASE_BY_KIND = {
+export const action_event_phase_by_kind = {
     request_response: [
         'send_request',
         'receive_request',
@@ -31,7 +31,7 @@ export const ACTION_EVENT_PHASE_BY_KIND = {
     remote_notification: ['send', 'receive'],
     local_call: ['execute'],
 };
-export const ACTION_EVENT_PHASE_TRANSITIONS = {
+export const action_event_phase_transitions = {
     send_request: 'receive_response',
     receive_request: 'send_response',
     send_response: null,

package/dist/actions/transports_ws_auth_guard.d.ts

@@ -36,7 +36,7 @@ export type AuditEventHandler = (event: AuditLogEvent) => void;
  * require either closing all sockets (too aggressive) or new tracking
  * (out of scope). Consumers that need it compose their own callback.
  */
-export declare const WS_DISCONNECT_EVENT_TYPES: ReadonlySet<string>;
+export declare const ws_disconnect_event_types: ReadonlySet<string>;
 /**
  * Create an audit event handler that closes WebSocket connections on auth changes.
  *
@@ -56,7 +56,7 @@ export declare const create_ws_auth_guard: (transport: BackendWebsocketTransport
  * user-initiated logout.
  *
  * Sibling helper to `create_ws_auth_guard` — kept separate because
- * `WS_DISCONNECT_EVENT_TYPES` deliberately omits `logout` (admin-initiated
+ * `ws_disconnect_event_types` deliberately omits `logout` (admin-initiated
  * revocations use `session_revoke`, while `logout` is the user-initiated
  * case). Three consumers (tx, undying, zzz) hand-rolled this same branch
  * before extraction.

package/dist/actions/transports_ws_auth_guard.js

@@ -23,7 +23,7 @@
  * require either closing all sockets (too aggressive) or new tracking
  * (out of scope). Consumers that need it compose their own callback.
  */
-export const WS_DISCONNECT_EVENT_TYPES = new Set([
+export const ws_disconnect_event_types = new Set([
     'session_revoke',
     'token_revoke',
     'session_revoke_all',
@@ -45,7 +45,7 @@ export const WS_DISCONNECT_EVENT_TYPES = new Set([
  */
 export const create_ws_auth_guard = (transport, log) => {
     return (event) => {
-        if (!WS_DISCONNECT_EVENT_TYPES.has(event.event_type))
+        if (!ws_disconnect_event_types.has(event.event_type))
             return;
         // Failed mutations carry attacker-controlled metadata — never act on them.
         if (event.outcome === 'failure')
@@ -90,7 +90,7 @@ export const create_ws_auth_guard = (transport, log) => {
  * user-initiated logout.
  *
  * Sibling helper to `create_ws_auth_guard` — kept separate because
- * `WS_DISCONNECT_EVENT_TYPES` deliberately omits `logout` (admin-initiated
+ * `ws_disconnect_event_types` deliberately omits `logout` (admin-initiated
  * revocations use `session_revoke`, while `logout` is the user-initiated
  * case). Three consumers (tx, undying, zzz) hand-rolled this same branch
  * before extraction.

package/dist/auth/CLAUDE.md

@@ -21,7 +21,7 @@ sections.
 | Module                 | Exports                                                                                                                                                                                                                                                                                   |
 | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `keyring.ts`           | `Keyring`, `create_keyring`, `validate_keyring`, `create_validated_keyring`, `ValidatedKeyringResult`                                                                                                                                                                                     |
-| `session_cookie.ts`    | `SessionOptions<T>`, `SessionCookieOptions`, `SESSION_COOKIE_OPTIONS`, `SESSION_AGE_MAX`, `SESSION_REFRESH_THRESHOLD_S`, `ParsedSession`, `ProcessSessionResult`, `parse_session`, `create_session_cookie_value`, `process_session_cookie`, `create_session_config`, `fuz_session_config` |
+| `session_cookie.ts`    | `SessionOptions<T>`, `SessionCookieOptions`, `session_cookie_options`, `SESSION_AGE_MAX`, `SESSION_REFRESH_THRESHOLD_S`, `ParsedSession`, `ProcessSessionResult`, `parse_session`, `create_session_cookie_value`, `process_session_cookie`, `create_session_config`, `fuz_session_config` |
 | `password.ts`          | `Password`, `PasswordProvided`, `PasswordHashDeps`, `PASSWORD_LENGTH_MIN` (12, OWASP), `PASSWORD_LENGTH_MAX` (300)                                                                                                                                                                        |
 | `password_argon2.ts`   | `hash_password`, `verify_password`, `verify_dummy`, `argon2_password_deps`                                                                                                                                                                                                                |
 | `api_token.ts`         | `API_TOKEN_PREFIX` (`secret_fuz_token_`), `hash_api_token`, `generate_api_token`                                                                                                                                                                                                          |
@@ -179,7 +179,7 @@ those three. Mirrors the open-registry pattern used for `RoleName` /
   constant is named `_API_TOKEN` (not `_BEARER`) so wire literal and
   the `api_token` storage table stay in lockstep.
 - `BUILTIN_CREDENTIAL_TYPES` const tuple, `BuiltinCredentialType` Zod
-  enum, `BUILTIN_CREDENTIAL_TYPE_META` admin-UI-facing descriptions.
+  enum, `builtin_credential_type_meta` admin-UI-facing descriptions.
 - `create_credential_type_schema(consumer_types?)`
   → `{CredentialType, credential_types: ReadonlyMap}`. Builtins always
   present; consumer collisions / regex failures / duplicates throw at
@@ -197,7 +197,7 @@ granted. Four builtins (`admin`, `self_service`, `system`, `bootstrap`).
 - `GRANT_PATH_ADMIN` / `_SELF_SERVICE` / `_SYSTEM` / `_BOOTSTRAP` —
   builtin literal constants.
 - `BUILTIN_GRANT_PATHS` const tuple, `BuiltinGrantPath` Zod enum,
-  `BUILTIN_GRANT_PATH_META` descriptions.
+  `builtin_grant_path_meta` descriptions.
 - `create_grant_path_schema(consumer_paths?)`
   → `{GrantPath, grant_paths: ReadonlyMap}`. Same construction-time
   guards as the credential-type schema. Pass the result into
@@ -224,7 +224,7 @@ against the corresponding open registries at construction time.
 - `ROLE_KEEPER = 'keeper'` — bootstrap-only via daemon token; `grant_paths: ['bootstrap']`,
   `required_credential_types: ['daemon_token']`.
 - `ROLE_ADMIN = 'admin'` — admin-grantable; `grant_paths: ['admin']`.
-- `BUILTIN_ROLES`, `BuiltinRole` (Zod enum), `BUILTIN_ROLE_SPECS_BY_NAME`
+- `BUILTIN_ROLES`, `BuiltinRole` (Zod enum), `builtin_role_specs_by_name`
   (`ReadonlyMap<string, RoleSpec>`) — not overridable by consumers.
 - `RoleSpec`: `{name, description?, required_credential_types?, applicable_scope_kinds?, grant_paths?}`
   — every cross-axis field is an open-registry string array. Empty
@@ -302,7 +302,7 @@ Zod enum; `AuditOutcome` is `'success' | 'failure'`.
 
 #### Metadata schemas
 
-- `AUDIT_METADATA_SCHEMAS` — per-type `z.looseObject`. Notable shapes:
+- `audit_metadata_schemas` — per-type `z.looseObject`. Notable shapes:
   - `role_grant_create` — `scope_id`, optional `role_grant_id` (failed grants
     omit — admin-grant-path denial never produces a row), optional
     `source_offer_id`, optional `self_service` (set by
@@ -376,7 +376,7 @@ Zod enum; `AuditOutcome` is `'success' | 'failure'`.
   without validation). Pass the result to `create_app_backend({audit_log_config})`
   — it gets captured inside the bound `AppDeps.audit` emitter, and every
   call to `audit.emit` validates against it (defaults to
-  `BUILTIN_AUDIT_LOG_CONFIG` when absent). `query_audit_log` still accepts
+  `builtin_audit_log_config` when absent). `query_audit_log` still accepts
   the trailing `config` positional arg for in-transaction emit sites that
   hold a transaction-scoped DB only. Builtin collisions and
   `AuditEventTypeName` format failures throw at construction. The DB
@@ -396,7 +396,7 @@ Zod enum; `AuditOutcome` is `'success' | 'failure'`.
   factory they track the same config, but a hand-rolled `AuditLogConfig`
   (or a cast escape) can fire both on a single emission. Sample via
   `get_*` getters; `reset_*` are test-only. `AUDIT_EVENT_TYPES`,
-  `AUDIT_METADATA_SCHEMAS`, `BUILTIN_AUDIT_LOG_CONFIG`, and the configs
+  `audit_metadata_schemas`, `builtin_audit_log_config`, and the configs
   returned by `create_audit_log_config` are `Object.freeze`'d to convert
   accidental mutation (bugs, test cross-contamination, cast escapes)
   into loud TypeErrors — not a security boundary.
@@ -470,7 +470,7 @@ exports: `RoleGrantOfferReceivedParams`, `_RetractedParams`, `_AcceptedParams`,
 `_DeclinedParams`, `_SupersedeParams`, `RoleGrantRevokeParams`. Notification
 builders: `build_role_grant_offer_received_notification(params)` etc.
 
-`ROLE_GRANT_OFFER_NOTIFICATION_SPECS: Array<EventSpec>` — pass to
+`role_grant_offer_notification_specs: Array<EventSpec>` — pass to
 `create_app_server`'s `event_specs` so the attack surface reflects them
 and DEV-mode `create_validated_broadcaster` catches payload drift.
 
@@ -521,6 +521,31 @@ account_id = ANY(...))` so `actor.id`s never round-trip back to the
   visibility). Returns `Array<AdminAccountEntryJson>`, sorted by
   `created_at`.
 
+### `actor_lookup_queries.ts`
+
+- `query_actors_by_ids(deps, ids) → Array<ActorLookupRow>` — batched
+  `actor` ⨝ `account` INNER JOIN, returns
+  `{id, username, display_name}` per resolved actor. Empty input
+  fast-paths to `[]`; hard-deleted (or cascade-orphaned) rows silently
+  drop. Row shape omits `account_id` — the join is control-plane, not
+  wire-visible. Caller bounds `ids.length` (the action spec enforces
+  `ACTOR_LOOKUP_IDS_MAX`); SQL does not.
+
+### `actor_search_queries.ts`
+
+- `query_actor_search(deps, {query, scope_ids?, limit}) → Array<ActorLookupRow>` —
+  case-insensitive LIKE-prefix on `actor.name`, backed by the
+  `idx_actor_name_lower` functional index in `auth_ddl.ts`. Returns the
+  same `{id, username, display_name}` row shape as `query_actors_by_ids`
+  so the labels arc stays uniform. LIKE wildcards (`%`, `_`, `\`) in
+  the user-supplied `query` are escaped before substitution so the
+  prefix-only contract is enforceable. When `scope_ids` is non-empty,
+  the result is filtered to actors holding an **active** role_grant
+  (`revoked_at IS NULL AND (expires_at IS NULL OR expires_at > NOW())`)
+  on one of the supplied scopes; `DISTINCT` collapses multi-grant
+  duplicates. When `scope_ids` is empty, no role_grant join — the handler
+  enforces admin for that path.
+
 ### `role_grant_queries.ts`
 
 - `query_create_role_grant` — idempotent; `ON CONFLICT` target and fallback
@@ -551,6 +576,12 @@ account_id = ANY(...))` so `actor.id`s never round-trip back to the
   that isn't the request actor (e.g., post-mutation verification, scripts,
   audit-time checks). For the request actor, prefer `has_scoped_role` /
   `has_any_scoped_role` on the in-memory `auth.role_grants` snapshot.
+- `query_account_has_global_role(deps, account_id, role)` — account-grain
+  sibling: does any actor on `account_id` hold an active **global**
+  (`scope_id IS NULL`) role_grant for `role`? For surfaces with
+  `auth: actor: 'none'` that don't load `auth.role_grants` and can't use
+  `has_scoped_role`. EXISTS over the `idx_role_grant_actor`-backed
+  subquery, stops at the first match.
 - `query_role_grant_find_account_id_for_role(deps, role)` — joins
   role_grant → actor → account, returns first match. Used by daemon token
   middleware to resolve the keeper account.
@@ -701,7 +732,7 @@ run'` if the seed somehow missed (defensive — migrations always seed).
 ### `audit_log_queries.ts`
 
 - `query_audit_log<T>(deps, input, config?)` — `config` defaults to
-  `BUILTIN_AUDIT_LOG_CONFIG`. Membership check runs against
+  `builtin_audit_log_config`. Membership check runs against
   `config.event_types`; metadata validation runs independently against
   `config.metadata_schemas[event_type]` when present. Mismatches and
   unknown types log + bump their counters (see schema section);
@@ -769,8 +800,8 @@ without rebuilding `AppDeps`.
 
 ### `migrations.ts`
 
-- `AUTH_MIGRATION_NAMESPACE = 'fuz_auth'`, `AUTH_MIGRATION_NS` (pre-composed), `RESERVED_MIGRATION_NAMESPACES: ReadonlyArray<string>` (membership list `create_app_backend` rejects on; consumer-discoverable instead of probing the runtime throw).
-- `AUTH_MIGRATIONS`:
+- `AUTH_MIGRATION_NAMESPACE = 'fuz_auth'`, `auth_migration_ns` (pre-composed), `reserved_migration_namespaces: ReadonlyArray<string>` (membership list `create_app_backend` rejects on; consumer-discoverable instead of probing the runtime throw).
+- `auth_migrations`:
   - **v0 `full_auth_schema`** — every table + index + seed for the v1
     identity system (account, actor, role_grant, auth_session, api_token,
     audit_log, bootstrap_lock, invite, app_settings). All
@@ -1253,7 +1284,7 @@ of paginated cross-account listings (`admin_account_list`,
 cross-account reads (`admin_session_list`, `invite_list`). The
 dispatcher's per-action hook (shared by HTTP RPC + WS) records every
 invocation regardless of outcome so successful probes consume budget.
-Default `DEFAULT_ACTION_ACCOUNT_RATE_LIMIT` is 1200/15min per actor —
+Default `default_action_account_rate_limit` is 1200/15min per actor —
 permissive enough for any human admin workflow, slow enough that
 scripted oracles surface in audit. Tighten downstream via
 `AppServerOptions.action_account_rate_limiter`.
@@ -1286,7 +1317,7 @@ self-service `account_actions.ts` surface):
 
 Closure state:
 
-- `grantable_roles` is derived once from `options.roles?.role_specs ?? BUILTIN_ROLE_SPECS_BY_NAME`
+- `grantable_roles` is derived once from `options.roles?.role_specs ?? builtin_role_specs_by_name`
   via `list_roles_with_grant_path(_, GRANT_PATH_ADMIN)` and closed over
   by the `admin_account_list` handler.
 - `options.app_settings` — when provided, captured by the
@@ -1430,7 +1461,7 @@ Options:
 
 - `roles?: RoleSchemaResult` — drives the admin-grant-path lookup
   (`role_has_grant_path(_, role, GRANT_PATH_ADMIN)`); defaults to
-  `BUILTIN_ROLE_SPECS_BY_NAME`.
+  `builtin_role_specs_by_name`.
 - `default_ttl_ms?: number` — applied to new offers (defaults to
   `ROLE_GRANT_OFFER_DEFAULT_TTL_MS`).
 - `authorize?: RoleGrantOfferCreateAuthorize` — custom policy for
@@ -1495,6 +1526,14 @@ and `create_frontend_rpc_client({specs})` wiring. Self-service role
 specs are not included (opt-in, app-specific `eligible_roles`) —
 spread `all_self_service_role_action_specs` separately when needed.
 
+### `all_action_spec_registries.ts` — walker-only registry-of-registries
+
+`all_fuz_auth_action_spec_registries` — walker/codegen entry for every
+fuz-auth action-spec bundle (`admin`, `role_grant_offer`, `account`,
+`self_service_role`, `actor_lookup`). Not a mounting surface; protocol
+specs are excluded. Iterated by `../../test/auth/action_spec_input_invariants.test.ts`
+and `../../test/auth/all_action_spec_registries.acting_biconditional.test.ts`.
+
 ### `account_action_specs.ts` + `account_actions.ts` — seven self-service RPC actions
 
 Counterpart to `account_routes.ts`. Cookie-lifecycle flows (`login`,
@@ -1583,7 +1622,7 @@ codegen invariant and grow the surface linearly per role.
 
 - `eligible_roles?: ReadonlyArray<string>` — optional override
   allowlist. When omitted, eligibility is derived from
-  `roles.role_specs` (or `BUILTIN_ROLE_SPECS_BY_NAME` when `roles` is
+  `roles.role_specs` (or `builtin_role_specs_by_name` when `roles` is
   also omitted) by selecting every role whose `RoleSpec.grant_paths`
   includes `'self_service'` (`GRANT_PATH_SELF_SERVICE`). Roles outside
   the eligible set are rejected with `forbidden` + reason
@@ -1610,6 +1649,109 @@ Deps: `Pick<RouteFactoryDeps, 'log' | 'audit'>`.
 `all_self_service_role_action_specs: ReadonlyArray<RequestResponseActionSpec>` —
 codegen-ready registry of the single unified spec.
 
+### `actor_lookup_action_specs.ts` + `actor_lookup_actions.ts` — opt-in batched actor → label resolver
+
+One static `request_response` action — `actor_lookup({ids}) → {actors:
+[{id, username, display_name?}]}` — powers the labels arc for surfaces
+that stamp an actor id (bylines, owner columns, grantor labels, audit
+"by" cells). One round trip resolves a batch to display strings;
+`ACTOR_LOOKUP_IDS_MAX = 50` cap per call.
+
+**Auth + rate-limit posture.** `{account: 'required', actor: 'none'}` +
+`rate_limit: 'account'`. Account-grain — the caller need only be signed
+in; resolution skips the actor phase. The auth gate + per-account rate
+limit + per-call cap bound the batched username-enumeration surface that
+a `cell_list` ↔ `actor_lookup` pair would otherwise present. Don't loosen
+to public — a public-surface byline should resolve via SSR-stamped labels
+or per-cell embedded actor labels, not by widening this gate.
+
+**Wire shape — info-leak audit.** Deliberately omitted from
+`ActorLookupEntryJson`:
+
+- `account_id` — the actor↔account join is a control-plane detail.
+- `email`, password/credential fields — never queried.
+- `created_at` / `updated_at` — timing-oracle avoidance.
+- role / role_grants / session state — separation of concern.
+
+`display_name` is omitted (not `null`) when `actor.name` is blank, so
+clients see `undefined` rather than a sentinel string. Unknown ids are
+silently absent — by construction this is an existence-oracle (caller
+diffs response ids against request ids), bounded by rate-limit, the
+50-id cap, actor-uuid intractability (122-bit random), and the
+hard-delete-cascade indistinguishability from never-existed (no
+tombstone oracle). Response order is unspecified — callers index by
+`id` when needed.
+
+`create_actor_lookup_actions(deps)` — `deps:
+Pick<RouteFactoryDeps, 'log'>`. Pure read; no audit, no side effects.
+Backed by `query_actors_by_ids` (see Queries §
+[`actor_lookup_queries.ts`](#actor_lookup_queriests)).
+
+Bundle is **not** included in `create_standard_rpc_actions` — consumers
+without a byline surface can skip it. Spread
+`all_actor_lookup_action_specs` alongside the standard bundle when the
+labels arc is needed.
+
+### `actor_search_action_specs.ts` + `actor_search_actions.ts` — opt-in prefix-search picker
+
+One static `request_response` action — `actor_search({query, scope_ids?, limit?}) → {actors: [{id, username, display_name?}]}` —
+powers person-target pickers. Sibling to `actor_lookup`: that resolves a
+batch of known ids to labels; this resolves a partial name to candidate
+actors. Reuses `ActorLookupEntryJson` from
+`./actor_lookup_action_specs.ts` so the labels arc on the consumer side
+stays uniform. Default limit `ACTOR_SEARCH_LIMIT_DEFAULT = 20`, hard cap
+`ACTOR_SEARCH_LIMIT_MAX = 50`. Query string capped at
+`ACTOR_SEARCH_QUERY_LENGTH_MAX = 50`.
+
+**Auth + rate-limit posture.** `{account: 'required', actor: 'none'}` +
+`rate_limit: 'account'`. Same shape as `actor_lookup`. The handler
+additionally requires the caller to be admin when `scope_ids` is empty —
+unbounded global search is the admin-only arm; non-admin callers must
+always pass at least one scope_id and get filtered to actors with active
+role_grants on those scopes. The admin check is **account-grain** (any
+actor on the caller's account holds a global `admin` role_grant) via
+`query_account_has_global_role` — the `actor: 'none'` posture means
+`auth.role_grants` is empty and the in-memory `has_scoped_role` helper
+doesn't apply.
+
+**Caller-passes-scope_ids design.** `scope_ids` is trusted as a filter,
+not as an authority claim — the SQL filters to actors with role_grants on
+those scopes regardless of whether the caller has authority over them.
+Consumers (e.g. visiones' `CellGrantsEditor.svelte`) pre-filter
+`scope_ids` against their own authority (the teacher-predicate stays in
+the consumer layer, not in fuz_app). This does **not** widen the
+scope-existence oracle: an attacker passing a random scope_id never
+learns the scope existed if no member happens to match the query, and
+even on a match the result row only carries the matching actor — never
+"which scope matched".
+
+**Wire shape — additional info-leak posture beyond `actor_lookup`'s.**
+
+- Prefix match (`LOWER(name) LIKE LOWER(query) || '%' ESCAPE '\\'`),
+  **not** full `%query%`. LIKE wildcards in the user-supplied query are
+  escaped at the JS layer so a `%xyz` input can't widen to full LIKE
+  and defeat the per-call cap.
+- Empty result set on no-match — fail-soft like `cell_list`. No "no
+  actor matches" error that would leak an existence boundary on the
+  search-term axis.
+- Hard-deleted actors silently drop (same `account_id` cascade as
+  `actor_lookup`).
+
+Reason constant exported for failed-arm matching: `ERROR_ACTOR_SEARCH_SCOPE_REQUIRED`
+(`'actor_search_scope_required'`) — fired with `invalid_params` when a
+non-admin caller omits `scope_ids` or passes `[]`. Surfaced on
+`spec.error_reasons` so codegen + form-state matching can read it
+declaratively.
+
+`create_actor_search_actions(deps)` — `deps:
+Pick<RouteFactoryDeps, 'log'>`. Pure read; no audit, no side effects.
+Backed by `query_actor_search` (see Queries §`actor_search_queries.ts`).
+
+Bundle is **not** included in `create_standard_rpc_actions` — consumers
+without a person-target picker can skip it. Spread
+`all_actor_search_action_specs` alongside the standard bundle when the
+picker is needed.
+
 ## Cleanup
 
 `cleanup.ts` — periodic auth maintenance:

package/dist/auth/actor_lookup_action_specs.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `actor_lookup` RPC spec — authenticated batched id → username/display_name
+ * resolver, keyed by actor id.
+ *
+ * Powers the labels arc for surfaces that stamp an actor id (bylines,
+ * owner columns, grantor labels, audit-log "by" cells). One round trip
+ * resolves an array of ids to display strings.
+ *
+ * ## Auth + rate-limit posture
+ *
+ * `{account: 'required', actor: 'none'}` + `rate_limit: 'account'`.
+ * Account-grain — only that the caller is signed in matters, not which
+ * actor is calling, so resolution skips the actor phase. The auth gate
+ * + per-account rate limit (default 1200/15min) + the
+ * {@link ACTOR_LOOKUP_IDS_MAX | per-call cap} bound the batched
+ * username-enumeration surface that the `cell_list` ↔ `actor_lookup`
+ * pair would otherwise present.
+ *
+ * If a public-surface byline ever lands (e.g. an unauthenticated
+ * gallery), it should resolve via a separate public-safe mechanism
+ * (SSR-stamped labels or a per-cell embedded actor label), **not** by
+ * loosening this gate.
+ *
+ * ## Wire shape — info-leak audit
+ *
+ * Output: `{actors: [{id, username, display_name?}]}`. Deliberately
+ * omitted:
+ *
+ * - `account_id` — the actor↔account join is a control-plane detail
+ * - `email`, password/credential fields — never queried
+ * - `created_at` / `updated_at` — timing-oracle avoidance
+ * - role / role_grants / session state — separation of concern
+ *
+ * `display_name` is omitted (not `null`) when `actor.name` is blank, so
+ * clients see `undefined` rather than a sentinel string. Unknown ids are
+ * silently absent from the response — by construction this is an
+ * existence-oracle (the caller can diff response ids against request
+ * ids), bounded by:
+ *
+ * 1. rate-limit (per-account, see above),
+ * 2. {@link ACTOR_LOOKUP_IDS_MAX} cap per call,
+ * 3. actor-uuid intractability (122-bit random),
+ * 4. hard-deleted actors are indistinguishable from never-existed (no
+ *    tombstone oracle — see `actor_lookup_queries.ts`).
+ *
+ * Response order is unspecified — callers index by `id` when needed.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Hard cap on the number of ids resolvable in one call. Bounds the
+ * batched username-enumeration surface.
+ */
+export declare const ACTOR_LOOKUP_IDS_MAX = 50;
+/** One resolved actor row. `display_name` omitted when blank. */
+export declare const ActorLookupEntryJson: z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    username: z.ZodString;
+    display_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ActorLookupEntryJson = z.infer<typeof ActorLookupEntryJson>;
+export declare const ActorLookupInput: z.ZodObject<{
+    ids: z.ZodArray<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+}, z.core.$strict>;
+export type ActorLookupInput = z.infer<typeof ActorLookupInput>;
+export declare const ActorLookupOutput: z.ZodObject<{
+    actors: z.ZodArray<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        username: z.ZodString;
+        display_name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ActorLookupOutput = z.infer<typeof ActorLookupOutput>;
+export declare const actor_lookup_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "none";
+    };
+    side_effects: false;
+    input: z.ZodObject<{
+        ids: z.ZodArray<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        actors: z.ZodArray<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            username: z.ZodString;
+            display_name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    async: true;
+    rate_limit: "account";
+    description: string;
+};
+/**
+ * All actor_lookup action specs — independent opt-in registry. Consumers
+ * spread alongside `all_standard_action_specs` if they want the labels
+ * arc; not folded into the standard bundle because consumers without a
+ * byline surface can skip it.
+ */
+export declare const all_actor_lookup_action_specs: readonly [{
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "none";
+    };
+    side_effects: false;
+    input: z.ZodObject<{
+        ids: z.ZodArray<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        actors: z.ZodArray<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            username: z.ZodString;
+            display_name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    async: true;
+    rate_limit: "account";
+    description: string;
+}];
+//# sourceMappingURL=actor_lookup_action_specs.d.ts.map