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

* 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

* fix(liveness,contract): position ledger rename + externalSharingModel classification + downstream fixture

Liveness: GOVERNED kind role→position; liveness/role.json→position.json
(flat, parent dropped); permission ledger rowLevelSecurity.positions;
object ledger gains externalSharingModel as 'authorable' with the P1
shape-only rationale and the #2696 pointer. Downstream-contract sharing
fixture moves to the position recipient.

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

* fix(examples): showcase stack positions property, coverage kind, position identifiers

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

* fix(runtime,sharing,examples): app-plugin position sections, runtime recipient enum, D1 grandfather stamps — dogfood 39/39 green

- app-plugin: stack section registration positions→'position' kind (the
  seeding gap: declared positions never reached the registry); standalone
  artifact surface roles→positions; CLI diff/stats keys.
- sys_sharing_rule.recipient_type runtime enum role→position (seeding
  inserted 'position' and was rejected by the stale enum), description
  updated to the BU-subtree semantics of unit_and_subordinates.
- ADR-0090 D1 grandfather stamps: explicit `sharingModel:
  'public_read_write'` on showcase/dogfood fixture objects whose isolation
  is RLS-owned or intentionally public (they carry an auto-injected
  owner_id, so the new unset⇒private default would owner-filter them).
- dogfood expectations updated to v2 semantics (recipient 'position';
  appDefaultPermissionSetName is isDefault-only).
- service-datasource test: explicit casts for Response.json() unknowns
  (latent, surfaced by the affected-package typecheck).

Full dogfood suite 39 files / 191 tests green; repo-wide typecheck clean.

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

* fix(spec,automation,core): regenerate API-surface snapshot for the position rename; runas/authz test fixtures to v2 field names

The spec export surface intentionally changed (RoleSchema→PositionSchema,
definePosition, ShareRecipientType 'position', ExecutionContext.positions,
principal-taxonomy fields, externalSharingModel) — snapshot regenerated per
the gate's documented flow. Test fixtures updated: sys_user_position rows
use the 'position' field, sys_position_permission_set uses position_id,
automation trigger identity uses positions[].

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

* chore(changeset): P1 breaking wave is a MAJOR bump per the API-surface gate

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

* test(plugin-security): RLSCompiler fixtures to current_user.positions (v2 vocabulary)

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

* docs(adr,design): ADR-0090 addendum — assignment-level BU anchor semantics, multi-org benchmark recalibration

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

* test(objectql,runtime,auth): remaining v2-vocabulary fixture updates — overlay whitelist guards, option-visibility positions, standalone surface

role/profile kinds asserted as retired (reintroduction guards per ADR-0090
D2/D3); position asserted allowOrgOverride:true. customSession projection
tests read user.positions. Standalone artifact surface tests use positions[].

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

---------

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

Author: os-zhuang

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

@@ -0,0 +1,47 @@
+---
+'@objectstack/spec': major
+'@objectstack/core': major
+'@objectstack/runtime': major
+'@objectstack/objectql': major
+'@objectstack/formula': major
+'@objectstack/rest': major
+'@objectstack/cli': major
+'@objectstack/plugin-security': major
+'@objectstack/plugin-sharing': major
+'@objectstack/plugin-auth': major
+'@objectstack/service-automation': major
+'@objectstack/trigger-record-change': major
+'@objectstack/platform-objects': major
+'@objectstack/metadata': major
+---
+
+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).

docs/adr/0090-permission-model-v2-concept-convergence.md

