@jini-ai/user-management 0.3.0 → 0.3.1

package/dist/react/users/hooks/use-users.hooks.js

@@ -1,9 +1,31 @@
-import { interpolate } from "@jini-ai/ui/panel-kit";
 import { useEffect, useRef, useState } from "react";
-import {} from "../../models.js";
+import { interpolate } from "@jini-ai/ui/panel-kit";
 import { useFetchMutation, useFetchQuery } from "@jini-ai/ui/panel-kit";
 import { useAsyncAction } from "@jini-ai/ui/panel-kit";
-import { describeApiError as describeFeatureError, KEYS } from "../rules.js";
+import { describeApiError, KEYS, isOwnerAccount, userAccountCapabilities } from "../rules.js";
+/** The shape `onAssignRole`/`onAttachPolicy` both repeat: set the shared `grantSaving`/`grantError`
+ *  pair, run one mutation, do a success-only side effect, and clear saving in a `finally` — the
+ *  "whole-hook" complexity view (brief §2) rolls every closure inside a hook into one score, so two
+ *  near-identical blocks count against `useUsers` even though `grantError`/`grantSaving` are
+ *  deliberately NOT a fit for `useAsyncAction` (see that file's own header: shared across three
+ *  handlers on purpose, not one action's own slot — `onSaveEmail` is the third, kept separate below
+ *  since it tracks its OWN `emailSaving`). Reproducing the shared-state shape as a local top-level
+ *  helper — rather than importing the generic primitive — collapses the two call sites without
+ *  forcing that mismatch onto them. `mutate` itself `invalidates: [KEYS.list]`, replacing the
+ *  pre-migration `reload()` call this helper used to make explicitly.
+ *
+ *  `onSuccess` (2026-09-05 fix, same bug class as `use-roles.hooks.ts`'s `onSaveRole`/
+ *  `onWritePermission`): nothing gates opening a DIFFERENT user's Manage panel
+ *  (`toggleExpanded`) while a grant for the previously expanded one is still in flight, and
+ *  `onSuccess` clears `pendingRoleId`/`pendingPolicyId` — a shared field, not keyed by principal.
+ *  `toggleGenerationRef` (bumped once per `toggleExpanded` call, regardless of which panel — see
+ *  that function) lets a stale grant tell whether the operator switched panels at ALL while it was
+ *  in flight, independent of which principal is currently expanded: comparing against the panel's
+ *  OWN identity would wrongly refuse a grant issued before any panel was ever expanded (a
+ *  legitimate, already-certified call shape), where `expandedId` never gets set to begin with.
+ *  `onSuccess` is skipped only when a switch actually happened since this call started — otherwise
+ *  a stale grant's success would erase a NEW, unrelated selection the operator has since made for
+ *  the panel they actually have open now. */
 async function runGrantMutation(generationAtStart, toggleGenerationRef, mutate, onSuccess, setGrantSaving, setGrantError, describeError) {
     setGrantSaving(true);
     setGrantError(null);
@@ -13,30 +35,69 @@ async function runGrantMutation(generationAtStart, toggleGenerationRef, mutate,
             onSuccess();
     }
     catch (e) {
+        // Same generation check as the success branch above (C8, plan-access.md §8, N3): a stale
+        // failure must not paint onto a DIFFERENT user's panel the operator has since opened.
         if (toggleGenerationRef.current === generationAtStart)
             setGrantError(describeError(e));
     }
     finally {
+        // Guarded the same way — a stale call's `finally` must not clear a NEWER call's own saving
+        // flag. `toggleExpanded` resets `grantSaving` itself when it bumps the generation, so a panel
+        // switch still leaves the new panel un-stuck even though this skip means THIS call no longer
+        // clears it.
         if (toggleGenerationRef.current === generationAtStart)
             setGrantSaving(false);
     }
 }
