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

package/src/status-mirror-cascade.integration.test.ts

@@ -0,0 +1,224 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #3783 — an approval decision cascades as the deciding user.
+ *
+ * "When the invoice is approved, do X" is the single most natural approvals
+ * automation there is, and until now it could not be written the obvious way.
+ * The status mirror — the write that puts `approved` on the business record, and
+ * therefore the write that fires that object's record-change flows — presented a
+ * bare `{ isSystem: true }` context with no `userId`. `isSystem` does not
+ * suppress trigger dispatch, so the flow DID fire; it just fired with no trigger
+ * user, and since #3760 a `runAs:'user'` run with no trigger user has its data
+ * operations refused. Authors were pushed to declare `runAs:'system'` — blanket
+ * elevation — for a case where a perfectly good scoped identity existed all
+ * along, sitting right there at the call site.
+ *
+ * The seam is invisible in a unit test of any single hop, so this one refuses to
+ * stub any of them: a real {@link ObjectKernel} with the real ObjectQL engine,
+ * the real record-change trigger, the real automation engine, and the real
+ * {@link ApprovalService}. The mirror is produced by an actual decision, not
+ * hand-written.
+ *
+ * The negative case is load-bearing, not decoration. It fires the SAME flow off
+ * the dead-run sweep's mirror, which has no human behind it and stays user-less
+ * on purpose — and shows it is still refused. Without it, the positive case
+ * would prove only that the flow runs, never that it runs *because* the identity
+ * arrived.
+ *
+ * The record lock is deliberately not bound here: it is a separate concern with
+ * its own end-to-end coverage (`record-lock-schedule-run.integration.test.ts`).
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ObjectKernel } from '@objectstack/core';
+import { ObjectQLPlugin } from '@objectstack/objectql';
+import { AutomationServicePlugin, type AutomationEngine } from '@objectstack/service-automation';
+import { RecordChangeTriggerPlugin } from '@objectstack/trigger-record-change';
+import { ApprovalService } from './approval-service.js';
+import { SysApprovalRequest } from './sys-approval-request.object.js';
+import { SysApprovalAction } from './sys-approval-action.object.js';
+import { SysApprovalApprover } from './sys-approval-approver.object.js';
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+const SUBMITTER = { userId: 'submitter', positions: [], permissions: [] } as any;
+const APPROVER = { userId: 'approver', positions: [], permissions: [] } as any;
+
+/** Equality-WHERE in-memory driver — the same shape the trigger's own e2e uses. */
+function makeMemoryDriver(): any {
+  const stores = new Map<string, Map<string, Record<string, unknown>>>();
+  const storeFor = (obj: string) => {
+    let s = stores.get(obj);
+    if (!s) { s = new Map(); stores.set(obj, s); }
+    return s;
+  };
+  let nextId = 0;
+  const matches = (row: Record<string, unknown>, where: any): boolean => {
+    if (!where || typeof where !== 'object') return true;
+    if (Array.isArray(where.$and)) return where.$and.every((w: any) => matches(row, w));
+    if (Array.isArray(where.$or)) return where.$or.some((w: any) => matches(row, w));
+    for (const [k, v] of Object.entries(where)) {
+      if (k.startsWith('$')) continue;
+      const expected = v && typeof v === 'object' && '$eq' in (v as any) ? (v as any).$eq : v;
+      const a = row[k] === undefined ? null : row[k];
+      const b = expected === undefined ? null : expected;
+      if (a !== b) return false;
+    }
+    return true;
+  };
+  return {
+    name: 'memory', version: '0.0.0', supports: {},
+    async connect() {}, async disconnect() {}, async checkHealth() { return true; },
+    async execute() { return null; }, async syncSchema() {},
+    async find(object: string, ast: any) {
+      return Array.from(storeFor(object).values()).filter((r) => matches(r, ast?.where));
+    },
+    findStream() { throw new Error('not implemented'); },
+    async findOne(object: string, ast: any) {
+      for (const r of storeFor(object).values()) if (matches(r, ast?.where)) return r;
+      return null;
+    },
+    async create(object: string, data: Record<string, unknown>) {
+      nextId += 1;
+      const id = (data.id as string) ?? `r_${nextId}`;
+      const row = { ...data, id };
+      storeFor(object).set(id, row);
+      return row;
+    },
+    async update(object: string, id: string, data: Record<string, unknown>) {
+      const s = storeFor(object);
+      const cur = s.get(id);
+      if (!cur) throw new Error(`not found: ${object}/${id}`);
+      const updated = { ...cur, ...data, id };
+      s.set(id, updated);
+      return updated;
+    },
+    async upsert(object: string, data: Record<string, unknown>) {
+      const id = data.id as string | undefined;
+      if (id && storeFor(object).has(id)) return this.update(object, id, data);
+      return this.create(object, data);
+    },
+    async delete(object: string, id: string) { return storeFor(object).delete(id); },
+    async count(object: string, ast: any) { return (await this.find(object, ast)).length; },
+    async bulkCreate(object: string, rows: Record<string, unknown>[]) {
+      return Promise.all(rows.map((r) => this.create(object, r)));
+    },
+    async bulkUpdate() { return []; }, async bulkDelete() {},
+    async beginTransaction() { return { commit: async () => {}, rollback: async () => {} }; },
+    async commit() {}, async rollback() {},
+  };
+}
+
+const opportunity = {
+  name: 'opportunity',
+  label: 'Opportunity',
+  fields: {
+    amount: { name: 'amount', label: 'Amount', type: 'number' },
+    approval_status: { name: 'approval_status', label: 'Approval Status', type: 'text' },
+    cascaded: { name: 'cascaded', label: 'Cascaded', type: 'text' },
+  },
+};
+
+/**
+ * The automation an author actually wants to write: react to the approval, no
+ * `runAs` — the spec default `'user'`. That default is the whole point; a flow
+ * forced to say `runAs:'system'` to work at all is the bug being fixed.
+ */
+const onApprovedFlow = {
+  name: 'on_approved',
+  label: 'On Approved',
+  type: 'record_change',
+  nodes: [
+    {
+      id: 'start', type: 'start', label: 'Start',
+      config: {
+        objectName: 'opportunity',
+        triggerType: 'record-after-update',
+        // Fires on BOTH terminal mirrors, so the two cases below differ only in
+        // whether the mirror that fired it carried a user — nothing else.
+        condition: "approval_status == 'approved' || approval_status == 'recalled'",
+      },
+    },
+    {
+      id: 'stamp', type: 'update_record', label: 'Stamp',
+      config: { objectName: 'opportunity', filter: { id: '{record.id}' }, fields: { cascaded: 'yes' } },
+    },
+    { id: 'end', type: 'end', label: 'End' },
+  ],
+  edges: [
+    { id: 'e1', source: 'start', target: 'stamp' },
+    { id: 'e2', source: 'stamp', target: 'end' },
+  ],
+};
+
+const nodeConfig = {
+  approvers: [{ type: 'user' as const, value: 'approver' }],
+  behavior: 'first_response' as const,
+  lockRecord: false,
+  approvalStatusField: 'approval_status',
+};
+
+describe('an approval decision cascades as the deciding user (#3783)', () => {
+  let data: any;
+  let svc: ApprovalService;
+
+  beforeEach(async () => {
+    const kernel = new ObjectKernel({ logLevel: 'silent' });
+    await kernel.use(new ObjectQLPlugin());
+    await kernel.use(new AutomationServicePlugin());
+    await kernel.use(new RecordChangeTriggerPlugin());
+    await kernel.bootstrap();
+
+    const objectql = kernel.getService('objectql') as any;
+    data = kernel.getService('data') as any;
+    const automation = kernel.getService<AutomationEngine>('automation');
+
+    objectql.registerDriver(makeMemoryDriver(), true);
+    for (const def of [opportunity, SysApprovalRequest, SysApprovalAction, SysApprovalApprover]) {
+      objectql.registry.registerObject(def as any, 'approvals-test', 'approvals-test');
+    }
+    automation.registerFlow('on_approved', onApprovedFlow as any);
+
+    svc = new ApprovalService({ engine: objectql });
+    await data.insert('opportunity', { id: 'opp1', amount: 100 }, { context: { isSystem: true } });
+  });
+
+  const readBack = () => data.findOne('opportunity', { where: { id: 'opp1' } });
+
+  const openRequest = () => svc.openNodeRequest({
+    object: 'opportunity', recordId: 'opp1', runId: 'run_1', nodeId: 'approve_step',
+    flowName: 'deal_approval', config: nodeConfig, submitterId: 'submitter',
+    record: { id: 'opp1', amount: 100 },
+  }, SUBMITTER);
+
+  it('the approve mirror hands the flow a trigger user, so its data node runs', async () => {
+    const req = await openRequest();
+    await svc.decide(req.id as string, { decision: 'approve', actorId: 'approver' }, APPROVER);
+    await sleep(300);
+
+    const row = await readBack();
+    expect(row?.approval_status, 'the mirror itself must still land').toBe('approved');
+    // Before #3783 this stayed undefined: the run inherited no trigger user, so
+    // `resolveRunDataContext` refused its `update_record` outright.
+    expect(row?.cascaded).toBe('yes');
+    // ObjectQL's audit stamp is gated on the write context's `userId` alone —
+    // `isSystem` buys no exemption — so this is direct evidence the elevated
+    // mirror named a user rather than nobody.
+    expect(row?.updated_by).toBe('approver');
+  });
+
+  it('a dead-run release cascades user-less, and is still refused', async () => {
+    await openRequest();
+    svc.attachAutomation({ getRun: async () => ({ status: 'failed' }) } as any);
+    await svc.releaseDeadRunRequests();
+    await sleep(300);
+
+    const row = await readBack();
+    expect(row?.approval_status, 'the sweep must still release the record').toBe('recalled');
+    // No human abandoned this request — a sweep did. The cascade therefore has
+    // no identity to inherit and stays refused; an author who wants to react to
+    // a dead-run release declares `runAs:'system'` and means it.
+    expect(row?.cascaded).toBeFalsy();
+  });
+});