@@ -489,6 +489,30 @@ launch shape (none of them changes P1's breaking surface):
   simulator UI, snapshot gate with the external-audience column. Proof: matrix snapshot diff drill
   on a seeded CRM stack, including an agent on-behalf-of case and an external-portal case.
 
+## Addendum (2026-07-09) — assignment-level BU anchor (D12 companion) and benchmark recalibration
+
+Two clarifications from review discussion, recorded here rather than as a new ADR:
+
+1. **Positions never bind to a business unit at the DEFINITION level** — that
+   recreates the position-per-department explosion (the SAP failure mode this
+   model deliberately factors away). The ASSIGNMENT row may: 
+   `sys_user_position.business_unit_id` (reserved by ADR-0057 D4) is adopted
+   with exactly three consumers — the depth anchor for that assignment's
+   `readScope`/`writeScope` (a 华东 sales manager gets manager depth in 华东
+   only, not in an unrelated project unit), the D12 delegated-administration
+   boundary check ("assignments you create must target your subtree"), and the
+   audit fact ("manager OF WHAT"). Capability bits are never BU-scoped.
+   Prior art: Dataverse assigns security roles per-BU at the assignment level;
+   NetSuite's subsidiary-restricted roles are the same shape. Semantics land
+   with the delegated-admin phase (P3); the column may be written earlier.
+2. **Scale benchmark recalibrated to the real deployment topology.** Group
+   deployments are multi-org (one org per legal entity; every record carries
+   `organization_id`, which prunes first). The P4 gate benchmark therefore
+   targets single-org populations (≈10k users × 1M rows per org), and the
+   "100k-user mega-unit" scenario moves from gate to non-goal; the closure-join
+   and per-object BU-stamping escape hatches remain documented alternatives in
+   the scale-hardening follow-up, not planned work.
+
 ## References
 
 - ADR-0049, ADR-0056, ADR-0057 (+ its 2026-06-25 addendum), ADR-0066, ADR-0086

docs/design/permission-model.md

@@ -33,6 +33,19 @@ The whole model in four sentences:
 | **OWD + sharing** | *whose records are visible by default, and what widens that* | per-object `sharingModel`; sharing rules, manual shares, teams as recipients | OWD: object author · sharing: environment |
 | **RLS** | *hard boundaries nothing widens* (dimension/compliance isolation) | CEL predicates on permission sets | expert escape hatch (~5% of cases) |
 
+**Position assignments may carry an optional business-unit anchor.** The
+POSITION DEFINITION never binds to a BU (that would recreate the
+position-per-department explosion); but an ASSIGNMENT row
+(`sys_user_position.business_unit_id`, reserved since ADR-0057 D4) may name
+the unit the person holds that position IN — "张三 is sales_manager **of
+华东**". When present it does exactly three things: anchors that
+assignment's depth grants (`readScope: unit*`) to that subtree, provides
+the delegated-administration boundary check (ADR-0090 D12), and makes the
+"manager of what" fact auditable instead of drifting with the user's BU
+membership. Capability bits (CRUD/FLS) are never BU-scoped — row filtering
+stays the job of OWD + depth. Semantics activate with the delegated-admin
+phase; simple orgs never touch the field.
+
 **Teams** are deliberately *not* a sixth concept: `sys_team` is a flat collaboration group that can
 **receive shared records and nothing else** — it never owns records and never carries permission
 sets (ADR-0090 D8). Positions distribute capability vertically; teams receive access horizontally.
@@ -69,6 +82,14 @@ both the admin "view-as" simulator and the publish-time access-matrix snapshot g
 *Who* is calling matters too — a human, an AI agent, an integration service, an anonymous
 visitor, or an external portal user each evaluate slightly differently. See §9.
 
+**Deployment note (multi-org groups).** Large groups on this platform run
+one organization per legal entity: every record carries `organization_id`
+and the tenant filter prunes FIRST, so the owner/BU `IN`-lists that follow
+are sized to a single org's population (hundreds–thousands), not the whole
+group. This is why records do not need a stamped BU column and why the
+`IN`-form stays comfortably within budget at group scale; cross-entity
+consolidation is a reporting concern, not a row-filter concern.
+
 ## 3. OWD (`sharingModel`) — the record baseline
 
 Four canonical values, no aliases (ADR-0090 D4):

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,25 @@
 // 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 +33,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 +53,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/objectstack.config.ts

@@ -31,7 +31,7 @@ import { allEmails } from './src/system/emails/index.js';
 import { allBooks } from './src/system/books/index.js';
 import { allApis } from './src/system/apis/index.js';
 import {
-  allRoles,
+  allPositions,
   allPermissionSets,
   allSharingRules,
 } from './src/security/index.js';
@@ -192,7 +192,7 @@ export default defineStack({
   webhooks: allWebhooks,
 
   // Security
-  roles: allRoles,
+  positions: allPositions,
   permissions: allPermissionSets,
   sharingRules: allSharingRules,
 

examples/app-showcase/src/coverage.ts

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

examples/app-showcase/src/data/objects/account.object.ts

@@ -14,6 +14,10 @@ import { P } from '@objectstack/spec';
  */
 export const Account = ObjectSchema.create({
   name: 'showcase_account',
+  // [ADR-0090 D1] Explicit grandfather stamp: record isolation for this demo
+  // object is RLS-owned / intentionally public; without this the new secure
+  // default (unset OWD => private) would owner-filter it.
+  sharingModel: 'public_read_write',
   label: 'Account',
   pluralLabel: 'Accounts',
   icon: 'building',