-export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset = false, onOwnPasswordResetClosed } = {}) {
-    const describeApiError = (error, fallback) => describeFeatureError({ error, fallback, translate });
-    const t = translate;
+/**
+ * Roles and policies for the grant controls, or `null` when the server refuses them with 403 (the
+ * caller lacks `role.manage`). Any other failure still rejects, so a real outage keeps surfacing as
+ * the screen's load error.
+ *
+ * @complexity O(1) requests (two, concurrent).
+ */
+async function loadGrantOptions(port) {
+    try {
+        const [r, p] = await Promise.all([port.listRoles({}), port.listPolicies({})]);
+        return { roles: r.roles, policies: p.policies };
+    }
+    catch (e) {
+        if (e && typeof e === "object" && "status" in e && e.status === 403)
+            return null;
+        throw e;
+    }
+}
+/**
+ * Everything the Users screen does — full state, effects, and every server write, as one hook so
+ * `Users.tsx` stays a pure render of whatever this returns. See this file's header for the
+ * `useFetchQuery`/`useFetchMutation` migration and the `port` injection it now also carries.
+ *
+ * @param deps - Injected collaborators; production callers get these from {@link useWiredUsers}.
+ * @returns The full `UsersController` the view renders from — see that interface for every field.
+ */
+export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset = false, onOwnPasswordResetClosed, passwordResetNotice, } = {}) {
     const boundT = translate;
+    const describeError = (error, fallback) => describeApiError({ error, fallback, translate });
+    // `portRef` (password-banner plan, 2026-09-24 Slice 3 deep-link half): captured once at mount and
+    // never written again, same discipline and same reasoning as `use-assistant-chats.hooks.ts`'s own
+    // `portRef` — the one-shot `me()` effect below must not spin if a caller builds a fresh port object
+    // per render (the host admin guidance's "Two traps" section). Every OTHER `port.xxx()` call in this
+    // file stays a direct closure read, unaffected — this ref exists only for the raw `useEffect` below,
+    // which is not a `useFetchQuery`/`useFetchMutation` closure and so does not get that discipline for
+    // free.
     const portRef = useRef(port);
     const list = useFetchQuery({
         key: [queryScope, ...KEYS.list],
         fetch: async () => {
-            const [u, r, p] = await Promise.all([port.listUsers({}), port.listRoles({}), port.listPolicies({})]);
-            return { users: u.users, roles: r.roles, policies: p.policies };
+            const [u, grantOptions] = await Promise.all([port.listUsers({}), loadGrantOptions(port)]);
+            return { users: u.users, grantOptions };
         },
     });
     const users = list.data?.users ?? null;
-    const roles = list.data?.roles ?? null;
-    const policies = list.data?.policies ?? null;
-    const error = list.error ? describeApiError(list.error, t("failed to load users")) : null;
+    const roles = list.data ? (list.data.grantOptions?.roles ?? []) : null;
+    const policies = list.data ? (list.data.grantOptions?.policies ?? []) : null;
+    const canGrant = list.data?.grantOptions != null;
+    const error = list.error ? describeError(list.error, translate("failed to load users")) : null;
     const [formOpen, setFormOpen] = useState(false);
     const [username, setUsername] = useState("");
     const [email, setEmail] = useState("");
@@ -48,6 +109,10 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
         invalidates: [[queryScope, ...KEYS.list]],
     });
     const [expandedId, setExpandedId] = useState(null);
+    // Bumped once per `toggleExpanded` call, regardless of which panel — `runGrantMutation` (a
+    // top-level function, outside this closure's re-render cycle) reads this to tell whether the
+    // operator switched panels AT ALL while its own grant was in flight. See that function's own doc
+    // comment for why this counts switches rather than comparing against `expandedId`'s value.
     const toggleGenerationRef = useRef(0);
     const [pendingRoleId, setPendingRoleId] = useState("");
     const [pendingPolicyId, setPendingPolicyId] = useState("");
@@ -77,11 +142,30 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
     }, {
         invalidates: [[queryScope, ...KEYS.list]],
     });
