fix(app-shell): bind current_user.positions into the client predicate scope; align role-gating examples (#1583 / ADR-0058) (#2573)

* test(e2e-live): B3 cascading-options live e2e — client re-filter + server rejection (#2559 / #1583)

Adds e2e/live/cascading-options.spec.ts, the live-backend counterpart to the
no-backend docs e2e (e2e/cascading-options.spec.ts). Against the real console +
backend it drives the showcase `showcase_cascade` create form and asserts the
dual-side B3 contract:

- CLIENT: the child `province`'s offered option set re-filters as the parent
  `country` changes, and a now-invalid child value clears (cascade-clear).
- SERVER: POST /api/v1/data/showcase_cascade rejects an out-of-set option value
  (400 VALIDATION_FAILED / invalid_option) and accepts the in-set one — client
  hiding is UX, the server is the boundary.

Excluded from the default/CI run (testIgnore '**/live/**'); opt-in via
`pnpm test:e2e:live` with the stack up. Requires the framework showcase_cascade
fixture (framework #2559).

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

* fix(app-shell): bind current_user.positions into the client predicate scope; align role-gating examples (#1583 / ADR-0058)

The console forwarded only id/name/email/role/roles/isPlatformAdmin into the
expression scope, so a position-gated option predicate
(`'admin' in current_user.positions` — the shape the framework rule-validator
binds and enforces, EvalUser) faulted client-side and FAILED OPEN: the gated
option stayed visible to everyone and was only rejected by the server on
submit. Forward `positions` (auth payload already carries it) in AppContent and
RecordFormPage so client hiding and the server verdict agree.

Also switch every role-gating example from `current_user.roles` — a key the
server never binds, so a predicate written that way is never enforced — to
`current_user.positions`: schema-catalog role-gated-options.json, fields/select
docs, the skills guide, ADR-0058 example spellings, TSDoc on
SelectOption.visibleWhen, evaluator header comments, and the three unit tests'
mock scopes. Matches @objectstack/spec's own SelectOption.visibleWhen example.

Verified: optionRules/optionLint/SelectField.cascade/useExpression 51/51,
schema-catalog 836/836 (incl. the option-predicate guard), eslint 0 errors.

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

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/b3-positions-predicate-scope.md

@@ -0,0 +1,5 @@
+---
+'@object-ui/app-shell': patch
+---
+
+Forward the authenticated user's `positions` into the client predicate scope (`current_user.positions`) in the console shell and the record form page. Position-gated select options (`'admin' in current_user.positions`, ADR-0058 / objectui#2284) now hide client-side like they do everywhere else, instead of failing open as visible and only being rejected by the server on submit — `positions` is the actor shape the framework rule-validator actually binds and enforces. Docs, the schema-catalog role-gated example, the skills guide, and inline examples switch the role-gating spelling from `current_user.roles` (never bound server-side, so never enforced) to `current_user.positions`.

content/docs/fields/select.mdx

@@ -70,7 +70,7 @@ cascade-clear propagate down the chain.
   { "label": "Private (only me)", "value": "private" },
   { "label": "My team", "value": "team" },
   { "label": "Whole organization", "value": "org" },
-  { "label": "Public — external", "value": "public", "visibleWhen": "'admin' in current_user.roles" }
+  { "label": "Public — external", "value": "public", "visibleWhen": "'admin' in current_user.positions" }
 ]}
 ```
 

docs/adr/0058-cascading-select-options.md

@@ -37,9 +37,9 @@ Rationale:
    its cascade; `visibleWhen` is already the field-level CEL predicate (ADR-0036).
    Reusing both introduces no new category and no bespoke matrix format.
 2. **`visibleWhen` is strictly more expressive than a value cascade.** It sees
-   `current_user` (roles/tenant) and `now()`, so the *same* knob covers cascades
+   `current_user` (positions/tenant) and `now()`, so the *same* knob covers cascades
    (`record.country == 'cn'`) **and** role/context gating
-   (`'admin' in current_user.roles`). `validFor` can only express "varies with
+   (`'admin' in current_user.positions`). `validFor` can only express "varies with
    another field's value" — it cannot gate by role. `current_user` is already
    bound on every predicate surface (server formula, RLS, client UI gates), so a
    role-referencing option predicate needs **zero new binding**.
@@ -113,7 +113,7 @@ expression parses and the field exists.
 `@object-ui/core`'s `lintOptionPredicates(fields)` (`evaluator/optionLint.ts`)
 closes this at authoring/CI time with three conservative checks: `syntax` (via
 `@objectstack/formula`'s `validateExpression`, no schema hint so a legitimate
-`current_user.roles` reference is never flagged), `unknown-field` (a `record.<name>`
+`current_user.positions` reference is never flagged), `unknown-field` (a `record.<name>`
 naming no declared sibling), and `option-literal-not-in-domain` (a literal
 compared against an *enum* sibling that is outside its declared value set). It
 only flags what it can statically prove — non-`record.` roots, open-domain

examples/schema-catalog/src/schemas/fields-select/role-gated-options.json

@@ -21,7 +21,7 @@
         {
           "label": "Public — external",
           "value": "public",
-          "visibleWhen": "'admin' in current_user.roles"
+          "visibleWhen": "'admin' in current_user.positions"
         }
       ]
     }

packages/app-shell/src/console/AppContent.tsx

@@ -619,8 +619,14 @@ export function AppContent({ extraRoutes, extraRoutesNoApp }: AppContentProps =
         // name/email/role were forwarded → isPlatformAdmin-gated actions were
         // hidden even for platform admins.
         isPlatformAdmin: (user as any).isPlatformAdmin ?? false,
+        // Positions are what the SERVER binds as `current_user` for per-option
+        // `visibleWhen` authorization gating (ADR-0058; framework EvalUser —
+        // objectui#2284). Forwarding them lets a position-gated option
+        // (`'admin' in current_user.positions`) hide client-side too, instead
+        // of failing open as visible and only being rejected on submit.
+        positions: (user as any).positions ?? [],
       }
-    : { name: 'Anonymous', email: '', role: 'guest', isPlatformAdmin: false };
+    : { name: 'Anonymous', email: '', role: 'guest', isPlatformAdmin: false, positions: [] };
 
   return (
     <ExpressionProvider user={expressionUser} app={activeApp} data={{}} features={features}>

packages/app-shell/src/views/RecordFormPage.tsx

@@ -159,8 +159,15 @@ export function RecordFormPage({ mode }: RecordFormPageProps) {
   const expressionUser = useMemo(
     () =>
       user
-        ? { name: user.name, email: user.email, role: user.role ?? 'user' }
-        : { name: 'Anonymous', email: '', role: 'guest' },
+        ? {
+            name: user.name,
+            email: user.email,
+            role: user.role ?? 'user',
+            // Server-parity actor shape for per-option `visibleWhen` gating
+            // (ADR-0058): the rule-validator binds `current_user.positions`.
+            positions: (user as any).positions ?? [],
+          }
+        : { name: 'Anonymous', email: '', role: 'guest', positions: [] },
     [user],
   );
 

packages/core/src/evaluator/__tests__/optionLint.test.ts

@@ -58,7 +58,7 @@ describe('lintOptionPredicates — clean predicates', () => {
         type: 'select',
         options: [
           { label: 'Standard', value: 'standard' },
-          { label: 'Admin only', value: 'admin_only', visibleWhen: "'admin' in current_user.roles" },
+          { label: 'Admin only', value: 'admin_only', visibleWhen: "'admin' in current_user.positions" },
         ],
       },
     ]);

packages/core/src/evaluator/__tests__/optionRules.test.ts

@@ -89,18 +89,18 @@ describe('resolveVisibleOptions — cascade', () => {
 describe('resolveVisibleOptions — role / context gating via scope', () => {
   const options: OptionLike[] = [
     { label: 'Standard', value: 'standard' },
-    { label: 'Admin only', value: 'admin_only', visibleWhen: "'admin' in current_user.roles" },
+    { label: 'Admin only', value: 'admin_only', visibleWhen: "'admin' in current_user.positions" },
   ];
 
   it('hides the admin option for a non-admin', () => {
-    const vals = resolveVisibleOptions(options, {}, { current_user: { roles: ['sales'] } }).map(
+    const vals = resolveVisibleOptions(options, {}, { current_user: { positions: ['sales'] } }).map(
       (o) => o.value,
     );
     expect(vals).toEqual(['standard']);
   });
 
   it('offers the admin option to an admin', () => {
-    const vals = resolveVisibleOptions(options, {}, { current_user: { roles: ['admin'] } }).map(
+    const vals = resolveVisibleOptions(options, {}, { current_user: { positions: ['admin'] } }).map(
       (o) => o.value,
     );
     expect(vals).toEqual(['standard', 'admin_only']);

packages/core/src/evaluator/optionLint.ts

@@ -27,7 +27,7 @@
  *   1. `syntax`      — the predicate is valid CEL. Delegated to the canonical
  *                      `@objectstack/formula` `validateExpression` (no schema
  *                      hint → pure parse validation, so a legitimate
- *                      `current_user.roles` reference is never flagged).
+ *                      `current_user.positions` reference is never flagged).
  *   2. `unknown-field` — a `record.<name>` reference names a field the form
  *                      doesn't declare (a sibling typo, `record.contry`).
  *   3. `option-literal-not-in-domain` — a `record.<enum> == '<literal>'` (or

packages/core/src/evaluator/optionRules.ts

@@ -16,7 +16,7 @@
  * {@link evalFieldPredicate}). This expresses both:
  *   - cascades — `record.country == 'cn'` (the dependent list narrows as the
  *     controlling field changes), and
- *   - role/context gating — `'admin' in current_user.roles`.
+ *   - role/context gating — `'admin' in current_user.positions`.
  *
  * A field declares which sibling fields its option list reacts to via
  * `dependsOn` (aligns with `@objectstack/spec` Field.dependsOn — the same knob