refactor(security): ADR-0057 open/paid seam — hierarchy scopes via pluggable IHierarchyScopeResolver

Hierarchy-relative visibility (scope unit/unit_and_below/own_and_reports) is an
enterprise capability, not open-core. The open framework keeps the secure baseline
(RLS/sharing/roles/own·org scope, BU data model + explicit business_unit recipient)
and a pluggable seam; the resolver implementation ships in the private
@objectstack/security-enterprise.

- spec/contracts: IHierarchyScopeResolver + HierarchyScope.
- plugin-sharing: SharingService delegates unit*/own_and_reports to a late-bound
  resolver (hierarchy-scope-resolver service); fails CLOSED to owner-only when absent
  (never fail-open). Removed the BU/manager rollup logic from the open SharingService.
- spec/defineStack: compile-error if a grant uses a hierarchy scope without
  requires:['hierarchy-security'] (ADR-0049 — no silent lie).
- dogfood showcase-scope-depth: registers a reference resolver (test fixture) to prove
  the seam (5/5), incl. a fail-closed case (no resolver → owner-only).
- authz-conformance + ADR-0057: record the seam.

Full build 75/75; spec 6599; dogfood 21/123; sharing 63; security 112 — all green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

docs/adr/0057-erp-authorization-core-business-units-and-scope-depth.md

