test(plugin-auth): migrate the four fixtures that pinned the removed auth-axis derivation

They asserted `positions[]` WAS the better-auth `sys_user.role` scalar split on
commas — the derivation the #15136 ruling removed — so they are fixtures to
migrate, not evidence against it. Each now asserts the scalar is absent from
the array while remaining untouched on the payload, which is the half of
ADR-0068 D2 that did not change. One case is added for the axis the payload was
missing entirely: a `sys_user_position` assignment reaching `positions[]`.

Also declares in `packages/spec` which axis `positions` is, and that the
better-auth role scalar is not it, with the regenerated reference page.

Part of #15136

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpTx2tbq3pZRYAdoGt6E6Y

Author: claude

.changeset/session-payload-positions-security-axis.md

@@ -0,0 +1,79 @@
+---
+"@objectstack/plugin-auth": minor
+"@objectstack/spec": minor
+---
+
+fix(plugin-auth)!: `positions[]` on the session payload is the SECURITY axis, not the better-auth role scalar (#15136)
+
+<!-- adr-0087: registered session-payload-positions-security-axis -->
+
+**BREAKING** meaning change on a published payload — `user.positions` in
+`GET /api/v1/auth/get-session`. Shipped as `minor` under the repo's
+launch-window convention for breaking changes. Maintainer ruling 2026-09-05 on
+#15136 (director decision batch #39, item 2, verbatim 「同意」): option A, one
+name, one meaning.
+
+`customSession` built the array from the better-auth `sys_user.role` scalar
+split on commas, plus the active membership mapped to `org_*`, plus
+`platform_admin` — and read **nothing** from `sys_user_position`, the ADR-0057
+D4 table that is the source of truth for custom positions. The Console binds
+that array straight through as the CEL root `current_user`, so an
+`action.visible` (or any `visibleWhen`, nav `visible`, page-tab gate) narrowed
+by a business position answered FALSE for **everyone**, including the user who
+genuinely held it.
+
+⭐ It failed **silently and in the invisible direction**: the root was bound and
+the key was present, so `has(current_user.positions)` was true, CEL raised
+nothing, and the predicate simply returned FALSE. A predicate that *faults*
+fails OPEN in the shell and would have shown the button; a successful FALSE
+shows nothing and reports nothing. The documented example
+(`'org_admin' in current_user.positions`) kept working throughout, because
+`org_admin` is the one name that sits on **both** axes.
+
+This was a **declared** contract being violated, not an ambiguous name:
+`EvalUserSchema` already specified `positions` as "built-in identity names +
+position names", exposed to "every predicate surface (server formula, server
+RLS, client UI gates) ... with an identical shape" so that a predicate
+"evaluates identically wherever it is written". `/auth/me/permissions` and
+every server-side evaluator (`ExecutionContext.positions`) already resolved the
+security axis; only the session payload did not.
+
+**What changes**
+
+- `packages/plugins/plugin-auth` — the hand-rolled derivation is **deleted**,
+  not repaired. `customSession` now asks `resolveUserAuthzGrants`, the ONE
+  authority (`core/security/resolve-authz-context.ts`, whose header forbids
+  every entry point from re-reading the `sys_*` grant tables itself), scoped to
+  the session's active organization. The payload therefore carries the
+  `sys_user_position` assignments and the ADR-0090 D5 `everyone` anchor, and
+  agrees with `/auth/me/permissions` set for set. Same move
+  `isPlatformAdminUserId` made at #10348.
+- `isPlatformAdmin` is now derived from that array (ADR-0068 D2 defines it as
+  an alias of `'platform_admin' in positions`), so one authority answers both.
+- `packages/spec` — `EvalUserSchema` states which axis `positions` is, and
+  states that the better-auth role scalar is not it.
+
+**No key is renamed, and none is added.** The ruling anticipated a renamed
+auth-role array; measured against the tree, it has no content to carry and no
+consumer. Everything the old union contributed beyond the security axis was the
+`sys_user.role` scalar's own tokens — and that scalar is **already published,
+unchanged, as `user.role`** (the single exception ADR-0090 D3's "role" word ban
+carves out, for third-party schema this platform does not own). Minting a
+`roles` array would revive the exact banned identifier `check:role-word`
+ratchets against, to publish information the payload already carries. A
+consumer that wants the better-auth role reads `user.role`.
+
+**What does NOT change:** `user.role` is still never overwritten (ADR-0068 D2);
+`platform_admin` still derives from the unscoped `admin_full_access` grant with
+its ADR-0091 validity window and ADR-0049 active flag intact — pinned shape for
+shape against both gates by `platform-admin-standing.consolidation.test.ts`
+PIN 6, which passes unchanged.
+
+**Upgrade.** If you gate on the better-auth role scalar, read `user.role`
+instead of looking for its tokens in `user.positions`. Predicates written
+against real position names, built-in identity names, or `everyone` need no
+change — they start working. Deployments that stored business role names in
+`sys_user.role` rather than assigning positions should assign them through
+`sys_user_position` (the governed ADR-0090 D12 channel); a name in
+`sys_member.role` is still projected, so membership-derived names are
+unaffected.

content/docs/references/identity/eval-user.mdx

@@ -18,6 +18,29 @@ it is written.
 `roles`, ADR-0090 D3). A singular field is NOT part of this contract — its legacy "overwritten to 'admin' on promotion"
 behavior is the footgun this eliminates.
 