package/src/sys-approval-action.object.ts

@@ -26,6 +26,15 @@ export const SysApprovalAction = ObjectSchema.create({
   titleFormat: '{action} · {step_name}',
   highlightFields: ['request_id', 'step_name', 'action', 'actor_id', 'created_at'],
 
+  // ADR-0104 D3 wave 2. `attachments` is a media field, so the files it holds
+  // are OWNED by this row — and the storage service would otherwise authorize
+  // their download by testing whether the caller can READ this row. It cannot:
+  // this table is deliberately closed to ordinary approver positions, so that
+  // test denies the very approver the attachment was filed for. The approvals
+  // service already owns the rule for seeing a decision (visibility of the
+  // parent request, exactly as `listActions` applies it), so it answers.
+  fileAccessDelegate: 'approvals',
+
   listViews: {
     recent: {
       type: 'grid',

package/src/sys-approval-delegation.object.test.ts

@@ -0,0 +1,42 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #3026 follow-up — `sys_approval_delegation` must expose the BATCH shape of
+ * the write verbs it already grants.
+ *
+ * The object is `managedBy: 'system'` but opens generic writes deliberately
+ * (`userActions: { create, edit, delete }` — an out-of-office rule is authored
+ * by its own user through the plain data endpoint), so the ADR-0103 D3
+ * reconciliation strips nothing and its boilerplate CRUD-five whitelist reaches
+ * the REST gate as authored. Since the #3391 P1 contract made bulk
+ * `bulk ∧ derived(child)`, that whitelist — which never named the `bulk`
+ * primitive — 405s every batch route while the single-record verbs stay open.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { resolveEffectiveApiMethods, isApiOperationAllowed } from '@objectstack/spec/data';
+import { SysApprovalDelegation } from './sys-approval-delegation.object';
+
+describe('sys_approval_delegation — batch exposure (#3026 / #3391 P1 companion)', () => {
+  it('grants the bulk primitive alongside its single-record write verbs', () => {
+    expect(SysApprovalDelegation.enable?.apiMethods).toContain('bulk');
+    for (const verb of ['get', 'list', 'create', 'update', 'delete'] as const) {
+      expect(SysApprovalDelegation.enable?.apiMethods, `must keep ${verb}`).toContain(verb);
+    }
+  });
+
+  it('admits createMany / updateMany / deleteMany and /batch', () => {
+    const eff = resolveEffectiveApiMethods(SysApprovalDelegation.enable);
+    expect(eff.mode).toBe('restricted');
+    for (const child of ['create', 'update', 'delete'] as const) {
+      expect(isApiOperationAllowed(eff, 'bulk', { bulkChild: child }), `batch ${child}`).toBe(true);
+    }
+  });
+
+  it('keeps the whitelist explicit so the ADR-0103 D3 backstop still runs', () => {
+    // `reconcileManagedApiMethods` early-returns on a non-array `apiMethods`.
+    // For a `managedBy` object, deleting the whitelist would silently disable
+    // managed-write stripping — it is not an equivalent refactor.
+    expect(Array.isArray(SysApprovalDelegation.enable?.apiMethods)).toBe(true);
+  });
+});

package/src/sys-approval-delegation.object.ts

@@ -135,8 +135,8 @@ export const SysApprovalDelegation = ObjectSchema.create({
     trackHistory: true,
     searchable: true,
     apiEnabled: true,
-    apiMethods: ['get', 'list', 'create', 'update', 'delete'],
-    trash: true,
-    mru: false,
+    // `bulk` = the batch shape of the verbs above; the gate is `bulk ∧ child`
+    // (#3391 P1), so omitting it 405s /batch and the *Many routes (#3026).
+    apiMethods: ['get', 'list', 'create', 'update', 'delete', 'bulk'],
   },
 });

package/src/sys-approval-request.object.test.ts

@@ -74,6 +74,19 @@ describe('sys_approval_request declared actions', () => {
     }
   });
 
+  it('the core decision levers OR in the admin override (#3424) so a stuck request is recoverable', () => {
+    // approve / reject / reassign additionally show for a platform/tenant admin
+    // (`record.viewer.can_override`) so an approval routed to an unstaffed
+    // position — otherwise undecidable, locking the record forever — can be
+    // rescued in-product. The secondary approver levers stay slot-only.
+    for (const name of ['approval_approve', 'approval_reject', 'approval_reassign']) {
+      expect(vis(name)).toContain('record.viewer.can_override');
+    }
+    for (const name of ['approval_send_back', 'approval_request_info']) {
+      expect(vis(name)).not.toContain('can_override');
+    }
+  });
+
   it('recall stays available while a returned request is still the submitter\'s to abandon', () => {
     expect(vis('approval_recall')).toContain('record.status == "returned"');
     expect(byName('approval_recall').confirmText).toBeTruthy();

package/src/sys-approval-request.object.ts

@@ -240,13 +240,22 @@ export const SysApprovalRequest = ObjectSchema.create({
   // per-viewer block (#3310): approver actions on `record.viewer.can_act`
   // (the caller is a current pending approver — same check the service
   // authorizes a decision with, so position/team approvers resolve correctly),
-  // submitter actions on `record.viewer.is_submitter`. `viewer` is attached by
-  // getRequest/listRequests; where it is absent the predicate fails closed.
+  // submitter actions on `record.viewer.is_submitter`. The core decision levers
+  // (approve/reject/reassign) additionally OR in `record.viewer.can_override`
+  // (#3424) so a platform/tenant admin can rescue a request routed to an
+  // unstaffed position — otherwise undecidable, locking the record forever — by
+  // approving, rejecting, or reassigning it to a real approver. `viewer` is
+  // attached by getRequest/listRequests; where it is absent the predicate fails
+  // closed.
   actions: [
     {
       name: 'approval_approve',
       label: 'Approve',
       icon: 'check-circle',
+      // Primary decision — the console renders this filled/highlighted so it
+      // stands out from the secondary levers in the drawer's action bar,
+      // matching the mobile card hierarchy (objectui#2762 P1-5).
+      variant: 'primary',
       type: 'api',
       method: 'POST',
       target: '/api/v1/approvals/requests/{id}/approve',
@@ -257,7 +266,7 @@ export const SysApprovalRequest = ObjectSchema.create({
         // string[]`; the decision route persists them on `sys_approval_action`.
         { name: 'attachments', label: 'Attachments', type: 'file', multiple: true, required: false },
       ],
-      visible: 'record.viewer.can_act',
+      visible: 'record.viewer.can_act || record.viewer.can_override',
       locations: ['record_section', 'list_item'],
       successMessage: 'Approved.',
       refreshAfter: true,
@@ -266,6 +275,9 @@ export const SysApprovalRequest = ObjectSchema.create({
       name: 'approval_reject',
       label: 'Reject',
       icon: 'x-circle',
+      // Destructive decision — rendered in the console's danger styling so it
+      // reads as the irreversible action it is (objectui#2762 P1-5).
+      variant: 'danger',
       type: 'api',
       method: 'POST',
       target: '/api/v1/approvals/requests/{id}/reject',
@@ -273,7 +285,7 @@ export const SysApprovalRequest = ObjectSchema.create({
         { name: 'comment', label: 'Comment', type: 'textarea', required: false },
         { name: 'attachments', label: 'Attachments', type: 'file', multiple: true, required: false },
       ],
-      visible: 'record.viewer.can_act',
+      visible: 'record.viewer.can_act || record.viewer.can_override',
       confirmText: 'Reject this request? A rejection is final for every approver.',
       locations: ['record_section', 'list_item'],
       successMessage: 'Rejected.',
@@ -295,7 +307,7 @@ export const SysApprovalRequest = ObjectSchema.create({
         { field: 'submitter_id', name: 'to', label: 'New approver', required: true, helpText: 'User to hand this step to' },
         { name: 'comment', label: 'Comment', type: 'textarea', required: false },
       ],
-      visible: 'record.viewer.can_act',
+      visible: 'record.viewer.can_act || record.viewer.can_override',
       locations: ['record_section'],
       successMessage: 'Reassigned.',
       refreshAfter: true,

package/src/translations/bundle-ownership.test.ts

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// Bundle-ownership guard (#2834 ⑤ / ADR-0029 D8): this package's generated
+// object-translation bundles must carry ONLY objects its extract config
+// (`scripts/i18n-extract.config.ts`) actually imports. When an object moves to
+// another package, its translations move with it — a leftover copy here
+// silently DIES on the next `os i18n extract` run, taking curated translations
+// with it (the sys_audit_log incident). This test turns that silent loss into a
+// red build: an object present in the bundle but not in the ownership list below
+// means either (a) the extract config gained an object — add it here — or (b) a
+// moved/removed object's keys were left behind — remove them from the bundles
+// (or migrate them to the owning package), then keep this list in sync.
+//
+// NB: this package defines more approval objects (sys_approval_approver,
+// sys_approval_token) that the extract config deliberately does NOT translate —
+// they are absent from both the config and the bundles, so they are correctly
+// out of scope here.
+
+import { describe, it, expect } from 'vitest';
+import { enObjects } from './en.objects.generated.js';
+
+// Objects the extract config (scripts/i18n-extract.config.ts) imports —
+// keep the two lists in sync when adding/moving objects.
+const OWNED_OBJECTS = new Set([
+  'sys_approval_request',
+  'sys_approval_action',
+  'sys_approval_delegation',
+]);
+
+describe('objects translation bundle ownership (ADR-0029 D8)', () => {
+  it('the en bundle contains no objects owned by other packages', () => {
+    const strays = Object.keys(enObjects).filter((o) => !OWNED_OBJECTS.has(o));
+    expect(
+      strays,
+      `bundle carries objects this package's extract config does not own: ${strays.join(', ')} — ` +
+        'their curated translations would be silently deleted on the next `os i18n extract`. ' +
+        'Remove the dead block from the four locale bundles, or add the object to the extract config + this list.',
+    ).toEqual([]);
+  });
+
+  it('every owned object is present in the bundle (extract config regression)', () => {
+    const missing = [...OWNED_OBJECTS].filter((o) => !(o in enObjects));
+    expect(
+      missing,
+      `objects the extract config should emit are missing from the bundle: ${missing.join(', ')} — was an import dropped from scripts/i18n-extract.config.ts?`,
+    ).toEqual([]);
+  });
+});

package/src/translations/en.objects.generated.ts

@@ -44,7 +44,8 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
           pending: "pending",
           approved: "approved",
           rejected: "rejected",
-          recalled: "recalled"
+          recalled: "recalled",
+          returned: "returned"
         }
       },
       current_step: {
@@ -86,7 +87,11 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
     },
     _views: {
       my_pending: {
-        label: "My Pending"
+        label: "My Pending",
+        emptyState: {
+          title: "No pending approvals",
+          message: "You're all caught up."
+        }
       },
       submitted_by_me: {
         label: "I Submitted"
@@ -97,6 +102,92 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       all_requests: {
         label: "All"
       }
+    },
+    _actions: {
+      approval_approve: {
+        label: "Approve",
+        successMessage: "Approved.",
+        params: {
+          comment: {
+            label: "Comment"
+          },
+          attachments: {
+            label: "Attachments"
+          }
+        }
+      },
+      approval_reject: {
+        label: "Reject",
+        confirmText: "Reject this request? A rejection is final for every approver.",
+        successMessage: "Rejected.",
+        params: {
+          comment: {
+            label: "Comment"
+          },
+          attachments: {
+            label: "Attachments"
+          }
+        }
+      },
+      approval_reassign: {
+        label: "Reassign",
+        successMessage: "Reassigned.",
+        params: {
+          to: {
+            label: "New approver",
+            helpText: "User to hand this step to"
+          },
+          comment: {
+            label: "Comment"
+          }
+        }
+      },
+      approval_send_back: {
+        label: "Send back",
+        successMessage: "Sent back for revision.",
+        params: {
+          comment: {
+            label: "Reason"
+          }
+        }
+      },
+      approval_request_info: {
+        label: "Request info",
+        successMessage: "Information requested.",
+        params: {
+          comment: {
+            label: "What do you need?"
+          }
+        }
+      },
+      approval_remind: {
+        label: "Send reminder",
+        successMessage: "Reminder sent.",
+        params: {
+          comment: {
+            label: "Note"
+          }
+        }
+      },
+      approval_recall: {
+        label: "Recall",
+        confirmText: "Recall this request? Approvers can no longer act on it and the record is unlocked.",
+        successMessage: "Recalled.",
+        params: {
+          comment: {
+            label: "Comment"
+          }
+        }
+      },
+      approval_resubmit: {
+        label: "Resubmit",
+        successMessage: "Resubmitted.",
+        params: {
+          comment: {
+            label: "What changed?"
+          }
+        }
+      }
     }
   },
   sys_approval_action: {
@@ -128,7 +219,14 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
           approve: "approve",
           reject: "reject",
           recall: "recall",
-          escalate: "escalate"
+          escalate: "escalate",
+          reassign: "reassign",
+          remind: "remind",
+          request_info: "request_info",
+          comment: "comment",
+          revise: "revise",
+          resubmit: "resubmit",
+          ooo_substitute: "ooo_substitute"
         }
       },
       actor_id: {
@@ -137,13 +235,21 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       comment: {
         label: "Comment"
       },
+      attachments: {
+        label: "Attachments",
+        help: "Files supporting this action — e.g. a signed contract or evidence (#3266)."
+      },
       created_at: {
         label: "Created At"
       }
     },
     _views: {
       recent: {
-        label: "Recent"
+        label: "Recent",
+        emptyState: {
+          title: "No approval actions yet",
+          message: "Actions are logged automatically when approvals progress."
+        }
       },
       by_actor: {
         label: "By Actor"
@@ -179,7 +285,7 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       },
       reason: {
         label: "Reason",
-        help: "Why the delegation exists (e.g. \"Annual leave 5/26\u20135/30\"). Recorded on the substitution audit row."
+        help: "Why the delegation exists (e.g. \"Annual leave 5/26–5/30\"). Recorded on the substitution audit row."
       },
       organization_id: {
         label: "Organization",