feat(spec,sharing): ADR-0056 D1 — canonical OWD vocabulary on object.sharingModel

Add the canonical OWD names (public_read / public_read_write) to the
object.sharingModel enum alongside the legacy read/read_write/full aliases
(non-breaking), and map them in the sharing runtime onto the three enforced
behaviours. Unknown values stay enum-rejected (authoring-time fail-closed).
Showcase announcement switched to canonical `public_read`, proven end-to-end.
sharing-service 32 tests (+4 D1); OWD dogfood proofs 8/8; liveness green.

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

Author: claude

.changeset/adr-0056-d1-owd-vocab.md

@@ -0,0 +1,16 @@
+---
+"@objectstack/spec": minor
+"@objectstack/plugin-sharing": patch
+"@objectstack/example-showcase": patch
+---
+
+feat(spec,sharing): canonical OWD vocabulary on `object.sharingModel` (ADR-0056 D1)
+
+Reconciles the Org-Wide-Default naming so authors use ONE vocabulary. `object.sharingModel`
+now accepts the canonical OWD names — `private` | `public_read` | `public_read_write` |
+`controlled_by_parent` — alongside the legacy `read` / `read_write` / `full` aliases (kept,
+non-breaking). The sharing runtime maps them onto the three enforced behaviours
+(`public_read` ≡ legacy `read` = everyone reads / owner writes; `public_read_write` =
+unscoped). Unknown values remain rejected by the enum (authoring-time, fail-closed). The
+showcase announcement now declares the canonical `public_read`, exercised end-to-end by the
+public-read dogfood proof.

examples/app-showcase/src/objects/announcement.object.ts

