@objectstack/plugin-approvals 12.6.0 → 14.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/plugin-approvals",
-  "version": "12.6.0",
+  "version": "14.3.0",
   "license": "Apache-2.0",
   "description": "Multi-step approval engine for ObjectStack — sys_approval_process + sys_approval_request + sys_approval_action + IApprovalService.",
   "main": "dist/index.js",
@@ -13,17 +13,17 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "12.6.0",
-    "@objectstack/formula": "12.6.0",
-    "@objectstack/metadata-core": "12.6.0",
-    "@objectstack/platform-objects": "12.6.0",
-    "@objectstack/spec": "12.6.0"
+    "@objectstack/core": "14.3.0",
+    "@objectstack/formula": "14.3.0",
+    "@objectstack/metadata-core": "14.3.0",
+    "@objectstack/platform-objects": "14.3.0",
+    "@objectstack/spec": "14.3.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@objectstack/service-automation": "12.6.0"
+    "@objectstack/service-automation": "14.3.0"
   },
   "keywords": [
     "objectstack",

package/src/approval-node.test.ts

@@ -5,7 +5,7 @@ import { AutomationEngine } from '@objectstack/service-automation';
 import { ApprovalService } from './approval-service.js';
 import { registerApprovalNode } from './approval-node.js';
 
-const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as any;
+const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as any;
 
 const noopLogger = {
   info() {}, warn() {}, error() {}, debug() {},
@@ -190,7 +190,7 @@ describe('Approval node bridge (ADR-0019)', () => {
     const request = (await fake.find('sys_approval_request', { where: { status: 'pending' } }))[0];
 
     await expect(
-      service.decideNode(request.id, { decision: 'approve', actorId: 'intruder' }, { isSystem: false, roles: [], permissions: [] } as any),
+      service.decideNode(request.id, { decision: 'approve', actorId: 'intruder' }, { isSystem: false, positions: [], permissions: [] } as any),
     ).rejects.toThrow(/FORBIDDEN/);
   });
 });

package/src/approval-node.ts

@@ -48,7 +48,7 @@ interface MinimalLogger {
   warn?: (msg: any, ...rest: any[]) => void;
 }
 