+    // Disable now confirms via a `RowMenu` item -> `ConfirmDialog` modal (replacing the in-place
+    // two-click `ConfirmButton`, which has no menu-item equivalent — same migration Posts.tsx/
+    // Redirects.tsx already made). `null` when the dialog is closed.
     const [confirmingDisable, setConfirmingDisable] = useState(null);
+    // Reset password moved out of the expanded "Manage" panel into its own `RowMenu` item, which
+    // opens this dialog (it needs a text field, so it's a `ConfirmDialog` with an input in the body,
+    // not a plain confirm). Kept open on failure (unlike the delete-style dialogs above, which close
+    // either way) so a failed attempt doesn't discard the password the operator just typed.
     const [resetPasswordFor, setResetPasswordFor] = useState(null);
     const [newPassword, setNewPassword] = useState("");
     const resetPassword = useAsyncAction();
+    /** The signed-in caller's own principal id (password-banner plan, 2026-09-24 Slice 3), from
+     *  `port.me()`. `null` until that call settles, or forever if it fails — both are treated as
+     *  "unknown", which the deep-link effect below and `confirmResetPassword`'s notice branch both
+     *  already handle as "not a self-reset".
+     *
+     *  Fetched unconditionally (not gated on `openOwnPasswordReset`) — a deliberate choice, not an
+     *  oversight: it makes the "sign in again" notice below correct for ANY self-reset, including an
+     *  admin resetting their OWN row from the ordinary row-menu (no deep link involved), not just the
+     *  one opened via `/users/change-password`. One extra `me()` call per screen load is cheaper than
+     *  threading two different notice code paths for what is, to the operator, the same event. */
     const [ownPrincipalId, setOwnPrincipalId] = useState(null);
+    // `canManageUserTrash` (delete-user plan v2, Slice 4): resolved by this SAME one-shot `me()` call
+    // rather than a second request — see `UsersController.canManageUserTrash`'s own doc comment.
     const [canManageUserTrash, setCanManageUserTrash] = useState(false);
     useEffect(() => {
         let cancelled = false;
@@ -94,12 +178,32 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
             }
         })
             .catch(() => {
+            // Best-effort, see `ownPrincipalId`'s own doc comment above — a failure just means the
+            // deep link can't auto-open and self-resets fall back to the per-username notice.
+            // `canManageUserTrash` stays `false`, the same "unknown means no affordance" default.
         });
         return () => {
             cancelled = true;
         };
     }, []);
+    /** Guards the one-shot deep-link auto-open effect below so it fires at most once per mount, even
+     *  as `users`/`ownPrincipalId` keep changing identity across the renders it's waiting on (list
+     *  reloads, `me()` settling). Separate from {@link openedViaDeepLinkRef}, which tracks a DIFFERENT
+     *  question ("should closing the dialog navigate away") over the dialog's own open/close lifetime
+     *  — this one is "has the auto-open already been attempted", which must stay true forever once it
+     *  fires, including after the dialog this effect opened has since been closed. */
+    function rowCapabilities(user) {
+        const roleMap = new Map((roles ?? []).map(role => [role.id, role]));
+        const ownRow = users?.find(row => row.principalId === ownPrincipalId);
+        return userAccountCapabilities({ user, callerPrincipalId: ownPrincipalId,
+            callerIsOwner: ownRow ? isOwnerAccount({ user: ownRow, roles: roleMap }) : false,
+            canManageUserTrash, roles: roleMap });
+    }
     const deepLinkAttemptedRef = useRef(false);