@@ -5,7 +5,7 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
 /**
  * Team Announcement — the canonical PUBLIC-READ object (ADR-0056 OWD).
  *
- * Declares `sharingModel: 'read'`: every member can READ every announcement,
+ * Declares `sharingModel: 'public_read'`: every member can READ every announcement,
  * but only the OWNER may edit or delete it (the engine derives "everyone reads,
  * owner writes" from the OWD baseline + the auto-stamped `owner_id`). No RLS
  * policy is authored. This is the sibling of `showcase_private_note`
@@ -20,8 +20,9 @@ export const Announcement = ObjectSchema.create({
   icon: 'megaphone',
   description: 'A team announcement everyone can read but only its owner can edit — `read` OWD (ADR-0056).',
 
-  // Everyone reads; owner writes. No RLS authored.
-  sharingModel: 'read',
+  // Everyone reads; owner writes. Canonical OWD name (ADR-0056 D1); `read` is
+  // the legacy alias. No RLS authored.
+  sharingModel: 'public_read',
 
   fields: {
     title: Field.text({ label: 'Title', required: true, searchable: true, maxLength: 160 }),

packages/plugins/plugin-sharing/src/sharing-service.test.ts

@@ -100,6 +100,18 @@ const PUBLIC_SCHEMA = {
   fields: { id: {}, name: {}, owner_id: {} },
 };
 
+// ADR-0056 D1 — canonical OWD vocabulary maps onto the same enforced behaviours.
+const CANON_PUBLIC_READ_SCHEMA = {
+  name: 'kbarticle',
+  sharingModel: 'public_read', // canonical alias of legacy `read`
+  fields: { id: {}, name: {}, owner_id: {} },
+};
+const CANON_PUBLIC_RW_SCHEMA = {
+  name: 'whiteboard',
+  sharingModel: 'public_read_write', // canonical alias of "public" (no record filter)
+  fields: { id: {}, name: {}, owner_id: {} },
+};
+
 const ORPHAN_SCHEMA = {
   name: 'note',
   sharingModel: 'private',
@@ -118,6 +130,8 @@ describe('SharingService.buildReadFilter', () => {
       lead: LEAD_SCHEMA,
       task: PUBLIC_SCHEMA,
       note: ORPHAN_SCHEMA,
+      kbarticle: CANON_PUBLIC_READ_SCHEMA,
+      whiteboard: CANON_PUBLIC_RW_SCHEMA,
       sys_record_share: { name: 'sys_record_share' },
     });
     svc = new SharingService({ engine });
@@ -139,6 +153,14 @@ describe('SharingService.buildReadFilter', () => {
     expect(await svc.buildReadFilter('lead', { userId: 'u1' })).toBeNull();
   });
 
+  it('canonical public_read reads like `read` (everyone reads → no filter) [ADR-0056 D1]', async () => {
+    expect(await svc.buildReadFilter('kbarticle', { userId: 'u1' })).toBeNull();
+  });
+
+  it('canonical public_read_write is unscoped on read [ADR-0056 D1]', async () => {
+    expect(await svc.buildReadFilter('whiteboard', { userId: 'u1' })).toBeNull();
+  });
+
   it('returns null for objects without owner_id even when private', async () => {
     expect(await svc.buildReadFilter('note', { userId: 'u1' })).toBeNull();
   });
@@ -171,6 +193,8 @@ describe('SharingService.canEdit', () => {
       account: ACCOUNT_SCHEMA,
       lead: LEAD_SCHEMA,
       task: PUBLIC_SCHEMA,
+      kbarticle: CANON_PUBLIC_READ_SCHEMA,
+      whiteboard: CANON_PUBLIC_RW_SCHEMA,
       sys_record_share: { name: 'sys_record_share' },
     });
     svc = new SharingService({ engine });
@@ -181,6 +205,9 @@ describe('SharingService.canEdit', () => {
     engine._tables.lead = [
       { id: 'l1', name: 'Lead1', owner_id: 'alice' },
     ];
+    engine._tables.kbarticle = [
+      { id: 'k1', name: 'KB1', owner_id: 'alice' },
+    ];
   });
 
   it('returns true for system context', async () => {
@@ -213,6 +240,15 @@ describe('SharingService.canEdit', () => {
     expect(await svc.canEdit('lead', 'l1', { userId: 'alice' })).toBe(true);
     expect(await svc.canEdit('lead', 'l1', { userId: 'bob' })).toBe(false);
   });
+
+  it('canonical public_read gates writes to the owner [ADR-0056 D1]', async () => {
+    expect(await svc.canEdit('kbarticle', 'k1', { userId: 'alice' })).toBe(true);
+    expect(await svc.canEdit('kbarticle', 'k1', { userId: 'bob' })).toBe(false);
+  });
+
+  it('canonical public_read_write lets anyone write [ADR-0056 D1]', async () => {
+    expect(await svc.canEdit('whiteboard', 'anything', { userId: 'bob' })).toBe(true);
+  });
 });
 
 describe('SharingService.grant / listShares / revoke', () => {

packages/plugins/plugin-sharing/src/sharing-service.ts

@@ -45,15 +45,21 @@ const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as const;
 const OWNER_FIELD = 'owner_id';
 
 /**
- * Effective sharing model. Anything other than `private` / `read` is
- * treated as public — that includes objects that don't declare
- * `sharingModel` at all, so existing CRM behaviour is preserved
- * until an admin opts an object in.
+ * Effective sharing model — collapses the authorable OWD vocabulary onto the
+ * three behaviours this service enforces (ADR-0056 D1):
+ *   - `private`                         → owner-only read + write
+ *   - `public_read` / legacy `read`     → everyone reads, owner writes
+ *   - everything else                   → public (no record-level filter)
+ *
+ * "Everything else" covers the canonical `public_read_write`, the legacy
+ * `read_write` / `full` aliases, `controlled_by_parent` (scoped separately by
+ * the security plugin), and objects that declare no `sharingModel` at all — so
+ * existing behaviour is preserved until an admin opts an object in.
  */
 function effectiveSharingModel(schema: any): 'private' | 'read' | 'public' {
   const m = schema?.sharingModel ?? schema?.security?.sharingModel;
   if (m === 'private') return 'private';
-  if (m === 'read') return 'read';
+  if (m === 'read' || m === 'public_read') return 'read';
   return 'public';
 }
 

packages/spec/src/data/object.zod.ts

@@ -598,7 +598,7 @@ const ObjectSchemaBase = z.object({
    * ids)` on reads and requires master edit-access on by-id writes. No RLS policy
    * is authored — the inheritance is derived from the relationship.
    */
-  sharingModel: z.enum(['private', 'read', 'read_write', 'full', 'controlled_by_parent']).optional().describe('Default sharing model'),
+  sharingModel: z.enum(['private', 'public_read', 'public_read_write', 'controlled_by_parent', 'read', 'read_write', 'full']).optional().describe('Org-Wide Default record visibility (OWD). Canonical: private (owner-only) | public_read (everyone reads, owner writes) | public_read_write (everyone reads+writes) | controlled_by_parent (derived from the master record). Legacy aliases: read=public_read, read_write/full=public_read_write. ADR-0056 D1.'),
 
   /**
    * Public Share-Link Policy