feat(security)!: ADR-0090 P1 breaking wave — position rename, profile removal, secure OWD default, principal/external spec shapes

One coordinated pre-launch pass implementing ADR-0090 D1-D4 and the P1
spec shapes of D10/D11 (docs/adr/0090). No compatibility aliases.

Renames (D3): sys_role→sys_position (+assignment/binding tables and
fields), RoleSchema→PositionSchema (flat, parent removed),
ctx.roles→ctx.positions, current_user.roles→current_user.positions
(formula validators, RLS docs, CEL examples), stack roles:→positions:,
metadata kinds role/profile→position. better-auth boundary untouched
(sys_member.role, additionalOrgRoles, org_membership_level).

Profile removal (D2): isProfile deleted from PermissionSetSchema and all
fixtures; isDefault narrowed to an install-time suggestion;
appDefaultProfileName→appDefaultPermissionSetName (isDefault-only).

OWD (D1/D4/D11): enum reduced to the canonical four; custom objects with
an owner field and no sharingModel now resolve PRIVATE (fail-closed for
unrecognised stored values; system objects keep the public fall-through);
new optional externalSharingModel field (external ≤ internal, P1 shape).
Regression tests pin the objectui#2348 incident shape (unset OWD + C/R/U
grant must not read others' records).

Principal taxonomy (D10, shape only): principalKind/audience/onBehalfOf
on ExecutionContext.

Sharing recipients: 'role'→'position' expanded via sys_user_position ∪
the membership transition source; 'role_and_subordinates' removed —
'unit_and_subordinates' expands the BU subtree (ADR-0057 D5 re-homing,
replacing the walk over a parent column that never existed).

Translations patched in place per generated-file contract; conformance
matrix row updated.

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

Author: claude

.changeset/adr-0090-p1-breaking-wave.md

