fix(types,app-shell): one ObjectPermission, and the preview stops hiding three of its fields (objectstack#4115) (#3077)

objectui had two mutually incompatible types named `ObjectPermission`.
Neither was the spec's.

**The legacy one was dead** — `field-types.ts` declared a pre-spec shape
(`profile` / `roles` / `create|read|update|delete` / `record_level` /
`field_permissions`) whose only referent was `ObjectSchemaMetadata.
permissions`, and `ObjectSchemaMetadata` itself has no consumer outside
`packages/types`. Nothing in the repo reads `permissions?.create`,
`record_level` or `own_records_only`. Its `SharingRule` was likewise
reachable only through `record_level.sharing_rules`. Renaming would have
kept dead weight under a new name, so the whole block is deleted; spec's
`PermissionSet` / `ObjectPermission` is the model that survives.

**The other was a hand copy that had silently gone stale.**
`PermissionPreview` declared its own 9-key `ObjectPermission` against the
spec's 12. The three it omitted were not cosmetic: `allowExport`, and the
ADR-0057 access-depth axis `readScope` / `writeScope`. A permission set
granting export — or writing wider than it reads — rendered *identically*
to one that did neither, so the reviewer the preview exists to inform had
no way to see it. It now imports the spec types, and the matrix gains an
Export column and a read/write Scope column.

Because `CAPS` is keyed by `keyof ObjectPermission`, a capability the spec
renames is now a compile error rather than a column that quietly vanishes.

Also adds the warning that axis makes checkable, in the same class as the
existing Modify-All-without-View-All one: a write scope wider than the read
scope means edits can target records the user cannot see.

Ledger 126 -> 124, regenerated with `--ledger`, diff is exactly
`ObjectPermission` and `SharingRule`.

Mutation-tested: removing the Export column and disabling the scope warning
each fail their assertion by name. 78/78 type-check; full suite 8786 green.

BREAKING CHANGE: `ObjectPermission` and `SharingRule` are removed from
`@object-ui/types`, along with `ObjectSchemaMetadata.permissions`. Consumers
that want object permissions should use `ObjectPermission` from
`@objectstack/spec/security`.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

packages/app-shell/src/views/metadata-admin/previews/PermissionPreview.test.tsx

@@ -0,0 +1,83 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * PermissionPreview ↔ spec `ObjectPermission` (objectstack#4115).
+ *
+ * The preview used to declare its own 9-key `ObjectPermission` interface, a
+ * hand copy of the spec's 12-key one. The three it omitted were not cosmetic:
+ * `allowExport` and the ADR-0057 access-depth axis (`readScope`/`writeScope`).
+ * A permission set granting export, or writing wider than it reads, rendered
+ * identically to one that did neither — the reviewer had no way to see it.
+ *
+ * These tests pin the three formerly-invisible fields. The typing is what
+ * keeps them honest going forward: `CAPS` is keyed by
+ * `keyof ObjectPermission`, so a capability the spec renames breaks the build
+ * rather than silently vanishing from the matrix.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, cleanup, within } from '@testing-library/react';
+import { PermissionPreview } from './PermissionPreview';
+
+afterEach(cleanup);
+
+const baseProps = { type: 'permission', name: 'sales_rep', locale: 'en-US' as const };
+
+function renderPreview(objects: Record<string, unknown>) {
+  return render(
+    <PermissionPreview
+      {...(baseProps as never)}
+      draft={{ name: 'sales_rep', label: 'Sales Rep', objects }}
+    />,
+  );
+}
+
+describe('PermissionPreview surfaces the spec fields the hand copy omitted', () => {
+  it('renders an Export column — allowExport used to be undeclared entirely', () => {
+    renderPreview({ opportunity: { allowRead: true, allowExport: true } });
+    const header = screen.getByTitle('Export');
+    expect(header).toBeTruthy();
+    expect(header.textContent).toBe('E');
+  });
+
+  it('shows the read/write access depth instead of dropping it', () => {
+    renderPreview({ opportunity: { allowRead: true, readScope: 'unit', writeScope: 'own' } });
+    const row = screen.getByText('opportunity').closest('tr')!;
+    const cells = within(row).getAllByRole('cell');
+    const scopeCell = cells[cells.length - 1];
+    expect(scopeCell.textContent).toContain('unit');
+    expect(scopeCell.textContent).toContain('own');
+  });
+
+  it('marks an object with no scopes set as using the default', () => {
+    renderPreview({ opportunity: { allowRead: true } });
+    const row = screen.getByText('opportunity').closest('tr')!;
+    const cells = within(row).getAllByRole('cell');
+    expect(cells[cells.length - 1].textContent).toBe('default');
+  });
+});
+
+describe('scope warnings (same class as Modify-All without View-All)', () => {
+  it('warns when the write scope is wider than the read scope', () => {
+    // Editable-but-invisible records: the reviewer needs this called out, and
+    // before the spec fields were declared the preview could not even see it.
+    renderPreview({ opportunity: { allowRead: true, allowEdit: true, readScope: 'own', writeScope: 'unit' } });
+    expect(screen.getByText(/Write scope \(unit\) is wider than read scope \(own\)/)).toBeTruthy();
+  });
+
+  it('stays quiet when write is no wider than read', () => {
+    renderPreview({ opportunity: { allowRead: true, allowEdit: true, readScope: 'org', writeScope: 'own' } });
+    expect(screen.queryByText(/wider than read scope/)).toBeNull();
+  });
+
+  it('stays quiet when neither scope is set', () => {
+    renderPreview({ opportunity: { allowRead: true, allowEdit: true } });
+    expect(screen.queryByText(/wider than read scope/)).toBeNull();
+  });
+
+  it('still reports the pre-existing capability warnings', () => {
+    renderPreview({ opportunity: { allowEdit: true, modifyAllRecords: true } });
+    expect(screen.getByText(/Edit granted without Read/)).toBeTruthy();
+    expect(screen.getByText(/Modify All without View All/)).toBeTruthy();
+  });
+});

packages/app-shell/src/views/metadata-admin/previews/PermissionPreview.tsx

@@ -37,38 +37,41 @@ import {
   Star,
   Tag,
 } from 'lucide-react';
+import type { ObjectAccessScope, ObjectPermission, FieldPermission } from '@objectstack/spec/security';
 import type { MetadataPreviewProps } from '../preview-registry';
 import { PreviewShell, PreviewMessage, PreviewErrorBoundary } from './PreviewShell';
 
-interface ObjectPermission {
-  allowCreate?: boolean;
-  allowRead?: boolean;
-  allowEdit?: boolean;
-  allowDelete?: boolean;
-  allowTransfer?: boolean;
-  allowRestore?: boolean;
-  allowPurge?: boolean;
-  viewAllRecords?: boolean;
-  modifyAllRecords?: boolean;
-}
-
-interface FieldPermission {
-  readable?: boolean;
-  editable?: boolean;
-}
-
+/**
+ * Boolean capabilities, in matrix-column order.
+ *
+ * Typed against the spec's `ObjectPermission` so a capability the spec adds
+ * cannot stay invisible here indefinitely — the hand-written copy this
+ * replaced was missing `allowExport` outright, so a permission set granting
+ * export rendered identically to one that did not (objectstack#4115).
+ */
 const CAPS: Array<{ key: keyof ObjectPermission; short: string; long: string; danger?: boolean }> = [
   { key: 'allowCreate', short: 'C', long: 'Create' },
   { key: 'allowRead', short: 'R', long: 'Read' },
   { key: 'allowEdit', short: 'U', long: 'Edit' },
   { key: 'allowDelete', short: 'D', long: 'Delete' },
+  { key: 'allowExport', short: 'E', long: 'Export' },
   { key: 'allowTransfer', short: 'T', long: 'Transfer' },
   { key: 'allowRestore', short: 'Re', long: 'Restore' },
   { key: 'allowPurge', short: 'P', long: 'Purge', danger: true },
   { key: 'viewAllRecords', short: 'V*', long: 'View All', danger: true },
   { key: 'modifyAllRecords', short: 'M*', long: 'Modify All', danger: true },
 ];
 
+/** Access-depth axis (ADR-0057), narrowest first — also the widening order. */
+const SCOPE_ORDER: ObjectAccessScope[] = ['own', 'own_and_reports', 'unit', 'unit_and_below', 'org'];
+const SCOPE_LABEL: Record<ObjectAccessScope, string> = {
+  own: 'own',
+  own_and_reports: 'own+reports',
+  unit: 'unit',
+  unit_and_below: 'unit+below',
+  org: 'org',
+};
+
 interface Warning {
   object: string;
   message: string;
@@ -81,6 +84,16 @@ function findWarnings(objects: Record<string, ObjectPermission>): Warning[] {
     if (p.allowDelete && !p.allowRead) out.push({ object: obj, message: 'Delete granted without Read.' });
     if (p.modifyAllRecords && !p.viewAllRecords) out.push({ object: obj, message: 'Modify All without View All — modifications may target invisible records.' });
     if (p.allowPurge && !p.allowDelete) out.push({ object: obj, message: 'Purge (hard delete) granted without Delete.' });
+    // Same class as Modify-All-without-View-All, one axis down: a write scope
+    // wider than the read scope lets a user edit records they cannot see.
+    const read = p.readScope ? SCOPE_ORDER.indexOf(p.readScope) : -1;
+    const write = p.writeScope ? SCOPE_ORDER.indexOf(p.writeScope) : -1;
+    if (read >= 0 && write > read) {
+      out.push({
+        object: obj,
+        message: `Write scope (${SCOPE_LABEL[p.writeScope!]}) is wider than read scope (${SCOPE_LABEL[p.readScope!]}) — edits may target invisible records.`,
+      });
+    }
   }
   return out;
 }
@@ -167,6 +180,9 @@ export function PermissionPreview({ name, draft }: MetadataPreviewProps) {
                           {c.short}
                         </th>
                       ))}