+    /** Set true exactly when this effect opens the dialog, cleared by the close-effect below the first
+     *  time it observes `resetPasswordFor` go back to `null`. Read there to decide whether to navigate
+     *  — an operator resetting a DIFFERENT row's password from the ordinary row menu, or cancelling a
+     *  normal reset, must not also get shoved to `/users`. */
     const openedViaDeepLinkRef = useRef(false);
     useEffect(() => {
         if (!openOwnPasswordReset || deepLinkAttemptedRef.current)
@@ -119,6 +223,8 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
         openedViaDeepLinkRef.current = false;
         onOwnPasswordResetClosed?.();
     }, [resetPasswordFor, onOwnPasswordResetClosed]);
+    // No `invalidates` — matches the pre-migration `confirmResetPassword`, which never called
+    // `reload()` either (a password reset changes nothing the users table shows).
     const resetPasswordMutation = useFetchMutation({
         run: ({ input }) => port.resetUserPassword(input),
     });
@@ -130,10 +236,13 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
                 setEmail("");
                 setPassword("");
                 setFormOpen(false);
-            }, describeError: (e) => describeApiError(e, t("failed to create user")) });
+            }, describeError: (e) => describeError(e, translate("failed to create user")) });
     }
     function toggleExpanded(user) {
         setGrantError(null);
+        // A still-in-flight grant for the panel being LEFT can no longer clear this itself
+        // (`runGrantMutation`'s `finally` now skips a stale call's own generation) — reset it here so
+        // the newly opened panel never inherits a stuck "saving" indicator from the old one.
         setGrantSaving(false);
         setPendingRoleId("");
         setPendingPolicyId("");
@@ -144,24 +253,35 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
     async function onAssignRole({ principalId }) {
         if (!pendingRoleId)
             return;
-        await runGrantMutation(toggleGenerationRef.current, toggleGenerationRef, () => assignRoleMutation.mutate({ input: { principalId, roleId: pendingRoleId } }), () => setPendingRoleId(""), setGrantSaving, setGrantError, (e) => describeApiError(e, t("failed to assign role")));
+        await runGrantMutation(toggleGenerationRef.current, toggleGenerationRef, () => assignRoleMutation.mutate({ input: { principalId, roleId: pendingRoleId } }), () => setPendingRoleId(""), setGrantSaving, setGrantError, (e) => describeError(e, translate("failed to assign role")));
     }
     async function onAttachPolicy({ principalId }) {
         if (!pendingPolicyId)
             return;
-        await runGrantMutation(toggleGenerationRef.current, toggleGenerationRef, () => attachPolicyMutation.mutate({ input: { principalId, policyId: pendingPolicyId } }), () => setPendingPolicyId(""), setGrantSaving, setGrantError, (e) => describeApiError(e, t("failed to attach policy")));
+        await runGrantMutation(toggleGenerationRef.current, toggleGenerationRef, () => attachPolicyMutation.mutate({ input: { principalId, policyId: pendingPolicyId } }), () => setPendingPolicyId(""), setGrantSaving, setGrantError, (e) => describeError(e, translate("failed to attach policy")));
     }
+    // `onSaveEmail` was left out of the `runGrantMutation` fold above on purpose: it tracks its OWN
+    // `emailSaving` flag rather than the shared `grantSaving` `onAssignRole`/`onAttachPolicy` use, so
+    // routing it through the same helper would mean passing a no-op in place of `setGrantSaving` —
+    // extraction for the sake of a shared call site, not a shared shape. Left hand-rolled; `emailSaving`
+    // now derives from `updateEmailMutation.status` since (unlike `grantSaving`) it was already this
+    // one mutation's own dedicated flag.
     async function onSaveEmail({ principalId }) {
         setGrantError(null);
         try {
             await updateEmailMutation.mutate({ input: { principalId, email: editEmail } });
         }
         catch (e) {
-            setGrantError(describeApiError(e, t("failed to update email")));
+            setGrantError(describeError(e, translate("failed to update email")));
         }
     }
     const emailSaving = updateEmailMutation.status === "pending";
+    /** Opens the reset-password dialog for `user` — the `RowMenu` item's `onSelect`. Guards against
+     *  opening a second one while a toggle or a previous reset is still in flight, same discipline
+     *  Redirects.tsx uses for its own `RowMenu` items (no per-item `disabled` on `RowMenu` itself). */
     function openResetPassword(user) {
+        if (!rowCapabilities(user).canResetPassword)
+            return;
         if (toggleSavingId || resetPassword.saving)
             return;
         resetPassword.setError(null);
@@ -169,34 +289,69 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
         setResetPasswordFor(user);
     }
     async function confirmResetPassword() {
-        if (!resetPasswordFor || !newPassword)
+        if (!resetPasswordFor || !newPassword || !rowCapabilities(resetPasswordFor).canResetPassword)
             return;
+        // Dialog stays open on failure (unlike the Disable/Delete-style dialogs elsewhere in this app,
+        // which close either way) — closing would discard the password the operator just typed for no
+        // reason; there's nothing sensitive left on screen once they retry or cancel. `resetPasswordFor`/
+        // `newPassword` are therefore only cleared in the success path below, never as a `finally`.
         await resetPassword.run({ action: async () => {
                 await resetPasswordMutation.mutate({ input: { principalId: resetPasswordFor.principalId, password: newPassword } });
+                // A self-reset (own row, deep-linked or from the ordinary row menu — see `ownPrincipalId`'s
+                // own doc comment) gets the "sign in again" notice instead of the per-username one: the reset
+                // just revoked the CALLER'S OWN session, so the next request 401s and `App.hooks.tsx` sends
+                // them to the login screen — the generic notice naming a DIFFERENT user would be misleading
+                // here, since it's actually their own sign-in that just ended.
                 setNotice(resetPasswordFor.principalId === ownPrincipalId
-                    ? t("Password changed. Sign in again with your new password.")
-                    : interpolate({ template: t('Password reset for "{username}" — every active session for this user was revoked.'), vars: { username: resetPasswordFor.username } }));
+                    ? translate("Password changed. Sign in again with your new password.")
+                    : passwordResetNotice?.({ username: resetPasswordFor.username }) ?? interpolate({
+                        template: translate('Password reset for "{username}" — every active session for this user was revoked.'),
+                        vars: { username: resetPasswordFor.username },
+                    }));
                 setResetPasswordFor(null);
                 setNewPassword("");
-            }, describeError: (e) => describeApiError(e, t("failed to reset password")) });
+            }, describeError: (e) => describeError(e, translate("failed to reset password")) });
     }
