feat(approvals): cross-organization approver targeting (ADR-0105 D9)

One organization id decided three different things at once in
`openNodeRequest`: where the request row lives, where its inbox index rows
live, and where its approvers are looked up. The first two are the request's
own organization by definition. The third is not — a group CFO holds her `cfo`
position in the GROUP organization while the purchase order she signs off
lives in the PLANT organization. `expandPositionUsers('cfo', <plant>)` matched
nobody, the slot fell back to the dead `position:cfo` literal, and a group
escalation could not be expressed at all.

An approver may now declare which organization's directory resolves it:

    - { type: position, value: plant_manager, group: plant }
    - { type: position, value: cfo, organization: $root, group: finance }

Four design points the ADR left open, settled from what the code and the
authoring model require (ADR text amended in this commit):

- PER APPROVER, not per node. The node-level form cannot express the commonest
  group shape — one node requiring a plant manager AND a group CFO in parallel.
  Splitting into serial nodes changes the semantics rather than the syntax. A
  node-level default remains addable later as sugar; the reverse is not true.

- SYMBOLS FIRST (`$root` / `$parent`). Flow metadata is portable across
  environments; an organization id is data minted per deployment, so a literal
  id in a flow is unportable by construction and an AI author cannot know one.
  The symbols walk D6's `parent_organization_id` tree with zero deployment
  knowledge. A slug covers what they cannot — notably a SIBLING organization
  (a shared-services centre approving payables for every plant).

- LEGALITY IS "SHARES A ROOT", not "is an ancestor" — the sibling case above is
  first-class. The rule reads only the organization tree, never the submitter,
  so one flow routes identically for everyone and a routing bug is reproducible.

- NON-`group` POSTURES REFUSE at runtime. Posture is environment configuration,
  so the same portable metadata deploys into any posture and no static check
  can see which; ignoring the declaration would let a group → isolated
  migration reroute approvals with no signal.

Two failure modes are made loud rather than silent: an approver type with no
org-scoped directory (`user`/`field`/`manager`/`team`) refuses the declaration
instead of ignoring it, with a new `approval-approver-cross-org-unsupported`
lint catching it at author time; and a targeted approver holding no membership
in the request's organization is dropped with a warning naming them — D2's
union wall would otherwise hide the request from someone already routed to,
leaving a task she cannot open. Dropping hands it to the node's existing
`onEmptyApprovers` policy.

An approver without `organization` is unchanged: same resolution, same
queries, no extra reads.

Tests: 17 resolver units (symbols, sibling/foreign slugs, posture, cycles,
unreadable-membership), 7 service integration (including the pre-D9 gap, the
mixed plant+group node, and that the request still belongs to the request org),
4 lint. plugin-approvals 305, lint 500, spec 6736, cli 682 all green.

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

Author: claude

.changeset/adr-0105-d9-cross-org-approver-targeting.md

@@ -0,0 +1,53 @@
+---
+"@objectstack/plugin-approvals": minor
+"@objectstack/spec": minor
+"@objectstack/lint": minor
+---
+
+feat(approvals): cross-organization approver targeting — a plant document can
+require a group-side sign-off (ADR-0105 D9)
+
+One organization id used to decide three different things at once in
+`openNodeRequest`: where the request row lives, where its inbox index rows
+live, and **where its approvers are looked up**. The first two are the
+request's own organization by definition. The third is not — a group CFO holds
+her `cfo` position in the GROUP organization while the purchase order she signs
+off lives in the PLANT organization. `expandPositionUsers('cfo', <plant>)`
+matched nobody, the slot fell back to the dead `position:cfo` literal, and a
+group escalation could not be expressed at all.
+
+An approver may now declare which organization's directory resolves it:
+
+```yaml
+approvers:
+  - { type: position, value: plant_manager, group: plant }
+  - { type: position, value: cfo, organization: $root, group: finance }
+behavior: per_group
+```
+
+- **`$root` / `$parent`** walk D6's `parent_organization_id` tree, so the two
+  common intents need **no deployment knowledge** — flow metadata is portable
+  across environments while organization ids are minted per deployment. A slug
+  covers what the symbols cannot, notably a **sibling** organization (a
+  shared-services centre approving payables for every plant).
+- Declared **per approver**, so one node can require a plant manager and a
+  group CFO in parallel. A node-level form cannot express that without
+  splitting into serial nodes, which changes the semantics.
+- **Bounded, not free:** the target must share a `parent_organization_id` root
+  with the request's organization. The rule reads only the organization tree —
+  never the submitter — so one flow routes identically for everyone.
+
+Everything else fails loudly rather than quietly:
+
+- a non-`group` posture **refuses** the declaration (a `group` → `isolated`
+  migration must not silently reroute approvals);
+- an approver type with no org-scoped directory (`user` / `field` / `manager` /
+  `team`) refuses it too, and a new `approval-approver-cross-org-unsupported`
+  lint catches that at author time;
+- a targeted approver holding no membership in the request's organization is
+  dropped with a warning naming them — D2's union wall would otherwise hide the
+  request from someone already routed to, so the node's existing
+  `onEmptyApprovers` policy takes over instead of leaving an unopenable task.
+
+Nothing changes for an approver without `organization`: same resolution, same
+queries, no extra reads.