@@ -335,3 +335,25 @@ Landed incrementally on branch `adr/0057-erp-authz-core`, each with a runtime pr
 **Deferred (evidence-gated, P4):** `sys_member.role`→`org_membership_level` relabel; manager-chain
 rollup (`subordinate_user_ids`); position hierarchy; record-owning teams; matrix cross-BU sharing;
 a full CEL→FilterCondition compiler (#1887) beyond the field-equality subset.
+
+### Open/paid seam — hierarchy scopes are a pluggable enterprise capability (2026-06-21)
+
+Hierarchy-relative visibility (scope `unit` / `unit_and_below` / `own_and_reports` —
+"you see records by where you sit in the org") is the Salesforce/Dynamics commercial
+hallmark and is **not** required to build a secure app (explicit RLS + sharing rules +
+`own`/`org` scope suffice). It is therefore an **enterprise** capability, not open-core:
+
+- **Open (framework):** the `IHierarchyScopeResolver` contract (`spec/contracts`),
+  `own`/`org` scope, the BU data model + graph + `business_unit` *explicit* sharing
+  recipient, roles, `#2077` seeding, the (future) predicate compiler. `SharingService`
+  delegates hierarchy scopes to the resolver and **fails closed to owner-only** when none
+  is registered — never fail-open. `defineStack` **errors** if a grant uses a hierarchy
+  scope without `requires: ['hierarchy-security']` (no silent lie, ADR-0049).
+- **Paid (`@objectstack/security-enterprise`, private cloud repo):** the
+  `hierarchy-scope-resolver` implementation (BU subtree + manager-chain rollup), plus the
+  P4 heavy org-modeling (position hierarchy, matrix cross-BU, owner-teams) and governance
+  (SSO/SCIM, audit/access-review, SoD).
+
+The commercial boundary ADR lives in `cloud/docs/adr/`; this note records only the
+open-side technical seam. Proof: `showcase-scope-depth.dogfood` (reference resolver +
+fail-closed case).

packages/dogfood/test/authz-conformance.matrix.ts

@@ -45,8 +45,8 @@ export const AUTHZ_CONFORMANCE: AuthzPrimitive[] = [
     enforcement: 'plugin-security/security-plugin.ts fallback resolution', proof: 'showcase-default-profile.dogfood.test.ts' },
 
   // ── ADR-0057 — ERP authorization core (enforced + e2e proven) ──────────
-  { id: 'scope-depth', summary: 'permission-grant access DEPTH (own/unit/unit_and_below/org)', state: 'enforced',
-    enforcement: 'plugin-security getEffectiveScope (stash) + plugin-sharing resolveOwnerScopeIds (owner IN unit-set) — ADR-0057 D1', proof: 'showcase-scope-depth.dogfood.test.ts' },
+  { id: 'scope-depth', summary: 'permission-grant access DEPTH (own/own_and_reports/unit/unit_and_below/org)', state: 'enforced',
+    enforcement: 'plugin-security getEffectiveScope (stash) + plugin-sharing delegates HIERARCHY scopes to a pluggable IHierarchyScopeResolver (open: fail-closed to own; enterprise @objectstack/security-enterprise; reference resolver in this proof) — ADR-0057 D1', proof: 'showcase-scope-depth.dogfood.test.ts' },
   { id: 'declarative-rbac-seeding', summary: 'stack-declared roles + sharingRules seeded at boot (#2077)', state: 'enforced',
     enforcement: 'plugin-security bootstrapDeclaredRoles + plugin-sharing bootstrapDeclaredSharingRules — ADR-0057 D6', proof: 'showcase-declarative-rbac-seeding.dogfood.test.ts' },
   { id: 'rbac-role-assignment', summary: 'platform-owned RBAC assignment (sys_user_role, decoupled from better-auth membership)', state: 'enforced',

packages/dogfood/test/showcase-scope-depth.dogfood.test.ts

@@ -6,6 +6,11 @@
 // → my BU plus all descendant BUs (BFS). Sharing still widens on top; cross-BU
 // stays isolated. ('own' depth is already proven by showcase-private-owd.)
 //
+// NOTE: hierarchy-scope resolution is an ENTERPRISE capability (lives in
+// @objectstack/security-enterprise). The open edition fails closed to owner-only.
+// This test registers a REFERENCE resolver (a test fixture) to prove the seam +
+// the contract end-to-end; production ships the enterprise resolver.
+//
 // @proof: showcase-scope-depth
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
@@ -37,7 +42,7 @@ interface World { stack: VerifyStack; tokens: Record<Who, string>; }
 
 // Build a BU world: bu_parent ⊃ bu_child (sibling bu_other is separate).
 // alice+carol ∈ bu_parent, bob ∈ bu_child, dave ∈ bu_other. Each owns one note.
-async function bootScopeWorld(scope: 'unit' | 'unit_and_below'): Promise<World> {
+async function bootScopeWorld(scope: 'unit' | 'unit_and_below', withResolver = true): Promise<World> {
   const stack = await bootStack(showcaseStack, {
     security: new SecurityPlugin({
       defaultPermissionSets: [...securityDefaultPermissionSets, scopeProfile(scope)],
@@ -49,6 +54,42 @@ async function bootScopeWorld(scope: 'unit' | 'unit_and_below'): Promise<World>
 
   const ql: any = await stack.kernel.getServiceAsync('objectql');
   const sys = (o: string, d: any) => ql.insert(o, d, { context: { isSystem: true } });
+
+  // Reference hierarchy-scope resolver (test fixture; prod = @objectstack/security-enterprise).
+  // Inlined (no plugin-sharing import) — proves the IHierarchyScopeResolver seam end-to-end.
+  const refResolver = {
+    async resolveOwnerIds(c: any, sc: string): Promise<string[]> {
+      const meId = c.userId as string;
+      const ids = new Set<string>([meId]);
+      if (sc === 'own_and_reports') {
+        let frontier: string[] = [meId]; const seen = new Set<string>([meId]);
+        for (let d = 0; d < 20 && frontier.length; d++) {
+          const rows = await ql.find('sys_user', { where: { manager_id: { $in: frontier } }, fields: ['id'], context: { isSystem: true } });
+          const next: string[] = [];
+          for (const r of rows ?? []) { const id = String(r.id ?? ''); if (id && !seen.has(id)) { seen.add(id); ids.add(id); next.push(id); } }
+          frontier = next;
+        }
+        return [...ids];
+      }
+      const myBus = await ql.find('sys_business_unit_member', { where: { user_id: meId }, fields: ['business_unit_id'], context: { isSystem: true } });
+      let buIds: string[] = [...new Set((myBus ?? []).map((r: any) => String(r.business_unit_id ?? '')).filter(Boolean))] as string[];
+      if (!buIds.length) return [meId];
+      if (sc === 'unit_and_below') {
+        const allBu = new Set<string>(buIds); let frontier: string[] = [...buIds];
+        for (let d = 0; d < 20 && frontier.length; d++) {
+          const kids = await ql.find('sys_business_unit', { where: { parent_business_unit_id: { $in: frontier } }, fields: ['id'], context: { isSystem: true } });
+          const next: string[] = [];
+          for (const k of kids ?? []) { const id = String(k.id ?? ''); if (id && !allBu.has(id)) { allBu.add(id); next.push(id); } }
+          frontier = next;
+        }
+        buIds = [...allBu];
+      }
+      const m = await ql.find('sys_business_unit_member', { where: { business_unit_id: { $in: buIds } }, fields: ['user_id'], context: { isSystem: true } });
+      for (const x of m ?? []) { const u = String(x.user_id ?? ''); if (u) ids.add(u); }
+      return [...ids];
+    },
+  };
+  if (withResolver) (stack.kernel as any).registerService('hierarchy-scope-resolver', refResolver);
   const uid = async (who: Who) =>
     (await ql.findOne('sys_user', { where: { email: `scope-${who}-${scope}@verify.test` }, context: { isSystem: true } }))?.id;
   const id = {} as Record<Who, string>;
@@ -119,3 +160,17 @@ describe('showcase: scope-depth read — `unit_and_below` (ADR-0057 D1)', () =>
     expect(t.sort()).toEqual(['bob note']); // child has no descendants; no upward visibility
   });
 });
+
+describe('open edition — hierarchy scope fails CLOSED without the enterprise resolver (ADR-0057)', () => {
+  let world: World;
+  beforeAll(async () => { world = await bootScopeWorld('unit', /* withResolver */ false); }, 120_000);
+  afterAll(async () => { await world?.stack?.stop(); });
+
+  it('a `unit` grant degrades to owner-only — no widening, never fail-open', async () => {
+    const t = await titles(world.stack, world.tokens.alice);
+    expect(t).toContain('alice note');      // own still works
+    expect(t).not.toContain('carol note');  // NO unit widening without @objectstack/security-enterprise
+    expect(t).not.toContain('bob note');
+    expect(t).not.toContain('dave note');
+  });
+});

packages/plugins/plugin-security/src/permission-evaluator.ts

@@ -87,9 +87,9 @@ export class PermissionEvaluator {
     opClass: 'read' | 'write',
     objectName: string,
     permissionSets: PermissionSet[],
-  ): 'own' | 'unit' | 'unit_and_below' | 'org' {
-    const RANK = { own: 0, unit: 1, unit_and_below: 2, org: 3 } as const;
-    const ORDER = ['own', 'unit', 'unit_and_below', 'org'] as const;
+  ): 'own' | 'own_and_reports' | 'unit' | 'unit_and_below' | 'org' {
+    const RANK = { own: 0, own_and_reports: 1, unit: 2, unit_and_below: 3, org: 4 } as const;
+    const ORDER = ['own', 'own_and_reports', 'unit', 'unit_and_below', 'org'] as const;
     let widest = -1;
     let matched = false;
     for (const ps of permissionSets) {

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

@@ -137,6 +137,12 @@ export class SharingServicePlugin implements Plugin {
       this.service = new SharingService({
         engine: engine as SharingEngine,
         bypassObjects: this.options.bypassObjects,
+        // [ADR-0057] Late-bound lookup of the enterprise hierarchy resolver.
+        // Open edition: not registered → hierarchy scopes fail closed to own.
+        hierarchyResolver: () => {
+          try { return ctx.getService<any>('hierarchy-scope-resolver'); }
+          catch { return null; }
+        },
       });
       ctx.registerService('sharing', this.service);
 

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

@@ -1,8 +1,8 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { BusinessUnitGraphService } from './business-unit-graph.js';
 import type {
   ISharingService,
+  IHierarchyScopeResolver,
   RecordShare,
   GrantShareInput,
   SharingExecutionContext,
@@ -72,6 +72,11 @@ export interface SharingServiceOptions {
   engine: SharingEngine;
   /** Object names that bypass sharing — typically platform internals. */
   bypassObjects?: string[];
+  /**
+   * [ADR-0057] Late-bound lookup for the enterprise hierarchy-scope resolver
+   * (`hierarchy-scope-resolver` service). Returns null in the open edition.
+   */
+  hierarchyResolver?: () => IHierarchyScopeResolver | null | undefined;
 }
 
 /**
@@ -85,9 +90,11 @@ export interface SharingServiceOptions {
 export class SharingService implements ISharingService {
   private readonly engine: SharingEngine;
   private readonly bypassObjects: Set<string>;
+  private readonly hierarchyResolver?: () => IHierarchyScopeResolver | null | undefined;
 
   constructor(options: SharingServiceOptions) {
     this.engine = options.engine;
+    this.hierarchyResolver = options.hierarchyResolver;
     this.bypassObjects = new Set([
       'sys_record_share',
       'sys_user',
@@ -125,7 +132,7 @@ export class SharingService implements ISharingService {
     // [ADR-0057 D1] Access DEPTH widens the owner-match for this grant:
     // own → [me], unit → my BU members, unit_and_below → my BU subtree, org →
     // no owner filter. Sharing grants are still OR-ed in on top (additive).
-    const readScope = (context as any).__readScope as ('own' | 'unit' | 'unit_and_below' | 'org' | undefined);
+    const readScope = (context as any).__readScope as ('own' | 'own_and_reports' | 'unit' | 'unit_and_below' | 'org' | undefined);
     if (readScope === 'org') return null;
     const ownerIds = await this.resolveOwnerScopeIds(context, readScope);
     const ownerMatch: Record<string, unknown> = ownerIds.length === 1
@@ -187,7 +194,7 @@ export class SharingService implements ISharingService {
     });
     const owner = Array.isArray(own) && own[0] ? (own[0] as any)[OWNER_FIELD] : undefined;
     if (owner != null) {
-      const writeScope = (context as any).__writeScope as ('own' | 'unit' | 'unit_and_below' | 'org' | undefined);
+      const writeScope = (context as any).__writeScope as ('own' | 'own_and_reports' | 'unit' | 'unit_and_below' | 'org' | undefined);
       if (writeScope === 'org') return true;
       const owners = await this.resolveOwnerScopeIds(context, writeScope);
       if (owners.includes(String(owner))) return true;
@@ -298,47 +305,35 @@ export class SharingService implements ISharingService {
   // ── helpers ──────────────────────────────────────────────────────
 
   /**
-   * [ADR-0057 D1] Resolve the owner-id set for a read/write DEPTH scope.
-   * `own`/unset → just the caller; `unit` → members of the caller's business
-   * unit(s); `unit_and_below` → the caller's BU subtree (BFS). Always includes
-   * self. Elevated to SYSTEM_CTX (membership graph is platform metadata).
+   * [ADR-0057] Resolve the owner-id set for a DEPTH scope. `own`/unset/`org`
+   * resolve locally to the caller. HIERARCHY scopes (`unit` / `unit_and_below`
+   * / `own_and_reports`) are an ENTERPRISE capability resolved by a pluggable
+   * {@link IHierarchyScopeResolver} (`hierarchy-scope-resolver` service, shipped
+   * only by `@objectstack/security-enterprise`). The open edition has none, so
+   * this fails CLOSED to owner-only — a hierarchy scope NEVER widens without the
+   * enterprise resolver (the spec gate also refuses to compile such a grant).
    */
   private async resolveOwnerScopeIds(
     context: SharingExecutionContext,
-    scope: 'own' | 'unit' | 'unit_and_below' | 'org' | undefined,
+    scope: 'own' | 'own_and_reports' | 'unit' | 'unit_and_below' | 'org' | undefined,
   ): Promise<string[]> {
     const me = String((context as any).userId);
     if (!scope || scope === 'own' || scope === 'org') return [me];
-    const orgId = (context as any).organizationId ?? (context as any).tenantId ?? null;
-    const myBus = await this.engine.find('sys_business_unit_member', {
-      where: { user_id: me },
-      fields: ['business_unit_id'],
-      limit: 1000,
-      context: SYSTEM_CTX,
-    });
-    const buIds = Array.from(
-      new Set((myBus ?? []).map((r: any) => String(r.business_unit_id ?? '')).filter(Boolean)),
-    );
-    if (buIds.length === 0) return [me];
-    const ids = new Set<string>([me]);
-    if (scope === 'unit') {
-      const members = await this.engine.find('sys_business_unit_member', {
-        where: { business_unit_id: { $in: buIds } },
-        fields: ['user_id'],
-        limit: 10000,
-        context: SYSTEM_CTX,
-      });
-      for (const m of members ?? []) {
-        const u = String((m as any).user_id ?? '');
-        if (u) ids.add(u);
-      }
-    } else {
-      const bug = new BusinessUnitGraphService({ engine: this.engine, organizationId: orgId });
-      for (const bu of buIds) {
-        for (const u of await bug.expandUsers(bu)) ids.add(u);
-      }
+    const resolver = this.hierarchyResolver?.();
+    if (!resolver) return [me];
+    try {
+      const ids = await resolver.resolveOwnerIds(
+        {
+          userId: me,
+          organizationId: (context as any).organizationId ?? null,
+          tenantId: (context as any).tenantId ?? null,
+        },
+        scope,
+      );
+      return Array.isArray(ids) && ids.length > 0 ? ids : [me];
+    } catch {
+      return [me];
     }
-    return Array.from(ids);
   }
 
   private shouldBypass(object: string, context: SharingExecutionContext): boolean {

packages/spec/src/contracts/sharing-service.ts

@@ -249,3 +249,32 @@ export interface IBusinessUnitGraphService {
   /** Return the manager id for a user — proxy to {@link ITeamGraphService.managerOf}. */
   managerOf(userId: string, organizationId?: string): Promise<string | null>;
 }
+
+
+/**
+ * [ADR-0057] HIERARCHY access scopes (the Dataverse-style "see records by where
+ * you sit in the org"). `own`/`org` are resolved by the open sharing layer
+ * itself; these three require a pluggable resolver.
+ */
+export type HierarchyScope = 'unit' | 'unit_and_below' | 'own_and_reports';
+
+export interface HierarchyScopeContext {
+  userId: string;
+  organizationId?: string | null;
+  tenantId?: string | null;
+}
+
+/**
+ * Pluggable resolver for {@link HierarchyScope}s. The OPEN edition ships no
+ * implementation; the ENTERPRISE package `@objectstack/security-enterprise`
+ * registers one under the `hierarchy-scope-resolver` kernel service. When
+ * absent, the sharing layer fails CLOSED to owner-only (a hierarchy scope never
+ * widens without the resolver).
+ */
+export interface IHierarchyScopeResolver {
+  /**
+   * Owner ids whose records the caller may see under `scope` (must include the
+   * caller). Empty/throw → caller falls back to owner-only.
+   */
+  resolveOwnerIds(context: HierarchyScopeContext, scope: HierarchyScope): Promise<string[]>;
+}

packages/spec/src/security/permission.zod.ts

@@ -18,7 +18,7 @@ import { lazySchema } from '../shared/lazy-schema';
  * [ADR-0057 D1] Object access DEPTH — the Dataverse "access level" axis,
  * layered on top of OWD. Widens the owner-match for owner-scoped objects.
  */
-export const ObjectAccessScopeSchema = z.enum(['own', 'unit', 'unit_and_below', 'org']);
+export const ObjectAccessScopeSchema = z.enum(['own', 'own_and_reports', 'unit', 'unit_and_below', 'org']);
 export type ObjectAccessScope = z.infer<typeof ObjectAccessScopeSchema>;
 
 export const ObjectPermissionSchema = lazySchema(() => z.object({
@@ -62,7 +62,8 @@ export const ObjectPermissionSchema = lazySchema(() => z.object({
   /**
    * [ADR-0057 D1] Read access DEPTH (Dataverse-style access level), layered on
    * top of OWD. For owner-scoped (`private`) objects it widens the owner-match:
-   * `own` (owner only) | `unit` (my business unit) | `unit_and_below` (my BU +
+   * `own` (owner only) | `own_and_reports` (me + my sys_user.manager_id
+   * report chain) | `unit` (my business unit) | `unit_and_below` (my BU +
    * descendants) | `org` (whole tenant). Unset = `own` baseline. Resolved into
    * an `owner_id IN (…)` set at request time; sharing rules still widen on top.
    */

packages/spec/src/stack.zod.ts

@@ -792,6 +792,40 @@ function mergeActionsIntoObjects(config: ObjectStackDefinition): ObjectStackDefi
  * const stack = defineStack({ manifest: { ... }, objects: [...], views: [...] }, { strict: true });
  * ```
  */
+/**
+ * [ADR-0057] HIERARCHY access scopes (`unit` / `unit_and_below` /
+ * `own_and_reports`) are an ENTERPRISE capability — their enforcement ships in
+ * `@objectstack/security-enterprise`, not the open edition. A stack that uses
+ * one MUST declare `requires: ['hierarchy-security']`; otherwise the open
+ * runtime would silently fail closed to owner-only (the metadata would lie,
+ * ADR-0049). This makes that an authoring-time error instead.
+ */
+function validateHierarchyScopeCapability(data: unknown): string[] {
+  const errors: string[] = [];
+  const d = data as { requires?: unknown; permissions?: unknown };
+  const requires = Array.isArray(d?.requires) ? (d.requires as string[]) : [];
+  if (requires.includes('hierarchy-security')) return errors;
+  const HIER = new Set(['unit', 'unit_and_below', 'own_and_reports']);
+  const perms = Array.isArray(d?.permissions) ? (d.permissions as any[]) : [];
+  for (const ps of perms) {
+    const objs = ps?.objects && typeof ps.objects === 'object' ? ps.objects : {};
+    for (const [objName, grant] of Object.entries(objs)) {
+      const g = grant as Record<string, unknown>;
+      for (const key of ['readScope', 'writeScope']) {
+        const v = g?.[key];
+        if (typeof v === 'string' && HIER.has(v)) {
+          errors.push(
+            `permission set '${ps?.name ?? '?'}' grant on '${objName}' uses ${key}='${v}', a HIERARCHY scope. ` +
+            `Declare \`requires: ['hierarchy-security']\` (provided by @objectstack/security-enterprise) — ` +
+            `the open edition cannot enforce it and would fail closed to owner-only.`,
+          );
+        }
+      }
+    }
+  }
+  return errors;
+}
+
 export function defineStack(
   config: ObjectStackDefinitionInput,
   options?: DefineStackOptions,
@@ -838,6 +872,13 @@ export function defineStack(
     throw new Error(`${header}\n\n${lines.join('\n')}`);
   }
 
+  const hierErrors = validateHierarchyScopeCapability(result.data);
+  if (hierErrors.length > 0) {
+    const header = `defineStack hierarchy-scope capability validation failed (${hierErrors.length} issue${hierErrors.length === 1 ? '' : 's'}):`;
+    const lines = hierErrors.map((e) => `  ✗ ${e}`);
+    throw new Error(`${header}\n\n${lines.join('\n')}`);
+  }
+
   return mergeActionsIntoObjects(result.data);
 }