feat(showcase,docs): ADR-0090 permission-model zoo + full docs alignment (#2739)

Showcase now exercises the complete Permission Model v2 authoring surface
(positions via typed factories, CRUD+FLS+RLS, org-depth read/write asymmetry,
VAMA, systemPermissions, the isDefault everyone-suggestion, guest-safe
capability, adminScope delegated administration anchored on a seeded
sys_business_unit tree, externalSharingModel dials) and opts into the D6
access-matrix snapshot gate; guarded end-to-end by a new dogfood test.

defineStack cross-reference validation learns that platform-provided
(sys_/cloud_/ai_) objects are legitimate permission-grant and seed targets
(ADR-0090 D12 delegated-admin shape; seed-loader parity), with tests.

Docs: protocol/objectql/security.mdx rewritten to the v2 vocabulary; isProfile
scrubbed from all authoring examples; dead identity/role reference link fixed;
stale zod docstrings (rls/territory/sharing/tool/agent) rewritten and the
security/ai references regenerated (adds the missing explain.mdx page).

Deliberately NOT demoed (declared ≠ enforced): hierarchy depth scopes
(enterprise hierarchy-security), tabPermissions (single-app package,
ADR-0019 D3), owner-type sharing rules (seed-skipped [experimental]).

Rename misses and platform bugs found while verifying are tracked in
#2722 #2723 #2724 (vocabulary leftovers) and #2734 #2735 #2737 (fresh-boot
org-RLS visibility, JSON-field seed batch inserts, count-scope leak).

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

Author: os-zhuang

.changeset/adr-0090-showcase-permission-zoo.md

@@ -0,0 +1,43 @@
+---
+"@objectstack/spec": minor
+"@objectstack/example-showcase": minor
+"@objectstack/plugin-sharing": patch
+"@objectstack/plugin-security": patch
+---
+
+ADR-0090 permission-model zoo + docs alignment.
+
+**Showcase (`@objectstack/example-showcase`)** now exercises the full Permission
+Model v2 authoring surface and is guarded by a new runtime dogfood test
+(`showcase-permission-zoo.dogfood.test.ts`): typed `definePosition`/
+`definePermissionSet`/`defineSharingRule` factories; six flat positions (the
+stale pre-D3 `parent` fields are gone); permission sets covering CRUD+FLS+RLS,
+org-depth read/write asymmetry (`readScope: 'org'` / `writeScope: 'own'`),
+View-All (auditor) and Modify-All (ops) bypasses, `systemPermissions`
+(`setup.access`), the `isDefault` everyone-suggestion (incl. personal-data
+grants on the `private`-OWD note object), a guest-safe set for the `guest`
+anchor (D9), and a delegated-administration `adminScope` bounded to a seeded
+`sys_business_unit` subtree (D12). Objects gain `externalSharingModel` dials
+(D11). A committed `access-matrix.json` opts the showcase into the D6 snapshot
+gate. Hierarchy depths (`own_and_reports`/`unit`/`unit_and_below`) are
+deliberately NOT authored — they are enterprise (`hierarchy-security`) and the
+open runtime fails closed; BU-shaped visibility is demonstrated via the
+enforced `unit_and_subordinates` sharing-rule recipient instead.
+
+**`@objectstack/spec`**: `defineStack` strict cross-reference validation no
+longer rejects permission grants or seed datasets that target platform-provided
+objects (`sys_`/`cloud_`/`ai_` prefixes) — a delegated-admin set carrying CRUD
+on the RBAC link tables (ADR-0090 D12) and an app seeding the business-unit
+tree are legitimate shapes; the typo net stays intact for the stack's own
+objects. Stale pre-ADR-0090 vocabulary in zod docstrings (rls/territory/
+sharing/tool/agent) is rewritten; the auto-generated references (including the
+previously missing `security/explain.mdx`) are regenerated.
+
+**Docs**: `protocol/objectql/security.mdx` rewritten to the v2 model (no
+profiles, positions, canonical OWD four + D1 private default +
+`externalSharingModel`, position-scoped RLS, enforced sharing recipients);
+`isProfile` scrubbed from every authoring example; the dead
+`/docs/references/identity/role` link fixed; implementation-status and
+plugin READMEs aligned. Remaining rename misses are tracked in #2722
+(RLSUserContext.role), #2723 (portal `profiles`), #2724 (sys_record_share
+`role` enum).