@@ -0,0 +1,47 @@
+---
+'@objectstack/spec': minor
+'@objectstack/core': minor
+'@objectstack/runtime': minor
+'@objectstack/objectql': minor
+'@objectstack/formula': minor
+'@objectstack/rest': minor
+'@objectstack/cli': minor
+'@objectstack/plugin-security': minor
+'@objectstack/plugin-sharing': minor
+'@objectstack/plugin-auth': minor
+'@objectstack/service-automation': minor
+'@objectstack/trigger-record-change': minor
+'@objectstack/platform-objects': minor
+'@objectstack/metadata': minor
+---
+
+ADR-0090 P1 breaking wave — permission model v2 concept convergence.
+
+Pre-launch one-step renames and secure defaults (no compatibility aliases, per
+ADR-0090 D3/D4 superseding ADR-0057 D5/D7's alias discipline):
+
+- `sys_role` → `sys_position`, `sys_user_role` → `sys_user_position` (field
+  `role` → `position`), `sys_role_permission_set` → `sys_position_permission_set`
+  (field `role_id` → `position_id`); `RoleSchema`/`defineRole` →
+  `PositionSchema`/`definePosition` with **no `parent`** (positions are flat;
+  hierarchy lives on the business-unit tree).
+- `ExecutionContext.roles[]` → `positions[]`; the EvalUser/CEL contract
+  `current_user.roles` → `current_user.positions` (formula validators updated);
+  stack property `roles:` → `positions:`; metadata kinds `role`/`profile` →
+  `position` (profile kind removed).
+- `isProfile` removed from `PermissionSetSchema` (ADR-0090 D2); `isDefault`
+  narrows to an install-time suggestion; `appDefaultProfileName` →
+  `appDefaultPermissionSetName` (isDefault-only).
+- OWD enum drops legacy aliases `read`/`read_write`/`full`; new optional
+  `externalSharingModel` (external dial, `private` default) lands as P1 spec
+  shape (ADR-0090 D11).
+- **Secure default (D1)**: a custom object with an owner field and NO
+  `sharingModel` now resolves `private` (was: fully public). System objects
+  keep their explicit posture. Unrecognised stored values fail closed.
+- ExecutionContext gains the P1 principal-taxonomy shape (D10):
+  `principalKind` / `audience` / `onBehalfOf` (optional, semantics phase in
+  later).
+- Sharing recipients: `role` → `position` (expanded via `sys_user_position`
+  ∪ the better-auth membership transition source); `role_and_subordinates`
+  removed — `unit_and_subordinates` now expands the business-unit subtree
+  (finishes ADR-0057 D5's re-homing).

examples/app-crm/objectstack.config.ts

@@ -12,9 +12,9 @@ import * as actions from './src/actions/index.js';
 import { allHooks } from './src/hooks/index.js';
 import { allFlows } from './src/flows/index.js';
 import {
-  SalesRepRole,
-  SalesManagerRole,
-  FinanceApproverRole,
+  SalesRepPosition,
+  SalesManagerPosition,
+  FinanceApproverPosition,
   SalesUserPermissionSet,
   GuestPortalProfile,
   HighValueOpportunitySharingRule,
@@ -89,7 +89,7 @@ export default defineStack({
   flows: allFlows,
 
   // Security
-  roles: [SalesRepRole, SalesManagerRole, FinanceApproverRole],
+  positions: [SalesRepPosition, SalesManagerPosition, FinanceApproverPosition],
   permissions: [SalesUserPermissionSet, GuestPortalProfile],
   sharingRules: [
     HighValueOpportunitySharingRule,

examples/app-crm/src/security/index.ts

@@ -1,12 +1,12 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 export {
-  SalesRepRole,
-  SalesManagerRole,
-  FinanceApproverRole,
+  SalesRepPosition,
+  SalesManagerPosition,
+  FinanceApproverPosition,
   SalesUserPermissionSet,
   GuestPortalProfile,
-} from './sales-roles.js';
+} from './sales-positions.js';
 
 export {
   HighValueOpportunitySharingRule,

…ples/app-crm/src/security/sales-roles.ts …/app-crm/src/security/sales-positions.tsexamples/app-crm/src/security/sales-roles.ts renamed to examples/app-crm/src/security/sales-positions.ts examples/app-crm/src/security/sales-roles.ts renamed to examples/app-crm/src/security/sales-positions.ts

@@ -1,26 +1,26 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { defineRole } from '@objectstack/spec/identity';
+import { definePosition } from '@objectstack/spec/identity';
 import { definePermissionSet } from '@objectstack/spec/security';
 
 /**
  * Example roles — a small sales hierarchy.
  */
-export const SalesRepRole = defineRole({
+export const SalesRepPosition = definePosition({
   name: 'sales_rep',
   label: 'Sales Representative',
   description: 'Front-line sales representative.',
 });
 
-export const SalesManagerRole = defineRole({
+export const SalesManagerPosition = definePosition({
   name: 'sales_manager',
   label: 'Sales Manager',
   description: 'Manages a team of sales reps.',
   parent: 'sales_rep',
 });
 
 /** Referenced by the Discount Approval second step. */
-export const FinanceApproverRole = defineRole({
+export const FinanceApproverPosition = definePosition({
   name: 'finance_approver',
   label: 'Finance Approver',
   description: 'Finance team member authorised to approve discounts above 30%.',
@@ -34,7 +34,6 @@ export const FinanceApproverRole = defineRole({
 export const SalesUserPermissionSet = definePermissionSet({
   name: 'crm_sales_user',
   label: 'CRM Sales User',
-  isProfile: false,
   objects: {
     crm_account:     { allowRead: true, allowCreate: true,  allowEdit: true,  allowDelete: false },
     crm_contact:     { allowRead: true, allowCreate: true,  allowEdit: true,  allowDelete: false },
@@ -55,7 +54,6 @@ export const SalesUserPermissionSet = definePermissionSet({
 export const GuestPortalProfile = definePermissionSet({
   name: 'guest_portal',
   label: 'Guest (Public Forms)',
-  isProfile: true,
   objects: {
     crm_lead: { allowRead: false, allowCreate: true, allowEdit: false, allowDelete: false },
   },

examples/app-crm/src/security/sharing-rules.ts

@@ -15,7 +15,7 @@ export const HighValueOpportunitySharingRule = defineSharingRule({
   condition: 'record.amount > 100000',
   accessLevel: 'edit',
   sharedWith: {
-    type: 'role',
+    type: 'position',
     value: 'sales_manager',
   },
   active: true,
@@ -32,12 +32,12 @@ export const RepLeadSharingRule = defineSharingRule({
   description: "Share each rep's leads with the Sales Manager role for coaching visibility.",
   object: 'crm_lead',
   ownedBy: {
-    type: 'role',
+    type: 'position',
     value: 'sales_rep',
   },
   accessLevel: 'read',
   sharedWith: {
-    type: 'role',
+    type: 'position',
     value: 'sales_manager',
   },
   active: true,
@@ -56,7 +56,7 @@ export const WonDealActivitySharingRule = defineSharingRule({
   condition: "record.status == 'completed'",
   accessLevel: 'read',
   sharedWith: {
-    type: 'role',
+    type: 'position',
     value: 'sales_rep',
   },
   active: true,

examples/app-showcase/src/coverage.ts

@@ -123,7 +123,7 @@ export const KIND_COVERAGE: Record<MetadataType, KindCoverage> = {
   profile: {
     status: 'demonstrated',
     files: ['src/security/index.ts'],
-    notes: 'MemberDefaultProfile — a permission set with isProfile: true (ADR-0056 D7).',
+    notes: 'MemberDefault — the isDefault permission set (ADR-0090 D5 suggestion flag).',
   },
   role: { status: 'demonstrated', files: ['src/security/index.ts'] },
 

examples/app-showcase/src/security/index.ts

@@ -35,7 +35,6 @@ export const ContributorPermissionSet = {
   name: 'showcase_contributor',
   label: 'Showcase Contributor',
   description: 'Standard access for contributors, with budget fields hidden and row-level scoping to own records.',
-  isProfile: false,
   objects: {
     showcase_project: { allowRead: true, allowCreate: false, allowEdit: true, allowDelete: false },
     showcase_task: { allowRead: true, allowCreate: true, allowEdit: true, allowDelete: false },
@@ -61,7 +60,7 @@ export const ContributorPermissionSet = {
       object: 'showcase_task',
       operation: 'select' as const,
       using: "assignee == current_user.email",
-      roles: ['contributor'],
+      positions: ['contributor'],
       enabled: true,
       priority: 10,
     },
@@ -76,7 +75,7 @@ export const ContributorPermissionSet = {
       object: 'showcase_invoice',
       operation: 'select' as const,
       using: "owner == current_user.email",
-      roles: ['contributor'],
+      positions: ['contributor'],
       enabled: true,
       priority: 10,
     },
@@ -92,7 +91,7 @@ export const ContributorPermissionSet = {
       object: 'showcase_invoice',
       operation: 'update' as const,
       check: "owner == current_user.email",
-      roles: ['contributor'],
+      positions: ['contributor'],
       enabled: true,
       priority: 10,
     },
@@ -114,7 +113,6 @@ export const MemberDefaultProfile = {
   name: 'showcase_member_default',
   label: 'Showcase Member (Default)',
   description: 'App-declared default profile for new sign-ups — read-mostly baseline (ADR-0056 D7).',
-  isProfile: true,
   isDefault: true,
   objects: {
     showcase_account: { allowRead: true },
@@ -136,7 +134,7 @@ export const RedProjectSharingRule = {
   object: 'showcase_project',
   condition: "record.health == 'red'",
   accessLevel: 'read' as const,
-  sharedWith: { type: 'role' as const, value: 'exec' },
+  sharedWith: { type: 'position' as const, value: 'exec' },
   active: true,
 };
 
@@ -155,7 +153,7 @@ export const HighValueRedProjectRule = {
   object: 'showcase_project',
   condition: "record.health == 'red' && record.budget > 100000",
   accessLevel: 'read' as const,
-  sharedWith: { type: 'role' as const, value: 'manager' },
+  sharedWith: { type: 'position' as const, value: 'manager' },
   active: true,
 };
 
@@ -166,9 +164,9 @@ export const ContributorTaskSharingRule = {
   label: "Contributor Tasks → Manager",
   description: "Share each contributor's tasks with managers for oversight.",
   object: 'showcase_task',
-  ownedBy: { type: 'role' as const, value: 'contributor' },
+  ownedBy: { type: 'position' as const, value: 'contributor' },
   accessLevel: 'read' as const,
-  sharedWith: { type: 'role' as const, value: 'manager' },
+  sharedWith: { type: 'position' as const, value: 'manager' },
   active: true,
 };
 

examples/app-todo/test/mcp-actions.e2e.ts

@@ -101,7 +101,7 @@ function mcpRequest(body: unknown): Request {
   });
 
   // The acting user — an authenticated, non-system principal.
-  const user = { userId: 'user_1', roles: [], permissions: [], systemPermissions: [] };
+  const user = { userId: 'user_1', positions: [], permissions: [], systemPermissions: [] };
   const bridge = bridgeFor(user);
 
   // ── Step 1 — the MCP server advertises the action tools ───────────
@@ -151,15 +151,15 @@ function mcpRequest(body: unknown): Request {
       ? o
       : { ...o, actions: o.actions.map((a: any) => (a.name === 'clone_task' ? { ...a, requiredPermissions: ['todo_admin'] } : a)) },
   );
-  const denyBridge = bridgeFor({ userId: 'user_2', roles: [], permissions: [], systemPermissions: [] }, gatedObjects);
+  const denyBridge = bridgeFor({ userId: 'user_2', positions: [], permissions: [], systemPermissions: [] }, gatedObjects);
   const denied = await callMcp(denyBridge, toolsCall(5, 'run_action', { actionName: 'clone_task', recordId: taskId }));
   check(denied.result?.isError === true, 'run_action denied when the caller lacks the capability');
   check(/requires capability/i.test(denied.result?.content?.[0]?.text ?? ''), 'denial cites the missing capability');
   // …and list_actions hides what the caller may not run.
   const denyList = JSON.parse((await callMcp(denyBridge, toolsCall(6, 'list_actions', {}))).result.content[0].text).actions as any[];
   check(!denyList.some((a) => a.name === 'clone_task'), 'list_actions hides the gated action from a non-holder');
 
-  const allowBridge = bridgeFor({ userId: 'admin_1', roles: [], permissions: [], systemPermissions: ['todo_admin'] }, gatedObjects);
+  const allowBridge = bridgeFor({ userId: 'admin_1', positions: [], permissions: [], systemPermissions: ['todo_admin'] }, gatedObjects);
   const allowed = await callMcp(allowBridge, toolsCall(7, 'run_action', { actionName: 'clone_task', recordId: taskId }));
   check(allowed.result?.isError !== true, 'run_action allowed for a holder of the capability');
   const allowList = JSON.parse((await callMcp(allowBridge, toolsCall(8, 'list_actions', {}))).result.content[0].text).actions as any[];

packages/cli/src/commands/serve.ts

@@ -1192,13 +1192,12 @@ export default class Serve extends Command {
 
             // Collect application-defined org roles from the stack so
             // Better-Auth's organization plugin accepts invitations to
-            // those roles (otherwise it 400s with `ROLE_NOT_FOUND`).
-            // Sources:
-            //   - top-level `roles[]` (role hierarchy entries)
-            //   - `permissions[]` PermissionSets where `isProfile === true`
-            //     (these double as role identifiers; e.g. CRM Profiles)
-            // Real RBAC enforcement is still owned by SecurityPlugin, which
-            // matches these names against `permission` metadata entries.
+            // those names (otherwise it 400s with `ROLE_NOT_FOUND`).
+            // better-auth boundary: its API keeps the word "roles"
+            // (ADR-0090 D3 exception). Sources:
+            //   - top-level `positions[]` (flat distribution groups)
+            //   - `permissions[]` PermissionSet names
+            // Real RBAC enforcement is still owned by SecurityPlugin.
             const additionalOrgRoles = new Set<string>();
             try {
               const stackAny: any = config ?? {};
@@ -1209,10 +1208,10 @@ export default class Serve extends Command {
                   if (n && n !== 'owner' && n !== 'admin' && n !== 'member') additionalOrgRoles.add(n);
                 }
               };
-              collect(stackAny.roles);
+              collect(stackAny.positions);
               if (Array.isArray(stackAny.permissions)) {
                 for (const p of stackAny.permissions) {
-                  if (p && typeof p.name === 'string' && p.isProfile !== false) {
+                  if (p && typeof p.name === 'string') {
                     if (p.name !== 'owner' && p.name !== 'admin' && p.name !== 'member') additionalOrgRoles.add(p.name);
                   }
                 }
@@ -1301,13 +1300,13 @@ export default class Serve extends Command {
             // Pair: SecurityPlugin (RBAC) — optional
             try {
               const securityPkg = '@objectstack/plugin-security';
-              const { SecurityPlugin, appDefaultProfileName } = await import(/* webpackIgnore: true */ securityPkg);
+              const { SecurityPlugin, appDefaultPermissionSetName } = await import(/* webpackIgnore: true */ securityPkg);
               // ADR-0056 D7 — honor an app-declared default profile. A stack
-              // permission set marked `isProfile && isDefault` becomes the
+              // permission set marked `isDefault` becomes the
               // fallback for users with no explicit grants. The SecurityPlugin's
               // own scan only sees its built-in sets, so the CLI passes the
               // declared name through explicitly (undefined → built-in default).
-              const appDefaultProfile = appDefaultProfileName((config as any)?.permissions);
+              const appDefaultProfile = appDefaultPermissionSetName((config as any)?.permissions);
               await kernel.use(new SecurityPlugin(appDefaultProfile ? { fallbackPermissionSet: appDefaultProfile } : undefined));
               trackPlugin('Security');
             } catch {

packages/cli/src/utils/format.ts

@@ -123,7 +123,7 @@ export interface MetadataStats {
   workflows: number;
   agents: number;
   apis: number;
-  roles: number;
+  positions: number;
   permissions: number;
   themes: number;
   datasources: number;
@@ -163,7 +163,7 @@ export function collectMetadataStats(config: any): MetadataStats {
     workflows: count(config.workflows),
     agents: count(config.agents),
     apis: count(config.apis),
-    roles: count(config.roles),
+    positions: count(config.positions),
     permissions: count(config.permissions),
     themes: count(config.themes),
     datasources: count(config.datasources),
@@ -268,7 +268,7 @@ export function printMetadataStats(stats: MetadataStats) {
     {
       label: 'Security',
       items: [
-        ['Roles', stats.roles],
+        ['Positions', stats.positions],
         ['Permissions', stats.permissions],
       ],
     },