+## Which axis `positions` is — and which it is not (#15136)
+
+It is the **security** axis: the built-in identity names plus the
+`sys_position` names the principal actually holds through `sys_user_position`
+(ADR-0057 D4) and their active membership, plus the `everyone` anchor
+(ADR-0090 D5) — exactly the set `/auth/me/permissions` reports and
+`resolveUserAuthzGrants` resolves. Every surface derives it from that one
+authority, so the "identical shape" promise above is a property of the
+producer, not a convention producers are asked to honour.
+
+⛔ It is **not** the better-auth `sys_user.role` scalar. That scalar is an
+authentication-layer field on a table this platform does not own; it stays
+published, unchanged, as `user.role` (the one exception ADR-0090 D3's word
+ban carves out), and a consumer that genuinely wants it reads it there.
+
+⚠️ The session payload used to union the scalar into this array and omit the
+`sys_user_position` names entirely, which made a position-narrowed client
+gate answer FALSE for its own holder — silently, since the root and the key
+were both bound and CEL raised nothing. The documented `org_admin` example
+kept working throughout because that name sits on both axes. If you are
+adding a producer of this shape: derive it from the authority, never
+assemble it from whatever identity fields are in reach.
+
 See also: docs/adr/0068-unified-user-context-and-built-in-identity-roles.md
 
 <Callout type="info">
@@ -45,7 +68,7 @@ const result = EvalUserSchema.parse(data);
 | **id** | `string` | ✅ | User ID |
 | **name** | `string` | optional | Display name |
 | **email** | `string` | optional | Email address |
-| **positions** | `string[]` | optional (default: `[]`) | Canonical position/identity names assigned to the user (scope-resolved) |
+| **positions** | `string[]` | optional (default: `[]`) | Canonical position/identity names the user holds — built-in identity names plus sys_position assignments, scope-resolved (ADR-0068 D3). The security axis, the same set /auth/me/permissions reports; NOT the better-auth user.role scalar, which remains published as user.role |
 | **isPlatformAdmin** | `boolean` | optional | DERIVED alias of 'platform_admin' in positions. Deprecated. |
 | **organizationId** | `string \| null` | optional | Active organization ID (null = platform/unscoped) |
 

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

