@jini-ai/user-management 0.3.1 → 0.3.2

package/dist/core/runtime-ports.d.ts

@@ -5,4 +5,24 @@ export interface SessionTokenPort {
         rawToken: string;
     }): string;
 }
+/** Host lifecycle for renames. Audit writes must join the identity transaction. */
+export interface UsernameChangePort {
+    /** A host can refuse a rename that its bootstrap identity cannot safely survive. */
+    assertSupported?: ((required: {
+        workspaceId: string;
+        principalId: string;
+    }, optional?: Record<string, never>) => Promise<void>) | undefined;
+    isInTrash(required: {
+        workspaceId: string;
+        principalId: string;
+    }, optional?: Record<string, never>): Promise<boolean>;
+    record(required: {
+        workspaceId: string;
+        principalId: string;
+        callerPrincipalId: string;
+        previousUsername: string;
+        username: string;
+        occurredAt: string;
+    }, optional?: Record<string, never>): Promise<void>;
+}
 //# sourceMappingURL=runtime-ports.d.ts.map

package/dist/core/types.d.ts

@@ -156,8 +156,11 @@ export declare class IdentityNotFoundError extends Error {
  * See docs/decisions/DR-001-identity-and-session-boundary.md.
  */
 export declare class IdentityConflictError extends Error {
-    constructor({ message }: {
+    /** Rename conflicts carry a precise reason; legacy conflicts retain their existing contract. */
+    readonly code?: "RESOURCE_CONFLICT" | "USER_IN_TRASH" | "USERNAME_IN_TRASH";
+    constructor({ message, code }: {
         message: string;
+        code?: "RESOURCE_CONFLICT" | "USER_IN_TRASH" | "USERNAME_IN_TRASH";
     }, optional?: ErrorOptions);
 }
 /** Raised by `login` on bad credentials, a disabled principal, or a blank field. See docs/decisions/DR-001-identity-and-session-boundary.md. */

package/dist/core/types.js

@@ -18,8 +18,12 @@ export class IdentityNotFoundError extends Error {
  * See docs/decisions/DR-001-identity-and-session-boundary.md.
  */
 export class IdentityConflictError extends Error {
-    constructor({ message }, optional = {}) {
+    /** Rename conflicts carry a precise reason; legacy conflicts retain their existing contract. */
+    code;
+    constructor({ message, code }, optional = {}) {
         super(message, optional);
+        if (code !== undefined)
+            this.code = code;
     }
 }
 /** Raised by `login` on bad credentials, a disabled principal, or a blank field. See docs/decisions/DR-001-identity-and-session-boundary.md. */

package/dist/react/index.d.ts

@@ -15,6 +15,9 @@ export type { MembersProps } from './members/Members.js';
 export { useMembers } from './members/hooks/use-members.hooks.js';
 export type { MembersController, MembersDependencies, MembersOptions } from './members/hooks/use-members.hooks.js';
 export { describeIdentityError } from './errors.js';
+export { useChangeUsername } from './users/hooks/use-change-username.hooks.js';
+export type { ChangeUsernameController } from './users/hooks/use-change-username.hooks.js';
+export { ChangeUsernameDialog } from './users/ChangeUsernameDialog.js';
 export { userAccountCapabilities, isOwnerAccount, grantOptionLabel, formatGrantLabel, userRowMenuItems, describeUsersError } from './users/rules.js';
 export type { UserAccountCapabilities, UserRowMenuHandlers } from './users/rules.js';
 export { emptyRowState, memberRowMenuItems, describeMembersError } from './members/rules.js';

package/dist/react/index.js

@@ -6,6 +6,8 @@ export { useResetPasswordFields } from './users/hooks/use-reset-password-fields.
 export { Members } from './members/Members.js';
 export { useMembers } from './members/hooks/use-members.hooks.js';
 export { describeIdentityError } from './errors.js';
+export { useChangeUsername } from './users/hooks/use-change-username.hooks.js';
+export { ChangeUsernameDialog } from './users/ChangeUsernameDialog.js';
 export { userAccountCapabilities, isOwnerAccount, grantOptionLabel, formatGrantLabel, userRowMenuItems, describeUsersError } from './users/rules.js';
 export { emptyRowState, memberRowMenuItems, describeMembersError } from './members/rules.js';
 //# sourceMappingURL=index.js.map

package/dist/react/members/Members.d.ts

@@ -29,5 +29,5 @@ export interface MembersProps extends MembersDependencies, MembersOptions {
         value: string;
     }) => ReactNode) | undefined;
 }
-export declare function Members({ useMembersHook, port, translate: injectedTranslate, refresh, description, emptyDescription, renderServerLabel }: MembersProps): import("react").JSX.Element;
+export declare function Members({ useMembersHook, port, translate: injectedTranslate, queryScope, refresh, description, emptyDescription, renderServerLabel }: MembersProps): import("react").JSX.Element;
 //# sourceMappingURL=Members.d.ts.map

package/dist/react/members/Members.js

@@ -28,8 +28,8 @@ function MemberRow({ member, rowState, isExpanded, detail, detailError, detailLo
                                         onRequestDisable: setConfirmingDisable,
                                     }, translate }) }), rowState.error ? (_jsx("div", { className: "notice error", role: "alert", children: rowState.error })) : null, rowState.notice ? _jsx("div", { className: "notice", children: rowState.notice }) : null] })] }), isExpanded ? (_jsx("tr", { children: _jsx("td", { colSpan: 5, children: _jsx(MemberDetailPanel, { memberId: member.id, detailLoadingId: detailLoadingId, detailError: detailError, detail: detail, t: t }) }) })) : null] }, member.id));
 }