+                      <th className="px-2 py-1.5 text-left font-medium" title="Read / write access depth (ADR-0057)">
+                        Scope
+                      </th>
                     </tr>
                   </thead>
                   <tbody className="divide-y">
@@ -183,6 +199,17 @@ export function PermissionPreview({ name, draft }: MetadataPreviewProps) {
                               </td>
                             );
                           })}
+                          <td className="px-2 py-1 whitespace-nowrap text-[10px] text-muted-foreground">
+                            {p.readScope || p.writeScope ? (
+                              <>
+                                <span title="Read scope">{p.readScope ? SCOPE_LABEL[p.readScope] : '—'}</span>
+                                <span className="mx-1 opacity-50">/</span>
+                                <span title="Write scope">{p.writeScope ? SCOPE_LABEL[p.writeScope] : '—'}</span>
+                              </>
+                            ) : (
+                              <span className="opacity-40">default</span>
+                            )}
+                          </td>
                         </tr>
                       );
                     })}

packages/types/src/field-types.ts

@@ -784,73 +784,6 @@ export interface ObjectTrigger {
   config?: Record<string, any>;
 }
 
-/**
- * Object permission configuration (Phase 3.1.4)
- */
-export interface ObjectPermission {
-  /**
-   * Permission profile name
-   */
-  profile?: string;
-  /**
-   * Role-based permissions
-   */
-  roles?: string[];
-  /**
-   * CRUD permissions
-   */
-  create?: boolean;
-  read?: boolean;
-  update?: boolean;
-  delete?: boolean;
-  /**
-   * Record-level permissions
-   */
-  record_level?: {
-    /**
-     * User can only access own records
-     */
-    own_records_only?: boolean;
-    /**
-     * Sharing rules
-     */
-    sharing_rules?: SharingRule[];
-  };
-  /**
-   * Field-level permissions
-   */
-  field_permissions?: Record<string, {
-    read?: boolean;
-    edit?: boolean;
-  }>;
-}
-
-/**
- * Sharing rule configuration
- */
-export interface SharingRule {
-  /**
-   * Rule name
-   */
-  name: string;
-  /**
-   * Criteria for sharing
-   */
-  criteria?: Record<string, any>;
-  /**
-   * Access level granted
-   */
-  access_level: 'read' | 'edit' | 'full';
-  /**
-   * Share with users/roles
-   */
-  share_with?: {
-    users?: string[];
-    roles?: string[];
-    groups?: string[];
-  };
-}
-
 /**
  * Object schema definition
  * Phase 3.1: Enhanced with inheritance, triggers, permissions, and caching
@@ -876,11 +809,6 @@ export interface ObjectSchemaMetadata {
    */
   fields: Record<string, FieldMetadata>;
 
-  /**
-   * Permissions (Phase 3.1.4: Enhanced permissions)
-   */
-  permissions?: ObjectPermission;
-  
   /**
    * Parent object to inherit from (Phase 3.1.2)
    */

packages/types/src/index.ts

@@ -428,8 +428,6 @@ export type {
   MasterDetailFieldMetadata,
   FieldMetadata,
   ObjectTrigger,
-  ObjectPermission,
-  SharingRule,
   ObjectSchemaMetadata,
   ObjectIndex,
   ObjectRelationship,

scripts/check-spec-symbol-derivation.mjs

@@ -157,7 +157,6 @@ const DEBT = {
     "NavigationAreaSchema",
     "NavigationItem",
     "NavigationItemSchema",
-    "ObjectPermission",
     "OfflineConfig",
     "PageRegion",
     "PageRegionSchema",
@@ -167,7 +166,6 @@ const DEBT = {
     "ScriptValidation",
     "SelectOption",
     "SelectOptionSchema",
-    "SharingRule",
     "StateMachineValidation",
     "Theme",
     "WidgetManifest",