@objectstack/plugin-approvals 16.0.0 → 17.0.0-rc.0

package/src/approvals-plugin.ts

@@ -121,6 +121,20 @@ export class ApprovalsServicePlugin implements Plugin {
       engine: engine as ApprovalEngine,
       logger: ctx.logger,
       publicBaseUrl: this.options.publicBaseUrl,
+      // [ADR-0105 D9] Cross-organization approver targeting is a `group`-posture
+      // capability. Read LAZILY (not captured at start) because the tenancy
+      // service resolves its posture during its own start, which may not have
+      // run yet; an unresolvable posture reads as "unknown" and the guard
+      // stands down rather than refusing a legitimate flow on a minimal stack.
+      tenancyPosture: () => {
+        try {
+          const tenancy = ctx.getService<{ posture?: string }>('tenancy');
+          const posture = tenancy?.posture;
+          return typeof posture === 'string' && posture ? posture : undefined;
+        } catch {
+          return undefined;
+        }
+      },
     });
 
     // Record lock: block edits to a record while it has a pending request.
@@ -161,12 +175,29 @@ export class ApprovalsServicePlugin implements Plugin {
         if (!jobs || typeof jobs.schedule !== 'function' || !this.service) return;
         const svc = this.service;
         const intervalMs = this.options.escalationScanIntervalMs ?? ESCALATION_SCAN_INTERVAL_MS;
-        await jobs.schedule(ESCALATION_JOB_NAME, { type: 'interval', intervalMs }, async () => {
-          await svc.runEscalations();
-        });
+        // Both sweeps ride this one clock: they walk the same `pending` set, and
+        // the dead-run release (#3456) is reconciliation with the same "catch up
+        // after a restart" requirement — a run killed BY the restart is exactly
+        // the shape no in-band handler can clean up.
+        // Genuinely independent — an escalation failure must not strand locked
+        // records, and vice versa, so neither can short-circuit the other.
+        const sweep = async () => {
+          const results = await Promise.allSettled([
+            svc.runEscalations(),
+            svc.releaseDeadRunRequests(),
+          ]);
+          for (const r of results) {
+            if (r.status === 'rejected') {
+              ctx.logger.warn?.('[approvals] periodic sweep leg failed', {
+                error: (r.reason as any)?.message ?? String(r.reason),
+              });
+            }
+          }
+        };
+        await jobs.schedule(ESCALATION_JOB_NAME, { type: 'interval', intervalMs }, sweep);
         this.escalationJobScheduled = true;
-        void svc.runEscalations().catch((err: any) => {
-          ctx.logger.warn?.('[approvals] boot escalation sweep failed', { error: err?.message });
+        void sweep().catch((err: any) => {
+          ctx.logger.warn?.('[approvals] boot sweep failed', { error: err?.message });
         });
         ctx.logger.info('ApprovalsServicePlugin: SLA escalation scan scheduled', { intervalMs });
       } catch { /* job service not installed */ }

package/src/approver-cross-org.integration.test.ts

@@ -0,0 +1,206 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [ADR-0105 D9] Cross-organization approver targeting, through the SERVICE.
+ *
+ * `approver-org-scope.test.ts` owns the resolver's own rules. What only this
+ * level can show is that the resolved organization actually reaches the
+ * directory lookups — the wiring D9 is: one organization id used to decide
+ * three different things at once (where the request lives, where its inbox rows
+ * live, where its approvers are looked up), and only the third moves.
+ *
+ * The scenario is the one D9 exists for: a purchase order raised in PLANT A
+ * needs the group CFO, who holds `cfo` in the GROUP organization and would have
+ * matched nobody before.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ApprovalService } from './approval-service.js';
+
+interface Row { [k: string]: any }
+
+function makeEngine(seed: Record<string, Row[]> = {}) {
+  const tables: Record<string, Row[]> = { ...seed };
+  const ensure = (n: string) => (tables[n] ??= []);
+  const matches = (row: Row, filter: any): boolean => {
+    if (!filter || typeof filter !== 'object') return true;
+    for (const [k, v] of Object.entries(filter)) {
+      if (k === '$or') {
+        if (!(v as any[]).some((sub) => matches(row, sub))) return false;
+        continue;
+      }
+      const rv = row[k];
+      if (v != null && typeof v === 'object' && '$in' in (v as any)) {
+        if (!(v as any).$in.includes(rv)) return false;
+        continue;
+      }
+      if (v != null && typeof v === 'object' && '$ne' in (v as any)) {
+        if (rv === (v as any).$ne) return false;
+        continue;
+      }
+      if (rv !== v) return false;
+    }
+    return true;
+  };
+  return {
+    _tables: tables,
+    async find(object: string, options?: any) {
+      return ensure(object).filter((r) => matches(r, options?.filter ?? options?.where));
+    },
+    async insert(object: string, data: Row) { ensure(object).push({ ...data }); return { ...data }; },
+    async update(_o: string, _w: any, _d: any) { return {}; },
+    async delete() { return {}; },
+    async count(object: string) { return ensure(object).length; },
+    registerHook() { /* no-op */ },
+    unregisterHooksByPackage() { /* no-op */ },
+  };
+}
+
+/** Plant A sits under the group; the CFO's position lives in the group org. */
+const SEED = () => ({
+  sys_organization: [
+    { id: 'o_group', slug: 'acme-group', parent_organization_id: null },
+    { id: 'o_plant', slug: 'acme-plant-a', parent_organization_id: 'o_group' },
+  ],
+  sys_user_position: [
+    { id: 'up1', user_id: 'u_cfo', position: 'cfo', organization_id: 'o_group' },
+    { id: 'up2', user_id: 'u_plant_mgr', position: 'plant_manager', organization_id: 'o_plant' },
+  ],
+  sys_member: [
+    // The intended group shape: group staff hold a membership in every plant
+    // (so D2's union lets them READ the request) while their POSITION lives in
+    // the group organization.
+    { id: 'm1', user_id: 'u_cfo', organization_id: 'o_plant', role: 'member' },
+    { id: 'm2', user_id: 'u_plant_mgr', organization_id: 'o_plant', role: 'member' },
+  ],
+});
+
+const CTX = { userId: 'u_submitter', organizationId: 'o_plant', positions: [], permissions: [] } as any;
+
+function openInput(approvers: any[], extra: Record<string, any> = {}) {
+  return {
+    object: 'purchase_order',
+    recordId: 'po1',
+    runId: 'run_1',
+    nodeId: 'group_signoff',
+    flowName: 'po_approval',
+    config: { approvers, behavior: 'unanimous' as const, lockRecord: false },
+    record: { id: 'po1', amount: 500000 },
+    ...extra,
+  };
+}
+
+describe('ADR-0105 D9 — cross-org approver targeting through ApprovalService', () => {
+  let engine: ReturnType<typeof makeEngine>;
+  let svc: ApprovalService;
+  let n = 0;
+
+  beforeEach(() => {
+    engine = makeEngine(SEED());
+    n = 0;
+    svc = new ApprovalService({
+      engine: engine as any,
+      clock: { now: () => new Date(1767000000000 + (n++) * 1000) },
+      tenancyPosture: () => 'group',
+    });
+  });
+
+  it('without targeting, a group position matches NOBODY — the gap D9 closes', async () => {
+    // The `cfo` position exists, but in the group org; the request is Plant A's.
+    // Pre-D9 this was the only possible outcome, and it was silent.
+    const req = await svc.openNodeRequest(openInput([{ type: 'position', value: 'cfo' }]), CTX);
+    expect(req.pending_approvers).toEqual(['position:cfo']); // the dead literal slot
+  });
+
+  it('`organization: $root` resolves the CFO against the GROUP directory', async () => {
+    const req = await svc.openNodeRequest(
+      openInput([{ type: 'position', value: 'cfo', organization: '$root' }]),
+      CTX,
+    );
+    expect(req.pending_approvers).toEqual(['u_cfo']);
+  });
+
+  it('the request and its inbox rows still belong to the REQUEST org — only the lookup moved', async () => {
+    await svc.openNodeRequest(
+      openInput([{ type: 'position', value: 'cfo', organization: '$root' }]),
+      CTX,
+    );
+    // This is the whole point of the split: targeting must not relocate the
+    // request into the approver's organization, or the plant would lose its own
+    // audit trail to the group.
+    expect(engine._tables['sys_approval_request'][0].organization_id).toBe('o_plant');
+    expect(engine._tables['sys_approval_approver'][0].organization_id).toBe('o_plant');
+    expect(engine._tables['sys_approval_action'][0].organization_id).toBe('o_plant');
+  });
+
+  it('mixes a plant approver and a group approver in ONE node — why targeting is per-approver', async () => {
+    // A node-level declaration could not express this: the plant manager and the
+    // group CFO sign off in parallel, each resolved in a different directory.
+    const req = await svc.openNodeRequest(
+      openInput([
+        { type: 'position', value: 'plant_manager', group: 'plant' },
+        { type: 'position', value: 'cfo', organization: '$root', group: 'finance' },
+      ]),
+      CTX,
+    );
+    expect(new Set(req.pending_approvers)).toEqual(new Set(['u_plant_mgr', 'u_cfo']));
+  });
+
+  it('drops a targeted approver who could not READ the request, leaving the empty-slate path', async () => {
+    // Same flow, but the CFO holds no membership in Plant A — D2's union wall
+    // would hide the request from her. Better an empty slate (which the node has
+    // an `onEmptyApprovers` policy for) than a task she cannot open.
+    engine._tables['sys_member'] = engine._tables['sys_member'].filter((m) => m.user_id !== 'u_cfo');
+    const req = await svc.openNodeRequest(
+      openInput([{ type: 'position', value: 'cfo', organization: '$root' }]),
+      CTX,
+    );
+    expect(req.pending_approvers).toEqual(['position:cfo']);
+  });
+
+  // Regression: `user` / `field` / `manager` return EARLY in
+  // `resolveApproverSpec`, before the graph-expansion branch. D9's resolution
+  // originally sat after those returns, so the declaration on a directory-less
+  // type was silently INERT rather than refused — the one behaviour ADR-0105 D9
+  // and the authoring docs both promise it is not. The resolver's own unit test
+  // could not see it (it calls the resolver directly); only a request opened
+  // through the service reaches the early return. Caught by cloud's
+  // group-posture dogfood.
+  it('refuses `organization` on a directory-less type — the early return must not skip the check', async () => {
+    for (const spec of [
+      { type: 'user', value: 'u_cfo', organization: '$root' },
+      { type: 'field', value: 'owner_id', organization: '$root' },
+      { type: 'manager', organization: '$root' },
+    ]) {
+      await expect(
+        svc.openNodeRequest(openInput([spec]), CTX),
+        `approver type '${spec.type}' must refuse a cross-org declaration`,
+      ).rejects.toThrow(/VALIDATION_FAILED.*no effect/);
+    }
+  });
+
+  it('a directory-less approver with NO declaration is untouched by D9', async () => {
+    // The guard must not cost the ordinary case anything.
+    const req = await svc.openNodeRequest(openInput([{ type: 'user', value: 'u_plant_mgr' }]), CTX);
+    expect(req.pending_approvers).toEqual(['u_plant_mgr']);
+  });
+
+  it('refuses a target outside the group — loudly, and no request is created', async () => {
+    engine._tables['sys_organization'].push({ id: 'o_rival', slug: 'rival-co', parent_organization_id: null });
+    await expect(
+      svc.openNodeRequest(openInput([{ type: 'position', value: 'cfo', organization: 'rival-co' }]), CTX),
+    ).rejects.toThrow(/VALIDATION_FAILED.*not in the same group/);
+    expect(engine._tables['sys_approval_request'] ?? []).toHaveLength(0);
+  });
+
+  it('refuses under a non-group posture — a posture migration cannot silently reroute', async () => {
+    const isolated = new ApprovalService({
+      engine: engine as any,
+      clock: { now: () => new Date(1767000000000) },
+      tenancyPosture: () => 'isolated',
+    });
+    await expect(
+      isolated.openNodeRequest(openInput([{ type: 'position', value: 'cfo', organization: '$root' }]), CTX),
+    ).rejects.toThrow(/VALIDATION_FAILED.*'group' tenancy posture/);
+  });
+});

package/src/approver-org-scope.test.ts

@@ -0,0 +1,201 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [ADR-0105 D9] Cross-organization approver targeting.
+ *
+ * The property that matters is that this is a route WITHIN one group, not a
+ * channel to an arbitrary tenant — so every test here is about a boundary
+ * holding or a failure being LOUD. The thing D9 exists to prevent is silence:
+ * an approval that reads as "escalate to group" but quietly resolves inside the
+ * plant, or one that routes to someone the D2 wall then hides the request from.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  filterApproversWhoCanRead,
+  resolveApproverDirectoryOrg,
+  type ApproverOrgScopeDeps,
+} from './approver-org-scope.js';
+
+/**
+ * A three-tier group: group → division → plant, plus a shared-services SIBLING
+ * of the plant, plus an organization in a DIFFERENT group entirely.
+ */
+const ORGS: Record<string, { id: string; slug: string; parent_organization_id: string | null }> = {
+  o_group: { id: 'o_group', slug: 'acme-group', parent_organization_id: null },
+  o_div: { id: 'o_div', slug: 'acme-north', parent_organization_id: 'o_group' },
+  o_plant: { id: 'o_plant', slug: 'acme-plant-a', parent_organization_id: 'o_div' },
+  o_ssc: { id: 'o_ssc', slug: 'acme-ssc', parent_organization_id: 'o_group' },
+  o_other: { id: 'o_other', slug: 'rival-co', parent_organization_id: null },
+  o_lone: { id: 'o_lone', slug: 'lone-co', parent_organization_id: null },
+};
+
+function makeDeps(over: Partial<ApproverOrgScopeDeps> & { members?: Array<{ user_id: string; organization_id: string }> } = {}): ApproverOrgScopeDeps & { warn: any } {
+  const warn = vi.fn();
+  const members = over.members ?? [];
+  const engine = {
+    find: vi.fn(async (object: string, opts: any) => {
+      const f = opts?.filter ?? {};
+      if (object === 'sys_organization') {
+        const rows = Object.values(ORGS).filter((o) =>
+          (f.id === undefined || o.id === f.id) && (f.slug === undefined || o.slug === f.slug));
+        return rows;
+      }
+      if (object === 'sys_member') {
+        const wanted: string[] = f.user_id?.$in ?? [];
+        return members.filter((m) => m.organization_id === f.organization_id && wanted.includes(m.user_id));
+      }
+      return [];
+    }),
+  };
+  return { engine, logger: { warn }, posture: () => 'group', ...over, warn } as any;
+}
+
+const resolve = (
+  deps: ApproverOrgScopeDeps,
+  declaration: string | undefined,
+  requestOrg: string | null,
+  type = 'position',
+  orgScoped = true,
+) => resolveApproverDirectoryOrg(deps, declaration, requestOrg, type, orgScoped);
+
+describe('resolveApproverDirectoryOrg — the default path is untouched', () => {
+  it('returns the request org and reads NOTHING when no organization is declared', async () => {
+    const deps = makeDeps();
+    await expect(resolve(deps, undefined, 'o_plant')).resolves.toBe('o_plant');
+    // The overwhelmingly common case must not cost a query.
+    expect((deps.engine.find as any)).not.toHaveBeenCalled();
+  });
+
+  it('passes a null request org straight through — a single-org deployment is unaffected', async () => {
+    const deps = makeDeps();
+    await expect(resolve(deps, undefined, null)).resolves.toBeNull();
+  });
+});
+
+describe('resolveApproverDirectoryOrg — symbols resolve against the D6 tree', () => {
+  it('$root climbs to the group organization, not just one level', async () => {
+    // o_plant → o_div → o_group. A one-level implementation would answer o_div.
+    await expect(resolve(makeDeps(), '$root', 'o_plant')).resolves.toBe('o_group');
+  });
+
+  it('$parent stops at exactly one level — division sign-off in a three-tier group', async () => {
+    await expect(resolve(makeDeps(), '$parent', 'o_plant')).resolves.toBe('o_div');
+  });
+
+  it('$root on an organization with no lineage FAILS instead of silently self-targeting', async () => {
+    // Returning o_lone would make "escalate to group" mean "approve in place" —
+    // the exact silent misrouting D9 exists to prevent.
+    await expect(resolve(makeDeps(), '$root', 'o_lone')).rejects.toThrow(
+      /VALIDATION_FAILED.*no 'parent_organization_id' lineage/,
+    );
+  });
+
+  it('$parent at the root of a group fails rather than resolving to nothing', async () => {
+    await expect(resolve(makeDeps(), '$parent', 'o_group')).rejects.toThrow(/VALIDATION_FAILED.*no parent/);
+  });
+});
+
+describe('resolveApproverDirectoryOrg — a slug names one organization, bounded by the group', () => {
+  it('accepts a SIBLING in the same group — the shared-services-centre shape', async () => {
+    // o_ssc is not an ancestor of o_plant; it shares the root. This is why the
+    // rule is "shares a root", not "is an ancestor".
+    await expect(resolve(makeDeps(), 'acme-ssc', 'o_plant')).resolves.toBe('o_ssc');
+  });
+
+  it('refuses an organization in a DIFFERENT group — this is not a channel to any tenant', async () => {
+    await expect(resolve(makeDeps(), 'rival-co', 'o_plant')).rejects.toThrow(
+      /VALIDATION_FAILED.*not in the same group/,
+    );
+  });
+
+  it('refuses an unknown slug and says an id is not accepted', async () => {
+    // The most likely authoring mistake is pasting an organization id, which is
+    // per-deployment and would make the flow unportable.
+    await expect(resolve(makeDeps(), 'o_plant', 'o_plant')).rejects.toThrow(
+      /VALIDATION_FAILED.*never an id/,
+    );
+  });
+});
+
+describe('resolveApproverDirectoryOrg — the guards', () => {
+  it('refuses under a non-group posture instead of silently ignoring the declaration', async () => {
+    // A deployment migrating group → isolated must not quietly reroute its
+    // approvals; that is an audit event, not a config detail.
+    const deps = makeDeps({ posture: () => 'isolated' });
+    await expect(resolve(deps, '$root', 'o_plant')).rejects.toThrow(
+      /VALIDATION_FAILED.*requires the 'group' tenancy posture.*isolated/,
+    );
+  });
+
+  it('stands down when the posture is unknown — a minimal stack is not broken by a guard it cannot answer', async () => {
+    const deps = makeDeps({ posture: () => undefined });
+    await expect(resolve(deps, '$root', 'o_plant')).resolves.toBe('o_group');
+  });
+
+  it('refuses the declaration on an approver type that has no organization directory', async () => {
+    // `user` names a person outright; an `organization` on it would have no
+    // effect. An author who wrote it believed it did something.
+    await expect(resolve(makeDeps(), '$root', 'o_plant', 'user', false)).rejects.toThrow(
+      /VALIDATION_FAILED.*would have no effect/,
+    );
+  });
+
+  it('refuses when the request carries no organization at all', async () => {
+    await expect(resolve(makeDeps(), '$root', null)).rejects.toThrow(
+      /VALIDATION_FAILED.*carries no organization/,
+    );
+  });
+
+  it('survives a cycle in the grouping metadata instead of looping forever', async () => {
+    const deps = makeDeps();
+    (deps.engine.find as any) = vi.fn(async (object: string, opts: any) => {
+      if (object !== 'sys_organization') return [];
+      const id = opts?.filter?.id;
+      // a → b → a
+      if (id === 'a') return [{ id: 'a', slug: 'a', parent_organization_id: 'b' }];
+      if (id === 'b') return [{ id: 'b', slug: 'b', parent_organization_id: 'a' }];
+      return [];
+    });
+    // Terminates; the cycle is broken and whatever it settles on is bounded.
+    await expect(resolve(deps, '$parent', 'a')).resolves.toBe('b');
+  });
+});
+
+describe('filterApproversWhoCanRead — routing to someone the wall hides is a silent failure', () => {
+  it('keeps approvers who hold a membership in the REQUEST org', async () => {
+    const deps = makeDeps({ members: [{ user_id: 'u_cfo', organization_id: 'o_plant' }] });
+    const kept = await filterApproversWhoCanRead(deps, ['u_cfo'], 'o_plant', {
+      approverType: 'position', value: 'cfo', directoryOrgId: 'o_group',
+    });
+    expect(kept).toEqual(['u_cfo']);
+    expect(deps.warn).not.toHaveBeenCalled();
+  });
+
+  it('drops an approver with no membership there, and says exactly why', async () => {
+    // She holds `cfo` in the group org but no membership in the plant, so D2's
+    // union would hide the request from her: routing succeeds, then she opens a
+    // task she cannot open. Convert that into the empty-slate path the node
+    // already has a policy for.
+    const deps = makeDeps({ members: [{ user_id: 'u_ok', organization_id: 'o_plant' }] });
+    const kept = await filterApproversWhoCanRead(deps, ['u_ok', 'u_no_membership'], 'o_plant', {
+      approverType: 'position', value: 'cfo', directoryOrgId: 'o_group',
+    });
+    expect(kept).toEqual(['u_ok']);
+    expect(deps.warn).toHaveBeenCalledTimes(1);
+    const msg = String(deps.warn.mock.calls[0][0]);
+    expect(msg).toMatch(/u_no_membership|cross-organization approver/);
+    expect(msg).toMatch(/Grant those users a membership|retarget/);
+  });
+
+  it('does NOT empty a live slate when membership is unreadable', async () => {
+    // An infrastructure hiccup must not silently unstaff a pending approval:
+    // routing to someone who may not see it is recoverable, emptying is not.
+    const deps = makeDeps();
+    (deps.engine.find as any) = vi.fn(async () => { throw new Error('driver hiccup'); });
+    const kept = await filterApproversWhoCanRead(deps, ['u1', 'u2'], 'o_plant', {
+      approverType: 'position', directoryOrgId: 'o_group',
+    });
+    expect(kept).toEqual(['u1', 'u2']);
+  });
+});