-export function Members({ useMembersHook = useMembers, port, translate: injectedTranslate, refresh, description = "People who have registered an account — review status, resend a sign-in link, or disable access.", emptyDescription = "Registered members will show up here.", renderServerLabel }) {
-    const { members, error, stateFor, onResendSignInLink, expandedId, detailById, detailError, detailLoadingId, onToggleDetail, confirmingDisable, setConfirmingDisable, confirmDisable, t, translate, } = useMembersHook({ port, translate: injectedTranslate }, { refresh });
+export function Members({ useMembersHook = useMembers, port, translate: injectedTranslate, queryScope, refresh, description = "People who have registered an account — review status, resend a sign-in link, or disable access.", emptyDescription = "Registered members will show up here.", renderServerLabel }) {
+    const { members, error, stateFor, onResendSignInLink, expandedId, detailById, detailError, detailLoadingId, onToggleDetail, confirmingDisable, setConfirmingDisable, confirmDisable, t, translate, } = useMembersHook({ port, translate: injectedTranslate, ...(queryScope === undefined ? {} : { queryScope }) }, { refresh });
     if (error)
         return _jsx("div", { className: "notice error", children: error });
     if (!members)

package/dist/react/members/hooks/use-members.hooks.d.ts

@@ -34,6 +34,8 @@ import type { Translate } from "@jini-ai/ui/panel-kit";
  */
 export interface MembersDependencies {
     port: MembersPort;
+    /** Same session/workspace scope as Users; isolated providers retain legacy composition. */
+    queryScope?: string;
     translate: Translate;
 }
 export interface MembersController {
@@ -70,5 +72,5 @@ export interface MembersController {
 export interface MembersOptions {
     refresh?: IdentityRefreshPort | undefined;
 }
-export declare function useMembers({ port, translate }: MembersDependencies, { refresh }?: MembersOptions): MembersController;
+export declare function useMembers({ port, translate, queryScope }: MembersDependencies, { refresh }?: MembersOptions): MembersController;
 //# sourceMappingURL=use-members.hooks.d.ts.map

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

@@ -1,60 +1,66 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { describeApiError, emptyRowState } from "../rules.js";
-import { useSettlementGeneration } from "@jini-ai/ui/panel-kit";
-export function useMembers({ port, translate }, { refresh } = {}) {
+import { useCachedLoader, useFetchMutation, useFetchQuery, useInvalidate } from "@jini-ai/ui/fetch-query";
+export function useMembers({ port, translate, queryScope = "members" }, { refresh } = {}) {
+    const scopeRef = useRef(queryScope);
+    scopeRef.current = queryScope;
     const boundT = translate;
     const describeError = (error, fallback) => describeApiError({ error, fallback, translate });
-    const [members, setMembers] = useState(null);
-    const [error, setError] = useState(null);
+    const listKey = [queryScope, 'members', 'list'];
+    const detailRoot = [queryScope, 'members', 'detail'];
+    const invalidate = useInvalidate();
+    // Mount reads and assistant refreshes can overlap; the shared cache owns list settlement
+    // order so a slow earlier success or failure cannot replace a newer roster.
+    const list = useFetchQuery({ key: listKey, fetch: () => port.listMembers({}) });
+    const members = list.data?.members ?? null;
+    const error = list.error ? describeError(list.error, translate("failed to load members")) : null;
+    const listLoader = useCachedLoader({ key: listKey, fetch: () => port.listMembers({}) }, { staleTime: 0 });
+    const disable = useFetchMutation({ run: ({ input: id }) => port.disableMember({ id }) }, { invalidates: [listKey, detailRoot] });
+    // Sending a link changes no list/detail fields; do not refetch the roster on success.
+    const resend = useFetchMutation({ run: ({ input: email }) => port.requestMemberMagicLink({ email }) });
     const [rowState, setRowState] = useState({});
     const [expandedId, setExpandedId] = useState(null);
     const [detailById, setDetailById] = useState({});
-    const [detailError, setDetailError] = useState(null);
-    const [detailLoadingId, setDetailLoadingId] = useState(null);
     // 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/Users.tsx already made). `null` when the dialog is closed.
     const [confirmingDisable, setConfirmingDisable] = useState(null);
-    const settlement = useSettlementGeneration();
     // Which row's detail panel is actually open (C7, plan-access.md §8, N2) — a ref, not just
-    // `expandedId` state, because `onToggleDetail`'s `catch`/`finally` read it after an `await`, where
-    // a state read would see the closure's stale value. Set by `onToggleDetail` alone. Without this,
-    // expanding row A (slow, then failing), then row B, lets A's `finally` blank B's loading indicator
-    // and lets A's failure paint onto B's now-open panel — the same "entity-scoped panel, unkeyed
-    // settle" shape `use-roles.hooks.ts`'s `permissionPolicyIdRef` fixes for `loadPermissions`.
+    // expandedId state, because onToggleDetail reads it after await, when a closure can be stale.
+    // Expanding slow/failing A then B must not let A's failure or finally blank B's panel/spinner.
     const expandedIdRef = useRef(null);
-    // Latest-wins for `onToggleDetail`'s detail loads, a separate instance from `settlement` (which
-    // tracks `load()`'s list reads).
-    const detailSettlement = useSettlementGeneration();
-    const load = useCallback(() => {
-        // Claim this call's generation BEFORE the request starts — see `useSettlementGeneration`'s own
-        // doc for why a synchronous ref bump, not `useState`, is what makes two overlapping calls each
-        // see the other's claim. Needed now that a content refresh can fire more than once per run
-        // (mid-run tool progress, see `AssistantDock.hooks.tsx`), so two overlapping `load()` calls have
-        // no ordering guarantee on their responses.
-        const generation = settlement.next();
-        port
-            .listMembers({})
-            .then((r) => {
-            if (!settlement.isCurrent({ generation }))
-                return;
-            setMembers(r.members);
-            setError(null);
-        })
-            .catch((e) => {
-            if (!settlement.isCurrent({ generation }))
-                return;
-            setError(e instanceof Error ? e.message : translate("failed to load members"));
-        });
-        // `port`/`locale`/`settlement` are added — see `use-page-editor.hooks.ts`'s identical note:
-        // function-scoped values ESLint's exhaustive-deps rule can see, referentially stable in
-        // production, so this changes nothing about when this callback's identity changes.
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [port, settlement, translate]);
+    const detailGenerations = useRef({});
+    const [detailGeneration, setDetailGeneration] = useState(0);
+    // Entity keys own settlement: a late A response cannot paint B's error/spinner. Detail
+    // data remains cached on collapse, while successful disables invalidate both resources.
+    const detail = useFetchQuery({
+        key: [...detailRoot, expandedId ?? '', detailGeneration],
+        fetch: () => port.getMember({ id: expandedId }),
+    }, { enabled: expandedId !== null, staleTime: Infinity });
+    const detailLoader = useCachedLoader({ key: [...detailRoot, expandedId ?? '', detailGeneration], fetch: () => port.getMember({ id: expandedId }) }, { staleTime: Infinity });
     useEffect(() => {
-        load();
-    }, [load]);
-    useEffect(() => refresh?.subscribe({ onRefresh: load }), [refresh, load]);
+        expandedIdRef.current = null;
+        detailGenerations.current = {};
+        setExpandedId(null);
+        setDetailGeneration(0);
+        setDetailById({});
+        setRowState({});
+        setConfirmingDisable(null);
+    }, [queryScope]);
+    // Only paint the failure onto the panel that is still expanded: the observer's entity key
+    // selects the current row, so a late rejection for a collapsed row cannot surface here.
+    const detailError = detail.error ? describeError(detail.error, translate("Failed to load member detail.")) : null;
+    // A superseded load leaves the spinner to its successor. Derive it from the current keyed
+    // observer instead of letting an old request's finally clear the new row's loading state.
+    const detailLoadingId = expandedId !== null && !detail.data && detail.isFetching ? expandedId : null;
+    useEffect(() => {
+        if (expandedId && detail.data)
+            setDetailById(current => ({ ...current, [expandedId]: detail.data.member }));
+    }, [expandedId, detail.data]);
+    useEffect(() => refresh?.subscribe({ onRefresh: () => {
+            invalidate({ key: listKey });
+            invalidate({ key: detailRoot });
+        } }), [refresh, invalidate, queryScope]);
     function stateFor({ id }) {
         return rowState[id] ?? emptyRowState({});
     }
@@ -66,8 +72,9 @@ export function useMembers({ port, translate }, { refresh } = {}) {
             return;
         patchRowState(member.id, { disabling: true, error: null, notice: null });
         try {
-            const result = await port.disableMember({ id: member.id });
-            setMembers((current) => (current ? current.map((m) => (m.id === member.id ? result.member : m)) : current));
+            const result = await disable.mutate({ input: member.id });
+            await listLoader.load().catch(() => { }); // Await roster settlement; list.error owns a failed read, not the accepted disable.
+            setDetailById(current => current[member.id] ? { ...current, [member.id]: result.member } : current);
             patchRowState(member.id, { disabling: false, notice: translate("Member disabled.") });
         }
         catch (e) {
@@ -79,7 +86,7 @@ export function useMembers({ port, translate }, { refresh } = {}) {
             return;
         patchRowState(member.id, { resending: true, error: null, notice: null });
         try {
-            await port.requestMemberMagicLink({ email: member.email });
+            await resend.mutate({ input: member.email });
             patchRowState(member.id, { resending: false, notice: translate("Sign-in link sent.") });
         }
         catch (e) {
@@ -103,30 +110,23 @@ export function useMembers({ port, translate }, { refresh } = {}) {
         }
         expandedIdRef.current = member.id;
         setExpandedId(member.id);
-        setDetailError(null);
-        if (detailById[member.id])
-            return;
-        setDetailLoadingId(member.id);
-        // Claimed before the `await`, so a later detail load (another row's, or this same row's after
-        // a close and reopen) supersedes this one. The row-id key alone cannot tell two loads of the
-        // SAME row apart.
-        const generation = detailSettlement.next();
+        // A collapsed unfinished request cannot own a reopened panel. A primitive generation
+        // creates a new read fence for that member, preserving the prior latest-wins contract;
+        // successful details keep their current generation so reopen reuses the cache.
+        // Claimed before await: even two loads of the SAME row must be distinguishable, since a
+        // row-id key alone cannot fence an unfinished request after collapse/reopen.
+        const generation = detailById[member.id] ? detailGenerations.current[member.id] ?? 1 : (detailGenerations.current[member.id] ?? 0) + 1;
+        detailGenerations.current[member.id] = generation;
+        setDetailGeneration(generation);
+        // Start through the same cache synchronously so imperative callers still await the
+        // detail read; the reactive observer joins it when React commits the selected identity.
+        const requestedScope = queryScope;
         try {
-            const result = await port.getMember({ id: member.id });
-            setDetailById((current) => ({ ...current, [member.id]: result.member }));
-        }
-        catch (e) {
-            // Only paint the failure onto the panel this load was actually for — a different row may
-            // already be open by the time this settles, or a newer load of this row may be running.
-            if (detailSettlement.isCurrent({ generation }) && expandedIdRef.current === member.id) {
-                setDetailError(describeError(e, translate("Failed to load member detail.")));
-            }
-        }
-        finally {
-            // A superseded load leaves the spinner to the load that superseded it.
-            if (detailSettlement.isCurrent({ generation }))
-                setDetailLoadingId(null);
+            const result = await detailLoader.load({ key: [...detailRoot, member.id, generation], fetch: () => port.getMember({ id: member.id }) });
+            if (scopeRef.current === requestedScope && detailGenerations.current[member.id] === generation)
+                setDetailById(current => ({ ...current, [member.id]: result.member }));
         }
+        catch { /* The keyed observer owns the failure for the panel that is still expanded. */ }
     }
     return {
         members,

package/dist/react/models.d.ts

@@ -14,6 +14,8 @@ export interface AdminIdentityUser {
     /** Server classification covers ownership granted by policy, not only named roles. */
     isOwner?: boolean | undefined;
     isProtectedAccount?: boolean | undefined;
+    /** Host refusal for accounts whose bootstrap identity cannot safely follow a rename yet. */
+    canRename?: boolean | undefined;
     roleIds: string[];
     policyIds: string[];
 }

package/dist/react/ports.d.ts

@@ -16,6 +16,7 @@ export interface UsersPort {
             id: string;
         };
         canManageUserTrash: boolean;
+        effectivePermissions?: string[] | undefined;
     }>;
     listRoles(required: Record<string, never>): Promise<{
         roles: AdminRole[];
@@ -35,6 +36,7 @@ export interface UsersPort {
         principalId: string;
     }, options?: {
         email?: string | undefined;
+        username?: string | undefined;
     }): Promise<{
         user: AdminIdentityUser;
     }>;

package/dist/react/testing.js

@@ -67,7 +67,7 @@ export function createFakeUsersPort(_required, options = {}) {
             if (options.updateUserError)
                 throw options.updateUserError;
             const current = requireUser(target.principalId);
-            return { user: replaceUser({ ...current, ...opts }) };
+            return { user: replaceUser({ ...current, ...opts, username: opts?.username ?? current.username }) };
         },
         async disableUser({ principalId }) {
             if (options.toggleStatusError)

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

@@ -0,0 +1,8 @@
+import type { Translate } from "@jini-ai/ui/panel-kit";
+import type { useChangeUsername } from "./hooks/use-change-username.hooks.js";
+/** Markup shared by row actions and the signed-in user's profile; state lives in the hook. */
+export declare function ChangeUsernameDialog({ controller, translate: t }: {
+    controller: ReturnType<typeof useChangeUsername>;
+    translate: Translate;
+}, _optional?: Record<string, never>): import("react").JSX.Element;
+//# sourceMappingURL=ChangeUsernameDialog.d.ts.map

package/dist/react/users/ChangeUsernameDialog.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ConfirmDialog } from "@jini-ai/admin/react";
+import { agentHandle } from "@jini-ai/agentic";
+/** Markup shared by row actions and the signed-in user's profile; state lives in the hook. */
+export function ChangeUsernameDialog({ controller, translate: t }, _optional = {}) {
+    return _jsx(ConfirmDialog, { open: controller.target !== null, agentHandle: "users-change-username", title: t("Change username"), cancelLabel: t("Cancel"), confirmLabel: t("Change username"), pending: controller.pending, onConfirm: () => void controller.confirm({}), onCancel: () => controller.cancel({}), body: _jsxs(_Fragment, { children: [_jsx("p", { children: controller.target?.username }), _jsxs("label", { children: [t("New username"), _jsx("input", { value: controller.username, autoComplete: "off", disabled: controller.pending, onChange: event => controller.setUsername(event.target.value), ...agentHandle({ handle: "users-change-username-input" }, { role: "field", label: "New login username" }) })] }), _jsx("p", { children: t("Existing sessions stay signed in. Use the new username the next time you sign in.") }), controller.error ? _jsx("p", { role: "alert", className: "save-error", children: controller.error }) : null] }) });
+}
+//# sourceMappingURL=ChangeUsernameDialog.js.map

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

@@ -1,7 +1,7 @@
 import { type Dispatch, type SetStateAction } from "react";
 import type { AdminIdentityUser, AdminPolicy, AdminRole } from "../models.js";
 import { type UserAccountCapabilities } from "./rules.js";
-import { useUsers, type UsersDependencies, type UsersOptions } from "./hooks/use-users.hooks.js";
+import { useUsers, type UsersController, type UsersDependencies, type UsersOptions } from "./hooks/use-users.hooks.js";
 import type { ReactNode } from "react";
 import type { Translate } from "@jini-ai/ui/panel-kit";
 /**
@@ -130,6 +130,7 @@ export interface UserRowActionsController {
     requestDisable: (user: AdminIdentityUser) => void;
     toggleStatus: (user: AdminIdentityUser) => Promise<void>;
     openResetPassword: (user: AdminIdentityUser) => void;
+    renameUserHandler?: UsersController["renameUserHandler"];
     /** Delete-user plan v2 (2026-09-24): whether the row's `RowMenu` should carry a "Delete" item at
      *  all — see `use-users.hooks.ts`'s `canManageUserTrash` doc comment for where this comes from. */
     canDelete: boolean;

package/dist/react/users/Users.js

@@ -7,6 +7,7 @@ import { formatGrantLabel, grantOptionLabel, userRowMenuItems, isOwnerAccount }
 import { useUsers } from "./hooks/use-users.hooks.js";
 import { InfoTip } from "@jini-ai/ui/admin-widgets";
 import { useResetPasswordFields } from "./hooks/use-reset-password-fields.hooks.js";
+import { ChangeUsernameDialog } from "./ChangeUsernameDialog.js";
 /** The "New user" form — extracted from `Users` verbatim; own scope for `formError`/`saving`. */
 function NewUserForm({ username, setUsername, email, setEmail, password, setPassword, saving, formError, onCreate, t }) {
     return (_jsxs("form", { onSubmit: onCreate, className: "notice integrations-form form-measure", children: [formError ? _jsx("span", { className: "save-error", children: formError }) : null, _jsxs("label", { children: [t("Username"), _jsx("input", { value: username, onChange: (e) => setUsername(e.target.value), required: true, ...agentHandle({ handle: "users-new-username" }, { role: "field", label: "The new user's username" }) })] }), _jsxs("label", { children: [t("Email (optional)"), _jsx("input", { type: "email", value: email, onChange: (e) => setEmail(e.target.value), ...agentHandle({ handle: "users-new-email" }, { role: "field", label: "The new user's email address" }) })] }), _jsxs("label", { children: [t("Password"), _jsx("input", { type: "password", autoComplete: "new-password", value: password, onChange: (e) => setPassword(e.target.value), required: true, minLength: 1, ...agentHandle({ handle: "users-new-password" }, {
@@ -43,6 +44,7 @@ function UserRow({ user, roleById, policyById, showGrants, actions, manage, agen
                                     onEnable: (u) => void actions.toggleStatus(u),
                                     onManage: actions.toggleExpanded,
                                     onResetPassword: actions.openResetPassword,
+                                    onChangeUsername: actions.renameUserHandler?.({ user }),
                                     onRequestDelete: actions.requestDelete,
                                 }, translate, canDelete: actions.canDelete,
                                 capabilities: actions.rowCapabilities?.(user) ?? actions.canDelete,
@@ -159,20 +161,21 @@ function UsersNotices({ toggleError, notice }) {
     return (_jsxs(_Fragment, { children: [toggleError ? _jsx("div", { className: "notice error", children: toggleError }) : null, notice ? _jsx("div", { className: "notice", children: notice }) : null] }));
 }
 export function Users({ useUsersHook = useUsers, port, translate: injectedTranslate, queryScope, openOwnPasswordReset, onOwnPasswordResetClosed, passwordResetNotice, renderServerLabel }) {
-    const { users, roles, policies, canGrant, error, formOpen, setFormOpen, username, setUsername, email, setEmail, password, setPassword, saving, formError, onCreate, expandedId, toggleExpanded, pendingRoleId, setPendingRoleId, pendingPolicyId, setPendingPolicyId, grantSaving, grantError, onAssignRole, onAttachPolicy, editEmail, setEditEmail, emailSaving, onSaveEmail, toggleSavingId, toggleError, notice, confirmingDisable, setConfirmingDisable, requestDisable, confirmDisable, onToggleStatus, resetPasswordFor, setResetPasswordFor, newPassword, setNewPassword, passwordSaving, passwordError, setPasswordError, openResetPassword, confirmResetPassword, canManageUserTrash, rowCapabilities, confirmingDelete, setConfirmingDelete, requestDelete, deleteSaving, confirmDelete, t, translate, } = useUsersHook({ port, translate: injectedTranslate, queryScope }, {
+    const { users, roles, policies, canGrant, error, formOpen, setFormOpen, username, setUsername, email, setEmail, password, setPassword, saving, formError, onCreate, expandedId, toggleExpanded, pendingRoleId, setPendingRoleId, pendingPolicyId, setPendingPolicyId, grantSaving, grantError, onAssignRole, onAttachPolicy, editEmail, setEditEmail, emailSaving, onSaveEmail, toggleSavingId, toggleError, notice, confirmingDisable, setConfirmingDisable, requestDisable, confirmDisable, onToggleStatus, resetPasswordFor, setResetPasswordFor, newPassword, setNewPassword, passwordSaving, passwordError, setPasswordError, openResetPassword, confirmResetPassword, canManageUserTrash, rowCapabilities, ownProfile, canRenameOwnProfile, openOwnRename, renameUserHandler, changeUsername, confirmingDelete, setConfirmingDelete, requestDelete, deleteSaving, confirmDelete, t, translate, } = useUsersHook({ port, translate: injectedTranslate, queryScope }, {
         openOwnPasswordReset, onOwnPasswordResetClosed, passwordResetNotice,
     });
     if (error)
         return _jsx("div", { className: "notice error", children: error });
     if (!users || !roles || !policies)
         return _jsx("div", { className: "notice", children: t("Loading users…") });
-    return (_jsxs("div", { className: "page", children: [_jsx(UsersPageHeader, { formOpen: formOpen, setFormOpen: setFormOpen, t: t }), formOpen ? (_jsx(NewUserForm, { username: username, setUsername: setUsername, email: email, setEmail: setEmail, password: password, setPassword: setPassword, saving: saving, formError: formError, onCreate: onCreate, t: t })) : null, _jsx(UsersNotices, { toggleError: toggleError, notice: notice }), _jsx(UsersTable, { users: users, roles: roles, policies: policies, showGrants: canGrant, actions: {
+    return (_jsxs("div", { className: "page", children: [_jsx(UsersPageHeader, { formOpen: formOpen, setFormOpen: setFormOpen, t: t }), ownProfile ? _jsxs("section", { className: "notice", "aria-label": t("My profile"), children: [_jsx("h2", { children: t("My profile") }), _jsx("p", { children: ownProfile.username }), canRenameOwnProfile ? _jsx("button", { type: "button", onClick: openOwnRename, ...agentHandle({ handle: "users-profile-change-username" }, { role: "button", label: "Change my login username" }), children: t("Change username") }) : null] }) : null, formOpen ? (_jsx(NewUserForm, { username: username, setUsername: setUsername, email: email, setEmail: setEmail, password: password, setPassword: setPassword, saving: saving, formError: formError, onCreate: onCreate, t: t })) : null, _jsx(UsersNotices, { toggleError: toggleError, notice: notice }), _jsx(UsersTable, { users: users, roles: roles, policies: policies, showGrants: canGrant, actions: {
                     expandedId,
                     toggleExpanded,
                     savingId: toggleSavingId,
                     requestDisable,
                     toggleStatus: onToggleStatus,
                     openResetPassword,
+                    renameUserHandler,
                     canDelete: canManageUserTrash,
                     rowCapabilities,
                     requestDelete,
@@ -186,6 +189,6 @@ export function Users({ useUsersHook = useUsers, port, translate: injectedTransl
                     policyGrant: canGrant
                         ? { options: policies, pendingId: pendingPolicyId, setPendingId: setPendingPolicyId, submit: onAttachPolicy }
                         : null,
-                }, t: t, translate: translate, renderServerLabel: renderServerLabel }), _jsx(UserDisableDialog, { confirmingDisable: confirmingDisable, setConfirmingDisable: setConfirmingDisable, toggleSavingId: toggleSavingId, confirmDisable: confirmDisable, t: t }), _jsx(UserDeleteDialog, { confirmingDelete: confirmingDelete, setConfirmingDelete: setConfirmingDelete, deleteSaving: deleteSaving, confirmDelete: confirmDelete, t: t }), _jsx(UserResetPasswordDialog, { resetPasswordFor: resetPasswordFor, setResetPasswordFor: setResetPasswordFor, newPassword: newPassword, setNewPassword: setNewPassword, passwordError: passwordError, setPasswordError: setPasswordError, passwordSaving: passwordSaving, confirmResetPassword: confirmResetPassword, t: t })] }));
+                }, t: t, translate: translate, renderServerLabel: renderServerLabel }), _jsx(UserDisableDialog, { confirmingDisable: confirmingDisable, setConfirmingDisable: setConfirmingDisable, toggleSavingId: toggleSavingId, confirmDisable: confirmDisable, t: t }), _jsx(UserDeleteDialog, { confirmingDelete: confirmingDelete, setConfirmingDelete: setConfirmingDelete, deleteSaving: deleteSaving, confirmDelete: confirmDelete, t: t }), _jsx(UserResetPasswordDialog, { resetPasswordFor: resetPasswordFor, setResetPasswordFor: setResetPasswordFor, newPassword: newPassword, setNewPassword: setNewPassword, passwordError: passwordError, setPasswordError: setPasswordError, passwordSaving: passwordSaving, confirmResetPassword: confirmResetPassword, t: t }), changeUsername ? _jsx(ChangeUsernameDialog, { controller: changeUsername, translate: t }) : null] }));
 }
 //# sourceMappingURL=Users.js.map

package/dist/react/users/hooks/use-change-username.hooks.d.ts

@@ -0,0 +1,27 @@
+import { type Dispatch, type SetStateAction } from "react";
+import { type Translate } from "@jini-ai/ui/panel-kit";
+import type { AdminIdentityUser } from "../../models.js";
+import type { UsersPort } from "../../ports.js";
+export interface ChangeUsernameController {
+    target: AdminIdentityUser | null;
+    username: string;
+    setUsername: Dispatch<SetStateAction<string>>;
+    error: string | null;
+    pending: boolean;
+    open: (required: {
+        user: AdminIdentityUser;
+    }, optional?: Record<string, never>) => void;
+    cancel: (required?: Record<string, never>, optional?: Record<string, never>) => void;
+    confirm: (required?: Record<string, never>, optional?: Record<string, never>) => Promise<void>;
+}
+/** Shared rename dialog lifecycle: guard, write through the existing user port, invalidate list.
+ * Failures retain the target/draft and the server's actual reason; duplicate submits are refused.
+ * @complexity O(1) client state and one PATCH per submission. No credential/session effects.
+ */
+export declare function useChangeUsername(required: {
+    port: Pick<UsersPort, "updateUser">;
+    queryScope: string;
+    translate: Translate;
+    canRename: (user: AdminIdentityUser) => boolean;
+}, _optional?: Record<string, never>): ChangeUsernameController;
+//# sourceMappingURL=use-change-username.hooks.d.ts.map

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

@@ -0,0 +1,53 @@
+import { useRef, useState } from "react";
+import { useFetchMutation } from "@jini-ai/ui/panel-kit";
+import { describeApiError, KEYS } from "../rules.js";
+/** Shared rename dialog lifecycle: guard, write through the existing user port, invalidate list.
+ * Failures retain the target/draft and the server's actual reason; duplicate submits are refused.
+ * @complexity O(1) client state and one PATCH per submission. No credential/session effects.
+ */
+export function useChangeUsername(required, _optional = {}) {
+    const [target, setTarget] = useState(null);
+    const [username, setUsername] = useState("");
+    const [error, setError] = useState(null);
+    const busy = useRef(false);
+    const mutation = useFetchMutation({
+        run: ({ input }) => required.port.updateUser({ principalId: input.principalId }, { username: input.username }),
+    }, { invalidates: [[required.queryScope, ...KEYS.list]] });
+    function open({ user }, _options = {}) {
+        if (busy.current || !required.canRename(user))
+            return;
+        setTarget(user);
+        setUsername(user.username);
+        setError(null);
+    }
+    function cancel(_input = {}, _options = {}) {
+        if (busy.current)
+            return;
+        setTarget(null);
+        setUsername("");
+        setError(null);
+    }
+    async function confirm(_input = {}, _options = {}) {
+        if (!target || busy.current || !required.canRename(target))
+            return;
+        if (!username.trim()) {
+            setError(required.translate("username must not be blank"));
+            return;
+        }
+        busy.current = true;
+        setError(null);
+        try {
+            await mutation.mutate({ input: { principalId: target.principalId, username } });
+            setTarget(null);
+            setUsername("");
+        }
+        catch (cause) {
+            setError(describeApiError({ error: cause, fallback: required.translate("failed to change username"), translate: required.translate }));
+        }
+        finally {
+            busy.current = false;
+        }
+    }
+    return { target, username, setUsername, error, pending: mutation.status === "pending", open, cancel, confirm };
+}
+//# sourceMappingURL=use-change-username.hooks.js.map

package/dist/react/users/hooks/use-users.hooks.d.ts

@@ -3,6 +3,7 @@ import type { AdminIdentityUser, AdminPolicy, AdminRole } from "../../models.js"
 import { type Translate } from "@jini-ai/ui/panel-kit";
 import { type UserAccountCapabilities } from "../rules.js";
 import type { UsersPort } from "../../ports.js";
+import { useChangeUsername } from "./use-change-username.hooks.js";
 /**
  * @file Everything the Users screen does, so `Users.tsx` is only markup.
  *
@@ -143,6 +144,14 @@ export interface UsersController {
      *  the real boundary is server-side, not this flag. */
     canManageUserTrash: boolean;
     rowCapabilities: (user: AdminIdentityUser) => UserAccountCapabilities;
+    ownProfile?: AdminIdentityUser | null;
+    canRenameUser?: ((user: AdminIdentityUser) => boolean) | undefined;
+    canRenameOwnProfile?: boolean | undefined;
+    openOwnRename?: (() => void) | undefined;
+    renameUserHandler?: ((required: {
+        user: AdminIdentityUser;
+    }) => ((user: AdminIdentityUser) => void) | undefined) | undefined;
+    changeUsername?: ReturnType<typeof useChangeUsername> | undefined;
     /** The user a `RowMenu` "Delete" selection is asking to confirm; `null` when the dialog is shut.
      *  Mirrors `confirmingDisable` exactly (own state, own request/confirm pair) rather than sharing
      *  it — Delete and Disable are two independent confirms an operator could otherwise not tell apart

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

@@ -3,6 +3,7 @@ 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, KEYS, isOwnerAccount, userAccountCapabilities } from "../rules.js";
+import { useChangeUsername } from "./use-change-username.hooks.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
@@ -164,6 +165,7 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
      *  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);
+    const [effectivePermissions, setEffectivePermissions] = useState([]);
     // `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);
@@ -174,6 +176,7 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
             .then((res) => {
             if (!cancelled) {
                 setOwnPrincipalId(res.user.id);
+                setEffectivePermissions(res.effectivePermissions ?? []);
                 setCanManageUserTrash(res.canManageUserTrash);
             }
         })
@@ -199,6 +202,28 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
             callerIsOwner: ownRow ? isOwnerAccount({ user: ownRow, roles: roleMap }) : false,
             canManageUserTrash, roles: roleMap });
     }
+    const ownProfile = users?.find(user => user.principalId === ownPrincipalId) ?? null;
+    function canRenameUser(user) {
+        if (user.canRename === false)
+            return false;
+        if (!ownPrincipalId || (!effectivePermissions.includes("*") && !effectivePermissions.includes("user.manage")))
+            return false;
+        const roleMap = new Map((roles ?? []).map(role => [role.id, role]));
+        const callerIsOwner = ownProfile ? isOwnerAccount({ user: ownProfile, roles: roleMap }) : false;
+        // Server-supplied owner flags remain authoritative when role.manage is unavailable.
+        const targetIsOwner = user.isOwner ?? (user.roleIds.some(id => !roleMap.has(id)) || isOwnerAccount({ user, roles: roleMap }));
+        return !targetIsOwner || callerIsOwner;
+    }
+    const changeUsername = useChangeUsername({ port, queryScope, translate, canRename: canRenameUser });
+    const canRenameOwnProfile = ownProfile !== null && canRenameUser(ownProfile);
+    /** Profile and row actions enter the same guarded dialog; the view only renders affordances. */
+    function openOwnRename() {
+        if (ownProfile)
+            changeUsername.open({ user: ownProfile });
+    }
+    function renameUserHandler({ user }, _options = {}) {
+        return canRenameUser(user) ? (target) => changeUsername.open({ user: target }) : undefined;
+    }
     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
@@ -443,6 +468,12 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
         confirmResetPassword,
         canManageUserTrash,
         rowCapabilities,
+        ownProfile,
+        canRenameUser,
+        canRenameOwnProfile,
+        openOwnRename,
+        renameUserHandler,
+        changeUsername,
         confirmingDelete,
         setConfirmingDelete,
         requestDelete,

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

@@ -47,6 +47,7 @@ export interface UserRowMenuHandlers {
     onEnable: (user: AdminIdentityUser) => void;
     onManage: (user: AdminIdentityUser) => void;
     onResetPassword: (user: AdminIdentityUser) => void;
+    onChangeUsername?: ((user: AdminIdentityUser) => void) | undefined;
     /** 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`

package/dist/react/users/rules.js

@@ -127,6 +127,9 @@ export function userRowMenuItems({ user, toggleSaving, handlers, translate, canD
     const permissions = typeof capabilities === "boolean"
         ? { canDelete: capabilities, canDisable: true, canEnable: true, canResetPassword: true }
         : capabilities;
+    if (handlers.onChangeUsername) {
+        items.push({ key: "change-username", label: translate("Change username"), onSelect: () => handlers.onChangeUsername?.(user) });
+    }
     if (permissions.canDelete) {
         items.push({
             key: "delete",

package/dist/server/admin-crud-service.d.ts

@@ -75,12 +75,13 @@ export declare function enablePrincipal(required: {
 }>;
 /**
  * `UPDATE_USER` (feature.spec.md ). Gated by `user.manage`; existing self-profile edits also
- * accept `member.manage`. Only owners may edit owner targets — `email` only; `username`/`password` are not
- * this transition's concern ( respectively). An absent or empty-string `email`
+ * accept `member.manage`. Username changes require `user.manage`, including self edits.
+ * Only owners may edit owner targets. Password is not this transition's concern.
+ * An absent or empty-string `email`
  * clears the stored value to `undefined` ( — no distinct "blank but present" state).
  *
- * @complexity O(1) — one lookup, one save.
- * @overallScore 100
+ * @complexity O(n) normalization for n username characters; fixed repo/Trash reads, one user save
+ * and one audit append for an actual rename, all inside the shared identity transaction.
  * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
  */
 export declare function updateUser(required: {
@@ -92,6 +93,7 @@ export declare function updateUser(required: {
     };
 }, optional?: {
     email?: string | undefined;
+    username?: string | undefined;
 }): Promise<{
     user: UserRecord;
 }>;

package/dist/server/admin-crud-service.js

@@ -2,6 +2,7 @@ import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
 import { inIdentityTransaction } from "./identity-transaction.js";
 import { assertCallerHasAnyPermission, assertGrantClamp, assertOwnerTargetMayBeModified, principalHoldsOwnerWildcard } from "./grant-service.js";
 import { validatePasswordPolicy } from "./password-policy.js";
+import { normalizeUsername } from "./username.js";
 import { isKnownPermission } from "../core/permissions.js";
 import { principalKindMayExercisePermission } from "../core/principal-kind-policy.js";
 import { IdentityConflictError, IdentityNotFoundError, IdentityValidationError, OwnerRequiredError, PermissionUnknownError, } from "../core/types.js";
@@ -138,12 +139,13 @@ export async function enablePrincipal(required) {
 }
 /**
  * `UPDATE_USER` (feature.spec.md ). Gated by `user.manage`; existing self-profile edits also
- * accept `member.manage`. Only owners may edit owner targets — `email` only; `username`/`password` are not
- * this transition's concern ( respectively). An absent or empty-string `email`
+ * accept `member.manage`. Username changes require `user.manage`, including self edits.
+ * Only owners may edit owner targets. Password is not this transition's concern.
+ * An absent or empty-string `email`
  * clears the stored value to `undefined` ( — no distinct "blank but present" state).
  *
- * @complexity O(1) — one lookup, one save.
- * @overallScore 100
+ * @complexity O(n) normalization for n username characters; fixed repo/Trash reads, one user save
+ * and one audit append for an actual rename, all inside the shared identity transaction.
  * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
  */
 export async function updateUser(required, optional = {}) {
@@ -158,7 +160,7 @@ export async function updateUser(required, optional = {}) {
                 workspaceId: input.workspaceId,
                 callerPrincipalId: input.callerPrincipalId,
                 // Preserve existing self-profile access without letting member.manage edit other operators.
-                permissions: input.callerPrincipalId === input.principalId
+                permissions: input.username === undefined && input.callerPrincipalId === input.principalId
                     ? ["user.manage", "member.manage"]
                     : ["user.manage"],
             });
@@ -174,12 +176,53 @@ export async function updateUser(required, optional = {}) {
                 callerPrincipalId: input.callerPrincipalId,
                 principalId: input.principalId,
             });
-            const updated = { ...target, email: input.email ? input.email : undefined };
+            const username = input.username === undefined ? target.username : await resolveUpdatedUsername({ deps, input, target });
+            // Preserve the old email setter contract, while a username-only call retains email.
+            const email = input.username !== undefined && !Object.hasOwn(optional, "email")
+                ? target.email : (input.email || undefined);
+            const updated = { ...target, username, email };
             await deps.repos.users.save(updated);
+            if (username !== target.username) {
+                // Renaming never changes the principal id or credentials: existing sessions stay valid.
+                await deps.usernameChanges.record({ workspaceId: input.workspaceId, principalId: input.principalId,
+                    callerPrincipalId: input.callerPrincipalId, previousUsername: target.username, username,
+                    occurredAt: kernelNowIso({ clock: deps.clock }) });
+            }
             return { user: updated };
         },
     });
 }
+/** Validate and reserve a normalized name inside the caller's identity transaction.
+ * Permission/owner gates run first, so conflicts never disclose accounts to unauthorized callers.
+ * @complexity O(n) normalization for n username characters; one indexed lookup and up to two Trash reads.
+ * Throws validation or conflict errors; performs no writes.
+ */
+async function resolveUpdatedUsername(required, _optional = {}) {
+    const { deps, input, target } = required;
+    if (typeof input.username !== "string")
+        throw new IdentityValidationError({ message: "username must be a string" });
+    const username = normalizeUsername({ raw: input.username });
+    if (!username)
+        throw new IdentityValidationError({ message: "username must not be blank" });
+    // Missing host ports are internal wiring faults, not user input errors (HTTP 500, not 400).
+    if (!deps.usernameChanges)
+        throw new Error("username changes are not configured");
+    if (await deps.usernameChanges.isInTrash({ workspaceId: input.workspaceId, principalId: input.principalId })) {
+        throw new IdentityConflictError({ message: "this user is in the Trash; restore them first", code: "USER_IN_TRASH" });
+    }
+    if (username !== target.username) {
+        await deps.usernameChanges.assertSupported?.({ workspaceId: input.workspaceId, principalId: input.principalId });
+    }
+    // Trash keeps credential rows until purge, so the unfiltered lookup reserves those names too.
+    const existing = await deps.repos.users.findByUsername({ workspaceId: input.workspaceId, username });
+    if (existing && existing.principalId !== target.principalId) {
+        if (await deps.usernameChanges.isInTrash({ workspaceId: input.workspaceId, principalId: existing.principalId })) {
+            throw new IdentityConflictError({ message: "a user with this username is in the Trash; restore or delete them permanently first", code: "USERNAME_IN_TRASH" });
+        }
+        throw new IdentityConflictError({ message: `username '${username}' is already in use`, code: "RESOURCE_CONFLICT" });
+    }
+    return username;
+}
 /**
  * `RESET_USER_PASSWORD` (feature.spec.md ). Gated by **`user.manage`** only
  * (resetting a credential is at least as sensitive as disabling the account, own reasoning). Hashes the new password identically to `CREATE_USER` (argon2id,

package/dist/server/agent-tool-registrations.d.ts

@@ -40,6 +40,7 @@ export interface IdentityToolDeps {
     /** Bind the same transaction port as every grant/status writer. */
     transactions: IdentityRepos["transactions"];
     tokens: AuthServiceDeps["tokens"];
+    usernameChanges?: AuthServiceDeps["usernameChanges"];
 }
 /**
  * This wiring layer's OWN risk classification, authored from what each handler below actually

package/dist/server/agent-tool-registrations.js

@@ -48,6 +48,7 @@ function identityServiceDepsFrom(deps) {
         clock: deps.clock,
         idGen: deps.idGen,
         tokens: deps.tokens,
+        usernameChanges: deps.usernameChanges,
     };
 }
 /**
@@ -64,6 +65,8 @@ export const identityDerivedRisk = new Map([
     ["identity_user_create", "mutates-durable-state"],
     // -> updateUser (admin-crud-service.ts): users.save, email field only.
     ["identity_user_update_email", "mutates-durable-state"],
+    // -> updateUser (admin-crud-service.ts): users.save, username field only, plus the transactional audit.
+    ["identity_user_change_username", "mutates-durable-state"],
     // -> disablePrincipal (admin-crud-service.ts): status flip, guarded by the owner floor. See docs/decisions/DR-007-workspace-and-owner-floors.md.
     ["identity_user_disable", "mutates-durable-state"],
     // -> enablePrincipal (admin-crud-service.ts): status flip back to active.
@@ -283,6 +286,17 @@ export function buildIdentityRegistrations(routeDeps) {
                 throw new Error(`principal '${input.req("principalId")}' was not found`);
             return { user: toIdentityUserView({ principal, user, roleIds: await roleIdsFor(routeDeps, principal.id) }) };
         },
+        identity_user_change_username: async (ctx) => {
+            const input = identityInput("identity_user_change_username", ctx.input);
+            const principalId = input.req("principalId");
+            const { user } = await updateUser({ deps: serviceDeps(), input: {
+                    workspaceId: routeDeps.workspaceId, callerPrincipalId: ctx.principal.id, principalId,
+                } }, { username: input.req("username") });
+            const principal = await routeDeps.principalRepo.findById({ workspaceId: routeDeps.workspaceId, id: principalId });
+            if (!principal)
+                throw new Error(`principal '${principalId}' was not found`);
+            return { user: toIdentityUserView({ principal, user, roleIds: await roleIdsFor(routeDeps, principalId) }) };
+        },
         identity_user_disable: async (ctx) => {
             const input = identityInput("identity_user_disable", ctx.input);
             const { principal } = await disablePrincipal({

package/dist/server/agent-tools.js

@@ -106,6 +106,17 @@ export const identityAgentToolCatalog = [
             },
         },
     },
+    {
+        name: "identity_user_change_username",
+        description: "Changes an operator user's login username. Call after finding their principalId with identity_user_list. Returns { user } with the normalized username; email, password and existing sessions stay unchanged. Requires user.manage even for your own profile; only owners may rename owner accounts. Fails for blank names, missing users, users in Trash, or names reserved by any user including Trash. Choose a different name or restore/purge the conflicting trashed user before retrying.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "user.manage" },
+        inputSchema: {
+            type: "object", additionalProperties: false, required: ["principalId", "username"],
+            properties: { principalId: PRINCIPAL_ID_SCHEMA, username: { type: "string", minLength: 1,
+                    description: "New login name. Trimmed, lowercased and Unicode NFC normalized; unique per workspace, including users in Trash." } },
+        },
+    },
     {
         name: "identity_user_disable",
         description: "Disables a user, revoking their access. Principals are never hard-deleted because the audit trail references them, so this is how a user is removed. Refuses to disable the seeded owner, and refuses any disable that would leave the workspace with no active owner. Already-disabled is a no-op.",

package/dist/server/auth-service.d.ts

@@ -1,5 +1,5 @@
 import { type UserManagementMessages } from "./messages.js";
-import type { SessionTokenPort } from "../core/runtime-ports.js";
+import type { SessionTokenPort, UsernameChangePort } from "../core/runtime-ports.js";
 import type { Clock, IdGenerator, ISODateTime, UUID } from "@jini-ai/core/primitives";
 import type { IdentityRepos, PasswordHasherPort } from "../core/ports.js";
 import { type PrincipalRecord, type SessionRecord } from "../core/types.js";
@@ -9,6 +9,8 @@ export interface AuthServiceDeps {
     clock: Clock;
     idGen: IdGenerator;
     tokens: SessionTokenPort;
+    /** Additive: legacy email updates need no rename lifecycle; renames require it. */
+    usernameChanges?: UsernameChangePort | undefined;
 }
 /**
  * Mint and persist a session for a principal the caller has ALREADY identified by some means

package/dist/server/seed.d.ts

@@ -24,6 +24,8 @@ export interface SeedIdentityInput {
 }
 export interface SeedIdentityOptions {
     ownerEmail?: string | undefined;
+    /** Stable bootstrap binding persisted by the host. Never derive this from a mutable login/title. */
+    seededOwnerPrincipalId?: UUID | undefined;
 }
 export interface SeedIdentityResult {
     ownerPrincipalId: UUID;
@@ -33,8 +35,8 @@ export interface SeedIdentityResult {
  * Seed first-boot identity data.
  *
  * Idempotent in two distinct senses, and both are load-bearing:
- * - A seed that RAN TO COMPLETION is a no-op — the owner-username lookup below early-returns after
- *   a single confirming read (`ensureOwnerRoleBinding`) and writes nothing. (This path does not
+ * - A seed that RAN TO COMPLETION is a no-op — the owner lookup below early-returns after
+ *   confirming its role binding (`ensureOwnerRoleBinding`) and writes nothing. (This path does not
  *   reconcile a built-in policy whose permission list has since grown; that is the host's job — see
  *   the host's `applyBuiltinRoleGrants` / `migrateDeprecatedPermissionGrants`, chained onto
  *   `identityReady`.)
@@ -45,8 +47,9 @@ export interface SeedIdentityResult {
  *   previous attempt already wrote and fills in only what is missing. See the block comment above
  *   `ensureBuiltinRole` for why this function must survive being killed halfway.
  *
- * @complexity O(1) — fixed small number of inserts (4 roles/policies, ~2
- * dozen policy_permissions, 3 principals, 1 user, 1 role assignment).
+ * @complexity O(1) owner lookup plus the existing principal roster read; fresh seeds make a
+ * fixed small number of inserts (4 roles/policies, ~2 dozen policy_permissions,
+ * 3 principals, 1 user, 1 role assignment).
  * @overallScore 100
  */
 export declare function seedIdentity(required: {

package/dist/server/seed.js

@@ -1,5 +1,6 @@
 import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
 import { normalizeUsername } from "./username.js";
+import { IdentityNotFoundError } from "../core/types.js";
 /**
  * @file First-boot identity seed (state.spec `SEED_FIRST_BOOT`).
  *
@@ -20,7 +21,7 @@ import { normalizeUsername } from "./username.js";
  * Seed data lives in one place so both composition roots stay identical
  * (mirrors `server/seed.ts`'s reasoning for workspace/post/presentation seed
  * data). Idempotent: re-seeding an already-seeded workspace is a no-op
- * (checked via the owner username).
+ * (checked via a host-supplied stable principal id, or the legacy owner username).
  * See docs/decisions/DR-001-identity-and-session-boundary.md.
  */
 /** : the literal id the legacy Article VI actor stamp resolves to. See docs/decisions/DR-001-identity-and-session-boundary.md. */
@@ -303,8 +304,8 @@ async function ensureOwnerRoleBinding(required) {
  * Seed first-boot identity data.
  *
  * Idempotent in two distinct senses, and both are load-bearing:
- * - A seed that RAN TO COMPLETION is a no-op — the owner-username lookup below early-returns after
- *   a single confirming read (`ensureOwnerRoleBinding`) and writes nothing. (This path does not
+ * - A seed that RAN TO COMPLETION is a no-op — the owner lookup below early-returns after
+ *   confirming its role binding (`ensureOwnerRoleBinding`) and writes nothing. (This path does not
  *   reconcile a built-in policy whose permission list has since grown; that is the host's job — see
  *   the host's `applyBuiltinRoleGrants` / `migrateDeprecatedPermissionGrants`, chained onto
  *   `identityReady`.)
@@ -315,8 +316,9 @@ async function ensureOwnerRoleBinding(required) {
  *   previous attempt already wrote and fills in only what is missing. See the block comment above
  *   `ensureBuiltinRole` for why this function must survive being killed halfway.
  *
- * @complexity O(1) — fixed small number of inserts (4 roles/policies, ~2
- * dozen policy_permissions, 3 principals, 1 user, 1 role assignment).
+ * @complexity O(1) owner lookup plus the existing principal roster read; fresh seeds make a
+ * fixed small number of inserts (4 roles/policies, ~2 dozen policy_permissions,
+ * 3 principals, 1 user, 1 role assignment).
  * @overallScore 100
  */
 export async function seedIdentity(required, optional = {}) {
@@ -326,7 +328,14 @@ export async function seedIdentity(required, optional = {}) {
     const ownerUsername = normalizeUsername({ raw: input.ownerUsername });
     const ownerPassword = input.ownerPassword;
     const nowIso = kernelNowIso({ clock: deps.clock });
-    const existingOwnerUser = await deps.repos.users.findByUsername({
+    // An explicit binding is authoritative, even when somebody has reused its former login name.
+    // A missing bound row is an error, never permission to mint a replacement owner.
+    const seededOwnerUser = input.seededOwnerPrincipalId !== undefined
+        ? await deps.repos.users.findByPrincipalId({ workspaceId, principalId: input.seededOwnerPrincipalId }) : null;
+    if (input.seededOwnerPrincipalId !== undefined && !seededOwnerUser) {
+        throw new IdentityNotFoundError({ message: "the bound seeded owner user was not found; restore the owner identity before booting" });
+    }
+    const existingOwnerUser = seededOwnerUser ?? await deps.repos.users.findByUsername({
         workspaceId,
         username: ownerUsername,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/user-management",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Runtime-separated user management contracts and Node authentication, authorization, and administration services.",
   "license": "Apache-2.0",
   "repository": {
@@ -87,16 +87,16 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@jini-ai/core": "^0.4.2"
+    "@jini-ai/core": "^0.4.3"
   },
   "peerDependencies": {
     "argon2": "^0.44.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0",
-    "@jini-ai/ui": "^0.4.0",
-    "@jini-ai/admin": "^0.4.0",
-    "@jini-ai/agentic": "^0.4.0",
-    "@jini-ai/ui-kit": "^0.1.1"
+    "@jini-ai/ui": "^0.4.8",
+    "@jini-ai/admin": "^0.4.6",
+    "@jini-ai/agentic": "^0.4.4",
+    "@jini-ai/ui-kit": "^0.1.3"
   },
   "peerDependenciesMeta": {
     "argon2": {
@@ -134,12 +134,12 @@
     "@testing-library/user-event": "^14.5.0",
     "@testing-library/jest-dom": "^6.6.3",
     "jsdom": "^25.0.1",
-    "@jini-ai/ui": "0.4.5",
-    "@jini-ai/cms": "0.5.3",
-    "@jini-ai/core": "^0.4.2",
-    "@jini-ai/ui-kit": "^0.1.2",
-    "@jini-ai/agentic": "0.4.3",
-    "@jini-ai/admin": "0.4.3"
+    "@jini-ai/ui": "0.4.8",
+    "@jini-ai/core": "^0.4.3",
+    "@jini-ai/agentic": "0.4.4",
+    "@jini-ai/admin": "0.4.6",
+    "@jini-ai/ui-kit": "^0.1.3",
+    "@jini-ai/cms": "0.5.6"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",