@@ -3474,52 +3474,85 @@ describe('AuthManager', () => {
       return plugin._fn as (input: { user: any; session: any }) => Promise<any>;
     };
 
-    it('returns positions=[] for a regular user with no stored role', async () => {
+    // [#15136 — maintainer ruling 2026-09-05, option A] These four cases used to
+    // pin the OPPOSITE contract: that the better-auth `sys_user.role` scalar,
+    // split on commas, WAS `positions[]`. That is the derivation the ruling
+    // removed — `positions[]` is the security axis on every surface — so they
+    // are migrated fixtures, not evidence against it. Each one now asserts the
+    // scalar is ABSENT from the array while remaining untouched on the payload,
+    // which is the half of ADR-0068 D2 that did not change.
+    it('carries the ADR-0090 D5 `everyone` anchor for a regular user with no stored role', async () => {
       const callback = await getSessionCallback(makeDataEngine({ platformAdmin: false }));
       const result = await callback({
         user: { id: 'u-1', email: 'a@b.com' },
         session: {},
       });
       expect(result.user.role).toBeUndefined();
-      expect(result.user.positions).toEqual([]);
+      expect(result.user.positions).toEqual(['everyone']);
     });
 
-    it('splits a stored role string into positions for a non-admin user', async () => {
+    it('does NOT project the stored role scalar into positions[]', async () => {
       const callback = await getSessionCallback(makeDataEngine({ platformAdmin: false }));
       const result = await callback({
         user: { id: 'u-1', email: 'a@b.com', role: 'manager' },
         session: {},
       });
-      // No promotion: `role` keeps its stored value.
+      // The scalar keeps its stored value — it is simply not an authorization
+      // axis, so it no longer appears in the array authored predicates read.
       expect(result.user.role).toBe('manager');
-      expect(result.user.positions).toEqual(['manager']);
+      expect(result.user.positions).not.toContain('manager');
+      expect(result.user.positions).toEqual(['everyone']);
     });
 
-    it('appends platform_admin to positions[] without overwriting role when promoting a platform admin', async () => {
+    it('derives platform_admin without overwriting role and without the scalar', async () => {
       const callback = await getSessionCallback(makeDataEngine({ platformAdmin: true }));
       const result = await callback({
         user: { id: 'u-1', email: 'a@b.com', role: 'manager' },
         session: {},
       });
       // ADR-0068: NO `role:'admin'` overwrite footgun. The deprecated scalar
-      // keeps its stored value; the canonical platform_admin identity is added
-      // to roles[], and isPlatformAdmin is a derived alias.
+      // keeps its stored value; the canonical platform_admin identity is on
+      // positions[], and isPlatformAdmin is a derived alias of it.
       expect(result.user.role).toBe('manager');
-      expect(result.user.positions).toEqual(['manager', 'platform_admin']);
+      expect(result.user.positions).toContain('platform_admin');
+      expect(result.user.positions).not.toContain('manager');
       expect(result.user.isPlatformAdmin).toBe(true);
     });
 
-    it('splits a multi-token stored role and appends platform_admin without duplicates', async () => {
+    it('ignores a multi-token stored role entirely while still deriving platform_admin', async () => {
       const callback = await getSessionCallback(makeDataEngine({ platformAdmin: true }));
       const result = await callback({
         user: { id: 'u-1', email: 'a@b.com', role: 'admin,manager' },
         session: {},
       });
       expect(result.user.role).toBe('admin,manager');
-      expect(result.user.positions).toEqual(['admin', 'manager', 'platform_admin']);
+      expect(result.user.positions).toContain('platform_admin');
+      for (const token of ['admin', 'manager']) {
+        expect(result.user.positions).not.toContain(token);
+      }
       expect(result.user.isPlatformAdmin).toBe(true);
     });
 
+    it('carries an ADR-0057 D4 `sys_user_position` assignment — the axis the payload was missing', async () => {
+      const engine = makeDataEngine({ platformAdmin: false });
+      const inner = engine.find;
+      engine.find = vi.fn(async (object: string, q?: any) => {
+        if (object === 'sys_user_position') {
+          return [{ user_id: 'u-1', position: 'demo_reviewer', organization_id: null }];
+        }
+        return inner(object, q);
+      }) as any;
+
+      const callback = await getSessionCallback(engine);
+      const result = await callback({
+        user: { id: 'u-1', email: 'a@b.com', role: 'manager' },
+        session: {},
+      });
+      expect(result.user.positions).toContain('demo_reviewer');
+      // Still not the scalar — the two axes do not blend.
+      expect(result.user.positions).not.toContain('manager');
+    });
+
     it('returns the payload untouched when the user has no id', async () => {
       const callback = await getSessionCallback(makeDataEngine({ platformAdmin: false }));
       const user = { email: 'anon@b.com' };

packages/spec/src/identity/eval-user.zod.ts

@@ -18,6 +18,29 @@ import type { PermissionSet } from '../security/permission.zod';
  * `roles`, ADR-0090 D3). A singular field is NOT part of this contract — its legacy "overwritten to 'admin' on promotion"
  * behavior is the footgun this eliminates.
  *
+ * ## Which axis `positions` is — and which it is not (#15136)
+ *
+ * It is the **security** axis: the built-in identity names plus the
+ * `sys_position` names the principal actually holds through `sys_user_position`
+ * (ADR-0057 D4) and their active membership, plus the `everyone` anchor
+ * (ADR-0090 D5) — exactly the set `/auth/me/permissions` reports and
+ * `resolveUserAuthzGrants` resolves. Every surface derives it from that one
+ * authority, so the "identical shape" promise above is a property of the
+ * producer, not a convention producers are asked to honour.
+ *
+ * ⛔ It is **not** the better-auth `sys_user.role` scalar. That scalar is an
+ * authentication-layer field on a table this platform does not own; it stays
+ * published, unchanged, as `user.role` (the one exception ADR-0090 D3's word
+ * ban carves out), and a consumer that genuinely wants it reads it there.
+ *
+ * ⚠️ The session payload used to union the scalar into this array and omit the
+ * `sys_user_position` names entirely, which made a position-narrowed client
+ * gate answer FALSE for its own holder — silently, since the root and the key
+ * were both bound and CEL raised nothing. The documented `org_admin` example
+ * kept working throughout because that name sits on both axes. If you are
+ * adding a producer of this shape: derive it from the authority, never
+ * assemble it from whatever identity fields are in reach.
+ *
  * @see docs/adr/0068-unified-user-context-and-built-in-identity-roles.md
  */
 
@@ -189,8 +212,12 @@ export const EvalUserSchema = lazySchema(() =>
     id: z.string().describe('User ID'),
     name: z.string().optional().describe('Display name'),
     email: z.string().optional().describe('Email address'),
-    /** CANONICAL. Scope-resolved (ADR-0068 D3); built-in identity names + position names. */
-    positions: z.array(z.string()).default([]).describe('Canonical position/identity names assigned to the user (scope-resolved)'),
+    /**
+     * CANONICAL. Scope-resolved (ADR-0068 D3); built-in identity names +
+     * position names. The SECURITY axis (#15136) — never the better-auth
+     * `sys_user.role` scalar, which stays published as `user.role`.
+     */
+    positions: z.array(z.string()).default([]).describe('Canonical position/identity names the user holds — built-in identity names plus sys_position assignments, scope-resolved (ADR-0068 D3). The security axis, the same set /auth/me/permissions reports; NOT the better-auth user.role scalar, which remains published as user.role'),
     /** DERIVED alias of positions.includes(platform_admin) (ADR-0068 D2). Deprecated surface. */
     isPlatformAdmin: z.boolean().optional().describe("DERIVED alias of 'platform_admin' in positions. Deprecated."),
     organizationId: z.string().nullable().optional().describe('Active organization ID (null = platform/unscoped)'),