content/docs/ai/actions-as-tools.mdx

@@ -210,7 +210,7 @@ await aiService.chatWithTools(messages, tools, {
     actor: {
       id: currentUser.id,
       name: currentUser.displayName,
-      roles: currentUser.roles,
+      positions: currentUser.positions,
       permissions: currentUser.permissions,
     },
     conversationId,

content/docs/ai/index.mdx

@@ -167,7 +167,7 @@ end-user's `ExecutionContext` so tool calls respect row-level security:
 ```typescript
 const reply = await aiService.chatWithTools(messages, tools, {
   toolExecutionContext: {
-    actor: { id: currentUser.id, name: currentUser.displayName, roles: currentUser.roles, permissions: currentUser.permissions },
+    actor: { id: currentUser.id, name: currentUser.displayName, positions: currentUser.positions, permissions: currentUser.permissions },
     conversationId,
     environmentId,
   },

content/docs/concepts/architecture.mdx

@@ -152,11 +152,12 @@ That's the job of the other layers.
 // src/permissions/sales_rep.permission.ts
 import { definePermissionSet } from '@objectstack/spec';
 
-// A permission set (here used as a profile) keyed by object and field.
+// A permission set keyed by object and field — the only capability
+// container (ADR-0090: capability is the union of held sets; the old
+// profile concept was removed).
 export const SalesRepPermission = definePermissionSet({
   name: 'sales_rep',
   label: 'Sales Rep',
-  isProfile: true,
   objects: {
     customer: {
       allowCreate: true,

content/docs/concepts/index.mdx

@@ -133,11 +133,11 @@ This ensures ObjectStack apps can run on Node.js + PostgreSQL today, Python + SQ
 | Layer | Responsibility | Example |
 | :--- | :--- | :--- |
 | **Protocol** | Defines capabilities | A row-level-security policy slot (`operation` + `using` clause) |
-| **App** | Defines business logic | `{ operation: 'select', using: "role == 'admin'" }` |
+| **App** | Defines business logic | `{ operation: 'select', using: "owner_id == current_user.id" }` |
 | **Engine** | Enforces the logic | Compiles the `using` condition into a query filter |
 
 <Callout type="info">
-CRUD permissions (`allowRead`, `allowEdit`, …) are simple booleans — they grant or deny an operation. Record-level *conditional* access is a separate mechanism: [Row-Level Security](/docs/concepts/architecture) policies, whose `using` clause is a CEL predicate over context variables such as `current_user.roles` and `current_user.id`.
+CRUD permissions (`allowRead`, `allowEdit`, …) are simple booleans — they grant or deny an operation. Record-level *conditional* access is a separate mechanism: [Row-Level Security](/docs/concepts/architecture) policies, whose `using` clause is a CEL predicate over context variables such as `current_user.positions` and `current_user.id`.
 </Callout>
 
 ### Single Source of Truth

content/docs/data-modeling/objects.mdx

@@ -183,7 +183,7 @@ indexes: [
 | `active` | `boolean` | Is object active (default: `true`) |
 | `isSystem` | `boolean` | System object, protected from deletion (default: `false`) |
 | `abstract` | `boolean` | Abstract base, cannot be instantiated (default: `false`) |
-| `sharingModel` | `enum` | Org-Wide Default record visibility (ADR-0055/0056). Canonical: `'private'`, `'public_read'`, `'public_read_write'`, `'controlled_by_parent'` (detail visibility derived from its master). Legacy aliases: `'read'`=public_read, `'read_write'`/`'full'`=public_read_write |
+| `sharingModel` | `enum` | Org-Wide Default record visibility (ADR-0055/0056/0090). Canonical four only: `'private'`, `'public_read'`, `'public_read_write'`, `'controlled_by_parent'` (detail visibility derived from its master). The legacy aliases (`'read'`, `'read_write'`, `'full'`) were removed from the enum (ADR-0090 D4) — authoring rejects them. Unset on a custom object resolves to `'private'` (ADR-0090 D1) |
 | `keyPrefix` | `string` | Short prefix for record IDs (e.g. `'001'`) |
 | `validations` | `ValidationRule[]` | Object-level validation rules (see [Validation](/docs/data-modeling/validation)) |
 

content/docs/getting-started/common-patterns.mdx

@@ -424,7 +424,6 @@ import { definePermissionSet } from '@objectstack/spec';
 export const HrRepPermission = definePermissionSet({
   name: 'hr_rep',
   label: 'HR Rep',
-  isProfile: true,
   objects: {
     employee: { allowCreate: true, allowRead: true, allowEdit: true, allowDelete: false },
   },

content/docs/getting-started/examples.mdx

@@ -230,10 +230,10 @@ hotcrm/
 │   ├── dashboards/       # Executive, Sales, Service dashboards
 │   ├── data/             # Seed data for all objects
 │   ├── flows/            # 5 automation flows: case escalation, approval, ...
-│   ├── profiles/         # 5 security profiles: admin, sales rep, manager, ...
+│   ├── security/         # 5 permission sets: admin, sales rep, manager, ...
 │   ├── rag/              # 4 RAG pipelines: product info, competitive intel, ...
 │   ├── reports/          # 7 reports with tabular, summary, matrix formats
-│   └── sharing/          # Sharing rules, role hierarchy, org defaults
+│   └── sharing/          # Sharing rules, business-unit hierarchy, org defaults
 ```
 
 ### Features Showcased
@@ -244,7 +244,7 @@ hotcrm/
 | **State Machine** | Lead lifecycle: `new → contacted → qualified → converted` with `Lead.state.ts` |
 | **AI Agents** | Sales Assistant, Service Agent, Revenue Intelligence, Email Campaign, Lead Enrichment |
 | **RAG Pipelines** | Product info, competitive intel, sales knowledge, support knowledge |
-| **Security Model** | 5 profiles (Admin, Manager, Rep, Agent, Marketing), sharing rules, role hierarchy |
+| **Security Model** | 5 permission sets (Admin, Manager, Rep, Agent, Marketing), sharing rules, business-unit hierarchy |
 | **Automation** | Lead conversion, case escalation, opportunity approval, campaign enrollment, quote generation |
 | **Custom APIs** | `POST /lead-convert`, `GET /pipeline-stats` |
 | **Seed Data** | 50+ realistic records across all objects |

content/docs/getting-started/glossary.mdx

@@ -53,7 +53,7 @@ External communication layer including REST contracts, API discovery, Realtime s
 Business process automation including Workflows (state machines), Flows (visual logic), and Webhooks (HTTP callbacks).
 
 ### Identity Protocol
-User, organization, and profile schemas for identity management.
+User, organization, and position schemas for identity management.
 
 ### Security Protocol
 RBAC, permissions, policy, and access-control schemas.

content/docs/getting-started/quick-reference.mdx

@@ -170,13 +170,13 @@ Access control, permissions, and row-level security.
 
 ## Identity Protocol (4 schemas)
 
-User identity, organizations, and role management.
+User identity, organizations, and position management.
 
 | Protocol | Source File | Key Schemas | Purpose |
 |:---------|:-----------|:------------|:--------|
 | **[Identity](/docs/references/identity/identity)** | `identity.zod.ts` | Identity, User | User identity management |
 | **[Organization](/docs/references/identity/organization)** | `organization.zod.ts` | Organization | Multi-organization support |
-| **[Role](/docs/references/identity/role)** | `role.zod.ts` | Role | Role-based access control |
+| **[Position](/docs/references/identity/position)** | `position.zod.ts` | Position | Permission-set distribution (岗位, ADR-0090) |
 | **[SCIM](/docs/references/identity/scim)** | `scim.zod.ts` | SCIMUser, SCIMGroup | SCIM 2.0 provisioning |
 
 ## Cloud Protocol (4 schemas)