-const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as const;
+const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;
 
 /**
  * Register the `approval` node executor on the automation engine. Idempotent at

package/src/approval-revise.test.ts

@@ -19,8 +19,8 @@ import { ApprovalService } from './approval-service.js';
 import { registerApprovalNode } from './approval-node.js';
 import { bindApprovalLockHook, APPROVALS_HOOK_PACKAGE } from './lifecycle-hooks.js';
 
-const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as any;
-const USER_CTX = { isSystem: false, roles: [], permissions: [] } as any;
+const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as any;
+const USER_CTX = { isSystem: false, positions: [], permissions: [] } as any;
 
 const noopLogger = { info() {}, warn() {}, error() {}, debug() {} };
 
@@ -288,7 +288,7 @@ describe('Send back for revision (ADR-0044)', () => {
     const editAttempt = () => hook!({
       object: 'fin_expense',
       input: { id: 'x1', data: { amount: 1200 } },
-      session: { isSystem: false, roles: [] },
+      session: { isSystem: false, positions: [] },
     });
 
     await expect(editAttempt()).rejects.toThrow(/RECORD_LOCKED/);          // pending → locked

package/src/approval-service.test.ts

@@ -110,8 +110,8 @@ function makeFakeEngine() {
   };
 }
 
-const CTX = { userId: 'u1', tenantId: 't1', roles: [], permissions: [] } as any;
-const SYS = { isSystem: true, roles: [], permissions: [] } as any;
+const CTX = { userId: 'u1', tenantId: 't1', positions: [], permissions: [] } as any;
+const SYS = { isSystem: true, positions: [], permissions: [] } as any;
 
 function nodeConfig(approvers: string[], extra: Record<string, any> = {}) {
   return {
@@ -187,6 +187,65 @@ describe('ApprovalService (node era)', () => {
     expect(engine._tables['opportunity'][0].approval_status).toBe('pending');
   });
 
+  // ── approver expansion: position (ADR-0090 D3) ──────────────────
+
+  const positionInput = (extra: Record<string, any> = {}) => ({
+    ...openInput([]),
+    config: {
+      approvers: [{ type: 'position' as const, value: 'sales_manager' }],
+      behavior: 'first_response' as const,
+      lockRecord: true,
+    },
+    ...extra,
+  });
+
+  it('position approver: expands via sys_user_position, org-scoped', async () => {
+    engine._tables['sys_user_position'] = [
+      { id: 'up1', user_id: 'u5', position: 'sales_manager', organization_id: 't1' },
+      { id: 'up2', user_id: 'u6', position: 'sales_manager', organization_id: 't1' },
+      { id: 'up3', user_id: 'u7', position: 'sales_manager', organization_id: 't2' }, // other tenant
+      { id: 'up4', user_id: 'u8', position: 'cfo', organization_id: 't1' },           // other position
+    ];
+    const req = await svc.openNodeRequest(positionInput(), CTX);
+    expect(req.pending_approvers.sort()).toEqual(['u5', 'u6']);
+  });
+
+  it('position approver: unions the sys_member.role transition source (ADR-0057 D4)', async () => {
+    engine._tables['sys_user_position'] = [
+      { id: 'up1', user_id: 'u5', position: 'sales_manager', organization_id: 't1' },
+    ];
+    engine._tables['sys_member'] = [
+      { id: 'm1', user_id: 'u6', role: 'sales_manager', organization_id: 't1' },
+      { id: 'm2', user_id: 'u5', role: 'sales_manager', organization_id: 't1' }, // deduped
+    ];
+    const req = await svc.openNodeRequest(positionInput(), CTX);
+    expect(req.pending_approvers.sort()).toEqual(['u5', 'u6']);
+  });
+
+  it('position approver: falls back to a position: literal when nobody holds it', async () => {
+    const req = await svc.openNodeRequest(positionInput(), CTX);
+    expect(req.pending_approvers).toEqual(['position:sales_manager']);
+  });
+
+  it("department approver: honors the spec enum value 'department' (not just the business_unit dialect)", async () => {
+    engine._tables['sys_business_unit'] = [
+      { id: 'bu1', organization_id: 't1', active: true },
+      { id: 'bu2', parent_business_unit_id: 'bu1', organization_id: 't1', active: true },
+    ];
+    engine._tables['sys_business_unit_member'] = [
+      { id: 'bm1', business_unit_id: 'bu1', user_id: 'u5' },
+      { id: 'bm2', business_unit_id: 'bu2', user_id: 'u6' },
+    ];
+    const req = await svc.openNodeRequest(positionInput({
+      config: {
+        approvers: [{ type: 'department' as const, value: 'bu1' }],
+        behavior: 'first_response' as const,
+        lockRecord: true,
+      },
+    }), CTX);
+    expect(req.pending_approvers.sort()).toEqual(['u5', 'u6']);
+  });
+
   // ── decideNode ──────────────────────────────────────────────────
 
   it('decideNode: first_response approve finalizes immediately', async () => {
@@ -219,7 +278,7 @@ describe('ApprovalService (node era)', () => {
   it('decideNode: blocks a non-approver in a non-system context', async () => {
     const req = await svc.openNodeRequest(openInput(['u9']), CTX);
     await expect(
-      svc.decideNode(req.id, { decision: 'approve', actorId: 'mallory' }, { isSystem: false, roles: [], permissions: [] } as any),
+      svc.decideNode(req.id, { decision: 'approve', actorId: 'mallory' }, { isSystem: false, positions: [], permissions: [] } as any),
     ).rejects.toThrow(/FORBIDDEN/);
   });
 
@@ -319,7 +378,7 @@ describe('ApprovalService (node era)', () => {
 
   it('recall: blocks a non-submitter in a non-system context', async () => {
     const req = await svc.openNodeRequest(openInput(['u9']), CTX);
-    await expect(svc.recall(req.id, { actorId: 'u9' }, { roles: [], permissions: [] } as any))
+    await expect(svc.recall(req.id, { actorId: 'u9' }, { positions: [], permissions: [] } as any))
       .rejects.toThrow(/FORBIDDEN/);
   });
 
@@ -483,7 +542,7 @@ describe('ApprovalService (node era)', () => {
 
   it('remind: only the submitter may nudge', async () => {
     const req = await svc.openNodeRequest(openInput(['u9']), CTX);
-    await expect(svc.remind(req.id, { actorId: 'u9' }, { roles: [], permissions: [] } as any))
+    await expect(svc.remind(req.id, { actorId: 'u9' }, { positions: [], permissions: [] } as any))
       .rejects.toThrow(/FORBIDDEN/);
   });
 
@@ -503,7 +562,7 @@ describe('ApprovalService (node era)', () => {
     const req = await svc.openNodeRequest(openInput(['u9']), CTX);
     await svc.comment(req.id, { actorId: 'u1', comment: 'Numbers attached.' }, CTX);
     await svc.comment(req.id, { actorId: 'u9', comment: 'Thanks, reviewing.' }, CTX);
-    await expect(svc.comment(req.id, { actorId: 'outsider', comment: 'hi' }, { roles: [], permissions: [] } as any))
+    await expect(svc.comment(req.id, { actorId: 'outsider', comment: 'hi' }, { positions: [], permissions: [] } as any))
       .rejects.toThrow(/FORBIDDEN/);
     const actions = await svc.listActions(req.id, SYS);
     expect(actions.filter(a => a.action === 'comment')).toHaveLength(2);
@@ -804,6 +863,40 @@ describe('ApprovalService (node era)', () => {
     expect(fresh?.pending_approvers).toEqual(['boss']);
   });
 
+  it('runEscalations: reassign expands a position escalateTo to its holders (ADR-0090 D3)', async () => {
+    engine._tables['sys_user_position'] = [
+      { id: 'up1', user_id: 'u5', position: 'approvals_supervisor', organization_id: 't1' },
+      { id: 'up2', user_id: 'u6', position: 'approvals_supervisor', organization_id: 't1' },
+      { id: 'up3', user_id: 'u7', position: 'approvals_supervisor', organization_id: 't2' }, // other tenant
+    ];
+    const req = await svc.openNodeRequest(
+      openInput(['u9'], {}, { escalation: { timeoutHours: 1, action: 'reassign', escalateTo: 'approvals_supervisor', notifySubmitter: false } }), CTX,
+    );
+    makeOverdue(req.id);
+    await svc.runEscalations();
+    const fresh = await svc.getRequest(req.id, SYS);
+    expect(fresh?.status).toBe('pending');
+    expect(fresh?.pending_approvers?.slice().sort()).toEqual(['u5', 'u6']);
+    // The audit trail keeps the AUTHORED target, not the expansion.
+    const actions = await svc.listActions(req.id, SYS);
+    expect(actions.find(a => a.action === 'escalate')?.comment).toBe('reassign → approvals_supervisor');
+  });
+
+  it('runEscalations: notify expands a position escalateTo into the audience', async () => {
+    engine._tables['sys_user_position'] = [
+      { id: 'up1', user_id: 'u5', position: 'approvals_supervisor', organization_id: 't1' },
+    ];
+    const emitted: any[] = [];
+    svc.attachMessaging({ async emit(input) { emitted.push(input); } });
+    const req = await svc.openNodeRequest(
+      openInput(['u9'], {}, { escalation: { timeoutHours: 2, action: 'notify', escalateTo: 'approvals_supervisor', notifySubmitter: false } }), CTX,
+    );
+    makeOverdue(req.id);
+    await svc.runEscalations();
+    expect(emitted).toHaveLength(1);
+    expect(emitted[0].audience).toEqual(['u9', 'u5']);
+  });
+
   it('runEscalations: skips requests that are not yet due or have no SLA', async () => {
     await svc.openNodeRequest(
       openInput(['u9'], {}, { escalation: { timeoutHours: 1000, action: 'auto_approve' } }), CTX,
@@ -882,7 +975,7 @@ describe('record-lock hook (node era)', () => {
       engine.fire('beforeUpdate', {
         object: 'opportunity',
         input: { id: 'opp1', data: { amount: 200 } },
-        session: { isSystem: false, roles: [], userId: 'u1' },
+        session: { isSystem: false, positions: [], userId: 'u1' },
       }),
     ).rejects.toThrow(/RECORD_LOCKED/);
   });
@@ -892,7 +985,7 @@ describe('record-lock hook (node era)', () => {
       engine.fire('beforeUpdate', {
         object: 'opportunity',
         input: { id: 'opp1', data: { approval_status: 'approved' } },
-        session: { isSystem: false, roles: [] },
+        session: { isSystem: false, positions: [] },
       }),
     ).resolves.toBeUndefined();
   });
@@ -902,7 +995,7 @@ describe('record-lock hook (node era)', () => {
       engine.fire('beforeUpdate', {
         object: 'opportunity',
         input: { id: 'opp1', data: { amount: 200 } },
-        session: { isSystem: true, roles: [] },
+        session: { isSystem: true, positions: [] },
       }),
     ).resolves.toBeUndefined();
   });
@@ -922,7 +1015,7 @@ describe('record-lock hook (node era)', () => {
       engine.fire('beforeUpdate', {
         object: 'opportunity',
         input: { id: 'other_record', data: { amount: 200 } },
-        session: { isSystem: false, roles: [] },
+        session: { isSystem: false, positions: [] },
       }),
     ).resolves.toBeUndefined();
   });

package/src/approval-service.ts

@@ -31,8 +31,8 @@ import type {
  * `approve` / `reject` edge.
  *
  * This service owns the durable approval *state* — `sys_approval_request` /
- * `sys_approval_action`, approver resolution (team / department / role /
- * manager graph), and the optional status-field mirror — plus the decision
+ * `sys_approval_action`, approver resolution (team / department / position /
+ * role / manager graph), and the optional status-field mirror — plus the decision
  * API. It does not author processes, submit, or walk multi-step machinery
  * anymore; that orchestration lives on the one automation engine.
  */