content/docs/references/automation/approval.mdx

@@ -58,6 +58,7 @@ const result = ApprovalDecision.parse(data);
 | **value** | `string` | optional | User id / membership tier / position / team / department / field — per `type`; for `expression`, a CEL expression over `current.*` / `trigger.*` / `vars.*` |
 | **resolveAs** | `Enum<'user' \| 'department' \| 'position' \| 'team'>` | optional | How an `expression` result is expanded into approvers (default 'user') |
 | **group** | `string` | optional | Group label for per_group sign-off (e.g. "legal", "finance") |
+| **organization** | `string` | optional | ADR-0105 D9 — organization whose directory resolves this approver: `$root` (group org), `$parent` (one level up), or an organization slug. Omitted = the request's own organization. |
 
 
 ---
@@ -68,7 +69,7 @@ const result = ApprovalDecision.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **approvers** | `{ type: Enum<'user' \| 'org_membership_level' \| 'role' \| 'position' \| 'team' \| 'department' \| 'manager' \| 'field' \| 'queue' \| 'expression'>; value?: string; resolveAs?: Enum<'user' \| 'department' \| 'position' \| 'team'>; group?: string }[]` | ✅ | Allowed approvers for this node |
+| **approvers** | `{ type: Enum<'user' \| 'org_membership_level' \| 'role' \| 'position' \| 'team' \| 'department' \| 'manager' \| 'field' \| 'queue' \| 'expression'>; value?: string; resolveAs?: Enum<'user' \| 'department' \| 'position' \| 'team'>; group?: string; … }[]` | ✅ | Allowed approvers for this node |
 | **behavior** | `Enum<'first_response' \| 'unanimous' \| 'quorum' \| 'per_group'>` | ✅ | How to combine multiple approvers |
 | **minApprovals** | `integer` | optional | Approvals required — total (quorum) or per group (per_group). Default 1 |
 | **lockRecord** | `boolean` | ✅ | Lock the record from editing while pending |

docs/adr/0105-group-tenancy-posture-and-first-class-org-scope.md

@@ -249,14 +249,53 @@ the `single`-posture deployment (plant-autonomous member admission) and is the
 natural admission UX in `group` posture.
 
 **D9 — Cross-org approval targeting.**