+    /** `setToggleSavingId`'s `finally` reset (2026-09-05 fix, same bug class as
+     *  `use-roles.hooks.ts`'s `onSaveRole`/`runRowDelete`) is a functional update keyed on THIS call's
+     *  own `principalId`: Enable fires with no confirmation gate, so two calls — on different users —
+     *  can genuinely overlap, and an unconditional reset would clear the busy indicator (which
+     *  `openResetPassword` below reads to refuse opening while a toggle is in flight) out from under a
+     *  still-in-flight, unrelated toggle. */
     async function onToggleStatus(user) {
+        const capabilities = rowCapabilities(user);
+        if (user.status === "active" ? !capabilities.canDisable : !capabilities.canEnable)
+            return;
         setToggleSavingId(user.principalId);
         setToggleError(null);
         try {
             await toggleStatusMutation.mutate({ input: user });
         }
         catch (e) {
-            setToggleError(describeApiError(e, t("failed to change status")));
+            setToggleError(describeError(e, translate("failed to change status")));
         }
         finally {
             setToggleSavingId((current) => (current === user.principalId ? null : current));
         }
     }
+    /** Opens the Disable confirm dialog for `user` — the `RowMenu` "Disable" item's `onSelect` when
+     *  the user is currently active. Was an inline closure inside the old `rowMenuItems`; named here
+     *  now that the item builder itself moved to `rules.ts` and needs a callback to hand it. */
     function requestDisable(user) {
+        if (!rowCapabilities(user).canDisable)
+            return;
         setToggleError(null);
         setConfirmingDisable(user);
     }
