@jini-ai/user-management 0.3.0 → 0.3.2

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

@@ -1,33 +1,141 @@
 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;
+    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`
+     *  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

package/dist/react/users/rules.js

@@ -1,20 +1,101 @@
 import { describeIdentityError } from "../errors.js";
+/**
+ * @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 const KEYS = {
     list: ["users-roles-policies"],
 };
+/** Server error `code` -> a plain-language prefix, for every code on this screen whose message is
+ *  a fixed string. Keyed by the same closed set of `ApiError` codes the old if-chain checked, in a
+ *  flat lookup rather than sequential branches — this is what actually lowered the function's
+ *  cognitive score (11 -> under the ceiling): the codes are a closed set of *literal string* keys,
+ *  not a discriminated union, so there is no TypeScript exhaustiveness to lose by using a table
+ *  (contrast `translateRunAgentPayload`'s `switch`, which stays a `switch` for exactly that reason).
+ *  Values are the English source strings — `t()`'s own keys — not yet localized; `describeApiError`
+ *  below is what translates them. */
 const STATIC_ERROR_MESSAGES = {
     GRANT_EXCEEDS_ISSUER: "You cannot grant a permission you do not hold.",
     FORBIDDEN: "You do not have permission to do that.",
     RESOURCE_CONFLICT: "That username is already in use.",
     OWNER_REQUIRED: "The workspace must keep at least one active owner.",
+    // Delete-user plan v2 (2026-09-24), Slice 3/decision 7 — the DELETE route's own 409s.
     SELF_DELETE: "You cannot delete your own account.",
     USER_IN_TRASH: "This user is in the Trash; restore them first.",
     USERNAME_IN_TRASH: "A user with this username is in the Trash; restore or delete them permanently first.",
 };
-export 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 function describeUsersError({ error, fallback, translate }, _optional = {}) {
     return describeIdentityError({ error, fallback, translate }, { messages: STATIC_ERROR_MESSAGES });
 }
-export function userRowMenuItems({ user, toggleSaving, handlers, translate, canDelete }) {
+export { describeUsersError as describeApiError };
+/** Courtesy mirror of the server target rule. Unknown identity/roles fail closed. */
+export function userAccountCapabilities(required, _optional = {}) {
+    const { user, callerPrincipalId, callerIsOwner, canManageUserTrash, roles } = required;
+    const known = callerPrincipalId !== null;
+    const protectedAccount = user.isProtectedAccount ?? (user.roleIds.some(id => {
+        const role = roles.get(id);
+        return !role || (role.isBuiltin && (role.name === "admin" || role.name === "owner"));
+    }));
+    const mayAct = known && (callerIsOwner || !protectedAccount);
+    const destructive = mayAct && callerPrincipalId !== user.principalId;
+    return { canDelete: destructive && canManageUserTrash, canDisable: destructive,
+        canEnable: mayAct, canResetPassword: mayAct };
+}
+export function isOwnerAccount(required, _optional = {}) {
+    return required.user.isOwner ?? required.user.roleIds.some(id => {
+        const role = required.roles.get(id);
+        return role?.isBuiltin === true && role.name === "owner";
+    });
+}
+/**
+ * `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 function userRowMenuItems({ user, toggleSaving, handlers, translate, canDelete, capabilities = canDelete }, _optional = {}) {
     const items = [
         {
             key: "toggle",
@@ -43,7 +124,13 @@ export function userRowMenuItems({ user, toggleSaving, handlers, translate, canD
             onSelect: () => handlers.onResetPassword(user),
         },
     ];
-    if (canDelete) {
+    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",
             label: translate("Delete"),
@@ -51,11 +138,30 @@ export function userRowMenuItems({ user, toggleSaving, handlers, translate, canD
             onSelect: () => handlers.onRequestDelete(user),
         });
     }
-    return items;
+    return items.filter(item => item.key === "toggle"
+        ? (user.status === "active" ? permissions.canDisable : permissions.canEnable)
+        : item.key !== "reset-password" || permissions.canResetPassword);
+}
+/**
+ * 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 function grantOptionLabel(required, _optional = {}) {
+    return required.option.isBuiltin && required.option.name === "owner" ? required.translate("Owner") : required.option.name;
 }
-export function formatGrantLabel({ ids, byId }) {
+export function formatGrantLabel({ ids, byId, translate = (key) => key }, _optional = {}) {
     if (ids.length === 0)
         return null;
-    return ids.map((id) => byId.get(id)?.name ?? id).join(", ");
+    return ids.map(id => {
+        const role = byId.get(id);
+        return role?.isBuiltin && role.name === "owner" ? translate("Owner") : role?.name ?? id;
+    }).join(", ");
 }
 //# sourceMappingURL=rules.js.map

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,
     });