@@ -97,7 +97,7 @@ export type ActionTokenOutcome =
   | { ok: true; action: 'approve' | 'reject'; request: ApprovalRequestRow; approverId: string }
   | { ok: false; reason: 'invalid' | 'expired' | 'consumed' | 'not_pending' | 'not_approver'; request?: ApprovalRequestRow };
 
-const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as const;
+const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;
 
 function uid(prefix: string): string {
   const g: any = globalThis as any;
@@ -274,16 +274,20 @@ export class ApprovalService implements IApprovalService {
 
   /**
    * Expand the approvers on an Approval node into user IDs by querying the
-   * graph tables for `team:` / `department:` / `role:` / `manager:` approver
-   * types. Falls back to a prefixed literal (`type:value`) when graph lookups
-   * produce nothing — so existing fixtures and flows that rely on substring
-   * matching keep working.
+   * graph tables for `team:` / `department:` / `position:` / `role:` /
+   * `manager:` approver types. Falls back to a prefixed literal
+   * (`type:value`) when graph lookups produce nothing — so existing fixtures
+   * and flows that rely on substring matching keep working.
    *
    * **Graph semantics:**
    *   - `team`       → flat members of `sys_team` (better-auth; no BFS)
    *   - `department` → recursive BFS of `sys_business_unit.parent_business_unit_id`
    *                    → members of every descendant via `sys_business_unit_member`
-   *   - `role`       → users with `sys_member.role = value` in tenant
+   *   - `position`   → holders via `sys_user_position` ∪ `sys_member.role`
+   *                    transition source (ADR-0090 D3 / ADR-0057 D4)
+   *   - `role`       → users with `sys_member.role = value` in tenant — the
+   *                    better-auth MEMBERSHIP TIER (owner/admin/member), not a
+   *                    position; author `position` for org positions
    *   - `manager`    → `sys_user.manager_id` of `record[value] ?? record.owner_id`
    *   - `field`      → literal user id stored in `record[value]`
    *   - `user`       → literal value
@@ -299,9 +303,12 @@ export class ApprovalService implements IApprovalService {
         if (a.type === 'team') {
           const users = await this.expandTeamUsers(String(a.value));
           if (users.length) { for (const u of users) out.push(u); continue; }
-        } else if (a.type === 'business_unit' || a.type === 'bu') {
+        } else if (a.type === 'department' || a.type === 'business_unit' || a.type === 'bu') {
           const users = await this.expandBusinessUnitUsers(String(a.value), organizationId);
           if (users.length) { for (const u of users) out.push(u); continue; }
+        } else if (a.type === 'position') {
+          const users = await this.expandPositionUsers(String(a.value), organizationId);
+          if (users.length) { for (const u of users) out.push(u); continue; }
         } else if (a.type === 'role') {
           const users = await this.expandRoleUsers(String(a.value), organizationId);
           if (users.length) { for (const u of users) out.push(u); continue; }
@@ -377,6 +384,33 @@ export class ApprovalService implements IApprovalService {
     return Array.from(new Set((rows ?? []).map((r: any) => String(r.user_id ?? '')).filter(Boolean)));
   }
 
+  /**
+   * Position holders (ADR-0090 D3): `sys_user_position` is the platform-owned
+   * assignment table, keyed by the position's machine name (ADR-0057 D4),
+   * unioned with the better-auth membership string (`sys_member.role`) as a
+   * transition source — the same semantics as `PositionGraphService` in
+   * `plugin-sharing`, so an approval routes to exactly the users the sharing
+   * engine would expand for the same position.
+   */
+  private async expandPositionUsers(positionName: string, organizationId?: string | null): Promise<string[]> {
+    if (!positionName) return [];
+    const users = new Set<string>();
+    const filter: any = { position: positionName };
+    if (organizationId) filter.organization_id = organizationId;
+    try {
+      const rows = await this.engine.find('sys_user_position', {
+        filter, fields: ['user_id'], limit: 10000, context: SYSTEM_CTX,
+      } as any);
+      for (const r of (rows ?? []) as any[]) {
+        const uid = String(r.user_id ?? '');
+        if (uid) users.add(uid);
+      }
+    } catch { /* table may not exist on minimal stacks — union source below still applies */ }
+    for (const uid of await this.expandRoleUsers(positionName, organizationId)) users.add(uid);
+    return Array.from(users);
+  }
+
+  /** better-auth org-membership tier (`sys_member.role`) — NOT positions. */
   private async expandRoleUsers(roleName: string, organizationId?: string | null): Promise<string[]> {
     if (!roleName) return [];
     const filter: any = { role: roleName };
@@ -1347,6 +1381,18 @@ export class ApprovalService implements IApprovalService {
     const now = this.clock.now().toISOString();
     const pending = csvSplit(raw.pending_approvers);
 
+    // `escalateTo` is a position machine name or a user id (same contract as
+    // the `position` ApproverType, ADR-0090 D3). Position holders win; an
+    // empty expansion falls back to the literal, so a config naming a
+    // specific user id keeps working unchanged.
+    let escalatees: string[] = [];
+    if (escalateTo) {
+      try {
+        escalatees = await this.expandPositionUsers(escalateTo, raw.organization_id ?? null);
+      } catch { escalatees = []; }
+      if (!escalatees.length) escalatees = [escalateTo];
+    }
+
     // Audit first — this row IS the idempotency marker (ADR-0042 §1).
     await this.engine.insert('sys_approval_action', {
       id: uid('aact'), request_id: raw.id, organization_id: raw.organization_id ?? null,
@@ -1356,14 +1402,14 @@ export class ApprovalService implements IApprovalService {
       created_at: now,
     }, { context: SYSTEM_CTX });
 
-    if (action === 'reassign' && escalateTo) {
+    if (action === 'reassign' && escalatees.length) {
       await this.engine.update('sys_approval_request', {
-        id: raw.id, pending_approvers: escalateTo, updated_at: now,
+        id: raw.id, pending_approvers: escalatees.join(','), updated_at: now,
       }, { context: SYSTEM_CTX });
-      await this.syncApproverIndex(raw.id, [escalateTo], raw.organization_id ?? null, now);
+      await this.syncApproverIndex(raw.id, escalatees, raw.organization_id ?? null, now);
       await this.notify({
         topic: 'approval.escalated',
-        audience: [escalateTo],
+        audience: escalatees,
         actorId: SLA_ACTOR_ID,
         source: { object: 'sys_approval_request', id: raw.id },
         payload: {
@@ -1382,7 +1428,7 @@ export class ApprovalService implements IApprovalService {
       // 'notify' (and the reassign-without-target fallback)
       await this.notify({
         topic: 'approval.sla_breached',
-        audience: [...pending, ...(escalateTo ? [escalateTo] : [])],
+        audience: [...pending, ...escalatees],
         actorId: SLA_ACTOR_ID,
         source: { object: 'sys_approval_request', id: raw.id },
         payload: {