+    /** Confirms the Disable that `RowMenu`'s "Disable" item asked about. Closes the dialog either
+     *  way (matching Posts.tsx/Redirects.tsx's own Disable/Delete `ConfirmDialog` convention) — a
+     *  failure surfaces via `toggleError` above the table, not by leaving the modal open.
+     *
+     *  2026-09-05 fix, same bug class as `use-roles.hooks.ts`'s `runRowDelete`: `setConfirmingDisable`
+     *  is exposed directly on the controller, so nothing at the hook level stops the operator opening
+     *  a DIFFERENT user's Disable confirmation while this one's toggle is still in flight. The close
+     *  below only clears it when it still names the SAME user this call started for — otherwise a
+     *  stale toggle's settlement would silently dismiss a newer, still-undecided confirmation. */
     async function confirmDisable() {
         if (!confirmingDisable)
             return;
@@ -204,25 +359,37 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
         await onToggleStatus(user);
         setConfirmingDisable((current) => (current?.principalId === user.principalId ? null : current));
     }
+    // Delete-user plan v2 (2026-09-24), Slice 4 — mirrors Disable's request/confirm pair above with
+    // its OWN state (see `confirmingDelete`'s own doc comment for why not shared). `deleteUserMutation`
+    // invalidates `KEYS.list` like every other write on this screen; the route already filters a newly
+    // trashed principal out of `listUsers()`, so the row disappears on the next render with no extra
+    // client-side bookkeeping.
     const deleteUserMutation = useFetchMutation({
-        run: ({ input: principalId }) => port.deleteUser({ principalId: principalId })
+        run: ({ input: principalId }) => port.deleteUser({ principalId })
     }, {
         invalidates: [[queryScope, ...KEYS.list]],
     });
     const [confirmingDelete, setConfirmingDelete] = useState(null);
     function requestDelete(user) {
+        if (!rowCapabilities(user).canDelete)
+            return;
         setToggleError(null);
         setConfirmingDelete(user);
     }
+    /** Confirms the Delete that `RowMenu`'s "Delete" item asked about. Closes the dialog either way
+     *  (matching `confirmDisable`'s and Posts.tsx/Redirects.tsx's own Delete `ConfirmDialog`
+     *  convention) — a failure surfaces via `toggleError` above the table, not by leaving the modal
+     *  open. Same stale-call guard as `confirmDisable`: only clears `confirmingDelete` when it still
+     *  names the SAME user this call started for. */
     async function confirmDelete() {
-        if (!confirmingDelete)
+        if (!confirmingDelete || !rowCapabilities(confirmingDelete).canDelete)
             return;
         const user = confirmingDelete;
         try {
             await deleteUserMutation.mutate({ input: user.principalId });
         }
         catch (e) {
-            setToggleError(describeApiError(e, t("failed to delete user")));
+            setToggleError(describeError(e, translate("failed to delete user")));
         }
         setConfirmingDelete((current) => (current?.principalId === user.principalId ? null : current));
     }
@@ -230,6 +397,7 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
         users,
         roles,
         policies,
+        canGrant,
         error,
         formOpen,
         setFormOpen,
@@ -274,6 +442,7 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
         openResetPassword,
         confirmResetPassword,
         canManageUserTrash,
+        rowCapabilities,
         confirmingDelete,
         setConfirmingDelete,
         requestDelete,

package/dist/react/users/rules.d.ts

@@ -1,33 +1,140 @@
 import type { AdminIdentityUser } from "../models.js";
-import type { Translate } from "@jini-ai/ui/panel-kit";
+import type { Translate, QueryKey } from "@jini-ai/ui/panel-kit";
 import type { RowMenuItem } from "@jini-ai/admin/react";
