feat(spec)!: book audience gates by permission set — retire the { profile } arm (ADR-0090) (#2732)

ADR-0090 D2 removed the Profile concept, but BookAudienceSchema still
modelled its gated arm as { profile: string } (with pre-D3 vocabulary in
the comments). Books ship in packages, and packages own permission sets
but never positions (D9 — the same environment-ownership argument that
removed profiles), so the gate is a capability reference:

- `{ profile: string }` → `{ permissionSet: string }` — one-step rename,
  no alias; the zod union now rejects `{ profile }` at parse time.
- `'public'` comment now points at the built-in `guest` position (D9)
  instead of the removed "guest profile".
- Regenerated content/docs/references (book.mdx), which also catches up
  security/* with the AdminScope (D12) and explain (D6) shapes that
  landed without a docs regen.


Claude-Session: https://claude.ai/code/session_01Ph4jEAfWDh6taMbZweWhom

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

Author: os-zhuang

.changeset/book-audience-permission-set.md

@@ -0,0 +1,13 @@
+---
+'@objectstack/spec': major
+---
+
+`BookAudience` gated arm renamed: `{ profile: string }` → `{ permissionSet: string }`.
+
+ADR-0090 D2 removed the Profile concept, but `book.audience` (ADR-0046 §6.7)
+still modelled its gated arm as a profile reference. Books ship in packages,
+and packages own permission sets but never positions (ADR-0090 D9), so the
+gate is a capability reference — a permission-set name the reader must hold,
+e.g. `{ permissionSet: 'crm_admin' }`. Pre-launch one-step rename, no alias:
+the zod union now rejects `{ profile }` at parse time. `'org'` and `'public'`
+literals are unchanged (`'public'` ≡ the built-in `guest` position, D9).

content/docs/references/system/book.mdx

@@ -94,7 +94,7 @@ Type: `string`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **profile** | `string` | ✅ |  |
+| **permissionSet** | `string` | ✅ |  |
 
 ---
 

packages/spec/src/system/book.test.ts

@@ -25,10 +25,13 @@ describe('BookSchema (ADR-0046 §6)', () => {
     expect(() => BookSchema.parse({ name: 'crm_guide', groups: [{ key: 'Start', label: 'x' }] })).toThrow();
   });
   it('accepts audience variants', () => {
-    for (const audience of ['org', 'public', { profile: 'admin' }] as const) {
+    for (const audience of ['org', 'public', { permissionSet: 'crm_admin' }] as const) {
       expect(() => BookSchema.parse({ name: 'b', audience, groups: [] })).not.toThrow();
     }
   });
+  it('rejects the removed { profile } audience shape (ADR-0090 D2)', () => {
+    expect(() => BookSchema.parse({ name: 'b', audience: { profile: 'admin' }, groups: [] })).toThrow();
+  });
 });
 
 describe('resolveBookTree — derived membership (the AI-safety core)', () => {
@@ -151,7 +154,7 @@ describe('deriveImplicitPackageBook + audience', () => {
   it('isPublicAudience only true for public', () => {
     expect(isPublicAudience('public')).toBe(true);
     expect(isPublicAudience('org')).toBe(false);
-    expect(isPublicAudience({ profile: 'admin' })).toBe(false);
+    expect(isPublicAudience({ permissionSet: 'crm_admin' })).toBe(false);
     expect(isPublicAudience(undefined)).toBe(false);
   });
 });

packages/spec/src/system/book.zod.ts

@@ -82,15 +82,22 @@ export type BookGroup = {
   pages?: BookNode[];
 };
 
-/** Access audience for a book — a reference into the permission model (ADR-0046 §6.7). */
+/**
+ * Access audience for a book — a reference into the permission model
+ * (ADR-0046 §6.7, vocabulary per ADR-0090). The gate is a capability
+ * reference (a permission-set name), never a distribution one: books ship in
+ * packages, and packages own permission sets but never positions (ADR-0090
+ * D9) — a package gating its Admin Guide to its own `crm_admin` set keeps
+ * provenance and uninstall semantics intact (ADR-0086).
+ */
 export const BookAudienceSchema = lazySchema(() =>
   z.union([
     z.literal('org'), // default — inherits the package grant (§3.6)
-    z.literal('public'), // ≡ the data-layer `guest` profile (anonymous, indexable)
-    z.object({ profile: z.string() }), // role-gated, e.g. { profile: 'admin' }
+    z.literal('public'), // ≡ the built-in `guest` position (ADR-0090 D9): anonymous, indexable
+    z.object({ permissionSet: z.string() }), // capability-gated, e.g. { permissionSet: 'crm_admin' }
   ]),
 );
-export type BookAudience = 'org' | 'public' | { profile: string };
+export type BookAudience = 'org' | 'public' | { permissionSet: string };
 
 export const BookSchema = lazySchema(() =>
   z.object({