From b425d6bd5bbaae06bfc3959b3132117439fbb6dd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 28 Jul 2026 02:40:40 +0000
Subject: [PATCH] feat(console): make `delegated_admin` reachable and narrow
 both role pickers (framework#3697)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The framework registered a fourth organization role — `delegated_admin`, the
grade that may reach `/organization/invite-member` WITHOUT being an org admin,
which is what finally gives ADR-0105 D8's scope-bounded issuance gate a caller.
#2868 already shipped the placement half of this UX, but the console could not
select the role at all: `MembersPage` and `InviteMemberDialog` each inlined
`type Role = 'owner' | 'admin' | 'member'`, so the capability the framework grew
was unreachable from either screen.

One vocabulary, not two. Role names, labels and narrowing rules now live in
`@object-ui/auth`'s new `org-roles` module and both screens consume it. The list
still MIRRORS the server rather than deriving from it — `/auth/config` publishes
feature flags but no role vocabulary — so the module says so and points at
objectstack-ai/objectstack#3723, which tracks making one list the source for all
of them.

Both pickers now narrow to what the server will accept, the way the placement
picker already does. They mirror DIFFERENT gates:

- invite role  ← `beforeCreateInvitation`'s role cap: never above the issuer's
  own grade; a below-admin issuer may invite as `member` only. A
  `delegated_admin` picking "Admin" would have 403'd; it is no longer offered.
- change role  ← better-auth's `update-member-role`: needs `member:["update"]`
  (owner/admin only), and only an owner may set `owner` or re-role an existing
  owner. An actor who may re-role nobody gets no items rather than three that
  would 403.

Narrowing is convenience, not the boundary — the server re-checks — and it fails
toward less: an unresolved membership offers `member` alone on invite, nothing
on re-role. An ordinary invitation's request body is byte-identical to before.

The existing placement test mocked `@object-ui/auth` wholesale; it now spreads
`importActual` so the narrowing helpers under test are the real ones.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015s4qPrCKBvVwmFeSsFHgNp
---
 .changeset/console-delegated-admin-role.md    |  50 +++++++
 .../InviteMemberDialog.placement.test.tsx     |   8 +-
 .../InviteMemberDialog.roleCap.test.tsx       | 141 ++++++++++++++++++
 .../manage/InviteMemberDialog.tsx             |  36 ++---
 .../organizations/manage/MembersPage.tsx      |  51 +++----
 packages/auth/src/__tests__/org-roles.test.ts | 117 +++++++++++++++
 packages/auth/src/index.ts                    |  15 ++
 packages/auth/src/org-roles.ts                | 135 +++++++++++++++++
 8 files changed, 507 insertions(+), 46 deletions(-)
 create mode 100644 .changeset/console-delegated-admin-role.md
 create mode 100644 packages/app-shell/src/console/organizations/__tests__/InviteMemberDialog.roleCap.test.tsx
 create mode 100644 packages/auth/src/__tests__/org-roles.test.ts
 create mode 100644 packages/auth/src/org-roles.ts

diff --git a/.changeset/console-delegated-admin-role.md b/.changeset/console-delegated-admin-role.md
new file mode 100644
index 000000000..5a9048744
--- /dev/null
+++ b/.changeset/console-delegated-admin-role.md
@@ -0,0 +1,50 @@
+---
+"@object-ui/auth": minor
+"@object-ui/app-shell": minor
+---
+
+feat(console): make the `delegated_admin` org role reachable, and narrow both role pickers to what the server will accept (framework#3697)
+
+The framework registered a fourth organization role — `delegated_admin`, the
+grade that may reach `/organization/invite-member` **without** being an org
+admin, which is what finally gives ADR-0105 D8's scope-bounded issuance gate a
+caller. objectui#2868 already shipped the placement half of that UX (units and
+positions narrowed by `describeDelegableScope()`), but the console could not
+select the role in the first place: `MembersPage` and `InviteMemberDialog` each
+inlined `type Role = 'owner' | 'admin' | 'member'`, so the capability the
+framework grew was unreachable from either screen.
+
+**One vocabulary, not two.** The role names, labels and narrowing rules now live
+in `@object-ui/auth`'s new `org-roles` module (`ORG_ROLES`, `ORG_ROLE_LABELS`,
+`orgRoleGrade`, `invitableOrgRoles`, `assignableOrgRoles`) and both screens
+consume it. Note this list still **mirrors** the server rather than deriving
+from it — `/auth/config` publishes feature flags but no role vocabulary, so
+there is no surface to read; objectstack-ai/objectstack#3723 tracks making one
+list the source for all of them. Until then a server-side role addition means
+one console edit instead of two.
+
+**The pickers now narrow, the way the placement picker already does.** Both
+mirror a *different* server gate, and offering an option the server would refuse
+is the failure they prevent:
+
+- **Invite role** ← the framework's `beforeCreateInvitation` role cap: never
+  above the issuer's own grade, and an issuer below admin grade may invite as
+  `member` only. A `delegated_admin` who picked "Admin" would have been refused
+  with a 403; that option is simply no longer offered.
+- **Change role** ← better-auth's `update-member-role` route: it requires the
+  `member:["update"]` permission (owner/admin only — `delegated_admin` is built
+  from `memberAc` and holds `member: []`), and only an owner may set `owner` or
+  re-role an existing owner. An actor who may re-role nobody now gets no items
+  instead of three that would 403.
+
+Narrowing is convenience, not the boundary — the server re-checks every one of
+these — and it fails toward *less*: an unresolved membership offers `member`
+alone on invite, and nothing on re-role.
+
+An ordinary invitation is unchanged: with the default role and no placement, the
+request body is byte-identical to before.
+
+Note for translators: `organization.roles.*` has never been defined in any
+locale bundle — all four labels (owner/admin/member included) resolve through
+their `defaultValue` English fallback. The new role follows the same pattern
+rather than being the only localized one.
diff --git a/packages/app-shell/src/console/organizations/__tests__/InviteMemberDialog.placement.test.tsx b/packages/app-shell/src/console/organizations/__tests__/InviteMemberDialog.placement.test.tsx
index 5080d3083..b83df298f 100644
--- a/packages/app-shell/src/console/organizations/__tests__/InviteMemberDialog.placement.test.tsx
+++ b/packages/app-shell/src/console/organizations/__tests__/InviteMemberDialog.placement.test.tsx
@@ -27,8 +27,12 @@ vi.mock('@object-ui/i18n', () => ({
 
 const inviteMember = vi.fn();
 const describeDelegableScope = vi.fn();
-vi.mock('@object-ui/auth', () => ({
-  useAuth: () => ({ inviteMember, describeDelegableScope }),
+// Only `useAuth` is faked — the role vocabulary / narrowing helpers stay REAL,
+// so a change to the cap surfaces here instead of being mocked away. These
+// cases are about placement, so the caller is an owner (widest role list).
+vi.mock('@object-ui/auth', async (importActual) => ({
+  ...(await importActual<typeof import('@object-ui/auth')>()),
+  useAuth: () => ({ inviteMember, describeDelegableScope, activeMember: { role: 'owner' } }),
 }));
 
 // Passthrough primitives — the Select is rendered as a native <select> so the
diff --git a/packages/app-shell/src/console/organizations/__tests__/InviteMemberDialog.roleCap.test.tsx b/packages/app-shell/src/console/organizations/__tests__/InviteMemberDialog.roleCap.test.tsx
new file mode 100644
index 000000000..982ee44d8
--- /dev/null
+++ b/packages/app-shell/src/console/organizations/__tests__/InviteMemberDialog.roleCap.test.tsx
@@ -0,0 +1,141 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * InviteMemberDialog — the role select is narrowed by the ISSUER's own grade
+ * (framework#3697).
+ *
+ * Before the framework registered `delegated_admin`, this select was a
+ * hardcoded owner/admin/member list. Two things had to change together:
+ *
+ *   1. the new role must be offerable at all — otherwise the capability the
+ *      framework grew is unreachable from the console;
+ *   2. the list must narrow to what the issuer may actually confer — a
+ *      `delegated_admin` who picks "Admin" gets a 403 from the server's role
+ *      cap, so offering it is a trap, not a feature.
+ *
+ * The server remains the boundary; this only stops the console from proposing
+ * something it knows will be refused.
+ */
+
+import '@testing-library/jest-dom/vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, waitFor, fireEvent } from '@testing-library/react';
+
+vi.mock('@object-ui/i18n', () => ({
+  useObjectTranslation: () => ({
+    t: (key: string, options?: Record<string, unknown>) => String(options?.defaultValue ?? key),
+  }),
+}));
+
+const inviteMember = vi.fn();
+const describeDelegableScope = vi.fn();
+// Mutable so each case can be a different kind of issuer. Only `useAuth` is
+// faked — the narrowing helpers stay real.
+const auth: { role: string | null } = { role: 'owner' };
+vi.mock('@object-ui/auth', async (importActual) => ({
+  ...(await importActual<typeof import('@object-ui/auth')>()),
+  useAuth: () => ({
+    inviteMember,
+    describeDelegableScope,
+    activeMember: auth.role === null ? null : { role: auth.role },
+  }),
+}));
+
+vi.mock('@object-ui/components', () => ({
+  Dialog: ({ open, children }: any) => (open ? <div>{children}</div> : null),
+  DialogContent: (p: any) => <div {...p} />,
+  DialogDescription: (p: any) => <p {...p} />,
+  DialogFooter: (p: any) => <div {...p} />,
+  DialogHeader: (p: any) => <div {...p} />,
+  DialogTitle: (p: any) => <h2 {...p} />,
+  Button: ({ children, ...rest }: any) => <button {...rest}>{children}</button>,
+  Input: (p: any) => <input {...p} />,
+  Label: (p: any) => <label {...p} />,
+  Select: ({ value, onValueChange, children }: any) => (
+    <select data-testid="select" value={value} onChange={(e) => onValueChange(e.target.value)}>
+      <option value="" />
+      {children}
+    </select>
+  ),
+  SelectContent: (p: any) => <>{p.children}</>,
+  SelectItem: ({ value, children, ...rest }: any) => (
+    <option value={value} {...rest}>
+      {children}
+    </option>
+  ),
+  SelectTrigger: (p: any) => <>{p.children}</>,
+  SelectValue: () => null,
+}));
+vi.mock('lucide-react', () => ({
+  Loader2: () => <span />,
+  Copy: () => <span />,
+  Check: () => <span />,
+}));
+vi.mock('sonner', () => ({ toast: { success: vi.fn(), error: vi.fn() } }));
+
+import { InviteMemberDialog } from '../manage/InviteMemberDialog';
+
+// `describeDelegableScope` resolves null in every case here, so the placement
+// section stays hidden and the role select is the only one on screen. (The
+// Select mock renders a native <select data-testid="select">; the component's
+// own testid lives on SelectTrigger, which the mock flattens away.)
+const renderAs = async (role: string | null) => {
+  auth.role = role;
+  render(<InviteMemberDialog organizationId="org-42" open onOpenChange={() => {}} />);
+  await waitFor(() => expect(screen.getByTestId('select')).toBeInTheDocument());
+};
+
+const offered = () =>
+  Array.from(screen.getByTestId('select').querySelectorAll('option'))
+    .map((o) => o.getAttribute('value'))
+    .filter(Boolean);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  describeDelegableScope.mockResolvedValue(null);
+  inviteMember.mockResolvedValue({ id: 'inv-1', email: 'p@x.test', role: 'member' });
+});
+
+describe('InviteMemberDialog — role cap (framework#3697)', () => {
+  it('an owner is offered every role, delegated_admin included', async () => {
+    await renderAs('owner');
+    expect(offered()).toEqual(['owner', 'admin', 'delegated_admin', 'member']);
+  });
+
+  it('an admin may provision a delegate but may not invite an owner', async () => {
+    await renderAs('admin');
+    const roles = offered();
+    expect(roles).toContain('delegated_admin');
+    expect(roles).not.toContain('owner');
+  });
+
+  it('a DELEGATE is offered member only — the escalation chain has no UI entry', async () => {
+    // Picking "Admin" here would 403 on the server's role cap; the console must
+    // not propose it. This is the whole reason the select stopped being a
+    // hardcoded three-item list.
+    await renderAs('delegated_admin');
+    expect(offered()).toEqual(['member']);
+    expect(screen.queryByTestId('invite-role-admin')).not.toBeInTheDocument();
+  });
+
+  it('an unloaded membership still allows the ordinary member invite', async () => {
+    await renderAs(null);
+    expect(offered()).toEqual(['member']);
+  });
+
+  it('the narrowed default still submits a plain, unchanged invitation', async () => {
+    // A delegate's ordinary invite must be byte-identical to what any other
+    // caller sends — narrowing the picker changed the options, not the payload.
+    await renderAs('delegated_admin');
+    fireEvent.change(screen.getByTestId('invite-email-input'), {
+      target: { value: 'p@x.test' },
+    });
+    fireEvent.submit(document.querySelector('form')!);
+    await waitFor(() => expect(inviteMember).toHaveBeenCalledTimes(1));
+    expect(inviteMember).toHaveBeenCalledWith({
+      organizationId: 'org-42',
+      email: 'p@x.test',
+      role: 'member',
+    });
+  });
+});
diff --git a/packages/app-shell/src/console/organizations/manage/InviteMemberDialog.tsx b/packages/app-shell/src/console/organizations/manage/InviteMemberDialog.tsx
index f993220a8..912640cfc 100644
--- a/packages/app-shell/src/console/organizations/manage/InviteMemberDialog.tsx
+++ b/packages/app-shell/src/console/organizations/manage/InviteMemberDialog.tsx
@@ -23,14 +23,12 @@ import {
   SelectTrigger,
   SelectValue,
 } from '@object-ui/components';
-import { useAuth } from '@object-ui/auth';
-import type { AuthInvitation, DelegableScope } from '@object-ui/auth';
+import { useAuth, invitableOrgRoles, ORG_ROLE_LABELS, ORG_ROLE_MEMBER } from '@object-ui/auth';
+import type { AuthInvitation, DelegableScope, OrgRole } from '@object-ui/auth';
 import { useObjectTranslation } from '@object-ui/i18n';
 import { Loader2, Copy, Check } from 'lucide-react';
 import { toast } from 'sonner';
 
-type Role = 'owner' | 'admin' | 'member';
-
 interface InviteMemberDialogProps {
   organizationId: string;
   open: boolean;
@@ -51,10 +49,18 @@ export function InviteMemberDialog({
   onInvited,
 }: InviteMemberDialogProps) {
   const { t } = useObjectTranslation();
-  const { inviteMember, describeDelegableScope } = useAuth();
+  const { inviteMember, describeDelegableScope, activeMember } = useAuth();
+
+  // [framework #3697] The roles this issuer may actually confer. Mirrors the
+  // server's invitation role cap — a below-admin issuer (e.g. a
+  // `delegated_admin`) may invite as `member` only, and nobody may invite above
+  // their own grade. Same property as the placement picker below: it NARROWS,
+  // it does not decide; the server re-checks and rejects the whole invitation
+  // when it is out of cap.
+  const roleOptions = invitableOrgRoles(activeMember?.role);
 
   const [email, setEmail] = useState('');
-  const [role, setRole] = useState<Role>('member');
+  const [role, setRole] = useState<OrgRole>(ORG_ROLE_MEMBER);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [createdInvitation, setCreatedInvitation] = useState<AuthInvitation | null>(null);
@@ -74,7 +80,7 @@ export function InviteMemberDialog({
   useEffect(() => {
     if (open) {
       setEmail('');
-      setRole('member');
+      setRole(ORG_ROLE_MEMBER);
       setError(null);
       setCreatedInvitation(null);
       setCopied(false);
@@ -219,20 +225,16 @@ export function InviteMemberDialog({
                 <Label htmlFor="invite-role">
                   {t('organization.invitations.roleLabel', { defaultValue: 'Role' })}
                 </Label>
-                <Select value={role} onValueChange={(v) => setRole(v as Role)}>
+                <Select value={role} onValueChange={(v) => setRole(v as OrgRole)}>
                   <SelectTrigger id="invite-role" data-testid="invite-role-select">
                     <SelectValue />
                   </SelectTrigger>
                   <SelectContent>
-                    <SelectItem value="member">
-                      {t('organization.roles.member', { defaultValue: 'Member' })}
-                    </SelectItem>
-                    <SelectItem value="admin">
-                      {t('organization.roles.admin', { defaultValue: 'Admin' })}
-                    </SelectItem>
-                    <SelectItem value="owner">
-                      {t('organization.roles.owner', { defaultValue: 'Owner' })}
-                    </SelectItem>
+                    {roleOptions.map((r) => (
+                      <SelectItem key={r} value={r} data-testid={`invite-role-${r}`}>
+                        {t(ORG_ROLE_LABELS[r].key, { defaultValue: ORG_ROLE_LABELS[r].defaultValue })}
+                      </SelectItem>
+                    ))}
                   </SelectContent>
                 </Select>
               </div>
diff --git a/packages/app-shell/src/console/organizations/manage/MembersPage.tsx b/packages/app-shell/src/console/organizations/manage/MembersPage.tsx
index 6b99407d4..08b40e81a 100644
--- a/packages/app-shell/src/console/organizations/manage/MembersPage.tsx
+++ b/packages/app-shell/src/console/organizations/manage/MembersPage.tsx
@@ -25,8 +25,8 @@ import {
   DropdownMenuTrigger,
   Separator,
 } from '@object-ui/components';
-import { useAuth } from '@object-ui/auth';
-import type { AuthOrganizationMember } from '@object-ui/auth';
+import { useAuth, assignableOrgRoles, ORG_ROLE_LABELS } from '@object-ui/auth';
+import type { AuthOrganizationMember, OrgRole } from '@object-ui/auth';
 import { useObjectTranslation } from '@object-ui/i18n';
 import { Loader2, MoreHorizontal, UserMinus, ShieldCheck } from 'lucide-react';
 import { toast } from 'sonner';
@@ -43,12 +43,10 @@ function getMemberInitials(name?: string): string {
     .slice(0, 2);
 }
 
-type Role = 'owner' | 'admin' | 'member';
-
 export function MembersPage() {
   const { t } = useObjectTranslation();
   const { org } = useOrgContext();
-  const { getMembers, removeMember, updateMemberRole } = useAuth();
+  const { getMembers, removeMember, updateMemberRole, activeMember } = useAuth();
 
   const [members, setMembers] = useState<AuthOrganizationMember[]>([]);
   const [isLoading, setIsLoading] = useState(true);
@@ -75,7 +73,7 @@ export function MembersPage() {
     fetchMembers();
   }, [fetchMembers]);
 
-  const handleChangeRole = async (member: AuthOrganizationMember, role: Role) => {
+  const handleChangeRole = async (member: AuthOrganizationMember, role: OrgRole) => {
     try {
       await updateMemberRole({ organizationId: org.id, memberId: member.id, role });
       toast.success(t('organization.members.roleUpdated', { defaultValue: 'Role updated' }));
@@ -175,27 +173,26 @@ export function MembersPage() {
                 </Button>
               </DropdownMenuTrigger>
               <DropdownMenuContent align="end">
-                <DropdownMenuItem
-                  onClick={() => handleChangeRole(member, 'owner')}
-                  disabled={member.role === 'owner'}
-                >
-                  <ShieldCheck className="mr-2 h-4 w-4" />
-                  {t('organization.roles.owner', { defaultValue: 'Owner' })}
-                </DropdownMenuItem>
-                <DropdownMenuItem
-                  onClick={() => handleChangeRole(member, 'admin')}
-                  disabled={member.role === 'admin'}
-                >
-                  <ShieldCheck className="mr-2 h-4 w-4" />
-                  {t('organization.roles.admin', { defaultValue: 'Admin' })}
-                </DropdownMenuItem>
-                <DropdownMenuItem
-                  onClick={() => handleChangeRole(member, 'member')}
-                  disabled={member.role === 'member'}
-                >
-                  <ShieldCheck className="mr-2 h-4 w-4" />
-                  {t('organization.roles.member', { defaultValue: 'Member' })}
-                </DropdownMenuItem>
+                {/* [framework #3697] Roles this actor may SET on THIS member.
+                    Mirrors better-auth's `update-member-role` route: it needs
+                    the `member:["update"]` permission (owner/admin only — a
+                    `delegated_admin` is built from `memberAc` and holds
+                    `member: []`), and only an owner may set `owner` or re-role
+                    someone who already is one. An actor who may re-role nobody
+                    gets no items rather than three that would 403. */}
+                {assignableOrgRoles(activeMember?.role, member.role).map((role) => (
+                  <DropdownMenuItem
+                    key={role}
+                    onClick={() => handleChangeRole(member, role)}
+                    disabled={member.role === role}
+                    data-testid={`member-role-${role}`}
+                  >
+                    <ShieldCheck className="mr-2 h-4 w-4" />
+                    {t(ORG_ROLE_LABELS[role].key, {
+                      defaultValue: ORG_ROLE_LABELS[role].defaultValue,
+                    })}
+                  </DropdownMenuItem>
+                ))}
                 <DropdownMenuItem
                   className="text-destructive focus:text-destructive"
                   onClick={() => setRemovingMember(member)}
diff --git a/packages/auth/src/__tests__/org-roles.test.ts b/packages/auth/src/__tests__/org-roles.test.ts
new file mode 100644
index 000000000..015e0a3a4
--- /dev/null
+++ b/packages/auth/src/__tests__/org-roles.test.ts
@@ -0,0 +1,117 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Organization role vocabulary + narrowing helpers.
+ *
+ * These MIRROR two different server gates, and the tests are written to fail
+ * loudly if either drifts:
+ *
+ *  - `invitableOrgRoles` ↔ the framework's `beforeCreateInvitation` role cap
+ *    (framework#3697): never above your own grade, and a below-admin issuer may
+ *    invite as `member` only.
+ *  - `assignableOrgRoles` ↔ better-auth's `update-member-role` route: needs
+ *    `member:["update"]` (owner/admin only), and only an owner may set `owner`
+ *    or re-role an existing owner.
+ *
+ * Both NARROW; neither decides. The server re-checks, so the only failure the
+ * console can cause is offering something that then 403s — which is exactly
+ * what these pin.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  ORG_ROLES,
+  ORG_ROLE_LABELS,
+  ORG_ROLE_DELEGATED_ADMIN,
+  orgRoleGrade,
+  invitableOrgRoles,
+  assignableOrgRoles,
+} from '../org-roles';
+
+describe('vocabulary', () => {
+  it('carries the delegated issuer grade the framework registers', () => {
+    expect(ORG_ROLES).toContain(ORG_ROLE_DELEGATED_ADMIN);
+  });
+
+  it('every role has a label — a role with no label renders as a raw key', () => {
+    for (const role of ORG_ROLES) {
+      expect(ORG_ROLE_LABELS[role]?.key).toBeTruthy();
+      expect(ORG_ROLE_LABELS[role]?.defaultValue).toBeTruthy();
+    }
+  });
+});
+
+describe('orgRoleGrade', () => {
+  it('ranks owner above admin above everything else', () => {
+    expect(orgRoleGrade('owner')).toBeGreaterThan(orgRoleGrade('admin'));
+    expect(orgRoleGrade('admin')).toBeGreaterThan(orgRoleGrade('member'));
+  });
+
+  it('the delegate grade and app roles are ordinary members', () => {
+    expect(orgRoleGrade(ORG_ROLE_DELEGATED_ADMIN)).toBe(orgRoleGrade('member'));
+    expect(orgRoleGrade('sales_manager')).toBe(orgRoleGrade('member'));
+  });
+
+  it('a comma list takes the HIGHEST grade', () => {
+    expect(orgRoleGrade('member,admin')).toBe(orgRoleGrade('admin'));
+  });
+
+  it('an unresolvable role grades BELOW a plain member (fail-closed floor)', () => {
+    for (const v of [null, undefined, '', 42, {}]) {
+      expect(orgRoleGrade(v)).toBeLessThan(orgRoleGrade('member'));
+    }
+  });
+});
+
+describe('invitableOrgRoles — mirrors the invitation role cap', () => {
+  it('an owner may invite every grade', () => {
+    expect(invitableOrgRoles('owner')).toEqual([...ORG_ROLES]);
+  });
+
+  it('an admin may invite everything except owner', () => {
+    const roles = invitableOrgRoles('admin');
+    expect(roles).toContain('admin');
+    expect(roles).toContain(ORG_ROLE_DELEGATED_ADMIN);
+    expect(roles).toContain('member');
+    expect(roles).not.toContain('owner');
+  });
+
+  it('a DELEGATE may invite as member only — the escalation chain, closed in the UI too', () => {
+    expect(invitableOrgRoles(ORG_ROLE_DELEGATED_ADMIN)).toEqual(['member']);
+  });
+
+  it('an unresolvable caller is offered member alone, never nothing', () => {
+    // Offering nothing would break the ordinary invite for a caller whose
+    // membership simply has not loaded yet; the server still allows `member`.
+    for (const v of [null, undefined, '']) {
+      expect(invitableOrgRoles(v)).toEqual(['member']);
+    }
+  });
+});
+
+describe('assignableOrgRoles — mirrors update-member-role', () => {
+  it('an owner may set anything, including owner', () => {
+    expect(assignableOrgRoles('owner', 'member')).toEqual([...ORG_ROLES]);
+  });
+
+  it('an admin may set the delegate grade but never owner', () => {
+    const roles = assignableOrgRoles('admin', 'member');
+    expect(roles).toContain(ORG_ROLE_DELEGATED_ADMIN);
+    expect(roles).not.toContain('owner');
+  });
+
+  it('an admin may not re-role an existing owner at all', () => {
+    expect(assignableOrgRoles('admin', 'owner')).toEqual([]);
+  });
+
+  it('a delegate may re-role NOBODY — they hold no member:update permission', () => {
+    expect(assignableOrgRoles(ORG_ROLE_DELEGATED_ADMIN, 'member')).toEqual([]);
+    expect(assignableOrgRoles('member', 'member')).toEqual([]);
+  });
+
+  it('an unresolvable actor may re-role nobody (fail closed)', () => {
+    for (const v of [null, undefined, '']) {
+      expect(assignableOrgRoles(v, 'member')).toEqual([]);
+    }
+  });
+});
diff --git a/packages/auth/src/index.ts b/packages/auth/src/index.ts
index 7c9b53585..5e35ffabb 100644
--- a/packages/auth/src/index.ts
+++ b/packages/auth/src/index.ts
@@ -37,6 +37,21 @@ export { normalizePhoneIdentifier, looksLikePhoneIdentifier } from './phone-iden
 export { createAuthenticatedFetch, ActiveOrganizationStorage, type AuthenticatedAdapterOptions } from './createAuthenticatedFetch';
 export { getUserInitials } from './types';
 
+// Organization membership-role vocabulary + the narrowing helpers every org
+// screen shares (see `org-roles.ts` for why this mirrors rather than derives).
+export {
+  ORG_ROLE_OWNER,
+  ORG_ROLE_ADMIN,
+  ORG_ROLE_DELEGATED_ADMIN,
+  ORG_ROLE_MEMBER,
+  ORG_ROLES,
+  ORG_ROLE_LABELS,
+  orgRoleGrade,
+  invitableOrgRoles,
+  assignableOrgRoles,
+  type OrgRole,
+} from './org-roles';
+
 // Shared auth form primitives — exposed so consumers can build custom forms
 // that match the look of LoginForm / RegisterForm / ForgotPasswordForm.
 export {
diff --git a/packages/auth/src/org-roles.ts b/packages/auth/src/org-roles.ts
new file mode 100644
index 000000000..0fa9ca3a5
--- /dev/null
+++ b/packages/auth/src/org-roles.ts
@@ -0,0 +1,135 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Organization membership roles — the ONE place the console names them.
+ *
+ * These are better-auth's organization roles as the ObjectStack framework
+ * registers them, stored in `sys_member.role` / `sys_invitation.role`. Before
+ * this module the vocabulary was inlined as `type Role = 'owner' | 'admin' |
+ * 'member'` in both `MembersPage` and `InviteMemberDialog`, so a role the
+ * server had learned about was still unreachable from either screen.
+ *
+ * ⚠️ This list MIRRORS the server; it does not derive from it. `/auth/config`
+ * exposes feature flags but no role vocabulary, so there is no surface to read
+ * — see objectstack-ai/objectstack#3723, which tracks making one list the
+ * source for all of them (the framework already carries the same list twice:
+ * the better-auth roles map and two enforced `Field.select` option sets). Until
+ * that lands, a role added server-side must be added HERE too — one place, not
+ * two.
+ */
+
+export const ORG_ROLE_OWNER = 'owner';
+export const ORG_ROLE_ADMIN = 'admin';
+/**
+ * [framework ADR-0105 D8] The delegated issuer grade. May reach
+ * `/organization/invite-member` WITHOUT being an org admin, which is what gives
+ * D8's scope-bounded issuance gate a caller. Carries no authority of its own:
+ * what a delegate may actually *place* comes from a separately-granted
+ * `adminScope`, surfaced to this console by `describeDelegableScope()`.
+ */
+export const ORG_ROLE_DELEGATED_ADMIN = 'delegated_admin';
+export const ORG_ROLE_MEMBER = 'member';
+
+export type OrgRole =
+  | typeof ORG_ROLE_OWNER
+  | typeof ORG_ROLE_ADMIN
+  | typeof ORG_ROLE_DELEGATED_ADMIN
+  | typeof ORG_ROLE_MEMBER;
+
+/** Display order: most privileged first, as the screens list them. */
+export const ORG_ROLES: readonly OrgRole[] = [
+  ORG_ROLE_OWNER,
+  ORG_ROLE_ADMIN,
+  ORG_ROLE_DELEGATED_ADMIN,
+  ORG_ROLE_MEMBER,
+] as const;
+
+/** i18n key + English fallback for a role, so every screen labels it identically. */
+export const ORG_ROLE_LABELS: Record<OrgRole, { key: string; defaultValue: string }> = {
+  [ORG_ROLE_OWNER]: { key: 'organization.roles.owner', defaultValue: 'Owner' },
+  [ORG_ROLE_ADMIN]: { key: 'organization.roles.admin', defaultValue: 'Admin' },
+  [ORG_ROLE_DELEGATED_ADMIN]: {
+    key: 'organization.roles.delegatedAdmin',
+    defaultValue: 'Delegated Admin',
+  },
+  [ORG_ROLE_MEMBER]: { key: 'organization.roles.member', defaultValue: 'Member' },
+};
+
+const GRADE_UNRESOLVED = 0;
+const GRADE_MEMBER = 1;
+const GRADE_ADMIN = 2;
+const GRADE_OWNER = 3;
+
+/**
+ * Grade ladder, mirroring the framework's invitation role cap. Anything
+ * unrecognized — `member`, `delegated_admin`, an app-registered role — grades
+ * as an ordinary member; only better-auth's two administrative roles outrank
+ * it, because only they are auto-elevated to `organization_admin` server-side.
+ *
+ * An absent/unreadable role grades BELOW a plain member: the fail-closed floor,
+ * so an unverified caller is offered nothing privileged.
+ */
+export function orgRoleGrade(raw: unknown): number {
+  if (typeof raw !== 'string') return GRADE_UNRESOLVED;
+  const roles = raw
+    .split(',')
+    .map((r) => r.trim().toLowerCase())
+    .filter(Boolean);
+  if (roles.length === 0) return GRADE_UNRESOLVED;
+  let grade = GRADE_MEMBER;
+  for (const role of roles) {
+    if (role === ORG_ROLE_OWNER) grade = Math.max(grade, GRADE_OWNER);
+    else if (role === ORG_ROLE_ADMIN) grade = Math.max(grade, GRADE_ADMIN);
+  }
+  return grade;
+}
+
+/**
+ * The roles `issuerRole` may confer through an INVITATION — mirroring the
+ * framework's `beforeCreateInvitation` role cap:
+ *
+ *  - an invited role may never outrank the issuer's own;
+ *  - an issuer below admin grade may invite as `member` only (an app-registered
+ *    role projects into `current_user.positions` and may be bound to permission
+ *    sets, so it is a capability channel too — a delegate's channel for
+ *    capability is the invitation's *placement*, which the D12 gate allowlists).
+ *
+ * Same property as the placement picker: this NARROWS, it does not decide. The
+ * server re-checks and rejects out-of-cap invitations, so the console is free to
+ * be helpful without being load-bearing — and it fails toward *less*: an
+ * unresolvable issuer role offers `member` alone.
+ */
+export function invitableOrgRoles(issuerRole: unknown): OrgRole[] {
+  const grade = orgRoleGrade(issuerRole);
+  if (grade < GRADE_ADMIN) return [ORG_ROLE_MEMBER];
+  return ORG_ROLES.filter((r) => orgRoleGrade(r) <= grade);
+}
+
+/**
+ * The roles `actorRole` may SET on an existing member — a different gate from
+ * invitation, mirroring better-auth's `update-member-role` route rather than the
+ * framework's cap:
+ *
+ *  - the route requires the `member: ["update"]` permission, which only
+ *    `owner`/`admin` hold (`delegated_admin` is built from `memberAc`, so it has
+ *    `member: []` and may not re-role anyone);
+ *  - only an owner may SET `owner`, and only an owner may modify a member who
+ *    already IS one (better-auth's `creatorRole` protection).
+ *
+ * Returns an empty list when the actor may not re-role at all, so the screen can
+ * omit the affordance instead of offering items that would 403.
+ */
+export function assignableOrgRoles(actorRole: unknown, targetRole?: unknown): OrgRole[] {
+  const actor = orgRoleGrade(actorRole);
+  if (actor < GRADE_ADMIN) return [];
+  const actorIsOwner = actor >= GRADE_OWNER;
+  // An existing owner is owner-editable only.
+  if (!actorIsOwner && orgRoleGrade(targetRole) >= GRADE_OWNER) return [];
+  return ORG_ROLES.filter((r) => (r === ORG_ROLE_OWNER ? actorIsOwner : true));
+}