-import type { QueryKey } from "@jini-ai/ui/panel-kit";
+/**
+ * @file Pure logic for the `users` feature — everything that computes a value rather than
+ * rendering one. Follows the `posts/rules.ts` convention: no React import, no hooks, directly
+ * testable.
+ *
+ * Moved here from `Users.tsx`: the screen's own `describeApiError` override (a branch per server
+ * error `code`), the row-menu item builder (a branch on `user.status` plus the confirm-vs-immediate
+ * split for Disable/Enable), and the role/policy grant label formatter (a branch on whether the
+ * user holds any grants of that kind). All three were previously closures or free functions inside
+ * the component, reachable only by rendering the full screen.
+ *
+ * `KEYS` (fetch-query migration, 2026-08-12): one identity for the combined users+roles+policies
+ * read — matches the pre-migration `reload()`, which always refetched all three together.
+ */
 export declare const KEYS: {
     list: QueryKey;
 };
-export declare function describeApiError({ error, fallback, translate }: {
+/** Server error `code` -> a plain-language prefix (SPEC-006 errors.spec.md §2), layered on the
+ *  shared default (`lib/api.ts`'s `describeApiError`) — this screen's `RESOURCE_CONFLICT` means
+ *  "username already in use", a different meaning than `Roles.tsx`'s "still referenced" or
+ *  `Workspace.tsx`'s "slug already taken" for the same code (audit cross-cutting finding #2 —
+ *  deliberately not unified into one table). `VALIDATION_ERROR` stays a dedicated branch rather than
+ *  joining the table above: its message comes from the error itself (`e.message`), not a fixed
+ *  string, so it isn't a value a plain lookup can hold.
+ *
+ *  `locale` (C4 fix, 2026-09-20): every branch here used to return its English literal directly,
+ *  leaking English into every non-`en` locale regardless of the caller's own translated fallback —
+ *  the fallback was already threaded through `t()` at each call site, but these overrides were not.
+ *  Each literal is now also a key into `users-i18n.ts`'s `USERS_DICT`. */
+export declare function describeUsersError({ error, fallback, translate }: {
     error: unknown;
     fallback: string;
     translate: Translate;
-}): string;
+}, _optional?: Record<string, never>): string;
+export { describeUsersError as describeApiError };
+/** The callbacks a row menu needs. Passed in rather than imported, so this module stays free of
+ *  state, and so a test can assert exactly which one a given row wires up (same convention as
+ *  `posts/rules.ts`'s `PostRowMenuHandlers`). */
 export interface UserRowMenuHandlers {
+    /** Asked only when `user.status === "active"` — opens the confirm dialog rather than acting. */
     onRequestDisable: (user: AdminIdentityUser) => void;
+    /** Asked only when `user.status !== "active"` — fires immediately, no confirm (Enable was never
+     *  confirm-gated). */
     onEnable: (user: AdminIdentityUser) => void;
     onManage: (user: AdminIdentityUser) => void;
     onResetPassword: (user: AdminIdentityUser) => void;
+    /** Delete-user plan v2 (2026-09-24) — always opens the confirm dialog, never fires immediately:
+     *  unlike Enable, "Delete" moves the user to the Trash, a destructive-looking action even though
+     *  it is recoverable there for 60 days. Only asked for when `userRowMenuItems`'s own `canDelete`
+     *  is true — see that function's doc comment. */
     onRequestDelete: (user: AdminIdentityUser) => void;
 }
