@objectstack/plugin-approvals 9.2.0 → 9.4.0

package/src/approval-service.test.ts

@@ -10,7 +10,7 @@
  */
 
 import { describe, it, expect, beforeEach } from 'vitest';
-import { ApprovalService } from './approval-service.js';
+import { ApprovalService, REMIND_COOLDOWN_MS } from './approval-service.js';
 import { bindApprovalLockHook, unbindAllHooks } from './lifecycle-hooks.js';
 
 interface FakeRow { [k: string]: any }
@@ -23,6 +23,10 @@ function makeFakeEngine() {
   function matches(row: FakeRow, 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;
@@ -32,6 +36,10 @@ function makeFakeEngine() {
         if (rv === (v as any).$ne) return false;
         continue;
       }
+      if (v != null && typeof v === 'object' && '$contains' in (v as any)) {
+        if (!String(rv ?? '').includes(String((v as any).$contains))) return false;
+        continue;
+      }
       if (rv !== v) return false;
     }
     return true;
@@ -43,15 +51,20 @@ function makeFakeEngine() {
     async find(object: string, options?: any) {
       const rows = ensure(object).filter(r => matches(r, options?.filter ?? options?.where));
       if (options?.orderBy?.[0]) {
-        const { field, direction } = options.orderBy[0];
+        // Canonical SortNode key only (spec/data/query.zod.ts): a sloppy
+        // `direction:` key must fall through to the schema default (asc),
+        // exactly like the real engine — that's how the remind() cool-down
+        // regression stayed invisible when this mock honored both keys.
+        const { field, order } = options.orderBy[0];
         rows.sort((a, b) => {
           const av = a[field]; const bv = b[field];
           if (av === bv) return 0;
           const cmp = av > bv ? 1 : -1;
-          return direction === 'desc' ? -cmp : cmp;
+          return order === 'desc' ? -cmp : cmp;
         });
       }
-      return rows.slice(0, options?.limit ?? 1000);
+      const start = options?.offset ?? 0;
+      return rows.slice(start, start + (options?.limit ?? 1000));
     },
     async insert(object: string, data: any) {
       ensure(object).push({ ...data });
@@ -407,6 +420,441 @@ describe('ApprovalService (node era)', () => {
     expect(actions.map(a => (a as any).actor_name)).toEqual(['Ada Lovelace', 'Grace Hopper']);
   });
 
+  // ── thread interactions ─────────────────────────────────────────
+
+  it('reassign: hands the slot to a new approver and audits the move', async () => {
+    const req = await svc.openNodeRequest(openInput(['u9', 'u2']), CTX);
+    const out = await svc.reassign(req.id, { actorId: 'u9', to: 'u7' }, CTX);
+    expect(out.request.pending_approvers).toEqual(['u7', 'u2']);
+    const actions = await svc.listActions(req.id, SYS);
+    expect(actions.at(-1)).toMatchObject({ action: 'reassign', actor_id: 'u9', comment: 'u9 → u7' });
+  });
+
+  it('reassign: notifies the new approver via messaging', async () => {
+    const emitted: any[] = [];
+    svc.attachMessaging({ async emit(input) { emitted.push(input); } });
+    const req = await svc.openNodeRequest(openInput(['u9']), CTX);
+    await svc.reassign(req.id, { actorId: 'u9', to: 'u7' }, CTX);
+    expect(emitted).toHaveLength(1);
+    expect(emitted[0]).toMatchObject({ topic: 'approval.reassigned', audience: ['u7'] });
+  });
+
+  it('reassign: blocks a non-holder and duplicate targets', async () => {
+    const req = await svc.openNodeRequest(openInput(['u9', 'u2']), CTX);
+    await expect(svc.reassign(req.id, { actorId: 'intruder', to: 'u7' }, CTX)).rejects.toThrow(/FORBIDDEN/);
+    await expect(svc.reassign(req.id, { actorId: 'u9', to: 'u2' }, CTX)).rejects.toThrow(/VALIDATION_FAILED/);
+  });
+
+  it('remind: notifies pending approvers, audits, and throttles repeats', async () => {
+    const emitted: any[] = [];
+    svc.attachMessaging({ async emit(input) { emitted.push(input); } });
+    const req = await svc.openNodeRequest(openInput(['u9', 'u2']), CTX);
+    const out = await svc.remind(req.id, { actorId: 'u1' }, CTX); // u1 = submitter (CTX.userId)
+    expect(out.notified).toBe(2);
+    // ADR-0043: per-approver fan-out so each reminder carries personal links.
+    const reminders = emitted.filter(e => e.topic === 'approval.reminder');
+    expect(reminders.map(r => r.audience)).toEqual([['u9'], ['u2']]);
+    const actions = await svc.listActions(req.id, SYS);
+    expect(actions.at(-1)?.action).toBe('remind');
+    // The fake clock steps 1s per call — well inside the 4h cool-down.
+    await expect(svc.remind(req.id, { actorId: 'u1' }, CTX)).rejects.toThrow(/THROTTLED/);
+  });
+
+  it('remind: cool-down measures from the NEWEST reminder, not the first', async () => {
+    // Regression: the throttle query sorted with the non-canonical
+    // `direction: 'desc'` key, which SortNode strips — so it sorted asc and
+    // compared against the FIRST reminder ever sent. Once 4h passed after
+    // reminder #1, every later remind() sailed through unthrottled.
+    let nowMs = baseTime;
+    const localSvc = new ApprovalService({
+      engine: engine as any,
+      clock: { now: () => new Date(nowMs += 1000) },
+    });
+    const req = await localSvc.openNodeRequest(openInput(['u9']), CTX);
+    await localSvc.remind(req.id, { actorId: 'u1' }, CTX);
+    // Jump past the cool-down: a second reminder is legitimately allowed.
+    nowMs += REMIND_COOLDOWN_MS;
+    await localSvc.remind(req.id, { actorId: 'u1' }, CTX);
+    // Immediately after reminder #2 the throttle must bite again — with the
+    // wrong sort key it compared against reminder #1 (now >4h old) and let
+    // unlimited reminders through.
+    await expect(localSvc.remind(req.id, { actorId: 'u1' }, CTX)).rejects.toThrow(/THROTTLED/);
+  });
+
+  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))
+      .rejects.toThrow(/FORBIDDEN/);
+  });
+
+  it('requestInfo: keeps the request pending and notifies the submitter', async () => {
+    const emitted: any[] = [];
+    svc.attachMessaging({ async emit(input) { emitted.push(input); } });
+    const req = await svc.openNodeRequest(openInput(['u9']), CTX);
+    const out = await svc.requestInfo(req.id, { actorId: 'u9', comment: 'Need the Q3 numbers' }, CTX);
+    expect(out.request.status).toBe('pending');
+    expect(out.request.pending_approvers).toEqual(['u9']);
+    expect(emitted[0]).toMatchObject({ topic: 'approval.request_info', audience: ['u1'] });
+    const actions = await svc.listActions(req.id, SYS);
+    expect(actions.at(-1)).toMatchObject({ action: 'request_info', comment: 'Need the Q3 numbers' });
+  });
+
+  it('comment: submitter and approver may reply; outsiders may not', async () => {
+    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))
+      .rejects.toThrow(/FORBIDDEN/);
+    const actions = await svc.listActions(req.id, SYS);
+    expect(actions.filter(a => a.action === 'comment')).toHaveLength(2);
+  });
+
+  // ── actionable links (ADR-0043) ─────────────────────────────────
+
+  it('issueActionTokens: stores hashes only and binds approver + action', async () => {
+    const req = await svc.openNodeRequest(openInput(['u9']), CTX);
+    const tokens = await svc.issueActionTokens(req.id, 'u9');
+    expect(tokens.approve).not.toBe(tokens.reject);
+    const rows = engine._tables['sys_approval_token'];
+    expect(rows).toHaveLength(2);
+    expect(rows.every(r => r.token_hash.length === 64)).toBe(true); // sha256 hex, never the raw token
+    expect(rows.every(r => !JSON.stringify(r).includes(tokens.approve))).toBe(true);
+    await expect(svc.issueActionTokens(req.id, 'stranger')).rejects.toThrow(/FORBIDDEN/);
+  });
+
+  it('redeem: approves as the bound approver and burns the token (single-use)', async () => {
+    const resumed: any[] = [];
+    svc.attachAutomation({ async resume(runId, signal) { resumed.push({ runId, signal }); } });
+    const req = await svc.openNodeRequest(openInput(['u9']), CTX);
+    const { approve } = await svc.issueActionTokens(req.id, 'u9');
+    const out = await svc.redeemActionToken(approve);
+    expect(out).toMatchObject({ ok: true, action: 'approve', approverId: 'u9' });
+    expect((out as any).request.status).toBe('approved');
+    expect(resumed[0]?.signal?.branchLabel).toBe('approve');
+    const acts = await svc.listActions(req.id, SYS);
+    expect(acts.at(-1)).toMatchObject({ action: 'approve', actor_id: 'u9', comment: 'Via action link' });
+    // replay
+    expect(await svc.redeemActionToken(approve)).toMatchObject({ ok: false, reason: 'consumed' });
+  });
+
+  it('peek: validates without consuming (GET never mutates)', async () => {
+    const req = await svc.openNodeRequest(openInput(['u9']), CTX);
+    const { reject } = await svc.issueActionTokens(req.id, 'u9');
+    expect(await svc.peekActionToken(reject)).toMatchObject({ ok: true, action: 'reject' });
+    expect(await svc.peekActionToken(reject)).toMatchObject({ ok: true }); // still live
+    const fresh = await svc.getRequest(req.id, SYS);
+    expect(fresh?.status).toBe('pending');
+  });
+
+  it('redeem: dead tokens — invalid, expired, decided request, reassigned slot', async () => {
+    const req = await svc.openNodeRequest(openInput(['u9']), CTX);
+    expect(await svc.redeemActionToken('garbage')).toMatchObject({ ok: false, reason: 'invalid' });
+
+    const short = await svc.issueActionTokens(req.id, 'u9', { ttlMs: 1 });
+    // fake clock advances 1s per call — far beyond a 1ms TTL
+    expect(await svc.redeemActionToken(short.approve)).toMatchObject({ ok: false, reason: 'expired' });
+
+    const live = await svc.issueActionTokens(req.id, 'u9');
+    await svc.reassign(req.id, { actorId: 'u9', to: 'u7' }, CTX);
+    expect(await svc.redeemActionToken(live.approve)).toMatchObject({ ok: false, reason: 'not_approver' });
+
+    const forU7 = await svc.issueActionTokens(req.id, 'u7');
+    await svc.decideNode(req.id, { decision: 'approve', actorId: 'u7' }, SYS);
+    expect(await svc.redeemActionToken(forU7.reject)).toMatchObject({ ok: false, reason: 'not_pending' });
+  });
+
+  it('remind: each concrete approver gets their own action links', async () => {
+    const emitted: any[] = [];
+    svc.attachMessaging({ async emit(input) { emitted.push(input); } });
+    const req = await svc.openNodeRequest(openInput(['u9', 'ada@example.com']), CTX);
+    await svc.remind(req.id, { actorId: 'u1' }, CTX);
+    const reminders = emitted.filter(e => e.topic === 'approval.reminder');
+    expect(reminders).toHaveLength(2);
+    for (const r of reminders) {
+      expect(r.audience).toHaveLength(1);
+      expect(r.payload.actions).toHaveLength(2);
+      expect(r.payload.actions[0].url).toContain('/api/v1/approvals/act?token=');
+    }
+    const urls = reminders.flatMap(r => r.payload.actions.map((a: any) => a.url));
+    expect(new Set(urls).size).toBe(4); // every link is personal + per-action
+  });
+
+  // ── pagination + search pushdown (#1745) ────────────────────────
+
+  async function openMany(n: number) {
+    for (let i = 0; i < n; i++) {
+      await svc.openNodeRequest(openInput(['u9'], {
+        recordId: `opp${i}`, record: { id: `opp${i}`, name: `Deal ${i}` },
+      }), CTX);
+    }
+  }
+
+  it('listRequests: windows pushable queries newest-first with limit/offset', async () => {
+    await openMany(5);
+    const page1 = await svc.listRequests({ limit: 2, offset: 0 }, SYS);
+    const page2 = await svc.listRequests({ limit: 2, offset: 2 }, SYS);
+    expect(page1.map(r => r.record_id)).toEqual(['opp4', 'opp3']); // created_at desc
+    expect(page2.map(r => r.record_id)).toEqual(['opp2', 'opp1']);
+  });
+
+  it('listRequests: q matches the payload snapshot (record titles) via pushdown', async () => {
+    await openMany(3);
+    const hit = await svc.listRequests({ q: 'Deal 1', limit: 10 }, SYS);
+    expect(hit.map(r => r.record_id)).toEqual(['opp1']);
+    const miss = await svc.listRequests({ q: 'no-such-thing', limit: 10 }, SYS);
+    expect(miss).toHaveLength(0);
+  });
+
+  it('countRequests: returns the unwindowed total for a filter', async () => {
+    await openMany(4);
+    expect(await svc.countRequests({ status: 'pending' }, SYS)).toBe(4);
+    expect(await svc.countRequests({ q: 'Deal 2' }, SYS)).toBe(1);
+  });
+
+  it('listRequests: approver queries resolve via the index and window engine-side', async () => {
+    await openMany(4); // approver u9 on all
+    await svc.openNodeRequest(openInput(['someone-else'], {
+      recordId: 'oppX', record: { id: 'oppX', name: 'Other' },
+    }), CTX);
+    const page = await svc.listRequests({ approverId: 'u9', limit: 2, offset: 2 }, SYS);
+    expect(page).toHaveLength(2);
+    expect(page.every(r => r.pending_approvers?.includes('u9'))).toBe(true);
+    expect(await svc.countRequests({ approverId: 'u9' }, SYS)).toBe(4);
+  });
+
+  it('listRequests/countRequests: status arrays push down as $in', async () => {
+    await openMany(3);
+    const all = await svc.listRequests({ status: 'pending' }, SYS);
+    await svc.decideNode(all[0].id, { decision: 'approve', actorId: 'u9' }, SYS);
+    await svc.decideNode(all[1].id, { decision: 'reject', actorId: 'u9' }, SYS);
+    const done = await svc.listRequests({ status: ['approved', 'rejected'] }, SYS);
+    expect(done.map(r => r.status).sort()).toEqual(['approved', 'rejected']);
+    expect(await svc.countRequests({ status: ['approved', 'rejected'] }, SYS)).toBe(2);
+    expect(await svc.countRequests({ status: ['recalled'] }, SYS)).toBe(0);
+  });
+
+  // ── pending-approver index (#1745 join table) ───────────────────
+
+  const indexRows = () => (engine._tables['sys_approval_approver'] ?? [])
+    .map(r => ({ request_id: r.request_id, approver: r.approver }));
+
+  it('openNodeRequest mirrors every approver identity into the index', async () => {
+    const req = await svc.openNodeRequest(openInput(['u9', 'ada@example.com', 'role:finance']), CTX);
+    expect(indexRows()).toEqual([
+      { request_id: req.id, approver: 'u9' },
+      { request_id: req.id, approver: 'ada@example.com' },
+      { request_id: req.id, approver: 'role:finance' },
+    ]);
+  });
+
+  it('decide and recall clear the request\'s index rows', async () => {
+    const a = await svc.openNodeRequest(openInput(['u9']), CTX);
+    await svc.decideNode(a.id, { decision: 'approve', actorId: 'u9' }, SYS);
+    expect(indexRows()).toHaveLength(0);
+
+    const b = await svc.openNodeRequest(openInput(['u9'], { recordId: 'opp2', record: { id: 'opp2' } }), CTX);
+    await svc.recall(b.id, { actorId: 'u1' }, CTX);
+    expect(indexRows()).toHaveLength(0);
+  });
+
+  it('unanimous partial approval shrinks the index to the still-pending set', async () => {
+    const req = await svc.openNodeRequest(openInput(['u1', 'u2'], {}, { behavior: 'unanimous' }), CTX);
+    await svc.decideNode(req.id, { decision: 'approve', actorId: 'u1' }, SYS);
+    expect(indexRows()).toEqual([{ request_id: req.id, approver: 'u2' }]);
+  });
+
+  it('reassign and SLA-reassign rewrite the index rows', async () => {
+    const req = await svc.openNodeRequest(
+      openInput(['u9', 'u2'], {}, { escalation: { timeoutHours: 1, action: 'reassign', escalateTo: 'boss', notifySubmitter: false } }), CTX,
+    );
+    await svc.reassign(req.id, { actorId: 'u9', to: 'u7' }, SYS);
+    expect(indexRows().map(r => r.approver).sort()).toEqual(['u2', 'u7']);
+
+    makeOverdue(req.id);
+    await svc.runEscalations();
+    expect(indexRows()).toEqual([{ request_id: req.id, approver: 'boss' }]);
+  });
+
+  it('approver-filtered pages stay correct past the old 500-row scan window', async () => {
+    // 30 u9 requests are the OLDEST rows, buried under 510 newer non-matching
+    // ones — the pre-#1745 bounded scan (limit 500, newest-first) could never
+    // reach them. Seeded directly: 540 openNodeRequest round-trips are noise.
+    const reqs = (engine._tables['sys_approval_request'] ??= []);
+    const idx = (engine._tables['sys_approval_approver'] ??= []);
+    const ts = (i: number) => new Date(baseTime + i * 1000).toISOString();
+    for (let i = 0; i < 30; i++) {
+      reqs.push({
+        id: `match_${i}`, process_name: 'flow:f', object_name: 'o', record_id: `m${i}`,
+        status: 'pending', pending_approvers: 'u9', created_at: ts(i), updated_at: ts(i),
+      });
+      idx.push({ id: `aapr_m${i}`, request_id: `match_${i}`, approver: 'u9', organization_id: null, created_at: ts(i) });
+    }
+    for (let i = 0; i < 510; i++) {
+      reqs.push({
+        id: `noise_${i}`, process_name: 'flow:f', object_name: 'o', record_id: `n${i}`,
+        status: 'pending', pending_approvers: 'someone-else', created_at: ts(100 + i), updated_at: ts(100 + i),
+      });
+      idx.push({ id: `aapr_n${i}`, request_id: `noise_${i}`, approver: 'someone-else', organization_id: null, created_at: ts(100 + i) });
+    }
+
+    expect(await svc.countRequests({ approverId: 'u9' }, SYS)).toBe(30);
+    const page = await svc.listRequests({ approverId: 'u9', limit: 10, offset: 20 }, SYS);
+    // Newest-first within the matches: offset 20 of 30 → match_9 … match_0.
+    expect(page.map(r => r.id)).toEqual(Array.from({ length: 10 }, (_, k) => `match_${9 - k}`));
+    expect(page.every(r => r.pending_approvers?.includes('u9'))).toBe(true);
+  });
+
+  it('rebuildApproverIndex backfills legacy rows, drops orphans + stale entries, and is idempotent', async () => {
+    const reqs = (engine._tables['sys_approval_request'] ??= []);
+    const idx = (engine._tables['sys_approval_approver'] ??= []);
+    const ts = new Date(baseTime).toISOString();
+    // Legacy pending row written before the index existed.
+    reqs.push({
+      id: 'legacy_1', process_name: 'flow:f', object_name: 'o', record_id: 'r1',
+      status: 'pending', pending_approvers: 'u1,u2', created_at: ts, updated_at: ts,
+    });
+    // Completed row whose index rows were never cleaned (orphan).
+    reqs.push({
+      id: 'done_1', process_name: 'flow:f', object_name: 'o', record_id: 'r2',
+      status: 'approved', pending_approvers: null, created_at: ts, updated_at: ts,
+    });
+    idx.push({ id: 'aapr_orphan', request_id: 'done_1', approver: 'u3', organization_id: null, created_at: ts });
+    // Pending row whose index drifted (holds an approver no longer in the CSV).
+    reqs.push({
+      id: 'drift_1', process_name: 'flow:f', object_name: 'o', record_id: 'r3',
+      status: 'pending', pending_approvers: 'u5', created_at: ts, updated_at: ts,
+    });
+    idx.push({ id: 'aapr_stale', request_id: 'drift_1', approver: 'u4', organization_id: null, created_at: ts });
+
+    const out = await svc.rebuildApproverIndex();
+    expect(out).toEqual({ requests: 2, inserted: 3, deleted: 2 }); // +u1 +u2 +u5 / -orphan -stale
+    expect(indexRows().sort((a, b) => a.approver.localeCompare(b.approver))).toEqual([
+      { request_id: 'legacy_1', approver: 'u1' },
+      { request_id: 'legacy_1', approver: 'u2' },
+      { request_id: 'drift_1', approver: 'u5' },
+    ]);
+
+    const again = await svc.rebuildApproverIndex();
+    expect(again).toEqual({ requests: 2, inserted: 0, deleted: 0 });
+  });
+
+  // ── SLA escalation (ADR-0042) ───────────────────────────────────
+
+  function makeOverdue(reqId: string) {
+    // Push created_at into the past so a small timeoutHours is breached.
+    const row = engine._tables['sys_approval_request'].find(r => r.id === reqId)!;
+    row.created_at = new Date(baseTime - 10 * 3600_000).toISOString();
+  }
+
+  it('runEscalations: notify action messages approvers + escalateTo + submitter, once', async () => {
+    const emitted: any[] = [];
+    svc.attachMessaging({ async emit(input) { emitted.push(input); } });
+    const req = await svc.openNodeRequest(
+      openInput(['u9'], {}, { escalation: { timeoutHours: 2, action: 'notify', escalateTo: 'boss', notifySubmitter: true } }), CTX,
+    );
+    makeOverdue(req.id);
+    const first = await svc.runEscalations();
+    expect(first.escalated).toBe(1);
+    expect(emitted.map(e => e.topic)).toEqual(['approval.sla_breached', 'approval.sla_breached']);
+    expect(emitted[0].audience).toEqual(['u9', 'boss']);
+    expect(emitted[1].audience).toEqual(['u1']); // submitter
+    const actions = await svc.listActions(req.id, SYS);
+    expect(actions.at(-1)).toMatchObject({ action: 'escalate', actor_id: 'system:sla', comment: 'notify → boss' });
+    // Single-shot: second sweep is a no-op.
+    const second = await svc.runEscalations();
+    expect(second.escalated).toBe(0);
+    expect(emitted).toHaveLength(2);
+  });
+
+  it('runEscalations: auto_approve decides as system:sla and resumes the flow', async () => {
+    const resumed: any[] = [];
+    svc.attachAutomation({ async resume(runId, signal) { resumed.push({ runId, signal }); } });
+    const req = await svc.openNodeRequest(
+      openInput(['u9'], {}, { escalation: { timeoutHours: 1, action: 'auto_approve', notifySubmitter: false } }), CTX,
+    );
+    makeOverdue(req.id);
+    const out = await svc.runEscalations();
+    expect(out.escalated).toBe(1);
+    const fresh = await svc.getRequest(req.id, SYS);
+    expect(fresh?.status).toBe('approved');
+    expect(resumed[0]).toMatchObject({ runId: 'run_1', signal: { branchLabel: 'approve' } });
+    const actions = await svc.listActions(req.id, SYS);
+    expect(actions.map(a => a.action)).toEqual(['submit', 'escalate', 'approve']);
+    expect(actions.at(-1)?.actor_id).toBe('system:sla');
+  });
+
+  it('runEscalations: auto_reject decides as system:sla', async () => {
+    const req = await svc.openNodeRequest(
+      openInput(['u9'], {}, { escalation: { timeoutHours: 1, action: 'auto_reject', notifySubmitter: false } }), CTX,
+    );
+    makeOverdue(req.id);
+    await svc.runEscalations();
+    const fresh = await svc.getRequest(req.id, SYS);
+    expect(fresh?.status).toBe('rejected');
+  });
+
+  it('runEscalations: reassign replaces the approver set with escalateTo', async () => {
+    const req = await svc.openNodeRequest(
+      openInput(['u9', 'u2'], {}, { escalation: { timeoutHours: 1, action: 'reassign', escalateTo: 'boss', 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).toEqual(['boss']);
+  });
+
+  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,
+    );
+    await svc.openNodeRequest(openInput(['u9'], { recordId: 'opp2', record: { id: 'opp2' } }), CTX);
+    const out = await svc.runEscalations();
+    expect(out.scanned).toBe(2);
+    expect(out.escalated).toBe(0);
+  });
+
+  // ── SLA + flow steps ────────────────────────────────────────────
+
+  it('rows expose sla_due_at when the node declares escalation.timeoutHours', async () => {
+    const req = await svc.openNodeRequest(
+      openInput(['u9'], {}, { escalation: { timeoutHours: 48, action: 'notify', notifySubmitter: true } }), CTX,
+    );
+    expect(req.sla_due_at).toBe(new Date(Date.parse(req.created_at!) + 48 * 3600_000).toISOString());
+    const noSla = await svc.openNodeRequest(openInput(['u9'], { recordId: 'opp2', record: { id: 'opp2' } }), CTX);
+    expect(noSla.sla_due_at).toBeUndefined();
+  });
+
+  it('getRequest attaches flow_steps from the owning flow graph', async () => {
+    svc.attachAutomation({
+      async getFlow(name: string) {
+        if (name !== 'deal_approval') return null;
+        return {
+          name: 'deal_approval',
+          nodes: [
+            { id: 'start', type: 'start', label: 'Start' },
+            { id: 'approve_step', type: 'approval', label: 'Manager Approval' },
+            { id: 'gate', type: 'decision', label: 'Big?' },
+            { id: 'exec_step', type: 'approval', label: 'Executive Approval' },
+            { id: 'end', type: 'end', label: 'End' },
+          ],
+          edges: [
+            { id: 'e1', source: 'start', target: 'approve_step' },
+            { id: 'e2', source: 'approve_step', target: 'gate', label: 'approve' },
+            { id: 'e3', source: 'gate', target: 'exec_step', label: 'true' },
+            { id: 'e4', source: 'exec_step', target: 'end', label: 'approve' },
+          ],
+        };
+      },
+    });
+    const req = await svc.openNodeRequest(openInput(['u9']), CTX);
+    const fresh = await svc.getRequest(req.id, SYS);
+    expect(fresh?.flow_steps).toEqual([
+      { id: 'approve_step', label: 'Manager Approval', state: 'current' },
+      { id: 'exec_step', label: 'Executive Approval', state: 'upcoming' },
+    ]);
+  });
+
   it('enrichment resolves an email submitter via sys_user.email', async () => {
     engine._tables['sys_user'] = [{ id: 'u7', name: 'Grace Hopper', email: 'grace@example.com' }];
     await svc.openNodeRequest(openInput(['u9'], { submitterId: 'grace@example.com' }), CTX);