-An approval chain node may name a **target organization** for approver
-resolution (default: the request's org, today's behavior at
-`approval-node.ts:118`). A plant document's escalation step declares
-`organization: <group org>` and resolves group-side position holders. Reads of
-the request by those approvers are covered by D2 (membership union) in `group`
-posture; in `isolated` posture this decision does not apply (cross-org
+An approval **approver** may name a **target organization** for its resolution
+(default: the request's org, today's behavior). A plant document's escalation
+step declares `organization: $root` and resolves group-side position holders.
+Reads of the request by those approvers are covered by D2 (membership union) in
+`group` posture; in `isolated` posture this decision does not apply (cross-org
 approval there remains mirroring via system context, cloud #2937 contract).
 
+*Amended during implementation (#3812). Four points the original text left
+open, each settled from what the code and the authoring model actually
+require:*
+
+1. *Per **approver**, not per node.* The node-level form cannot express the
+   commonest group shape — one node requiring a plant manager **and** a group
+   CFO in parallel (`behavior: 'per_group'`). Expressing it as two serial nodes
+   changes the semantics (parallel co-sign becomes sequential approval), so the
+   node-level form distorts the model rather than merely inconveniencing the
+   author. A node-level default is a strict special case of the per-approver
+   form and remains addable later as sugar; the reverse is not true.
+2. *Symbolic references first: `$root`, `$parent`.* Flow metadata is portable
+   across environments; an organization id is data minted per deployment. A
+   literal id in a flow is therefore unportable by construction, and an AI
+   author cannot know one at authoring time. The symbols express the two common
+   intents against D6's tree with **zero deployment knowledge**. A slug covers
+   what they cannot — notably a **sibling** organization (a shared-services
+   centre approving payables for every plant).
+3. *Legality is "shares a `parent_organization_id` root", not "is an
+   ancestor".* The sibling case above is first-class, as is downward targeting.
+   The rule depends only on the organization tree and **never on the
+   submitter**, so one flow routes identically for everyone — which is what
+   makes a routing bug reproducible. A deployment with no grouping metadata
+   gets a refusal naming D6, not a silent pass.
+4. *Non-`group` postures **refuse** at runtime rather than ignoring.* Posture is
+   environment configuration, so the same portable metadata may be deployed
+   into any posture and no static check can see which. Silently ignoring the
+   declaration would let a `group` → `isolated` migration reroute approvals
+   with no signal — an audit event, not a config detail.
+
+*Two consequences worth stating, both enforced:* an approver type that resolves
+no org-scoped directory (`user` / `field` / `manager` / `team`) **refuses** the
+declaration instead of ignoring it (an author who wrote it believed it did
+something); and a targeted approver who holds no membership in the request's
+organization is **dropped with a warning** naming them, because D2's union
+would otherwise hide the request from someone the router had already committed
+to — routing succeeds, the inbox row is written, and the approver opens a task
+she cannot open. Dropping converts that silent dead-end into the node's
+existing `onEmptyApprovers` policy.
+
 **D10 — Layered master data (group template + org override).**
 A spec-level pattern for the SAP material-master / 用友-金蝶 distribution
 shape: an object may declare layered governance — group-level template rows

packages/lint/src/index.ts

@@ -135,6 +135,7 @@ export {
   APPROVAL_EXPRESSION_INVALID,
   APPROVAL_EXPRESSION_NO_EMPTY_POLICY,
   APPROVAL_DECISION_OUTPUTS_RESERVED,
+  APPROVAL_APPROVER_CROSS_ORG_UNSUPPORTED,
 } from './validate-approval-approvers.js';
 export type { ApprovalApproverFinding, ApprovalApproverSeverity } from './validate-approval-approvers.js';
 

packages/lint/src/validate-approval-approvers.test.ts

@@ -12,6 +12,7 @@ import {
   APPROVAL_EXPRESSION_INVALID,
   APPROVAL_EXPRESSION_NO_EMPTY_POLICY,
   APPROVAL_DECISION_OUTPUTS_RESERVED,
+  APPROVAL_APPROVER_CROSS_ORG_UNSUPPORTED,
 } from './validate-approval-approvers.js';
 
 function stackWithApprovers(approvers: unknown[]): Record<string, unknown> {
@@ -334,3 +335,39 @@ describe('expression approvers (#3447 P2)', () => {
     }))).toEqual([]);
   });
 });
