@objectstack/plugin-approvals 15.1.1 → 16.0.0-rc.1

package/src/approvals-plugin.ts

@@ -5,6 +5,7 @@ import { SysApprovalRequest } from './sys-approval-request.object.js';
 import { SysApprovalAction } from './sys-approval-action.object.js';
 import { SysApprovalApprover } from './sys-approval-approver.object.js';
 import { SysApprovalToken } from './sys-approval-token.object.js';
+import { SysApprovalDelegation } from './sys-approval-delegation.object.js';
 import { renderConfirmPage, renderResultPage } from './action-link-pages.js';
 import {
   ApprovalService,
@@ -12,7 +13,7 @@ import {
   ESCALATION_SCAN_INTERVAL_MS,
   type ApprovalEngine,
 } from './approval-service.js';
-import { bindApprovalLockHook, unbindAllHooks } from './lifecycle-hooks.js';
+import { bindApprovalLockHook, bindDelegationWriteGuard, unbindAllHooks } from './lifecycle-hooks.js';
 import { registerApprovalNode, type ApprovalAutomationSurface } from './approval-node.js';
 
 export interface ApprovalsPluginOptions {
@@ -70,7 +71,7 @@ export class ApprovalsServicePlugin implements Plugin {
       scope: 'system',
       defaultDatasource: 'cloud',
       namespace: 'sys',
-      objects: [SysApprovalRequest, SysApprovalAction, SysApprovalApprover, SysApprovalToken],
+      objects: [SysApprovalRequest, SysApprovalAction, SysApprovalApprover, SysApprovalToken, SysApprovalDelegation],
       // ADR-0029 D7 — contribute the Approvals entries into the Setup app's
       // `group_approvals` slot. This plugin owns these objects (K2.b), so it
       // ships their menu too; when the plugin isn't installed the slot is empty.
@@ -82,6 +83,7 @@ export class ApprovalsServicePlugin implements Plugin {
           items: [
             { id: 'nav_approval_requests', type: 'object', label: 'Requests', objectName: 'sys_approval_request', icon: 'inbox', requiresObject: 'sys_approval_request' },
             { id: 'nav_approval_actions', type: 'object', label: 'Action History', objectName: 'sys_approval_action', icon: 'history', requiresObject: 'sys_approval_action' },
+            { id: 'nav_approval_delegations', type: 'object', label: 'Delegations (OOO)', objectName: 'sys_approval_delegation', icon: 'user-clock', requiresObject: 'sys_approval_delegation' },
           ],
         },
       ],
@@ -122,12 +124,16 @@ export class ApprovalsServicePlugin implements Plugin {
     });
 
     // Record lock: block edits to a record while it has a pending request.
+    // Delegation write-guard: a self-service OOO delegation may only name the
+    // acting user as delegator (#1322 follow-up). Both bind under the same
+    // package id, so unbindAllHooks clears them together.
     if (!this.options.disableAutoHooks) {
       try {
         unbindAllHooks(engine);
         bindApprovalLockHook(engine, ctx.logger);
+        bindDelegationWriteGuard(engine, ctx.logger);
       } catch (err: any) {
-        ctx.logger.warn?.('[approvals] failed to bind record-lock hook', { error: err?.message });
+        ctx.logger.warn?.('[approvals] failed to bind approval hooks', { error: err?.message });
       }
     }
 

package/src/index.ts

@@ -13,6 +13,7 @@
 export { SysApprovalRequest } from './sys-approval-request.object.js';
 export { SysApprovalAction } from './sys-approval-action.object.js';
 export { SysApprovalApprover } from './sys-approval-approver.object.js';
+export { SysApprovalDelegation } from './sys-approval-delegation.object.js';
 export {
   ApprovalService,
   type ApprovalEngine,

package/src/lifecycle-hooks.ts

@@ -109,6 +109,70 @@ export function bindApprovalLockHook(engine: MinimalEngine, logger?: MinimalLogg
   logger?.info?.('[approvals] record-lock hook bound');
 }
 
+/** The self-service out-of-office delegation object (#1322). */
+export const DELEGATION_OBJECT = 'sys_approval_delegation';
+
+/**
+ * Self-service write guard for `sys_approval_delegation` (#1322 follow-up).
+ *
+ * The object is `apiEnabled` CRUD so a user can declare their own out-of-office
+ * delegation. But it is a system object: it gets no auto `owner_id` anchor and
+ * (with no `sharingModel`) defaults to a `public` sharing model, so an
+ * unguarded member could **forge a delegation for someone else**
+ * (`delegator_id = victim`) and reroute the victim's individually-routed
+ * approvals to themselves. This guard forces a normal user's writes to name
+ * themselves as the delegator:
+ *
+ *   - **system** context (service / seed / import) → bypass;
+ *   - **admin** (`roles` includes `'admin'`) → may set `delegator_id` to anyone;
+ *   - otherwise `delegator_id` must equal the acting user — an absent delegator
+ *     on insert is stamped to the caller, a foreign delegator is rejected.
+ *
+ * Row-level ownership on update/delete (you can only touch a delegation you
+ * created) is already enforced by `member_default`'s wildcard
+ * `created_by == current_user.id` RLS; this guard adds the delegator-identity
+ * check that RLS alone can't express. Mirrors the ADR-0092 identity write-guard
+ * shape and the security plugin's `owner_id` anchor guard, scoped to this one
+ * object.
+ */
+export function bindDelegationWriteGuard(engine: MinimalEngine, logger?: MinimalLogger): void {
+  const makeGuard = (isInsert: boolean) => async (ctx: any) => {
+    const session = (ctx?.session ?? {}) as any;
+    if (session.isSystem) return;                                    // service / seed / import
+    const roles = (session.roles ?? []) as unknown[];
+    if (Array.isArray(roles) && roles.includes('admin')) return;     // admin may act for anyone
+    const userId = session.userId != null ? String(session.userId) : '';
+    const data = ctx?.input?.data;
+    const rows = Array.isArray(data) ? data : (data && typeof data === 'object' ? [data] : []);
+    const deny = (): never => {
+      const err: any = new Error(
+        'FORBIDDEN: you may only manage out-of-office delegations where you are the delegator'
+        + (userId ? ` ('${userId}')` : ''),
+      );
+      err.code = 'FORBIDDEN';
+      err.statusCode = 403;
+      throw err;
+    };
+    for (const row of rows) {
+      if (!row || typeof row !== 'object' || Array.isArray(row)) continue;
+      const has = Object.prototype.hasOwnProperty.call(row, 'delegator_id');
+      const supplied = has ? String((row as any).delegator_id ?? '') : '';
+      if (isInsert && (!has || supplied === '')) {
+        // Self-service: stamp the caller as delegator when omitted (the schema's
+        // `required` is the fallback if the engine doesn't persist the stamp).
+        if (!userId) deny();
+        (row as any).delegator_id = userId;
+        continue;
+      }
+      // A foreign delegator on insert (forge) or update (relabel/hijack) → deny.
+      if (has && supplied !== userId) deny();
+    }
+  };
+  engine.registerHook('beforeInsert', makeGuard(true), { object: DELEGATION_OBJECT, packageId: APPROVALS_HOOK_PACKAGE, priority: 50 });
+  engine.registerHook('beforeUpdate', makeGuard(false), { object: DELEGATION_OBJECT, packageId: APPROVALS_HOOK_PACKAGE, priority: 50 });
+  logger?.info?.('[approvals] delegation write-guard bound');
+}
+
 /** Unregister every hook the lock module registered. */
 export function unbindAllHooks(engine: MinimalEngine): number {
   return engine.unregisterHooksByPackage(APPROVALS_HOOK_PACKAGE);

package/src/nav-contribution.test.ts

@@ -28,6 +28,7 @@ describe('ApprovalsServicePlugin schema + nav contribution (ADR-0029 K2.b)', ()
     expect(manifest.objects.map((o: any) => o.name).sort()).toEqual([
       'sys_approval_action',
       'sys_approval_approver',
+      'sys_approval_delegation',
       'sys_approval_request',
       'sys_approval_token',
     ]);
@@ -38,6 +39,7 @@ describe('ApprovalsServicePlugin schema + nav contribution (ADR-0029 K2.b)', ()
     expect(contribution).toMatchObject({ app: 'setup', group: 'group_approvals' });
     expect(contribution.items.map((i: any) => i.objectName).sort()).toEqual([
       'sys_approval_action',
+      'sys_approval_delegation',
       'sys_approval_request',
     ]);
     // Each entry is gated so the slot stays empty when the plugin is absent.

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

@@ -92,8 +92,9 @@ export const SysApprovalAction = ObjectSchema.create({
       // Keep in sync with `ApprovalActionKind` (spec/contracts). reassign /
       // remind / request_info / comment are thread interactions — they never
       // move the flow. revise / resubmit (ADR-0044) DO move it: send back for
-      // revision and the later resubmission.
-      ['submit', 'approve', 'reject', 'recall', 'escalate', 'reassign', 'remind', 'request_info', 'comment', 'revise', 'resubmit'],
+      // revision and the later resubmission. ooo_substitute (#1322 M1) is a
+      // system-recorded reroute of an out-of-office approver — no flow movement.
+      ['submit', 'approve', 'reject', 'recall', 'escalate', 'reassign', 'remind', 'request_info', 'comment', 'revise', 'resubmit', 'ooo_substitute'],
       {
         label: 'Action',
         required: true,
@@ -109,6 +110,14 @@ export const SysApprovalAction = ObjectSchema.create({
 
     comment: Field.textarea({ label: 'Comment', required: false, group: 'Action' }),
 
+    attachments: Field.file({
+      label: 'Attachments',
+      required: false,
+      multiple: true,
+      group: 'Action',
+      description: 'Files supporting this action — e.g. a signed contract or evidence (#3266).',
+    }),
+
     created_at: Field.datetime({
       label: 'Created At',
       required: true,
@@ -122,4 +131,10 @@ export const SysApprovalAction = ObjectSchema.create({
     { fields: ['request_id', 'created_at'] },
     { fields: ['request_id', 'step_index', 'action'] },
   ],
+
+  enable: {
+    // [ADR-0103] Engine-owned append-only decision log: appended by the approval
+    // engine (SYSTEM_CTX). Reads stay open.
+    apiMethods: ['get', 'list'],
+  },
 });

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

@@ -30,7 +30,7 @@ export const SysApprovalApprover = ObjectSchema.create({
   pluralLabel: 'Approval Approvers',
   icon: 'users',
   isSystem: true,
-  managedBy: 'system',
+  managedBy: 'engine-owned',
   description: 'Normalized pending-approver rows for indexed inbox queries',
   displayNameField: 'id',
   nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
@@ -76,4 +76,10 @@ export const SysApprovalApprover = ObjectSchema.create({
     // Sync path: rewrite all rows of one request on each approver-set change.
     { fields: ['request_id'] },
   ],
+
+  enable: {
+    // [ADR-0103] Engine-owned: approver rows are rewritten by the approval
+    // engine (SYSTEM_CTX) on each approver-set change, never via generic CRUD.
+    apiMethods: ['get', 'list'],
+  },
 });

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

@@ -0,0 +1,142 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * sys_approval_delegation — self-service out-of-office (OOO) delegation (#1322 M1).
+ *
+ * A standing, self-declared rule: "while I (the delegator) am out between
+ * `valid_from` and `valid_until`, route the approver slots that would resolve
+ * to me onto my delegate instead." The approval service consults active rows
+ * in `ApprovalService.expandApprovers` when resolving an approval node's
+ * INDIVIDUALLY-routed approvers (`type: user` / `field` / `manager`) — the
+ * delegate becomes a real pending approver and acts under their own identity,
+ * so nothing is impersonated and the audit trail stays honest.
+ *
+ * Modelled as its own object (not a scalar on the better-auth-locked
+ * `sys_user`), mirroring the `sys_user_position` delegation precedent
+ * (ADR-0091): the validity window is enforced at RESOLUTION time via the
+ * shared `isGrantActive` predicate — never by a background job (ADR-0049).
+ * The window is half-open `[valid_from, valid_until)` in UTC.
+ *
+ * Scope note: this is the community-core OOO auto-skip only. Long-term proxy
+ * "act-as" access (viewing/acting on another user's full queue under their
+ * authority), delegation governance / segregation-of-duties, and org-wide
+ * administration of others' delegations are enterprise concerns tracked
+ * separately (objectstack-ai/cloud#855), not here.
+ *
+ * @namespace sys
+ */
+export const SysApprovalDelegation = ObjectSchema.create({
+  name: 'sys_approval_delegation',
+  label: 'Approval Delegation',
+  pluralLabel: 'Approval Delegations',
+  icon: 'user-clock',
+  isSystem: true,
+  managedBy: 'system',
+  // [ADR-0103] Admin/user-writable DATA on a platform-defined schema: a user
+  // authors their own out-of-office delegation. Affordance only (matches the
+  // full-CRUD apiMethods below) — RLS/permission sets are the authz; opening it
+  // keeps the system write guard from rejecting the self-service write.
+  userActions: { create: true, edit: true, delete: true },
+  description:
+    'Self-service out-of-office rule: route this user\'s approver slots to a delegate within a time window (#1322 M1).',
+  titleFormat: '{delegator_id} → {delegate_id}',
+  highlightFields: ['delegator_id', 'delegate_id', 'valid_from', 'valid_until'],
+
+  listViews: {
+    active: {
+      type: 'grid',
+      name: 'active',
+      label: 'Active',
+      data: { provider: 'object', object: 'sys_approval_delegation' },
+      columns: ['delegator_id', 'delegate_id', 'valid_from', 'valid_until', 'reason'],
+      sort: [{ field: 'valid_until', order: 'asc' }],
+      pagination: { pageSize: 50 },
+      emptyState: {
+        title: 'No delegations',
+        message: 'Declare an out-of-office delegation so approvals route to a backup while you are away.',
+      },
+    },
+  },
+
+  fields: {
+    id: Field.text({ label: 'Delegation ID', required: true, readonly: true, group: 'System' }),
+
+    delegator_id: Field.lookup('sys_user', {
+      label: 'Delegator',
+      required: true,
+      group: 'Delegation',
+      description: 'The user going out of office; their individually-routed approver slots are rerouted while active.',
+    }),
+
+    delegate_id: Field.lookup('sys_user', {
+      label: 'Delegate',
+      required: true,
+      group: 'Delegation',
+      description: 'The backup who receives the delegator\'s approvals while this rule is active. Acts under their own identity.',
+    }),
+
+    valid_from: Field.datetime({
+      label: 'Valid From',
+      required: false,
+      group: 'Delegation',
+      description:
+        'Rule is inactive before this instant. Null = active immediately. ' +
+        'Enforced at resolution time via isGrantActive (ADR-0091 D2 predicate) — never by a background job.',
+    }),
+
+    valid_until: Field.datetime({
+      label: 'Valid Until',
+      required: false,
+      group: 'Delegation',
+      description:
+        'Rule is inactive AT and AFTER this instant (half-open [from, until), UTC). Null = never expires.',
+    }),
+
+    reason: Field.text({
+      label: 'Reason',
+      required: false,
+      maxLength: 500,
+      group: 'Delegation',
+      description: 'Why the delegation exists (e.g. "Annual leave 5/26–5/30"). Recorded on the substitution audit row.',
+    }),
+
+    organization_id: Field.lookup('sys_organization', {
+      label: 'Organization',
+      required: false,
+      group: 'System',
+      description: 'Tenant that owns this rule; null = applies across tenants for this delegator.',
+    }),
+
+    created_at: Field.datetime({
+      label: 'Created At',
+      defaultValue: 'NOW()',
+      readonly: true,
+      group: 'System',
+    }),
+
+    updated_at: Field.datetime({
+      label: 'Updated At',
+      defaultValue: 'NOW()',
+      readonly: true,
+      group: 'System',
+    }),
+  },
+
+  indexes: [
+    // Resolution-time lookup: "active delegations for this delegator".
+    { fields: ['delegator_id', 'organization_id'] },
+    { fields: ['delegate_id'] },
+    { fields: ['valid_until'] },
+  ],
+
+  enable: {
+    trackHistory: true,
+    searchable: true,
+    apiEnabled: true,
+    apiMethods: ['get', 'list', 'create', 'update', 'delete'],
+    trash: true,
+    mru: false,
+  },
+});

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

@@ -0,0 +1,103 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Contract test for the server-declared decision actions on
+ * `sys_approval_request` (objectui#2678 P2-4 / retire-hardcoded-buttons).
+ *
+ * The console's generic action runtime renders + executes these wherever the
+ * object is surfaced (the approvals inbox included), so the inbox no longer
+ * hand-writes a button per capability. That only holds if the declared set
+ * stays faithful to the REST routes it targets and to the who-can-act gating.
+ * This pins both:
+ *
+ *   • every `type:'api'` target resolves `{id}` and points at a route that the
+ *     REST server actually registers (approve/reject/reassign/recall/remind/
+ *     request-info/revise/resubmit) — a typo'd verb would 404 silently in the UI;
+ *   • submitter-only levers (remind/recall/resubmit) gate on
+ *     `submitter_id == ctx.user.id` so a non-submitter never sees them.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { SysApprovalRequest } from './sys-approval-request.object.js';
+
+const actions = (SysApprovalRequest as any).actions as any[];
+const byName = (n: string) => actions.find((a) => a.name === n);
+/** `ObjectSchema.create` normalizes `visible` strings into a
+ *  `{ dialect: 'cel', source }` envelope — read the source for substring asserts. */
+const vis = (n: string): string => {
+  const v = byName(n).visible;
+  return typeof v === 'string' ? v : String(v?.source ?? '');
+};
+
+/** Verbs the REST server registers under `/api/v1/approvals/requests/:id/*`. */
+const ROUTE_VERBS = new Set([
+  'approve', 'reject', 'reassign', 'recall', 'remind', 'request-info', 'revise', 'resubmit',
+]);
+
+describe('sys_approval_request declared actions', () => {
+  it('declares the full decision + continuity set', () => {
+    expect(actions.map((a) => a.name).sort()).toEqual(
+      [
+        'approval_approve',
+        'approval_recall',
+        'approval_reassign',
+        'approval_reject',
+        'approval_remind',
+        'approval_request_info',
+        'approval_resubmit',
+        'approval_send_back',
+      ].sort(),
+    );
+  });
+
+  it('every api target points at a registered approvals route verb and injects {id}', () => {
+    for (const a of actions) {
+      expect(a.type).toBe('api');
+      expect(a.method).toBe('POST');
+      const m = /^\/api\/v1\/approvals\/requests\/\{id\}\/([a-z-]+)$/.exec(a.target);
+      expect(m, `${a.name} target ${a.target}`).not.toBeNull();
+      expect(ROUTE_VERBS.has(m![1]), `${a.name} → ${m![1]}`).toBe(true);
+      expect(a.refreshAfter).toBe(true);
+    }
+  });
+
+  it('gates on the server-computed viewer block (#3310): approver actions on can_act, submitter levers on is_submitter', () => {
+    for (const name of ['approval_remind', 'approval_recall', 'approval_resubmit']) {
+      expect(vis(name)).toContain('record.viewer.is_submitter');
+      expect(vis(name)).not.toContain('can_act');
+    }
+    for (const name of ['approval_approve', 'approval_reject', 'approval_send_back', 'approval_request_info', 'approval_reassign']) {
+      expect(vis(name)).toContain('record.viewer.can_act');
+      // who-can-act is server-derived, never a client identity guess
+      expect(vis(name)).not.toContain('ctx.user.id');
+      expect(vis(name)).not.toContain('is_submitter');
+    }
+  });
+
+  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();
+  });
+
+  it('reassign collects the new approver via a field-backed sys_user picker keyed as `to`', () => {
+    const toParam = byName('approval_reassign').params.find((p: any) => p.name === 'to');
+    expect(toParam).toMatchObject({ field: 'submitter_id', name: 'to', required: true });
+  });
+
+  it('request-info requires a comment; other params stay optional', () => {
+    const ri = byName('approval_request_info').params.find((p: any) => p.name === 'comment');
+    expect(ri.required).toBe(true);
+    for (const name of ['approval_send_back', 'approval_remind', 'approval_recall', 'approval_resubmit']) {
+      const c = byName(name).params.find((p: any) => p.name === 'comment');
+      expect(c.required ?? false).toBe(false);
+    }
+  });
+
+  it('approve/reject collect optional multi-file decision attachments', () => {
+    for (const name of ['approval_approve', 'approval_reject']) {
+      const att = byName(name).params.find((p: any) => p.name === 'attachments');
+      expect(att, `${name}.attachments`).toMatchObject({ type: 'file', multiple: true });
+      expect(att.required ?? false).toBe(false);
+    }
+  });
+});

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

@@ -28,7 +28,7 @@ export const SysApprovalRequest = ObjectSchema.create({
   pluralLabel: 'Approval Requests',
   icon: 'inbox',
   isSystem: true,
-  managedBy: 'system',
+  managedBy: 'engine-owned',
   description: 'Live approval instance tracked per submission',
   displayNameField: 'id',
   nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
@@ -229,4 +229,173 @@ export const SysApprovalRequest = ObjectSchema.create({
     { fields: ['status', 'updated_at'] },
     { fields: ['submitter_id', 'status'] },
   ],
+
+  // Server-declared decision actions (objectui#2678 P2-4). The console's
+  // generic action runtime renders and executes these wherever this object is
+  // surfaced — the approvals inbox included — so new decision capabilities
+  // (and their params) ship as metadata, not as hand-written buttons. Each
+  // targets the existing approvals REST route; `{id}` resolves from the row
+  // and `actorId` defaults to the caller server-side. The service remains the
+  // authority on who may act; `visible` gates on the server-computed
+  // 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.
+  actions: [
+    {
+      name: 'approval_approve',
+      label: 'Approve',
+      icon: 'check-circle',
+      type: 'api',
+      method: 'POST',
+      target: '/api/v1/approvals/requests/{id}/approve',
+      params: [
+        { name: 'comment', label: 'Comment', type: 'textarea', required: false },
+        // Decision attachments (#3266). The console renders `type:'file'` params
+        // through the shared upload widget and POSTs the resolved `attachments:
+        // 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',
+      locations: ['record_section', 'list_item'],
+      successMessage: 'Approved.',
+      refreshAfter: true,
+    },
+    {
+      name: 'approval_reject',
+      label: 'Reject',
+      icon: 'x-circle',
+      type: 'api',
+      method: 'POST',
+      target: '/api/v1/approvals/requests/{id}/reject',
+      params: [
+        { name: 'comment', label: 'Comment', type: 'textarea', required: false },
+        { name: 'attachments', label: 'Attachments', type: 'file', multiple: true, required: false },
+      ],
+      visible: 'record.viewer.can_act',
+      confirmText: 'Reject this request? A rejection is final for every approver.',
+      locations: ['record_section', 'list_item'],
+      successMessage: 'Rejected.',
+      refreshAfter: true,
+    },
+    {
+      name: 'approval_reassign',
+      label: 'Reassign',
+      icon: 'arrow-right-left',
+      type: 'api',
+      method: 'POST',
+      target: '/api/v1/approvals/requests/{id}/reassign',
+      params: [
+        // Field-backed on `submitter_id` (the object's only `sys_user` lookup):
+        // the console resolves its lookup config (`reference_to: sys_user`) so the
+        // dialog renders a real user picker, while `name: 'to'` overrides the
+        // request-body key to the `to` the reassign route expects. This is a
+        // config-borrow, not a submitter pre-fill (`defaultFromRow` stays off).
+        { 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',
+      locations: ['record_section'],
+      successMessage: 'Reassigned.',
+      refreshAfter: true,
+    },
+
+    // ── Approver secondary decisions ────────────────────────────────
+    // Send back for revision / request more info (ADR-0044). Both are approver
+    // actions, so `visible` gates on `record.viewer.can_act` (a current pending
+    // approver) — same as approve/reject. The service stays the authority.
+    {
+      name: 'approval_send_back',
+      label: 'Send back',
+      icon: 'corner-up-left',
+      type: 'api',
+      method: 'POST',
+      target: '/api/v1/approvals/requests/{id}/revise',
+      params: [
+        { name: 'comment', label: 'Reason', type: 'textarea', required: false },
+      ],
+      visible: 'record.viewer.can_act',
+      locations: ['record_section'],
+      successMessage: 'Sent back for revision.',
+      refreshAfter: true,
+    },
+    {
+      name: 'approval_request_info',
+      label: 'Request info',
+      icon: 'help-circle',
+      type: 'api',
+      method: 'POST',
+      target: '/api/v1/approvals/requests/{id}/request-info',
+      params: [
+        { name: 'comment', label: 'What do you need?', type: 'textarea', required: true },
+      ],
+      visible: 'record.viewer.can_act',
+      locations: ['record_section'],
+      successMessage: 'Information requested.',
+      refreshAfter: true,
+    },
+
+    // ── Submitter continuity actions ────────────────────────────────
+    // Remind / recall (pending) and resubmit / recall (returned). These are the
+    // submitter's own levers, so `visible` gates on `record.viewer.is_submitter`
+    // (server-computed on the current viewer). The service re-checks ownership;
+    // the predicate keeps a non-submitter from ever seeing a button they cannot
+    // use.
+    {
+      name: 'approval_remind',
+      label: 'Send reminder',
+      icon: 'bell-ring',
+      type: 'api',
+      method: 'POST',
+      target: '/api/v1/approvals/requests/{id}/remind',
+      params: [
+        { name: 'comment', label: 'Note', type: 'textarea', required: false },
+      ],
+      visible: 'record.status == "pending" && record.viewer.is_submitter',
+      locations: ['record_section'],
+      successMessage: 'Reminder sent.',
+      refreshAfter: true,
+    },
+    {
+      name: 'approval_recall',
+      label: 'Recall',
+      icon: 'undo-2',
+      type: 'api',
+      method: 'POST',
+      target: '/api/v1/approvals/requests/{id}/recall',
+      params: [
+        { name: 'comment', label: 'Comment', type: 'textarea', required: false },
+      ],
+      // Recall applies while the request is live for the submitter — pending
+      // (withdraw) or returned (abandon the revision instead of resubmitting).
+      visible: '(record.status == "pending" || record.status == "returned") && record.viewer.is_submitter',
+      confirmText: 'Recall this request? Approvers can no longer act on it and the record is unlocked.',
+      locations: ['record_section'],
+      successMessage: 'Recalled.',
+      refreshAfter: true,
+    },
+    {
+      name: 'approval_resubmit',
+      label: 'Resubmit',
+      icon: 'refresh-cw',
+      type: 'api',
+      method: 'POST',
+      target: '/api/v1/approvals/requests/{id}/resubmit',
+      params: [
+        { name: 'comment', label: 'What changed?', type: 'textarea', required: false },
+      ],
+      visible: 'record.status == "returned" && record.viewer.is_submitter',
+      locations: ['record_section'],
+      successMessage: 'Resubmitted.',
+      refreshAfter: true,
+    },
+  ],
+
+  enable: {
+    // [ADR-0103] Engine-owned: the approval engine owns the request lifecycle
+    // (SYSTEM_CTX); users act via domain actions (Submit/Approve/Recall), never
+    // generic CRUD. Reads stay open.
+    apiMethods: ['get', 'list'],
+  },
 });

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

@@ -19,7 +19,7 @@ export const SysApprovalToken = ObjectSchema.create({
   pluralLabel: 'Approval Action Tokens',
   icon: 'key',
   isSystem: true,
-  managedBy: 'system',
+  managedBy: 'engine-owned',
   description: 'Single-use tokens behind actionable approval links',
   displayNameField: 'id',
   nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
@@ -92,4 +92,10 @@ export const SysApprovalToken = ObjectSchema.create({
     { fields: ['token_hash'] },
     { fields: ['request_id'] },
   ],
+
+  enable: {
+    // [ADR-0103] Engine-owned: one-time email-approval tokens are minted and
+    // consumed by the approval engine (SYSTEM_CTX), never via the data API.
+    apiMethods: ['get', 'list'],
+  },
 });