@jini-ai/user-management 0.2.0 → 0.3.1

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

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

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,10 @@ 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 (permissions.canDelete) {
         items.push({
             key: "delete",
             label: translate("Delete"),
@@ -51,11 +135,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.js

@@ -3,6 +3,7 @@ import { inIdentityTransaction } from "./identity-transaction.js";
 import { assertCallerHasAnyPermission, assertGrantClamp, assertOwnerTargetMayBeModified, principalHoldsOwnerWildcard } from "./grant-service.js";
 import { validatePasswordPolicy } from "./password-policy.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";
 /**
  * @file An amendment that completes the users/roles/policies admin CRUD surface
@@ -554,7 +555,9 @@ export async function removePolicyPermission(required) {
 async function countActiveOwnerWildcardPrincipals(required) {
     const { deps, workspaceId } = required;
     const principals = await deps.repos.principals.list({ workspaceId });
-    const activePrincipals = principals.filter((principal) => principal.status === "active");
+    // A kind barred from operator permissions (a site `member`) can never act as an owner, so it is
+    // not counted even if a `*` row reaches it — and members never cost a grant read here.
+    const activePrincipals = principals.filter((principal) => principal.status === "active" && principalKindMayExercisePermission({ kind: principal.kind, permission: "*" }));
     const flags = await Promise.all(activePrincipals.map((principal) => principalHoldsOwnerWildcard({ deps, workspaceId, principalId: principal.id })));
     return flags.filter(Boolean).length;
 }

package/dist/server/authorize.d.ts

@@ -19,8 +19,8 @@ import type { PolicyPermissionRecord } from "../core/types.js";
  *
  * Architectural role:
  * Implements the matcher precedence in behavior.spec §1.1 exactly:
- * disabled-principal short-circuit > owner wildcard > exact matching row >
- * fail-closed default. Fail-closed extensibility: a non-null
+ * disabled-principal short-circuit > principal-kind bar > owner wildcard >
+ * exact matching row > fail-closed default. Fail-closed extensibility: a non-null
  * `constraintJson` is never treated as unconstrained, and a `resourceType`
  * mismatch/absence is never treated as a global grant.
  * See docs/decisions/DR-001-identity-and-session-boundary.md.
@@ -34,7 +34,7 @@ export interface AuthorizeContext {
 /** `authorize`'s result — always fail-closed on `allowed: false`. See docs/decisions/DR-001-identity-and-session-boundary.md. */
 export interface AuthorizeResult {
     allowed: boolean;
-    /** Machine-readable reason: `principal_disabled | no_grant | resource_scope_mismatch | unconstrained_deny | owner_wildcard | matched`. */
+    /** Machine-readable reason: `principal_disabled | principal_kind_denied | no_grant | resource_scope_mismatch | unconstrained_deny | owner_wildcard | matched`. */
     reason: string;
 }
 /** Repos `authorize()`/`resolveEffectivePermissions()` read. Not a port bag with alternate adapters — see file header. */
@@ -68,10 +68,13 @@ export declare function resolveEffectivePermissions(required: {
  *
  * Precedence (behavior.spec §1.1, highest to lowest):
  * 1. Disabled principal -> `false`, `principal_disabled` (overrides all grants).
- * 2. An unconstrained owner `"*"` row -> `true`, `owner_wildcard`.
- * 3. An exact matching row (permission + workspace + resource-scope + no
+ * 2. A principal whose kind may not exercise `permission` (today: `member`, see
+ * `principal-kind-policy.ts`) -> `false`, `principal_kind_denied` (overrides all grants,
+ * including the owner wildcard).
+ * 3. An unconstrained owner `"*"` row -> `true`, `owner_wildcard`.
+ * 4. An exact matching row (permission + workspace + resource-scope + no
  * constraint) -> `true`, `matched`.
- * 4. Fail-closed default -> `false`, with the most specific diagnostic reason
+ * 5. Fail-closed default -> `false`, with the most specific diagnostic reason
  * available among same-permission candidates (`unconstrained_deny` over
  * `resource_scope_mismatch` over `no_grant` — an inferred, undocumented-but-
  * reasonable tie-break; the spec only pins each reason in isolation, see

package/dist/server/authorize.js

@@ -1,3 +1,4 @@
+import { principalKindMayExercisePermission } from "../core/principal-kind-policy.js";
 /**
  * Resolve a principal's effective permission rows: the union of (a) its
  * roles' policies' permissions and (b) policies attached directly via
@@ -46,10 +47,13 @@ function matchesRow(row, permission, context) {
  *
  * Precedence (behavior.spec §1.1, highest to lowest):
  * 1. Disabled principal -> `false`, `principal_disabled` (overrides all grants).
- * 2. An unconstrained owner `"*"` row -> `true`, `owner_wildcard`.
- * 3. An exact matching row (permission + workspace + resource-scope + no
+ * 2. A principal whose kind may not exercise `permission` (today: `member`, see
+ * `principal-kind-policy.ts`) -> `false`, `principal_kind_denied` (overrides all grants,
+ * including the owner wildcard).
+ * 3. An unconstrained owner `"*"` row -> `true`, `owner_wildcard`.
+ * 4. An exact matching row (permission + workspace + resource-scope + no
  * constraint) -> `true`, `matched`.
- * 4. Fail-closed default -> `false`, with the most specific diagnostic reason
+ * 5. Fail-closed default -> `false`, with the most specific diagnostic reason
  * available among same-permission candidates (`unconstrained_deny` over
  * `resource_scope_mismatch` over `no_grant` — an inferred, undocumented-but-
  * reasonable tie-break; the spec only pins each reason in isolation, see
@@ -68,6 +72,10 @@ export async function authorize(required, optional = {}) {
     if (!principal || principal.status === "disabled") {
         return { allowed: false, reason: "principal_disabled" };
     }
+    // Ahead of every grant read: a barred kind is denied even when a `*` row reaches it.
+    if (!principalKindMayExercisePermission({ kind: principal.kind, permission })) {
+        return { allowed: false, reason: "principal_kind_denied" };
+    }
     const effectiveRows = await resolveEffectivePermissions({
         deps,
         principalId,

package/dist/server/permission-migrations.d.ts

@@ -16,11 +16,17 @@ import type { IdentityTransactionPort, PolicyPermissionRepoPort, PolicyRepoPort
  * hand-rolling a fourth divergent copy of the same fix.
  *
  * How it relates to the project:
- * - `registerPermissionMigration`/`listPermissionMigrations` are a small,
- * in-process registry — pure metadata, no I/O, mirrors
- * `permissions.ts`'s `PermissionCatalog.register` overwrite semantics.
+ * - `createPermissionMigrationRegistry` builds a small, in-process registry
+ * object — pure metadata, no I/O, mirrors `permissions.ts`'s
+ * `PermissionCatalog.register` overwrite semantics. A host creates ONE at its
+ * composition root and registers its own pairs on it explicitly; there is no
+ * module-scope registry, so which migrations exist never depends on which
+ * modules a process happened to import (a module-singleton filled by import
+ * side effects once ran a standalone script's boot reconciliation against an
+ * empty registry because that script never imported the registering module).
  * - `migrateDeprecatedPermissionGrants` is the actual grant fan-out: for
- * every registered pair, every policy holding `from` gets every string in
+ * every pair the caller passes in `deps.migrations` (normally its registry's
+ * `list({})`), every policy holding `from` gets every string in
  * `to` it doesn't already hold. It is deliberately, structurally
  * additive-only — there is no delete/update call against
  * `policy_permissions` anywhere in this file.
@@ -42,29 +48,43 @@ export type { PermissionMigration } from '../core/builtin-permissions.js';
 export interface MigrateDeprecatedPermissionGrantsDeps {
     /** Bound to the same storage as both repository ports; required before any migration work. */
     transactions: IdentityTransactionPort;
+    /** Every `{from, to}` pair to fan out — normally `createPermissionMigrationRegistry(...).list({})`. */
+    migrations: readonly PermissionMigration[];
     policyPermissions: PolicyPermissionRepoPort;
     policies: PolicyRepoPort;
     idGen: IdGenerator;
     workspaceId: UUID;
 }
 export interface MigrateDeprecatedPermissionGrantsResult {
-    /** Total new `policy_permissions` rows written across every policy and every registered pair. */
+    /** Total new `policy_permissions` rows written across every policy and every passed pair. */
     migratedGrantCount: number;
 }
+/** A host-owned set of `{from, to, reason}` pairs; see {@link createPermissionMigrationRegistry}. */
+export interface PermissionMigrationRegistry {
+    /**
+     * Register a `{from, to, reason}` rename/split pair for later fan-out.
+     * Idempotent: re-registering the same `from` overwrites the prior entry
+     * rather than duplicating it (matches `PermissionCatalog.register`'s
+     * existing overwrite semantics, `identity/permissions.ts`).
+     *
+     * @complexity O(1).
+     */
+    register(migration: PermissionMigration): void;
+    /** Enumerate every registered migration pair, built-ins first, in first-registration order. */
+    list(_required: Record<string, never>): PermissionMigration[];
+}
 /**
- * Register a `{from, to, reason}` rename/split pair for later fan-out.
- * Idempotent: re-registering the same `from` overwrites the prior entry
- * rather than duplicating it (matches `PermissionCatalog.register`'s
- * existing overwrite semantics, `identity/permissions.ts`).
+ * Create a migration registry seeded with the library's built-in pairs, then `optional.migrations`.
+ * Keyed by `from`, so a host pair with a built-in's `from` overwrites it rather than duplicating.
  *
- * @complexity O(1).
+ * @complexity O(b + m) where b = built-in pairs and m = `optional.migrations`.
  * @overallScore 100
  */
-export declare function registerPermissionMigration(migration: PermissionMigration): void;
-/** Enumerate every registered migration pair. */
-export declare function listPermissionMigrations(_required: Record<string, never>): PermissionMigration[];
+export declare function createPermissionMigrationRegistry(_required?: Record<string, never>, optional?: {
+    migrations?: readonly PermissionMigration[];
+}): PermissionMigrationRegistry;
 /**
- * For every registered `{from, to}` pair, for every policy in the workspace
+ * For every `{from, to}` pair in `deps.migrations`, for every policy in the workspace
  * holding `from`, ensure every string in `to` is also granted — adding only
  * the rows that are missing. Never removes or mutates `from` (or any other
  * existing row) — additive-only by construction. The entire fan-out runs in
@@ -75,7 +95,7 @@ export declare function listPermissionMigrations(_required: Record<string, never
  * returns `migratedGrantCount: 0` (mirrors `migrateLegacyPresentationSettings`'s
  * boot-safety precedent).
  *
- * @complexity O(p * m) where p = policies in the workspace, m = registered
+ * @complexity O(p * m) where p = policies in the workspace, m = passed
  * migration pairs; both are small, bounded collections in this app's shape.
  * @overallScore 100
  * See docs/decisions/DR-003-additive-permission-migration.md.

package/dist/server/permission-migrations.js

@@ -1,25 +1,25 @@
 import { inIdentityTransaction } from "./identity-transaction.js";
 import { BUILTIN_PERMISSION_MIGRATIONS } from '../core/builtin-permissions.js';
-/** Module-singleton registry — keyed by `from` so re-registration overwrites (idempotent, matches `PermissionCatalog.register`). */
-const registry = new Map(BUILTIN_PERMISSION_MIGRATIONS.map((migration) => [migration.from, migration]));
 /**
- * Register a `{from, to, reason}` rename/split pair for later fan-out.
- * Idempotent: re-registering the same `from` overwrites the prior entry
- * rather than duplicating it (matches `PermissionCatalog.register`'s
- * existing overwrite semantics, `identity/permissions.ts`).
+ * Create a migration registry seeded with the library's built-in pairs, then `optional.migrations`.
+ * Keyed by `from`, so a host pair with a built-in's `from` overwrites it rather than duplicating.
  *
- * @complexity O(1).
+ * @complexity O(b + m) where b = built-in pairs and m = `optional.migrations`.
  * @overallScore 100
  */
-export function registerPermissionMigration(migration) {
-    registry.set(migration.from, migration);
-}
-/** Enumerate every registered migration pair. */
-export function listPermissionMigrations(_required) {
-    return [...registry.values()];
+export function createPermissionMigrationRegistry(_required = {}, optional = {}) {
+    const byFrom = new Map();
+    const register = (migration) => {
+        byFrom.set(migration.from, migration);
+    };
+    for (const migration of BUILTIN_PERMISSION_MIGRATIONS)
+        register(migration);
+    for (const migration of optional.migrations ?? [])
+        register(migration);
+    return { register, list: () => [...byFrom.values()] };
 }
 /**
- * For every registered `{from, to}` pair, for every policy in the workspace
+ * For every `{from, to}` pair in `deps.migrations`, for every policy in the workspace
  * holding `from`, ensure every string in `to` is also granted — adding only
  * the rows that are missing. Never removes or mutates `from` (or any other
  * existing row) — additive-only by construction. The entire fan-out runs in
@@ -30,13 +30,13 @@ export function listPermissionMigrations(_required) {
  * returns `migratedGrantCount: 0` (mirrors `migrateLegacyPresentationSettings`'s
  * boot-safety precedent).
  *
- * @complexity O(p * m) where p = policies in the workspace, m = registered
+ * @complexity O(p * m) where p = policies in the workspace, m = passed
  * migration pairs; both are small, bounded collections in this app's shape.
  * @overallScore 100
  * See docs/decisions/DR-003-additive-permission-migration.md.
  */
 export async function migrateDeprecatedPermissionGrants(deps) {
-    const migrations = listPermissionMigrations({});
+    const { migrations } = deps;
     if (migrations.length === 0)
         return { migratedGrantCount: 0 };
     return inIdentityTransaction({

package/dist/server/seed.js

@@ -126,7 +126,12 @@ const BUILTIN_ADMIN_PERMISSIONS = [
     // directly at seed — a distinct grant from settings.write, not owner-only (unlike user.manage/
     // role.manage below).
     "workspace.manage",
-    // Owner-only per : "user.manage", "role.manage" are deliberately absent. See docs/decisions/DR-001-identity-and-session-boundary.md.
+    // Roles & Permissions: admin holds role.manage (owner decision 2026-10-05, reversing DR-001's
+    // owner-only placement for this one string). The grant service's issuer clamp still refuses any
+    // grant beyond what the caller holds (GRANT_EXCEEDS_ISSUER), so an admin cannot hand out owner.
+    // Hosts reconcile already-seeded workspaces themselves; seedIdentity never revisits them.
+    "role.manage",
+    // Owner-only per DR-001: "user.manage" is deliberately absent. See docs/decisions/DR-001-identity-and-session-boundary.md.
 ];
 const BUILTIN_EDITOR_PERMISSIONS = [
     "content.read",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/user-management",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Runtime-separated user management contracts and Node authentication, authorization, and administration services.",
   "license": "Apache-2.0",
   "repository": {
@@ -86,13 +86,17 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "dependencies": {
+    "@jini-ai/core": "^0.4.2"
+  },
   "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/agentic": "^0.4.0",
+    "@jini-ai/ui-kit": "^0.1.1"
   },
   "peerDependenciesMeta": {
     "argon2": {
@@ -112,6 +116,9 @@
     },
     "@jini-ai/agentic": {
       "optional": true
+    },
+    "@jini-ai/ui-kit": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -127,14 +134,12 @@
     "@testing-library/user-event": "^14.5.0",
     "@testing-library/jest-dom": "^6.6.3",
     "jsdom": "^25.0.1",
-    "@jini-ai/agentic": "0.4.0",
-    "@jini-ai/admin": "0.4.0",
-    "@jini-ai/cms": "0.4.0",
-    "@jini-ai/ui": "0.4.0"
-  },
-  "dependencies": {
-    "@jini-ai/core": "0.4.0",
-    "@jini-ai/ui-kit": "0.1.0"
+    "@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"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",