fix(auth): the role picker shows the declared label, not a title-cased name

Deriving the option label by title-casing the machine name made a THIRD source
of truth for one string: a position declaring `{ name: 'exec', label:
'Executive' }` rendered as "Exec" in the picker, contradicting the very
metadata it came from. Worse for a non-English stack — a position labelled
`销售代表` came out as "Sales Rep".

Same one-list principle as the role set itself, applied to how it is displayed:
`collectStackOrgRoles` carries each entry's declared label through, and
`additionalOrgRoles` accepts `{ name, label }` alongside a bare name (a
widening — `string[]` callers are unaffected). Title-casing survives only as
the fallback for a host that had no label to offer.

Presentation only: better-auth is handed names via `orgRoleNames`, and the
stored value is always the name.

Pinned in the dogfood gate against a real difference — showcase's `exec`
declares `Executive`, which title-casing could never produce.

Author: claude

.changeset/app-org-roles-storable.md

@@ -43,9 +43,19 @@ New exports:
 
 Hosts that boot `AuthPlugin` from a loaded stack should derive
 `additionalOrgRoles` with `collectStackOrgRoles(stack)` rather than walking the
-stack themselves — `objectstack serve` and the `@objectstack/verify` harness now
-both do (the harness previously passed none, which is why a dogfood proof could
-boot a stack whose declared roles better-auth had never heard of).
+stack themselves — `objectstack serve`, the `@objectstack/verify` harness and
+`DevPlugin` now all do. The harness previously passed none, which is why a
+dogfood proof could boot a stack whose declared roles better-auth had never
+heard of; `DevPlugin` documents itself as equivalent to the full stack and
+silently excluded app roles from that equivalence.
+
+`additionalOrgRoles` accepts `{ name, label }` alongside a bare name, and
+`collectStackOrgRoles` now returns those descriptors. The label is what the
+declaring `position` / `permission` metadata already says, so the role picker
+shows `Executive` for a position declared as such instead of title-casing the
+machine name into `Exec` — a third source of truth for one string. Presentation
+only: better-auth sees just the name, and the stored value is always the name.
+Passing `string[]` keeps working unchanged.
 
 Behaviour change worth noting: a declared role name that is not a valid machine
 name (`/^[a-z][a-z0-9_]*$/`, min 2 chars) is no longer registered at all, with a

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -21,7 +21,7 @@ import {
 import { MCP_OAUTH_SCOPES } from '@objectstack/spec/ai';
 import { createObjectQLAdapterFactory, withSystemReadContext } from './objectql-adapter.js';
 import { invitationRoleCapFailure, isPlainMemberInvitation } from './invitation-role-cap.js';
-import { normalizeAdditionalOrgRoles } from './org-roles.js';
+import { normalizeAdditionalOrgRoles, orgRoleNames, type OrgRoleInput } from './org-roles.js';
 import { isPlaceholderEmail } from './placeholder-email.js';
 import { reconcileMembership, type MembershipPolicy } from './reconcile-membership.js';
 import type { TenancyService } from './tenancy-service.js';
@@ -404,12 +404,18 @@ export interface AuthManagerOptions extends Partial<AuthConfig> {
    * Better-Auth's `member` role) so it cannot inadvertently grant org-level
    * admin capabilities.
    *
-   * Typical source: the union of `permission` metadata names that have
-   * declared names, collected from the loaded stack at CLI boot.
+   * Typical source: `collectStackOrgRoles(stack)` — the one walk every host
+   * shares (`objectstack serve`, the verify harness, DevPlugin).
    *
-   * @example ['sales_rep', 'sales_manager', 'service_agent']
+   * Accepts a bare name, or `{ name, label }` to carry the declaring
+   * metadata's own display label into the role picker (#3723) — without it the
+   * picker would title-case the machine name and contradict a position that
+   * already says `销售代表`. The label is presentation only: better-auth sees
+   * just the name, and the stored value is always the name.
+   *
+   * @example ['sales_rep', { name: 'sales_manager', label: '销售经理' }]
    */
-  additionalOrgRoles?: string[];
+  additionalOrgRoles?: OrgRoleInput[];
 
   /**
    * Optional outbound email service used by better-auth callbacks
@@ -1601,7 +1607,9 @@ export class AuthManager {
             ...stmts,
             invitation: ['create'],
           });
-          for (const name of extra) {
+          // Names only — a descriptor's `label` is presentation for the role
+          // picker and means nothing to better-auth.
+          for (const name of orgRoleNames(extra)) {
             if (!name) continue;
             if (built[name]) continue;
             built[name] = defaultAc.newRole(stmts);

packages/plugins/plugin-auth/src/auth-plugin.ts

@@ -35,7 +35,7 @@ import {
   authIdentityObjects,
   authPluginManifestHeader,
 } from './manifest.js';
-import { normalizeAdditionalOrgRoles, withMembershipRoleOptions } from './org-roles.js';
+import { normalizeAdditionalOrgRoles, withMembershipRoleOptions, type OrgRoleInput } from './org-roles.js';
 
 /**
  * Auth Plugin Options
@@ -80,7 +80,7 @@ export interface AuthPluginOptions extends Partial<AuthConfig> {
    * ROLE_NOT_FOUND. Forwarded as-is to AuthManager. See
    * {@link AuthManagerOptions.additionalOrgRoles} for details.
    */
-  additionalOrgRoles?: string[];
+  additionalOrgRoles?: OrgRoleInput[];
 
   /**
    * ADR-0081 D1 — single-org default-organization bootstrap. In single-org

packages/plugins/plugin-auth/src/org-roles.test.ts

@@ -29,30 +29,54 @@ const roleOptionsOf = (object: unknown): { label: string; value: string }[] =>
 describe('#3723 normalizeAdditionalOrgRoles — the one normalizer', () => {
   it('keeps valid app role names, in declaration order', () => {
     expect(normalizeAdditionalOrgRoles(['sales_rep', 'sales_manager', 'service_agent'])).toEqual([
-      'sales_rep',
-      'sales_manager',
-      'service_agent',
+      { name: 'sales_rep' },
+      { name: 'sales_manager' },
+      { name: 'service_agent' },
     ]);
   });
 
+  it('carries a declared label through, and tolerates entries without one', () => {
+    expect(
+      normalizeAdditionalOrgRoles([{ name: 'sales_rep', label: '销售代表' }, 'ops']),
+    ).toEqual([{ name: 'sales_rep', label: '销售代表' }, { name: 'ops' }]);
+  });
+
+  it('drops a blank label rather than storing an empty picker entry', () => {
+    expect(normalizeAdditionalOrgRoles([{ name: 'ops', label: '   ' }])).toEqual([{ name: 'ops' }]);
+  });
+
   it('drops the built-ins — an app may not redefine owner/admin/member/delegated_admin', () => {
     // Silently downgrading `owner` to a plain-member role would strip its
     // `invitation:create` and 403 every org mutation.
     expect(
       normalizeAdditionalOrgRoles(['owner', 'admin', 'member', 'delegated_admin', 'sales_rep']),
-    ).toEqual(['sales_rep']);
+    ).toEqual([{ name: 'sales_rep' }]);
   });
 
   it('de-duplicates and trims', () => {
-    expect(normalizeAdditionalOrgRoles(['  sales_rep ', 'sales_rep', ''])).toEqual(['sales_rep']);
+    expect(normalizeAdditionalOrgRoles(['  sales_rep ', 'sales_rep', ''])).toEqual([
+      { name: 'sales_rep' },
+    ]);
   });
 
-  it('ignores non-strings and a non-array input', () => {
-    expect(normalizeAdditionalOrgRoles([null, 42, {}, 'sales_rep'] as unknown[])).toEqual(['sales_rep']);
+  it('ignores unusable entries and a non-array input', () => {
+    expect(normalizeAdditionalOrgRoles([null, 42, {}, { name: 7 }, 'sales_rep'] as unknown[])).toEqual([
+      { name: 'sales_rep' },
+    ]);
     expect(normalizeAdditionalOrgRoles(undefined)).toEqual([]);
     expect(normalizeAdditionalOrgRoles(null)).toEqual([]);
   });
 
+  it('a blank label never masks the built-in drop or the name filter', () => {
+    expect(
+      normalizeAdditionalOrgRoles([
+        { name: 'owner', label: 'Boss' },
+        { name: 'bad.name', label: 'Bad' },
+        { name: 'ok_role', label: 'OK' },
+      ]),
+    ).toEqual([{ name: 'ok_role', label: 'OK' }]);
+  });
+
   it('REFUSES a name that cannot round-trip through Field.select — loudly', () => {
     // `Field.select` lowercases values and strips everything outside
     // [a-z0-9_], so `showcase.export_data` would be registered with
@@ -64,7 +88,7 @@ describe('#3723 normalizeAdditionalOrgRoles — the one normalizer', () => {
         ['showcase.export_data', 'Sales Rep', '_leading', 'x', 'sales_rep'],
         { warn },
       ),
-    ).toEqual(['sales_rep']);
+    ).toEqual([{ name: 'sales_rep' }]);
     expect(warn).toHaveBeenCalledTimes(4);
     expect(warn.mock.calls.map((c) => String(c[0])).join('\n')).toContain('showcase.export_data');
   });
@@ -81,13 +105,13 @@ describe('#3723 membershipRoleOptions — the option list both selects get', ()
   });
 
   it('appends app roles after the built-ins, with humanized labels', () => {
-    const options = membershipRoleOptions(['sales_rep']);
+    const options = membershipRoleOptions([{ name: 'sales_rep' }]);
     expect(values(options)).toEqual(['owner', 'admin', 'delegated_admin', 'member', 'sales_rep']);
     expect(options.at(-1)).toEqual({ label: 'Sales Rep', value: 'sales_rep' });
   });
 
   it('never duplicates a built-in', () => {
-    expect(values(membershipRoleOptions(['member', 'sales_rep']))).toEqual([
+    expect(values(membershipRoleOptions([{ name: 'member' }, { name: 'sales_rep' }]))).toEqual([
       'owner',
       'admin',
       'delegated_admin',
@@ -99,11 +123,20 @@ describe('#3723 membershipRoleOptions — the option list both selects get', ()
   it('humanizes labels without ever changing the stored value', () => {
     expect(membershipRoleLabel('sales_rep')).toBe('Sales Rep');
     expect(membershipRoleLabel('ops')).toBe('Ops');
-    expect(membershipRoleOptions(['field_ops_delegate']).at(-1)).toEqual({
+    expect(membershipRoleOptions([{ name: 'field_ops_delegate' }]).at(-1)).toEqual({
       label: 'Field Ops Delegate',
       value: 'field_ops_delegate',
     });
   });
+
+  it('a declared label WINS over the title-cased machine name', () => {
+    // The whole point: a position that says `销售代表` must not be rendered as
+    // "Sales Rep" by a picker deriving its own label from the machine name.
+    expect(membershipRoleOptions([{ name: 'sales_rep', label: '销售代表' }]).at(-1)).toEqual({
+      label: '销售代表',
+      value: 'sales_rep',
+    });
+  });
 });
 
 describe('#3723 withMembershipRoleOptions — materializing onto the platform objects', () => {
@@ -112,27 +145,27 @@ describe('#3723 withMembershipRoleOptions — materializing onto the platform ob
   it('widens BOTH role selects — fixing one leaves the other rejecting the same value', () => {
     // The lesson from #3722: `sys_member.role` alone still left
     // `sys_invitation.role` refusing the invitation at issuance.
-    const [, member, invitation] = withMembershipRoleOptions(objects, ['sales_rep']);
+    const [, member, invitation] = withMembershipRoleOptions(objects, [{ name: 'sales_rep' }]);
     expect(values(roleOptionsOf(member))).toContain('sales_rep');
     expect(values(roleOptionsOf(invitation))).toContain('sales_rep');
     expect(values(roleOptionsOf(member))).toEqual(values(roleOptionsOf(invitation)));
   });
 
   it('leaves unrelated objects untouched, by identity', () => {
-    const [user] = withMembershipRoleOptions(objects, ['sales_rep']);
+    const [user] = withMembershipRoleOptions(objects, [{ name: 'sales_rep' }]);
     expect(user).toBe(SysUser);
   });
 
   it('is copy-on-write — the shared module-level definitions are never mutated', () => {
     // `authIdentityObjects` is a process-wide singleton also used by the
     // compile-time `objectstack.config.ts`; two kernels booted with different
     // app roles in one test run must not see each other's options.
-    withMembershipRoleOptions(objects, ['sales_rep']);
+    withMembershipRoleOptions(objects, [{ name: 'sales_rep' }]);
     expect(values(roleOptionsOf(SysMember))).toEqual(values(BUILTIN_MEMBERSHIP_ROLE_OPTIONS));
     expect(values(roleOptionsOf(SysInvitation))).toEqual(values(BUILTIN_MEMBERSHIP_ROLE_OPTIONS));
 
-    const a = withMembershipRoleOptions(objects, ['role_a']);
-    const b = withMembershipRoleOptions(objects, ['role_b']);
+    const a = withMembershipRoleOptions(objects, [{ name: 'role_a' }]);
+    const b = withMembershipRoleOptions(objects, [{ name: 'role_b' }]);
     expect(values(roleOptionsOf(a[1]))).toContain('role_a');
     expect(values(roleOptionsOf(a[1]))).not.toContain('role_b');
     expect(values(roleOptionsOf(b[1]))).toContain('role_b');
@@ -158,20 +191,25 @@ describe('#3723 collectStackOrgRoles — one walk for every host', () => {
       positions: [{ name: 'sales_rep' }, { name: 'sales_manager' }],
       permissions: [{ name: 'sales_user' }, { name: 'guest_portal' }],
     });
-    expect(roles).toEqual(['sales_rep', 'sales_manager', 'sales_user', 'guest_portal']);
+    expect(roles.map((r) => r.name)).toEqual([
+      'sales_rep',
+      'sales_manager',
+      'sales_user',
+      'guest_portal',
+    ]);
   });
 
   it('accepts bare strings as well as named entries', () => {
     expect(collectStackOrgRoles({ positions: ['sales_rep', { name: 'ops' }] })).toEqual([
-      'sales_rep',
-      'ops',
+      { name: 'sales_rep' },
+      { name: 'ops' },
     ]);
   });
 
   it('normalizes on the way out — the built-ins never leak into the extras', () => {
     expect(
       collectStackOrgRoles({ positions: [{ name: 'member' }, { name: 'owner' }, { name: 'ops' }] }),
-    ).toEqual(['ops']);
+    ).toEqual([{ name: 'ops' }]);
   });
 
   it('a stack with no role metadata yields nothing (and does not throw)', () => {