-export declare function userRowMenuItems({ user, toggleSaving, handlers, translate, canDelete }: {
+export interface UserAccountCapabilities {
+    canDelete: boolean;
+    canDisable: boolean;
+    canEnable: boolean;
+    canResetPassword: boolean;
+}
+/** Courtesy mirror of the server target rule. Unknown identity/roles fail closed. */
+export declare function userAccountCapabilities(required: {
+    user: AdminIdentityUser;
+    callerPrincipalId: string | null;
+    callerIsOwner: boolean;
+    canManageUserTrash: boolean;
+    roles: ReadonlyMap<string, {
+        name: string;
+        isBuiltin: boolean;
+    }>;
+}, _optional?: Record<string, never>): UserAccountCapabilities;
+export declare function isOwnerAccount(required: {
+    user: AdminIdentityUser;
+    roles: ReadonlyMap<string, {
+        name: string;
+        isBuiltin: boolean;
+    }>;
+}, _optional?: Record<string, never>): boolean;
+/**
+ * `RowMenu` items for one user row — matches `Posts.tsx`/`Pages.tsx`'s three-dot menu shape:
+ * Disable/Enable, Manage, Reset password, and — delete-user plan v2 (2026-09-24) — Delete, appended
+ * only when `canDelete` is true. The server gate (owner or the built-in `admin` role,
+ * `delete-user-service.ts`'s `callerMayManageUserTrash`) is the real boundary; `canDelete` is this
+ * row's own affordance-hiding mirror of it, computed once per render from `/auth/me` by
+ * `use-users.hooks.ts` — see that hook's `canManageUserTrash` state for where it comes from.
+ *
+ * Disable/Enable share a single "toggle" item (label follows status, same shape as
+ * `Redirects.tsx`'s own toggle item) — Disable confirms via the modal below; Enable fires
+ * immediately, matching this screen's existing behavior (Enable was never confirm-gated). The
+ * `toggleSaving` guard reproduces the original inline check (`if (toggleSavingId) return`) against
+ * whatever row action is currently in flight, read fresh at click time.
+ *
+ * "Manage" always reads "Manage", never "Close": the item still toggles the expanded panel
+ * (`onManage` — closing it again by selecting "Manage" a second time still works exactly as it did
+ * as a standalone button), but a `RowMenu` item disappears the instant it is selected, so a label
+ * that flips to "Close" is never actually visible mid-interaction — it would only ever describe a
+ * state the operator cannot see while the menu that shows it is open. A static label sidesteps that
+ * without losing any capability.
+ *
+ * "Delete" always opens the confirm dialog (`onRequestDelete`), matching Disable's shape rather than
+ * Enable's immediate-fire one — see `UserRowMenuHandlers.onRequestDelete`'s own doc comment.
+ *
+ * @complexity Time/space: O(1) — at most four entries, no iteration.
+ */
+export declare function userRowMenuItems({ user, toggleSaving, handlers, translate, canDelete, capabilities }: {
     user: AdminIdentityUser;
     toggleSaving: boolean;
     handlers: UserRowMenuHandlers;
     translate: Translate;
     canDelete: boolean;
-}): RowMenuItem[];
-export declare function formatGrantLabel({ ids, byId }: {
+    capabilities?: boolean | UserAccountCapabilities | undefined;
+}, _optional?: Record<string, never>): RowMenuItem[];
+/**
+ * The role or policy names a user holds, for the "Roles"/"Policies" table cells — `null` when the
+ * user holds none, which the caller renders as the `muted-cell` "none" fallback (a plain ternary on
+ * this already-computed value, per this feature's extraction rule).
+ *
+ * A grant id with no matching entry in `byId` (a role/policy deleted out from under a still-held
+ * grant) falls back to rendering the raw id rather than dropping it silently — the operator sees
+ * something is wrong instead of an undercount with no explanation.
+ *
+ * @complexity Time: O(n) in the number of granted ids; space: O(n) for the joined string.
+ */
+export declare function grantOptionLabel(required: {
+    option: {
+        name: string;
+        isBuiltin: boolean;
+    };
+    translate: (key: string) => string;
+}, _optional?: Record<string, never>): string;
+export declare function formatGrantLabel({ ids, byId, translate }: {
     ids: readonly string[];
     byId: ReadonlyMap<string, {
         name: string;
+        isBuiltin?: boolean;
     }>;
-}): string | null;
+    translate?: Translate | undefined;
+}, _optional?: Record<string, never>): string | null;
 //# sourceMappingURL=rules.d.ts.map