+
+describe('cross-organization targeting (ADR-0105 D9)', () => {
+  it('is clean when `organization` sits on an org-scoped approver type', () => {
+    // The whole point of D9: a group CFO resolved against the group directory.
+    const findings = validateApprovalApprovers(
+      stackWithApprovers([{ type: 'position', value: 'cfo', organization: '$root' }]),
+    );
+    expect(findings.filter(f => f.rule === APPROVAL_APPROVER_CROSS_ORG_UNSUPPORTED)).toEqual([]);
+  });
+
+  it('errors when `organization` sits on a type with no organization directory', () => {
+    // `user` names a person outright — the declaration cannot narrow anything,
+    // and the runtime refuses it. Catch it at author time instead.
+    const findings = validateApprovalApprovers(
+      stackWithApprovers([{ type: 'user', value: 'u1', organization: '$root' }]),
+    );
+    const f = findings.find(x => x.rule === APPROVAL_APPROVER_CROSS_ORG_UNSUPPORTED);
+    expect(f?.severity).toBe('error');
+    expect(f?.path).toBe('flows[0].nodes[1].config.approvers[0].organization');
+    expect(f?.hint).toMatch(/position.*org_membership_level.*department.*expression/);
+  });
+
+  it('errors for `team` too — team membership carries no organization', () => {
+    const findings = validateApprovalApprovers(
+      stackWithApprovers([{ type: 'team', value: 't1', organization: 'acme-ssc' }]),
+    );
+    expect(findings.some(f => f.rule === APPROVAL_APPROVER_CROSS_ORG_UNSUPPORTED)).toBe(true);
+  });
+
+  it('stays silent when no organization is declared — the default path', () => {
+    const findings = validateApprovalApprovers(
+      stackWithApprovers([{ type: 'user', value: 'u1' }]),
+    );
+    expect(findings.filter(f => f.rule === APPROVAL_APPROVER_CROSS_ORG_UNSUPPORTED)).toEqual([]);
+  });
+});

packages/lint/src/validate-approval-approvers.ts

@@ -24,6 +24,7 @@
  * | approval-expression-invalid                | error/info | #3447 P2 closed-root expressions |
  * | approval-expression-no-empty-policy        | info     | #3447 P2 empty-slate policy |
  * | approval-decision-outputs-reserved         | error    | #3447 P2 resume envelope   |
+ * | approval-approver-cross-org-unsupported    | error    | ADR-0105 D9 targeting      |
  *
  * The first two are mutually exclusive by construction — a bad *value* wins,
  * because its fix (`position`) differs from the deprecation's fix
@@ -42,6 +43,7 @@ import {
   APPROVAL_NODE_TYPE,
   DEPRECATED_APPROVER_TYPES,
   APPROVER_VALUE_BINDINGS,
+  approverTypeIsOrgScoped,
   canonicalApproverType,
   normalizeDecisionOutputs,
 } from '@objectstack/spec/automation';
@@ -57,6 +59,7 @@ export const APPROVAL_APPROVERS_MAY_RESOLVE_EMPTY = 'approval-approvers-may-reso
 export const APPROVAL_EXPRESSION_INVALID = 'approval-expression-invalid';
 export const APPROVAL_EXPRESSION_NO_EMPTY_POLICY = 'approval-expression-no-empty-policy';
 export const APPROVAL_DECISION_OUTPUTS_RESERVED = 'approval-decision-outputs-reserved';
+export const APPROVAL_APPROVER_CROSS_ORG_UNSUPPORTED = 'approval-approver-cross-org-unsupported';
 
 /**
  * The CLOSED root set an `expression` approver may reference (#3447 P2) —
@@ -304,6 +307,31 @@ export function validateApprovalApprovers(stack: AnyRec): ApprovalApproverFindin
               `Queue approvers need a real ownership-queue implementation before they take effect.`,
           });
         }
+
+        // [ADR-0105 D9] Cross-organization targeting on a type that has no
+        // organization-scoped directory. `user` / `field` / `manager` name a
+        // person outright and `team` membership carries no organization, so the
+        // declaration cannot narrow anything — it is a misunderstanding of what
+        // the field does, and the runtime refuses it. Error, not warning: this
+        // is a certain authoring mistake with a certain fix, and letting it
+        // reach the runtime turns author time into an incident.
+        const declaredOrg = (a as AnyRec).organization;
+        if (typeof declaredOrg === 'string' && declaredOrg.trim() !== ''
+          && ApproverType.options.includes(canonical as never)
+          && !approverTypeIsOrgScoped(canonical)) {
+          findings.push({
+            severity: 'error',
+            rule: APPROVAL_APPROVER_CROSS_ORG_UNSUPPORTED,
+            where,
+            path: `${path}.organization`,
+            message:
+              `approver type '${type}' does not resolve through an organization directory, so ` +
+              `'organization: ${declaredOrg}' has no effect (ADR-0105 D9) — the runtime refuses it.`,
+            hint:
+              `Drop 'organization' here. Cross-organization targeting applies to ` +
+              `'position', 'org_membership_level', 'department' and 'expression' approvers.`,
+          });
+        }
       }
 
       // Empty-slate dead-end (#3424): when EVERY approver on the node routes to