@objectstack/plugin-approvals 9.2.0 → 9.4.0

package/dist/index.mjs

@@ -744,7 +744,9 @@ var SysApprovalRequest = ObjectSchema.create({
       group: "Target"
     }),
     status: Field.select(
-      ["pending", "approved", "rejected", "recalled"],
+      // Keep in sync with `ApprovalStatus` (spec/contracts). `returned` =
+      // sent back for revision (ADR-0044) — terminal for this round.
+      ["pending", "approved", "rejected", "recalled", "returned"],
       {
         label: "Status",
         required: true,
@@ -824,9 +826,11 @@ var SysApprovalRequest = ObjectSchema.create({
     // guard on submit and on edit-while-locked checks.
     { fields: ["object_name", "record_id"] },
     { fields: ["status", "object_name"] },
-    // "My approvals" inbox — pending_approvers is a CSV string so this
-    // index only helps with status pre-filtering; the engine does a
-    // post-filter substring match per row.
+    // Status-windowed listings (escalation sweep, "All" tab ordering).
+    // "My approvals" matching no longer scans this table: the service keeps
+    // a normalized per-approver index in `sys_approval_approver` (#1745) and
+    // resolves approver filters there; `pending_approvers` stays the
+    // human-readable CSV source of truth only.
     { fields: ["status", "updated_at"] },
     { fields: ["submitter_id", "status"] }
   ]
@@ -902,7 +906,11 @@ var SysApprovalAction = ObjectSchema2.create({
       group: "Target"
     }),
     action: Field2.select(
-      ["submit", "approve", "reject", "recall", "escalate"],
+      // 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"],
       {
         label: "Action",
         required: true,
@@ -929,10 +937,65 @@ var SysApprovalAction = ObjectSchema2.create({
   ]
 });
 
+// src/sys-approval-approver.object.ts
+import { ObjectSchema as ObjectSchema3, Field as Field3 } from "@objectstack/spec/data";
+var SysApprovalApprover = ObjectSchema3.create({
+  name: "sys_approval_approver",
+  label: "Approval Approver",
+  pluralLabel: "Approval Approvers",
+  icon: "users",
+  isSystem: true,
+  managedBy: "system",
+  description: "Normalized pending-approver rows for indexed inbox queries",
+  displayNameField: "id",
+  titleFormat: "{approver} \xB7 {request_id}",
+  compactLayout: ["request_id", "approver", "created_at"],
+  fields: {
+    id: Field3.text({ label: "Row ID", required: true, readonly: true, group: "System" }),
+    organization_id: Field3.lookup("sys_organization", {
+      label: "Organization",
+      required: false,
+      group: "System",
+      description: "Tenant that owns this row (mirrors the parent request)"
+    }),
+    request_id: Field3.lookup("sys_approval_request", {
+      label: "Request",
+      required: true,
+      group: "Target"
+    }),
+    approver: Field3.text({
+      label: "Approver",
+      required: true,
+      maxLength: 255,
+      description: "One pending-approver identity: user id, email, or role:/team: literal",
+      group: "Target"
+    }),
+    created_at: Field3.datetime({
+      label: "Created At",
+      required: true,
+      defaultValue: "NOW()",
+      readonly: true,
+      group: "System"
+    })
+  },
+  indexes: [
+    // "My pending" inbox: equality on the identity literal, scoped by tenant.
+    { fields: ["approver", "organization_id"] },
+    // Sync path: rewrite all rows of one request on each approver-set change.
+    { fields: ["request_id"] }
+  ]
+});
+
 // src/approval-service.ts
+import { createHash, randomBytes } from "crypto";
 import {
   APPROVAL_BRANCH_LABELS
 } from "@objectstack/spec/automation";
+var REMIND_COOLDOWN_MS = 4 * 60 * 60 * 1e3;
+var ESCALATION_JOB_NAME = "approvals-sla-escalation";
+var ESCALATION_SCAN_INTERVAL_MS = 5 * 60 * 1e3;
+var SLA_ACTOR_ID = "system:sla";
+var ACTION_TOKEN_TTL_MS = 72 * 60 * 60 * 1e3;
 var SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] };
 function uid(prefix) {
   const g = globalThis;
@@ -984,9 +1047,19 @@ function rowFromRequest(row) {
     // The row is created at submission time; expose the stable inbox-facing name.
     submitted_at: row.created_at ?? void 0,
     process_label: cfg?.__flowLabel ?? prettifyMachineName(row.process_name),
-    step_label: cfg?.__nodeLabel ?? prettifyMachineName(row.current_step)
+    step_label: cfg?.__nodeLabel ?? prettifyMachineName(row.current_step),
+    sla_due_at: slaDueAt(row.created_at, cfg),
+    // ADR-0044 revision round (rides the config snapshot; absent ⇒ round 1).
+    round: typeof cfg?.__round === "number" ? cfg.__round : void 0
   };
 }
+function slaDueAt(createdAt, cfg) {
+  const hours = cfg?.escalation?.timeoutHours;
+  if (typeof hours !== "number" || hours <= 0 || !createdAt) return void 0;
+  const t = Date.parse(String(createdAt));
+  if (Number.isNaN(t)) return void 0;
+  return new Date(t + hours * 36e5).toISOString();
+}
 function rowFromAction(row) {
   return {
     id: String(row.id),
@@ -999,17 +1072,51 @@ function rowFromAction(row) {
     created_at: row.created_at ?? void 0
   };
 }
-var ApprovalService = class _ApprovalService {
+var _ApprovalService = class _ApprovalService {
   constructor(opts) {
     this.engine = opts.engine;
     this.clock = opts.clock ?? { now: () => /* @__PURE__ */ new Date() };
     this.logger = opts.logger;
     this.automation = opts.automation;
+    this.messaging = opts.messaging;
+    this.publicBaseUrl = (opts.publicBaseUrl ?? "").replace(/\/$/, "");
   }
   /** Attach (or replace) the automation surface used to resume flow runs. */
   attachAutomation(automation) {
     this.automation = automation;
   }
+  /** Attach (or replace) the messaging surface used for thread notifications. */
+  attachMessaging(messaging) {
+    this.messaging = messaging;
+  }
+  /** Best-effort notification fan-out — failures only log. */
+  async notify(input) {
+    const audience = input.audience.filter((a) => a && !a.includes(":"));
+    if (!this.messaging || !audience.length) return 0;
+    try {
+      await this.messaging.emit({ severity: "info", ...input, audience });
+      return audience.length;
+    } catch (err) {
+      this.logger?.warn?.("[approvals] notification failed", {
+        topic: input.topic,
+        error: err?.message ?? String(err)
+      });
+      return 0;
+    }
+  }
+  /** Load a request row and assert it is still pending. */
+  async loadPendingRow(requestId) {
+    if (!requestId) throw new Error("VALIDATION_FAILED: requestId is required");
+    const rows = await this.engine.find("sys_approval_request", {
+      where: { id: requestId },
+      limit: 1,
+      context: SYSTEM_CTX
+    });
+    const raw = Array.isArray(rows) ? rows[0] : null;
+    if (!raw) throw new Error(`REQUEST_NOT_FOUND: ${requestId}`);
+    if (raw.status !== "pending") throw new Error(`INVALID_STATE: request is ${raw.status}`);
+    return raw;
+  }
   /**
    * Expand the approvers on an Approval node into user IDs by querying the
    * graph tables for `team:` / `department:` / `role:` / `manager:` approver
@@ -1204,6 +1311,16 @@ var ApprovalService = class _ApprovalService {
     const configSnapshot = { ...input.config };
     if (input.flowLabel) configSnapshot.__flowLabel = input.flowLabel;
     if (input.nodeLabel) configSnapshot.__nodeLabel = input.nodeLabel;
+    try {
+      const prior = await this.engine.find("sys_approval_request", {
+        where: { flow_run_id: input.runId, flow_node_id: input.nodeId },
+        limit: 500,
+        context: SYSTEM_CTX
+      });
+      const n = Array.isArray(prior) ? prior.length : 0;
+      if (n > 0) configSnapshot.__round = n + 1;
+    } catch {
+    }
     const row = {
       id,
       process_name: processName,
@@ -1223,6 +1340,7 @@ var ApprovalService = class _ApprovalService {
       updated_at: now
     };
     await this.engine.insert("sys_approval_request", row, { context: SYSTEM_CTX });
+    await this.syncApproverIndex(id, approvers, ctxOrg, now);
     await this.engine.insert("sys_approval_action", {
       id: uid("aact"),
       request_id: id,
@@ -1299,6 +1417,7 @@ var ApprovalService = class _ApprovalService {
           pending_approvers: stillPending.join(","),
           updated_at: now
         }, { context: SYSTEM_CTX });
+        await this.syncApproverIndex(requestId, stillPending, org, now);
         const fresh2 = await this.getRequest(requestId, context);
         return { request: fresh2, runId, nodeId, finalized: false, decision: input.decision };
       }
@@ -1311,6 +1430,7 @@ var ApprovalService = class _ApprovalService {
       completed_at: now,
       updated_at: now
     }, { context: SYSTEM_CTX });
+    await this.syncApproverIndex(requestId, [], org, now);
     if (config.approvalStatusField) {
       await this.mirrorStatusField(raw.object_name, raw.record_id, config.approvalStatusField, finalStatus);
     }
@@ -1353,8 +1473,14 @@ var ApprovalService = class _ApprovalService {
    * Withdraw a pending request (submitter only). Finalises the row as
    * `recalled`, releases the record lock (keyed on pending status), mirrors
    * the status field when configured, and resumes the owning flow run down
-   * the `reject` branch with `output.decision = 'recall'` — the engine has no
-   * run-cancel primitive, and leaving the run suspended forever would leak it.
+   * the `reject` branch with `output.decision = 'recall'` — leaving the run
+   * suspended forever would leak it.
+   *
+   * ADR-0044: also valid on the LATEST `returned` request of its run — the
+   * submitter abandons the revision window instead of resubmitting. The run
+   * is then paused at the revise wait node (no reject edge), so it is
+   * terminally cancelled via {@link ApprovalResumeSurface.cancelRun} rather
+   * than resumed.
    */
   async recall(requestId, input, context) {
     if (!requestId) throw new Error("VALIDATION_FAILED: requestId is required");
@@ -1366,10 +1492,14 @@ var ApprovalService = class _ApprovalService {
     });
     const raw = Array.isArray(rawRows) ? rawRows[0] : null;
     if (!raw) throw new Error(`REQUEST_NOT_FOUND: ${requestId}`);
-    if (raw.status !== "pending") throw new Error(`INVALID_STATE: request is ${raw.status}`);
+    const inReviseWindow = raw.status === "returned";
+    if (raw.status !== "pending" && !inReviseWindow) {
+      throw new Error(`INVALID_STATE: request is ${raw.status}`);
+    }
     if (!context.isSystem && raw.submitter_id && String(raw.submitter_id) !== String(input.actorId)) {
       throw new Error(`FORBIDDEN: only the submitter may recall this request`);
     }
+    if (inReviseWindow) await this.assertLatestForRun(raw);
     const config = parseJson(raw.node_config_json, { approvers: [], behavior: "first_response" });
     const org = raw.organization_id ?? null;
     const nodeId = raw.flow_node_id ?? raw.current_step ?? null;
@@ -1393,11 +1523,24 @@ var ApprovalService = class _ApprovalService {
       completed_at: now,
       updated_at: now
     }, { context: SYSTEM_CTX });
+    await this.syncApproverIndex(requestId, [], org, now);
     if (config.approvalStatusField) {
       await this.mirrorStatusField(raw.object_name, raw.record_id, config.approvalStatusField, "recalled");
     }
     let resumed = false;
-    if (runId && typeof this.automation?.resume === "function") {
+    if (inReviseWindow) {
+      if (runId && typeof this.automation?.cancelRun === "function") {
+        try {
+          await this.automation.cancelRun(runId, `approval request ${requestId} recalled during revision`);
+        } catch (err) {
+          this.logger?.warn?.("[approvals] cancelRun after revise-window recall failed", {
+            request: requestId,
+            run: runId,
+            error: err?.message ?? String(err)
+          });
+        }
+      }
+    } else if (runId && typeof this.automation?.resume === "function") {
       try {
         await this.automation.resume(runId, {
           branchLabel: APPROVAL_BRANCH_LABELS.reject,
@@ -1415,6 +1558,676 @@ var ApprovalService = class _ApprovalService {
     const fresh = await this.getRequest(requestId, context);
     return { request: fresh, runId, resumed };
   }
+  // ── Send back for revision / resubmit (ADR-0044) ─────────────
+  /**
+   * ADR-0044 send back for revision. Finalises the pending request as
+   * `returned` (a third terminal state — approver-initiated rework, distinct
+   * from submitter-initiated `recalled`) and resumes the owning flow run down
+   * its `revise` edge to a wait point: the record lock (keyed on `pending`)
+   * releases, the submitter reworks the data, then {@link resubmit}s.
+   *
+   * Requires the approval node to declare a `revise` out-edge — validated
+   * BEFORE any mutation, because resuming with an unmatched `branchLabel`
+   * falls back to *all* out-edges. Past the node's `maxRevisions` budget the
+   * request auto-rejects instead (resumes down `reject` with
+   * `output.autoRejected = true`) so instances cannot orbit forever.
+   */
+  async sendBack(requestId, input, context) {
+    if (!input?.actorId) throw new Error("VALIDATION_FAILED: actorId is required");
+    const raw = await this.loadPendingRow(requestId);
+    const pending = csvSplit(raw.pending_approvers);
+    if (!context.isSystem && !pending.includes(input.actorId)) {
+      throw new Error(`FORBIDDEN: actor '${input.actorId}' is not a pending approver`);
+    }
+    const config = parseJson(raw.node_config_json, { approvers: [], behavior: "first_response" });
+    const org = raw.organization_id ?? null;
+    const nodeId = raw.flow_node_id ?? raw.current_step ?? null;
+    const runId = raw.flow_run_id ?? null;
+    await this.assertReviseEdge(raw, nodeId);
+    const now = this.clock.now().toISOString();
+    const maxRevisions = typeof config.maxRevisions === "number" ? config.maxRevisions : 3;
+    let priorSendBacks = 0;
+    if (runId && nodeId) {
+      const siblings = await this.engine.find("sys_approval_request", {
+        where: { flow_run_id: runId, flow_node_id: nodeId, status: "returned" },
+        limit: 500,
+        context: SYSTEM_CTX
+      });
+      priorSendBacks = Array.isArray(siblings) ? siblings.length : 0;
+    }
+    await this.engine.insert("sys_approval_action", {
+      id: uid("aact"),
+      request_id: requestId,
+      organization_id: org,
+      step_name: nodeId,
+      step_index: 0,
+      action: "revise",
+      actor_id: input.actorId,
+      comment: input.comment ?? null,
+      created_at: now
+    }, { context: SYSTEM_CTX });
+    if (priorSendBacks >= maxRevisions) {
+      await this.engine.insert("sys_approval_action", {
+        id: uid("aact"),
+        request_id: requestId,
+        organization_id: org,
+        step_name: nodeId,
+        step_index: 0,
+        action: "reject",
+        actor_id: input.actorId,
+        comment: `Auto-rejected: revision limit (${maxRevisions}) exceeded`,
+        created_at: now
+      }, { context: SYSTEM_CTX });
+      await this.engine.update("sys_approval_request", {
+        id: requestId,
+        status: "rejected",
+        pending_approvers: null,
+        completed_at: now,
+        updated_at: now
+      }, { context: SYSTEM_CTX });
+      await this.syncApproverIndex(requestId, [], org, now);
+      if (config.approvalStatusField) {
+        await this.mirrorStatusField(raw.object_name, raw.record_id, config.approvalStatusField, "rejected");
+      }
+      let resumed2 = false;
+      if (runId && typeof this.automation?.resume === "function") {
+        try {
+          await this.automation.resume(runId, {
+            branchLabel: APPROVAL_BRANCH_LABELS.reject,
+            output: { decision: "reject", autoRejected: true, requestId }
+          });
+          resumed2 = true;
+        } catch (err) {
+          this.logger?.warn?.("[approvals] resume after auto-reject failed", {
+            request: requestId,
+            run: runId,
+            error: err?.message ?? String(err)
+          });
+        }
+      }
+      if (raw.submitter_id) {
+        await this.notify({
+          topic: "approval.returned",
+          audience: [String(raw.submitter_id)],
+          actorId: input.actorId,
+          source: { object: "sys_approval_request", id: requestId },
+          payload: {
+            title: "Approval auto-rejected",
+            message: `Your ${raw.object_name}/${raw.record_id} exceeded the revision limit (${maxRevisions}) and was rejected.`,
+            actionUrl: "/system/approvals"
+          }
+        });
+      }
+      const fresh2 = await this.getRequest(requestId, context);
+      return { request: fresh2, runId, resumed: resumed2, autoRejected: true };
+    }
+    await this.engine.update("sys_approval_request", {
+      id: requestId,
+      status: "returned",
+      pending_approvers: null,
+      completed_at: now,
+      updated_at: now
+    }, { context: SYSTEM_CTX });
+    await this.syncApproverIndex(requestId, [], org, now);
+    if (config.approvalStatusField) {
+      await this.mirrorStatusField(raw.object_name, raw.record_id, config.approvalStatusField, "returned");
+    }
+    let resumed = false;
+    if (runId && typeof this.automation?.resume === "function") {
+      try {
+        await this.automation.resume(runId, {
+          branchLabel: APPROVAL_BRANCH_LABELS.revise,
+          output: { decision: "revise", requestId }
+        });
+        resumed = true;
+      } catch (err) {
+        this.logger?.warn?.("[approvals] resume after send-back failed", {
+          request: requestId,
+          run: runId,
+          error: err?.message ?? String(err)
+        });
+      }
+    }
+    if (raw.submitter_id) {
+      await this.notify({
+        topic: "approval.returned",
+        audience: [String(raw.submitter_id)],
+        actorId: input.actorId,
+        source: { object: "sys_approval_request", id: requestId },
+        payload: {
+          title: "Sent back for revision",
+          message: input.comment?.trim() || `Your ${raw.object_name}/${raw.record_id} needs rework before it can be approved.`,
+          actionUrl: "/system/approvals"
+        }
+      });
+    }
+    const fresh = await this.getRequest(requestId, context);
+    return { request: fresh, runId, resumed };
+  }
+  /**
+   * ADR-0044 resubmit after rework. Valid on the LATEST `returned` request of
+   * its run, submitter-only. Audits `resubmit` on the returned (round-N)
+   * request and resumes the run from the revise wait node; traversal walks
+   * the declared back-edge into the approval node, whose executor opens the
+   * round-N+1 request — fresh approver slate, record re-locks.
+   */
+  async resubmit(requestId, input, context) {
+    if (!input?.actorId) throw new Error("VALIDATION_FAILED: actorId is required");
+    const rawRows = await this.engine.find("sys_approval_request", {
+      where: { id: requestId },
+      limit: 1,
+      context: SYSTEM_CTX
+    });
+    const raw = Array.isArray(rawRows) ? rawRows[0] : null;
+    if (!raw) throw new Error(`REQUEST_NOT_FOUND: ${requestId}`);
+    if (raw.status !== "returned") {
+      throw new Error(`INVALID_STATE: request is ${raw.status} (resubmit applies to returned requests)`);
+    }
+    if (!context.isSystem && raw.submitter_id && String(raw.submitter_id) !== String(input.actorId)) {
+      throw new Error("FORBIDDEN: only the submitter may resubmit");
+    }
+    await this.assertLatestForRun(raw);
+    const colliding = await this.engine.find("sys_approval_request", {
+      where: { object_name: raw.object_name, record_id: raw.record_id, status: "pending" },
+      limit: 1,
+      context: SYSTEM_CTX
+    });
+    if (Array.isArray(colliding) && colliding[0]) {
+      throw new Error(
+        `DUPLICATE_REQUEST: another approval request is already pending on ${raw.object_name}/${raw.record_id} \u2014 resolve it before resubmitting`
+      );
+    }
+    const org = raw.organization_id ?? null;
+    const nodeId = raw.flow_node_id ?? raw.current_step ?? null;
+    const runId = raw.flow_run_id ?? null;
+    const now = this.clock.now().toISOString();
+    await this.engine.insert("sys_approval_action", {
+      id: uid("aact"),
+      request_id: requestId,
+      organization_id: org,
+      step_name: nodeId,
+      step_index: 0,
+      action: "resubmit",
+      actor_id: input.actorId,
+      comment: input.comment ?? null,
+      created_at: now
+    }, { context: SYSTEM_CTX });
+    let resumed = false;
+    if (runId && typeof this.automation?.resume === "function") {
+      try {
+        await this.automation.resume(runId, {
+          branchLabel: APPROVAL_BRANCH_LABELS.resubmit,
+          output: { resubmitted: true, requestId }
+        });
+        resumed = true;
+      } catch (err) {
+        this.logger?.warn?.("[approvals] resume after resubmit failed", {
+          request: requestId,
+          run: runId,
+          error: err?.message ?? String(err)
+        });
+      }
+    }
+    const fresh = await this.getRequest(requestId, context);
+    return { request: fresh, runId, resumed };
+  }
+  /**
+   * ADR-0044 guard: the flow's approval node must declare a `revise`
+   * out-edge before send-back is allowed — the engine's branch-label fallback
+   * (no matching label ⇒ ALL out-edges) must never be reachable from a user
+   * action.
+   */
+  async assertReviseEdge(raw, nodeId) {
+    const processName = String(raw.process_name ?? "");
+    const flowName = processName.startsWith("flow:") ? processName.slice("flow:".length) : void 0;
+    if (!flowName || !nodeId || typeof this.automation?.getFlow !== "function") {
+      throw new Error("VALIDATION_FAILED: send-back requires the owning flow definition (automation engine unavailable)");
+    }
+    const flow = await this.automation.getFlow(flowName);
+    const hasRevise = Array.isArray(flow?.edges) && flow.edges.some((e) => e?.source === nodeId && e?.label === APPROVAL_BRANCH_LABELS.revise);
+    if (!hasRevise) {
+      throw new Error(
+        `VALIDATION_FAILED: approval node '${nodeId}' has no '${APPROVAL_BRANCH_LABELS.revise}' out-edge \u2014 the flow does not support send-back for revision`
+      );
+    }
+  }
+  /**
+   * ADR-0044 guard: a `returned` request is only actionable (resubmit /
+   * recall) while it is still the newest request on its run — a later round
+   * or a later node's request supersedes it.
+   */
+  async assertLatestForRun(raw) {
+    const runId = raw.flow_run_id;
+    if (!runId) return;
+    const rows = await this.engine.find("sys_approval_request", {
+      where: { flow_run_id: runId },
+      orderBy: [{ field: "created_at", order: "desc" }],
+      limit: 1,
+      context: SYSTEM_CTX
+    });
+    const latest = Array.isArray(rows) ? rows[0] : null;
+    if (latest && String(latest.id) !== String(raw.id)) {
+      throw new Error("INVALID_STATE: a newer approval request supersedes this one");
+    }
+  }
+  // ── Thread interactions (no flow movement) ───────────────────
+  /**
+   * Hand a pending-approver slot to someone else. `from` defaults to the
+   * actor itself; the actor must hold the slot being handed over (or be a
+   * system caller). Audits `reassign` and notifies the new approver.
+   */
+  async reassign(requestId, input, context) {
+    if (!input?.actorId) throw new Error("VALIDATION_FAILED: actorId is required");
+    const to = String(input?.to ?? "").trim();
+    if (!to) throw new Error("VALIDATION_FAILED: `to` (new approver) is required");
+    const raw = await this.loadPendingRow(requestId);
+    const pending = csvSplit(raw.pending_approvers);
+    const from = String(input.from ?? input.actorId).trim();
+    if (!pending.includes(from)) {
+      throw new Error(`FORBIDDEN: '${from}' is not a pending approver on this request`);
+    }
+    if (!context.isSystem && input.actorId !== from && !pending.includes(input.actorId)) {
+      throw new Error(`FORBIDDEN: actor '${input.actorId}' is not a pending approver`);
+    }
+    if (pending.includes(to)) {
+      throw new Error(`VALIDATION_FAILED: '${to}' is already a pending approver`);
+    }
+    const next = pending.map((a) => a === from ? to : a);
+    const now = this.clock.now().toISOString();
+    await this.engine.insert("sys_approval_action", {
+      id: uid("aact"),
+      request_id: requestId,
+      organization_id: raw.organization_id ?? null,
+      step_name: raw.flow_node_id ?? raw.current_step ?? null,
+      step_index: 0,
+      action: "reassign",
+      actor_id: input.actorId,
+      comment: input.comment ?? `${from} \u2192 ${to}`,
+      created_at: now
+    }, { context: SYSTEM_CTX });
+    await this.engine.update("sys_approval_request", {
+      id: requestId,
+      pending_approvers: next.join(","),
+      updated_at: now
+    }, { context: SYSTEM_CTX });
+    await this.syncApproverIndex(requestId, next, raw.organization_id ?? null, now);
+    await this.notify({
+      topic: "approval.reassigned",
+      audience: [to],
+      actorId: input.actorId,
+      source: { object: "sys_approval_request", id: requestId },
+      dedupKey: `approval-reassign-${requestId}-${to}`,
+      payload: {
+        title: "Approval handed to you",
+        message: `You are now an approver on ${raw.object_name}/${raw.record_id}.`,
+        actionUrl: "/system/approvals"
+      }
+    });
+    const fresh = await this.getRequest(requestId, context);
+    return { request: fresh };
+  }
+  /**
+   * Submitter nudge — notify every pending approver. Throttled to one
+   * reminder per {@link REMIND_COOLDOWN_MS} per request.
+   */
+  async remind(requestId, input, context) {
+    if (!input?.actorId) throw new Error("VALIDATION_FAILED: actorId is required");
+    const raw = await this.loadPendingRow(requestId);
+    if (!context.isSystem && raw.submitter_id && String(raw.submitter_id) !== String(input.actorId)) {
+      throw new Error("FORBIDDEN: only the submitter may send reminders");
+    }
+    const acts = await this.engine.find("sys_approval_action", {
+      where: { request_id: requestId, action: "remind" },
+      orderBy: [{ field: "created_at", order: "desc" }],
+      limit: 1,
+      context: SYSTEM_CTX
+    });
+    const last = Array.isArray(acts) ? acts[0] : null;
+    const now = this.clock.now();
+    if (last?.created_at && now.getTime() - Date.parse(last.created_at) < REMIND_COOLDOWN_MS) {
+      throw new Error("THROTTLED: a reminder was already sent recently");
+    }
+    const pending = csvSplit(raw.pending_approvers);
+    const nowIso = now.toISOString();
+    await this.engine.insert("sys_approval_action", {
+      id: uid("aact"),
+      request_id: requestId,
+      organization_id: raw.organization_id ?? null,
+      step_name: raw.flow_node_id ?? raw.current_step ?? null,
+      step_index: 0,
+      action: "remind",
+      actor_id: input.actorId,
+      comment: input.comment ?? null,
+      created_at: nowIso
+    }, { context: SYSTEM_CTX });
+    let notified = 0;
+    const concrete = pending.filter((a) => a && !a.includes(":"));
+    const literals = pending.filter((a) => a && a.includes(":"));
+    for (const approver of concrete) {
+      try {
+        const tokens = await this.issueActionTokens(requestId, approver);
+        notified += await this.notify({
+          topic: "approval.reminder",
+          audience: [approver],
+          actorId: input.actorId,
+          source: { object: "sys_approval_request", id: requestId },
+          dedupKey: `approval-remind-${requestId}-${nowIso}-${approver}`,
+          payload: {
+            title: "Approval reminder",
+            message: `A decision on ${raw.object_name}/${raw.record_id} is still waiting on you.`,
+            actionUrl: "/system/approvals",
+            actions: [
+              { label: "Approve", url: this.actionLinkUrl(tokens.approve) },
+              { label: "Reject", url: this.actionLinkUrl(tokens.reject) }
+            ]
+          }
+        });
+      } catch (err) {
+        this.logger?.warn?.("[approvals] reminder with action links failed", {
+          request: requestId,
+          approver,
+          error: err?.message ?? String(err)
+        });
+      }
+    }
+    if (literals.length) {
+      notified += await this.notify({
+        topic: "approval.reminder",
+        audience: literals,
+        actorId: input.actorId,
+        source: { object: "sys_approval_request", id: requestId },
+        dedupKey: `approval-remind-${requestId}-${nowIso}`,
+        payload: {
+          title: "Approval reminder",
+          message: `A decision on ${raw.object_name}/${raw.record_id} is still waiting on you.`,
+          actionUrl: "/system/approvals"
+        }
+      });
+    }
+    const fresh = await this.getRequest(requestId, context);
+    return { request: fresh, notified };
+  }
+  // ── Actionable links (ADR-0043) ──────────────────────────────
+  /** Build the session-less confirm-page URL for a raw token. */
+  actionLinkUrl(rawToken) {
+    return `${this.publicBaseUrl}/api/v1/approvals/act?token=${encodeURIComponent(rawToken)}`;
+  }
+  /**
+   * Issue one-tap approve/reject tokens for one approver on one pending
+   * request. Raw tokens are returned ONCE; only SHA-256 hashes are stored
+   * (`sys_approval_token`), so a DB leak yields no usable links.
+   */
+  async issueActionTokens(requestId, approverId, opts) {
+    if (!approverId?.trim()) throw new Error("VALIDATION_FAILED: approverId is required");
+    const raw = await this.loadPendingRow(requestId);
+    const pending = csvSplit(raw.pending_approvers);
+    if (!pending.includes(approverId)) {
+      throw new Error(`FORBIDDEN: '${approverId}' is not a pending approver on this request`);
+    }
+    const now = this.clock.now();
+    const expires = new Date(now.getTime() + (opts?.ttlMs ?? ACTION_TOKEN_TTL_MS)).toISOString();
+    const out = { approve: "", reject: "" };
+    for (const action of ["approve", "reject"]) {
+      const rawToken = randomBytes(32).toString("base64url");
+      await this.engine.insert("sys_approval_token", {
+        id: uid("atok"),
+        organization_id: raw.organization_id ?? null,
+        token_hash: createHash("sha256").update(rawToken).digest("hex"),
+        request_id: requestId,
+        action,
+        approver_id: approverId,
+        expires_at: expires,
+        consumed_at: null,
+        created_at: now.toISOString()
+      }, { context: SYSTEM_CTX });
+      out[action] = rawToken;
+    }
+    return out;
+  }
+  /** Shared validation chain for peek/redeem. Returns the token row when live. */
+  async resolveActionToken(rawToken) {
+    const trimmed = rawToken?.trim();
+    if (!trimmed) return { ok: false, reason: "invalid" };
+    const hash = createHash("sha256").update(trimmed).digest("hex");
+    const rows = await this.engine.find("sys_approval_token", {
+      where: { token_hash: hash },
+      limit: 1,
+      context: SYSTEM_CTX
+    });
+    const token = Array.isArray(rows) ? rows[0] : null;
+    if (!token) return { ok: false, reason: "invalid" };
+    if (token.consumed_at) return { ok: false, reason: "consumed" };
+    if (Date.parse(token.expires_at) < this.clock.now().getTime()) {
+      return { ok: false, reason: "expired" };
+    }
+    const request = await this.getRequest(token.request_id, SYSTEM_CTX);
+    if (!request || request.status !== "pending") {
+      return { ok: false, reason: "not_pending", request: request ?? void 0 };
+    }
+    if (!(request.pending_approvers ?? []).includes(token.approver_id)) {
+      return { ok: false, reason: "not_approver", request };
+    }
+    return { ok: true, token, request };
+  }
+  /** GET confirm page: validate WITHOUT consuming — never mutates. */
+  async peekActionToken(rawToken) {
+    const res = await this.resolveActionToken(rawToken);
+    if (!res.ok) return res;
+    return { ok: true, action: res.token.action, request: res.request, approverId: res.token.approver_id };
+  }
+  /**
+   * POST redemption: consume the token FIRST (a failed decide still burns
+   * it — replay-safe), then decide as the bound approver.
+   */
+  async redeemActionToken(rawToken) {
+    const res = await this.resolveActionToken(rawToken);
+    if (!res.ok) return res;
+    await this.engine.update("sys_approval_token", {
+      id: res.token.id,
+      consumed_at: this.clock.now().toISOString()
+    }, { context: SYSTEM_CTX });
+    const out = await this.decide(res.token.request_id, {
+      decision: res.token.action,
+      actorId: res.token.approver_id,
+      comment: "Via action link"
+    }, SYSTEM_CTX);
+    return { ok: true, action: res.token.action, request: out.request, approverId: res.token.approver_id };
+  }
+  /**
+   * Approver asks the submitter for more information. The request stays
+   * pending — a thread interaction, not a flow decision.
+   */
+  async requestInfo(requestId, input, context) {
+    if (!input?.actorId) throw new Error("VALIDATION_FAILED: actorId is required");
+    if (!input?.comment?.trim()) throw new Error("VALIDATION_FAILED: comment is required");
+    const raw = await this.loadPendingRow(requestId);
+    const pending = csvSplit(raw.pending_approvers);
+    if (!context.isSystem && !pending.includes(input.actorId)) {
+      throw new Error(`FORBIDDEN: actor '${input.actorId}' is not a pending approver`);
+    }
+    const now = this.clock.now().toISOString();
+    await this.engine.insert("sys_approval_action", {
+      id: uid("aact"),
+      request_id: requestId,
+      organization_id: raw.organization_id ?? null,
+      step_name: raw.flow_node_id ?? raw.current_step ?? null,
+      step_index: 0,
+      action: "request_info",
+      actor_id: input.actorId,
+      comment: input.comment.trim(),
+      created_at: now
+    }, { context: SYSTEM_CTX });
+    if (raw.submitter_id) {
+      await this.notify({
+        topic: "approval.request_info",
+        audience: [String(raw.submitter_id)],
+        actorId: input.actorId,
+        source: { object: "sys_approval_request", id: requestId },
+        payload: {
+          title: "More information requested",
+          message: input.comment.trim(),
+          actionUrl: "/system/approvals"
+        }
+      });
+    }
+    const fresh = await this.getRequest(requestId, context);
+    return { request: fresh };
+  }
+  /** Free-form reply on the thread (submitter or any pending approver). */
+  async comment(requestId, input, context) {
+    if (!input?.actorId) throw new Error("VALIDATION_FAILED: actorId is required");
+    if (!input?.comment?.trim()) throw new Error("VALIDATION_FAILED: comment is required");
+    const raw = await this.loadPendingRow(requestId);
+    const pending = csvSplit(raw.pending_approvers);
+    const isSubmitter = raw.submitter_id && String(raw.submitter_id) === String(input.actorId);
+    if (!context.isSystem && !isSubmitter && !pending.includes(input.actorId)) {
+      throw new Error(`FORBIDDEN: actor '${input.actorId}' is not on this request`);
+    }
+    const now = this.clock.now().toISOString();
+    await this.engine.insert("sys_approval_action", {
+      id: uid("aact"),
+      request_id: requestId,
+      organization_id: raw.organization_id ?? null,
+      step_name: raw.flow_node_id ?? raw.current_step ?? null,
+      step_index: 0,
+      action: "comment",
+      actor_id: input.actorId,
+      comment: input.comment.trim(),
+      created_at: now
+    }, { context: SYSTEM_CTX });
+    const audience = isSubmitter ? pending : [String(raw.submitter_id ?? "")].filter(Boolean);
+    await this.notify({
+      topic: "approval.comment",
+      audience,
+      actorId: input.actorId,
+      source: { object: "sys_approval_request", id: requestId },
+      payload: {
+        title: "New comment on an approval",
+        message: input.comment.trim(),
+        actionUrl: "/system/approvals"
+      }
+    });
+    const fresh = await this.getRequest(requestId, context);
+    return { request: fresh };
+  }
+  // ── SLA escalation (ADR-0042) ─────────────────────────────────
+  /**
+   * One escalation sweep: every *pending* request whose node config declares
+   * `escalation.timeoutHours` and whose deadline has passed is escalated
+   * **at most once, ever** — the `escalate` audit row is the idempotency
+   * marker, written before any mutation (audit-first, like reassign). One
+   * bad row never stops the sweep.
+   */
+  async runEscalations() {
+    let rows = [];
+    try {
+      rows = await this.engine.find("sys_approval_request", {
+        where: { status: "pending" },
+        limit: 500,
+        context: SYSTEM_CTX
+      }) ?? [];
+    } catch (err) {
+      this.logger?.warn?.("[approvals] escalation scan failed to list requests", {
+        error: err?.message ?? String(err)
+      });
+      return { scanned: 0, escalated: 0 };
+    }
+    let escalated = 0;
+    for (const raw of rows) {
+      try {
+        const cfg = parseJson(raw.node_config_json, void 0);
+        const esc2 = cfg?.escalation;
+        if (!esc2 || typeof esc2.timeoutHours !== "number" || esc2.timeoutHours <= 0) continue;
+        const due = slaDueAt(raw.created_at, cfg);
+        if (!due || Date.parse(due) > this.clock.now().getTime()) continue;
+        const prior = await this.engine.find("sys_approval_action", {
+          where: { request_id: raw.id, action: "escalate" },
+          limit: 1,
+          context: SYSTEM_CTX
+        });
+        if (Array.isArray(prior) && prior[0]) continue;
+        await this.escalateRequest(raw, esc2);
+        escalated++;
+      } catch (err) {
+        this.logger?.warn?.("[approvals] escalation failed for request", {
+          request: raw?.id,
+          error: err?.message ?? String(err)
+        });
+      }
+    }
+    if (escalated > 0) {
+      this.logger?.info?.("[approvals] SLA escalation sweep", { scanned: rows.length, escalated });
+    }
+    return { scanned: rows.length, escalated };
+  }
+  /** Execute the configured escalation action for one overdue request. */
+  async escalateRequest(raw, esc2) {
+    const action = esc2.action ?? "notify";
+    const escalateTo = typeof esc2.escalateTo === "string" && esc2.escalateTo.trim() ? esc2.escalateTo.trim() : void 0;
+    const now = this.clock.now().toISOString();
+    const pending = csvSplit(raw.pending_approvers);
+    await this.engine.insert("sys_approval_action", {
+      id: uid("aact"),
+      request_id: raw.id,
+      organization_id: raw.organization_id ?? null,
+      step_name: raw.flow_node_id ?? raw.current_step ?? null,
+      step_index: 0,
+      action: "escalate",
+      actor_id: SLA_ACTOR_ID,
+      comment: `${action}${escalateTo ? ` \u2192 ${escalateTo}` : ""}`,
+      created_at: now
+    }, { context: SYSTEM_CTX });
+    if (action === "reassign" && escalateTo) {
+      await this.engine.update("sys_approval_request", {
+        id: raw.id,
+        pending_approvers: escalateTo,
+        updated_at: now
+      }, { context: SYSTEM_CTX });
+      await this.syncApproverIndex(raw.id, [escalateTo], raw.organization_id ?? null, now);
+      await this.notify({
+        topic: "approval.escalated",
+        audience: [escalateTo],
+        actorId: SLA_ACTOR_ID,
+        source: { object: "sys_approval_request", id: raw.id },
+        payload: {
+          title: "Approval escalated to you",
+          message: `An overdue approval on ${raw.object_name}/${raw.record_id} was escalated to you.`,
+          actionUrl: "/system/approvals"
+        }
+      });
+    } else if (action === "auto_approve" || action === "auto_reject") {
+      await this.decide(raw.id, {
+        decision: action === "auto_approve" ? "approve" : "reject",
+        actorId: SLA_ACTOR_ID,
+        comment: "SLA escalation"
+      }, SYSTEM_CTX);
+    } else {
+      await this.notify({
+        topic: "approval.sla_breached",
+        audience: [...pending, ...escalateTo ? [escalateTo] : []],
+        actorId: SLA_ACTOR_ID,
+        source: { object: "sys_approval_request", id: raw.id },
+        payload: {
+          title: "Approval SLA breached",
+          message: `A decision on ${raw.object_name}/${raw.record_id} is overdue.`,
+          actionUrl: "/system/approvals"
+        }
+      });
+    }
+    if (esc2.notifySubmitter !== false && raw.submitter_id) {
+      await this.notify({
+        topic: "approval.sla_breached",
+        audience: [String(raw.submitter_id)],
+        actorId: SLA_ACTOR_ID,
+        source: { object: "sys_approval_request", id: raw.id },
+        payload: {
+          title: "Your approval request breached its SLA",
+          message: `${raw.object_name}/${raw.record_id}: escalation action '${action}' was taken.`,
+          actionUrl: "/system/approvals"
+        }
+      });
+    }
+  }
   // ── Display enrichment ───────────────────────────────────────
   /**
    * Resolve the schema-declared display field for an object, when the engine
@@ -1612,37 +2425,208 @@ var ApprovalService = class _ApprovalService {
       }
     }
   }
+  // ── Pending-approver index (issue #1745) ─────────────────────
+  /**
+   * Mirror one request's `pending_approvers` CSV into the normalized
+   * `sys_approval_approver` index. Called by every write path that changes
+   * the approver set; an empty `approvers` clears the request's rows (the
+   * request left `pending`). Diff-based so reassign/unanimous churn doesn't
+   * rewrite untouched rows.
+   */
+  async syncApproverIndex(requestId, approvers, org, now) {
+    const desired = new Set(approvers.map((a) => String(a).trim()).filter(Boolean));
+    const existing = await this.engine.find("sys_approval_approver", {
+      where: { request_id: requestId },
+      limit: 500,
+      context: SYSTEM_CTX
+    });
+    const rows = Array.isArray(existing) ? existing : [];
+    for (const row of rows) {
+      if (desired.has(String(row.approver))) desired.delete(String(row.approver));
+      else await this.engine.delete("sys_approval_approver", { where: { id: row.id }, context: SYSTEM_CTX });
+    }
+    for (const approver of desired) {
+      await this.engine.insert("sys_approval_approver", {
+        id: uid("aapr"),
+        request_id: requestId,
+        approver,
+        organization_id: org,
+        created_at: now
+      }, { context: SYSTEM_CTX });
+    }
+  }
+  /**
+   * Rebuild the whole `sys_approval_approver` index from the CSV source of
+   * truth. Idempotent; run at plugin start so rows written before the index
+   * existed (or drifted past a crashed sync) become queryable. Cost tracks
+   * the number of *pending* requests, not the request history.
+   */
+  async rebuildApproverIndex() {
+    const desired = /* @__PURE__ */ new Map();
+    const PAGE = 500;
+    for (let offset = 0; ; offset += PAGE) {
+      const batch = await this.engine.find("sys_approval_request", {
+        where: { status: "pending" },
+        fields: ["id", "pending_approvers", "organization_id"],
+        limit: PAGE,
+        offset,
+        context: SYSTEM_CTX
+      });
+      const rows = Array.isArray(batch) ? batch : [];
+      for (const r of rows) {
+        desired.set(String(r.id), {
+          approvers: new Set(csvSplit(r.pending_approvers)),
+          org: r.organization_id ?? null
+        });
+      }
+      if (rows.length < PAGE) break;
+    }
+    const indexRows = [];
+    for (let offset = 0; ; offset += PAGE) {
+      const batch = await this.engine.find("sys_approval_approver", {
+        orderBy: [{ field: "created_at", order: "asc" }],
+        limit: PAGE,
+        offset,
+        context: SYSTEM_CTX
+      });
+      const rows = Array.isArray(batch) ? batch : [];
+      indexRows.push(...rows);
+      if (rows.length < PAGE) break;
+    }
+    let inserted = 0;
+    let deleted = 0;
+    const seen = /* @__PURE__ */ new Map();
+    for (const row of indexRows) {
+      const reqId = String(row.request_id);
+      const want = desired.get(reqId);
+      const have = seen.get(reqId) ?? seen.set(reqId, /* @__PURE__ */ new Set()).get(reqId);
+      if (!want || !want.approvers.has(String(row.approver)) || have.has(String(row.approver))) {
+        await this.engine.delete("sys_approval_approver", { where: { id: row.id }, context: SYSTEM_CTX });
+        deleted++;
+        continue;
+      }
+      have.add(String(row.approver));
+    }
+    const now = this.clock.now().toISOString();
+    for (const [reqId, want] of desired) {
+      const have = seen.get(reqId);
+      for (const approver of want.approvers) {
+        if (have?.has(approver)) continue;
+        await this.engine.insert("sys_approval_approver", {
+          id: uid("aapr"),
+          request_id: reqId,
+          approver,
+          organization_id: want.org,
+          created_at: now
+        }, { context: SYSTEM_CTX });
+        inserted++;
+      }
+    }
+    return { requests: desired.size, inserted, deleted };
+  }
   // ── Read API ─────────────────────────────────────────────────
-  async listRequests(filter, context) {
+  /** Filter type accepted by {@link listRequests} / {@link countRequests}. */
+  buildRequestWhere(filter, context) {
     const f = {};
     if (filter?.object) f.object_name = filter.object;
     if (filter?.recordId) f.record_id = filter.recordId;
     if (filter?.submitterId) f.submitter_id = filter.submitterId;
-    const tenantOrg = context?.organizationId ?? context?.tenantId;
+    const tenantOrg = context?.organizationId ?? context?.tenantId ?? null;
     if (tenantOrg) f.organization_id = tenantOrg;
-    let statusFilter;
-    if (Array.isArray(filter?.status)) statusFilter = filter.status;
-    else if (filter?.status) f.status = filter.status;
-    const rows = await this.engine.find("sys_approval_request", {
-      where: f,
-      limit: 500,
-      orderBy: [{ field: "updated_at", direction: "desc" }],
+    const q = filter?.q?.trim();
+    if (q) {
+      f.$or = [
+        { process_name: { $contains: q } },
+        { object_name: { $contains: q } },
+        { record_id: { $contains: q } },
+        { submitter_id: { $contains: q } },
+        { payload_json: { $contains: q } }
+      ];
+    }
+    if (Array.isArray(filter?.status)) {
+      const statuses = filter.status.filter(Boolean);
+      if (statuses.length === 1) f.status = statuses[0];
+      else if (statuses.length > 1) f.status = { $in: statuses };
+    } else if (filter?.status) {
+      f.status = filter.status;
+    }
+    return { where: f, tenantOrg };
+  }
+  /**
+   * Resolve an approver filter to matching request ids via the normalized
+   * `sys_approval_approver` index — the indexed replacement for the old
+   * in-memory CSV scan, and what makes approver-filtered pagination correct
+   * past any scan window (issue #1745). A request matches when ANY of the
+   * caller's identities (user id / email / role:<r>) holds a pending slot.
+   * Returns null when the filter is absent (callers skip the id constraint).
+   */
+  async approverRequestIds(targets, tenantOrg) {
+    if (!targets.length) return null;
+    const where = targets.length === 1 ? { approver: targets[0] } : { approver: { $in: targets } };
+    if (tenantOrg) where.organization_id = tenantOrg;
+    const rows = await this.engine.find("sys_approval_approver", {
+      where,
+      fields: ["request_id"],
+      limit: _ApprovalService.APPROVER_INDEX_CAP,
       context: SYSTEM_CTX
     });
-    let list = Array.isArray(rows) ? rows.map(rowFromRequest) : [];
-    if (statusFilter) list = list.filter((r) => statusFilter.includes(r.status));
-    if (filter?.approverId) {
-      const targets = (Array.isArray(filter.approverId) ? filter.approverId : [filter.approverId]).map((t) => String(t).trim()).filter(Boolean);
-      if (targets.length) {
-        list = list.filter((r) => {
-          const pending = r.pending_approvers ?? [];
-          return targets.some((t) => pending.includes(t));
-        });
-      }
+    const list = Array.isArray(rows) ? rows : [];
+    if (list.length >= _ApprovalService.APPROVER_INDEX_CAP) {
+      this.logger?.warn?.("[approvals] approver index probe hit its window \u2014 results may be truncated", {
+        cap: _ApprovalService.APPROVER_INDEX_CAP,
+        targets: targets.length
+      });
     }
+    return [...new Set(list.map((r) => String(r.request_id)))];
+  }
+  async listRequests(filter, context) {
+    const { where, tenantOrg } = this.buildRequestWhere(filter, context);
+    const approverTargets = (Array.isArray(filter?.approverId) ? filter.approverId : filter?.approverId ? [filter.approverId] : []).map((t) => String(t).trim()).filter(Boolean);
+    const ids = await this.approverRequestIds(approverTargets, tenantOrg);
+    if (ids) {
+      if (ids.length === 0) return [];
+      where.id = ids.length === 1 ? ids[0] : { $in: ids };
+    }
+    const findOpts = {
+      where,
+      orderBy: [{ field: "created_at", order: "desc" }],
+      context: SYSTEM_CTX
+    };
+    if (filter?.limit != null || filter?.offset != null) {
+      findOpts.limit = Math.min(Math.max(filter?.limit ?? 50, 1), 200);
+      if (filter?.offset) findOpts.offset = Math.max(filter.offset, 0);
+    } else {
+      findOpts.limit = 500;
+    }
+    const rows = await this.engine.find("sys_approval_request", findOpts);
+    const list = Array.isArray(rows) ? rows.map(rowFromRequest) : [];
     await this.enrichRows(list);
     return list;
   }
+  async countRequests(filter, context) {
+    const { where, tenantOrg } = this.buildRequestWhere(filter, context);
+    const approverTargets = (Array.isArray(filter?.approverId) ? filter.approverId : filter?.approverId ? [filter.approverId] : []).map((t) => String(t).trim()).filter(Boolean);
+    const ids = await this.approverRequestIds(approverTargets, tenantOrg);
+    if (ids) {
+      if (ids.length === 0) return 0;
+      where.id = ids.length === 1 ? ids[0] : { $in: ids };
+    }
+    const countFn = this.engine.count;
+    if (typeof countFn === "function") {
+      try {
+        const n = await countFn.call(this.engine, "sys_approval_request", { where, context: SYSTEM_CTX });
+        if (typeof n === "number") return n;
+      } catch {
+      }
+    }
+    const rows = await this.engine.find("sys_approval_request", {
+      where,
+      fields: ["id"],
+      limit: ids ? Math.max(500, ids.length) : 500,
+      context: SYSTEM_CTX
+    });
+    return Array.isArray(rows) ? rows.length : 0;
+  }
   async getRequest(requestId, context) {
     if (!requestId) return null;
     const where = { id: requestId };
@@ -1656,8 +2640,44 @@ var ApprovalService = class _ApprovalService {
     if (!Array.isArray(rows) || !rows[0]) return null;
     const row = rowFromRequest(rows[0]);
     await this.enrichRows([row]);
+    await this.attachFlowSteps(row);
     return row;
   }
+  /**
+   * Derive approval-step progress from the owning flow's graph (single-read
+   * enrichment only — list reads skip it). Walks from the start node
+   * preferring `approve`/`true` edges, so the result is the flow's main
+   * approval trunk; conditional side-steps show as part of the potential
+   * path. Display-only and best-effort.
+   */
+  async attachFlowSteps(row) {
+    try {
+      const flowName = row.process_name?.startsWith("flow:") ? row.process_name.slice(5) : void 0;
+      if (!flowName || typeof this.automation?.getFlow !== "function") return;
+      const flow = await this.automation.getFlow(flowName);
+      if (!flow?.nodes?.length) return;
+      const nodesById = new Map(flow.nodes.map((n) => [n.id, n]));
+      const steps = [];
+      const seen = /* @__PURE__ */ new Set();
+      let cur = flow.nodes.find((n) => n.type === "start");
+      while (cur && !seen.has(cur.id)) {
+        seen.add(cur.id);
+        if (cur.type === "approval") steps.push({ id: cur.id, label: cur.label || cur.id });
+        const out = (flow.edges ?? []).filter((e) => e.source === cur.id);
+        if (!out.length) break;
+        const pick = out.find((e) => e.label === "approve") ?? out.find((e) => e.label === "true") ?? out[0];
+        cur = nodesById.get(pick.target);
+      }
+      if (steps.length === 0) return;
+      const currentId = row.flow_node_id ?? row.current_step;
+      const currentIdx = steps.findIndex((s) => s.id === currentId);
+      row.flow_steps = steps.map((s, i) => ({
+        ...s,
+        state: currentIdx < 0 ? "upcoming" : i < currentIdx ? "done" : i === currentIdx ? row.status === "approved" ? "done" : "current" : "upcoming"
+      }));
+    } catch {
+    }
+  }
   async listActions(requestId, context) {
     if (!requestId) return [];
     const req = await this.getRequest(requestId, context);
@@ -1665,7 +2685,7 @@ var ApprovalService = class _ApprovalService {
     const rows = await this.engine.find("sys_approval_action", {
       where: { request_id: requestId },
       limit: 500,
-      orderBy: [{ field: "created_at", direction: "asc" }],
+      orderBy: [{ field: "created_at", order: "asc" }],
       context: SYSTEM_CTX
     });
     const actions = Array.isArray(rows) ? rows.map(rowFromAction) : [];
@@ -1679,6 +2699,153 @@ var ApprovalService = class _ApprovalService {
     return actions;
   }
 };
+/** Window the approver-index probe — pending queues live far below this. */
+_ApprovalService.APPROVER_INDEX_CAP = 1e4;
+var ApprovalService = _ApprovalService;
+
+// src/sys-approval-token.object.ts
+import { ObjectSchema as ObjectSchema4, Field as Field4 } from "@objectstack/spec/data";
+var SysApprovalToken = ObjectSchema4.create({
+  name: "sys_approval_token",
+  label: "Approval Action Token",
+  pluralLabel: "Approval Action Tokens",
+  icon: "key",
+  isSystem: true,
+  managedBy: "system",
+  description: "Single-use tokens behind actionable approval links",
+  displayNameField: "id",
+  fields: {
+    id: Field4.text({ label: "Token ID", required: true, readonly: true, group: "System" }),
+    organization_id: Field4.lookup("sys_organization", {
+      label: "Organization",
+      required: false,
+      group: "System"
+    }),
+    token_hash: Field4.text({
+      label: "Token Hash",
+      required: true,
+      maxLength: 100,
+      readonly: true,
+      description: "SHA-256 hex of the raw token \u2014 the raw value is never stored",
+      group: "Token"
+    }),
+    request_id: Field4.text({
+      label: "Request",
+      required: true,
+      maxLength: 100,
+      readonly: true,
+      group: "Token"
+    }),
+    action: Field4.select(["approve", "reject"], {
+      label: "Action",
+      required: true,
+      readonly: true,
+      group: "Token"
+    }),
+    approver_id: Field4.text({
+      label: "Approver",
+      required: true,
+      maxLength: 200,
+      readonly: true,
+      description: "Identity the token is bound to; the decision is audited as this approver",
+      group: "Token"
+    }),
+    expires_at: Field4.datetime({
+      label: "Expires At",
+      required: true,
+      readonly: true,
+      group: "Lifecycle"
+    }),
+    consumed_at: Field4.datetime({
+      label: "Consumed At",
+      required: false,
+      group: "Lifecycle"
+    }),
+    created_at: Field4.datetime({
+      label: "Created At",
+      required: true,
+      defaultValue: "NOW()",
+      readonly: true,
+      group: "System"
+    })
+  },
+  indexes: [
+    { fields: ["token_hash"] },
+    { fields: ["request_id"] }
+  ]
+});
+
+// src/action-link-pages.ts
+function esc(s) {
+  return String(s ?? "").replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+function shell(title, body) {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${esc(title)}</title>
+<style>
+  body{font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"PingFang SC","Microsoft YaHei",sans-serif;
+       background:#f6f7f9;color:#1a202c;margin:0;display:flex;min-height:100vh;align-items:center;justify-content:center}
+  .card{background:#fff;border:1px solid #e2e8f0;border-radius:12px;max-width:440px;width:calc(100% - 32px);
+        padding:28px 32px;box-shadow:0 1px 3px rgba(0,0,0,.06)}
+  h1{font-size:18px;margin:0 0 4px}
+  .sub{color:#64748b;font-size:13px;margin:0 0 20px}
+  .row{display:flex;justify-content:space-between;gap:12px;padding:7px 0;border-bottom:1px solid #f1f5f9;font-size:14px}
+  .row b{font-weight:600;text-align:right}
+  .k{color:#64748b}
+  .actions{margin-top:22px;display:flex;gap:10px}
+  button{flex:1;padding:10px 16px;border-radius:8px;border:1px solid transparent;font-size:15px;font-weight:600;cursor:pointer}
+  .approve{background:#059669;color:#fff}
+  .reject{background:#fff;color:#dc2626;border-color:#fca5a5}
+  .badge{display:inline-block;padding:2px 10px;border-radius:999px;font-size:12px;font-weight:600;margin-bottom:14px}
+  .ok{background:#ecfdf5;color:#047857}.warn{background:#fffbeb;color:#b45309}.err{background:#fef2f2;color:#b91c1c}
+  a{color:#2563eb;text-decoration:none}
+  .foot{margin-top:18px;font-size:12px;color:#94a3b8}
+</style></head><body><div class="card">${body}</div></body></html>`;
+}
+function summaryRows(req) {
+  const rows = [
+    ["Process \xB7 \u6D41\u7A0B", req.process_label || req.process_name],
+    ["Step \xB7 \u6B65\u9AA4", req.step_label || req.current_step || "\u2014"],
+    ["Record \xB7 \u8BB0\u5F55", req.record_title || req.record_id],
+    ["Object \xB7 \u5BF9\u8C61", req.object_label || req.object_name],
+    ["Requester \xB7 \u7533\u8BF7\u4EBA", req.submitter_name || req.submitter_id || "\u2014"]
+  ];
+  return rows.map(([k, v]) => `<div class="row"><span class="k">${esc(k)}</span><b>${esc(v)}</b></div>`).join("");
+}
+function renderConfirmPage(input) {
+  const approving = input.action === "approve";
+  const verb = approving ? "Approve \xB7 \u901A\u8FC7" : "Reject \xB7 \u62D2\u7EDD";
+  return shell(`${verb} \u2014 Approval`, `
+    <h1>${approving ? "\u2705 Approve this request?" : "\u26D4 Reject this request?"}</h1>
+    <p class="sub">${approving ? "\u786E\u8BA4\u901A\u8FC7\u8BE5\u5BA1\u6279\u8BF7\u6C42\uFF1F" : "\u786E\u8BA4\u62D2\u7EDD\u8BE5\u5BA1\u6279\u8BF7\u6C42\uFF1F"}
+      Acting as \xB7 \u64CD\u4F5C\u8EAB\u4EFD\uFF1A<b>${esc(input.approverId)}</b></p>
+    ${summaryRows(input.request)}
+    <form method="post" action="${esc(input.actPath)}" class="actions">
+      <input type="hidden" name="token" value="${esc(input.token)}">
+      <button type="submit" class="${approving ? "approve" : "reject"}">${verb}</button>
+    </form>
+    <p class="foot">This link is single-use and expires automatically. \xB7 \u6B64\u94FE\u63A5\u4E00\u6B21\u6709\u6548\uFF0C\u8FC7\u671F\u81EA\u52A8\u5931\u6548\u3002</p>`);
+}
+var RESULT_COPY = {
+  approved: { cls: "ok", title: "\u2705 Approved \xB7 \u5DF2\u901A\u8FC7", body: "The decision was recorded. \xB7 \u5BA1\u6279\u7ED3\u679C\u5DF2\u8BB0\u5F55\u3002" },
+  rejected: { cls: "ok", title: "\u26D4 Rejected \xB7 \u5DF2\u62D2\u7EDD", body: "The decision was recorded. \xB7 \u5BA1\u6279\u7ED3\u679C\u5DF2\u8BB0\u5F55\u3002" },
+  invalid: { cls: "err", title: "Invalid link \xB7 \u94FE\u63A5\u65E0\u6548", body: "This link is not recognized. \xB7 \u65E0\u6CD5\u8BC6\u522B\u8BE5\u94FE\u63A5\u3002" },
+  expired: { cls: "warn", title: "Link expired \xB7 \u94FE\u63A5\u5DF2\u8FC7\u671F", body: "Ask the requester to send a new reminder. \xB7 \u8BF7\u8BA9\u7533\u8BF7\u4EBA\u91CD\u65B0\u53D1\u9001\u50AC\u529E\u3002" },
+  consumed: { cls: "warn", title: "Already used \xB7 \u94FE\u63A5\u5DF2\u4F7F\u7528", body: "This link was already used once. \xB7 \u8BE5\u94FE\u63A5\u5DF2\u88AB\u4F7F\u7528\u8FC7\u3002" },
+  not_pending: { cls: "warn", title: "Already decided \xB7 \u8BF7\u6C42\u5DF2\u5904\u7406", body: "This request is no longer pending. \xB7 \u8BE5\u8BF7\u6C42\u5DF2\u4E0D\u5728\u5F85\u5BA1\u6279\u72B6\u6001\u3002" },
+  not_approver: { cls: "warn", title: "No longer your approval \xB7 \u5DF2\u4E0D\u5728\u4F60\u540D\u4E0B", body: "This approval was handed to someone else. \xB7 \u8BE5\u5BA1\u6279\u5DF2\u8F6C\u7531\u4ED6\u4EBA\u5904\u7406\u3002" }
+};
+function renderResultPage(kind, request) {
+  const copy = RESULT_COPY[kind] ?? RESULT_COPY.invalid;
+  return shell(copy.title, `
+    <span class="badge ${copy.cls}">${esc(copy.title)}</span>
+    ${request ? summaryRows(request) : ""}
+    <p>${esc(copy.body)}</p>
+    <p class="foot"><a href="/system/approvals">Open the Approvals Inbox \xB7 \u6253\u5F00\u5BA1\u6279\u4E2D\u5FC3</a></p>`);
+}
 
 // src/lifecycle-hooks.ts
 var APPROVALS_HOOK_PACKAGE = "plugin-approvals:lock";
@@ -1817,6 +2984,7 @@ var ApprovalsServicePlugin = class {
     this.version = "1.0.0";
     this.type = "standard";
     this.dependencies = ["com.objectstack.engine.objectql"];
+    this.escalationJobScheduled = false;
     this.options = options;
   }
   async init(ctx) {
@@ -1828,7 +2996,7 @@ var ApprovalsServicePlugin = class {
       scope: "system",
       defaultDatasource: "cloud",
       namespace: "sys",
-      objects: [SysApprovalRequest, SysApprovalAction],
+      objects: [SysApprovalRequest, SysApprovalAction, SysApprovalApprover, SysApprovalToken],
       // 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.
@@ -1878,7 +3046,8 @@ var ApprovalsServicePlugin = class {
     this.engine = engine;
     this.service = new ApprovalService({
       engine,
-      logger: ctx.logger
+      logger: ctx.logger,
+      publicBaseUrl: this.options.publicBaseUrl
     });
     if (!this.options.disableAutoHooks) {
       try {
@@ -1890,6 +3059,86 @@ var ApprovalsServicePlugin = class {
     }
     ctx.registerService("approvals", this.service);
     ctx.logger.info("ApprovalsServicePlugin: service registered");
+    try {
+      const messaging = ctx.getService("messaging");
+      if (messaging && typeof messaging.emit === "function") {
+        this.service.attachMessaging(messaging);
+      }
+    } catch {
+    }
+    const wireEscalationClock = async () => {
+      try {
+        const jobs = ctx.getService("job");
+        if (!jobs || typeof jobs.schedule !== "function" || !this.service) return;
+        const svc = this.service;
+        const intervalMs = this.options.escalationScanIntervalMs ?? ESCALATION_SCAN_INTERVAL_MS;
+        await jobs.schedule(ESCALATION_JOB_NAME, { type: "interval", intervalMs }, async () => {
+          await svc.runEscalations();
+        });
+        this.escalationJobScheduled = true;
+        void svc.runEscalations().catch((err) => {
+          ctx.logger.warn?.("[approvals] boot escalation sweep failed", { error: err?.message });
+        });
+        ctx.logger.info("ApprovalsServicePlugin: SLA escalation scan scheduled", { intervalMs });
+      } catch {
+      }
+    };
+    const mountActionPages = async () => {
+      try {
+        const http = ctx.getService("http-server");
+        const rawApp = http && typeof http.getRawApp === "function" ? http.getRawApp() : null;
+        if (!rawApp || !this.service) return;
+        const svc = this.service;
+        const ACT_PATH = "/api/v1/approvals/act";
+        const html = (c, body, status = 200) => c.body(body, status, { "Content-Type": "text/html; charset=utf-8" });
+        rawApp.get(ACT_PATH, async (c) => {
+          const token = String(c.req.query("token") ?? "");
+          const peek = await svc.peekActionToken(token);
+          if (!peek.ok) return html(c, renderResultPage(peek.reason, peek.request), 200);
+          return html(c, renderConfirmPage({
+            request: peek.request,
+            action: peek.action,
+            approverId: peek.approverId,
+            token,
+            actPath: ACT_PATH
+          }));
+        });
+        rawApp.post(ACT_PATH, async (c) => {
+          let token = "";
+          try {
+            const body = await c.req.parseBody();
+            token = String(body?.token ?? "");
+          } catch {
+          }
+          const out = await svc.redeemActionToken(token);
+          if (!out.ok) return html(c, renderResultPage(out.reason, out.request), 200);
+          return html(c, renderResultPage(out.action === "approve" ? "approved" : "rejected", out.request));
+        });
+        ctx.logger.info(`ApprovalsServicePlugin: actionable-link pages mounted at ${ACT_PATH}`);
+      } catch {
+      }
+    };
+    const backfillApproverIndex = async () => {
+      try {
+        const svc = this.service;
+        if (!svc) return;
+        const out = await svc.rebuildApproverIndex();
+        if (out.inserted > 0 || out.deleted > 0) {
+          ctx.logger.info("ApprovalsServicePlugin: approver index rebuilt", out);
+        }
+      } catch (err) {
+        ctx.logger.warn?.("[approvals] approver index backfill failed", { error: err?.message });
+      }
+    };
+    if (typeof ctx.hook === "function") {
+      ctx.hook("kernel:ready", wireEscalationClock);
+      ctx.hook("kernel:ready", mountActionPages);
+      ctx.hook("kernel:ready", backfillApproverIndex);
+    } else {
+      await wireEscalationClock();
+      await mountActionPages();
+      await backfillApproverIndex();
+    }
     try {
       const automation = ctx.getService("automation");
       if (automation && typeof automation.registerNodeExecutor === "function") {
@@ -1900,7 +3149,15 @@ var ApprovalsServicePlugin = class {
       ctx.logger.info("ApprovalsServicePlugin: no automation engine \u2014 approval node not registered");
     }
   }
-  async stop(_ctx) {
+  async stop(ctx) {
+    if (this.escalationJobScheduled) {
+      try {
+        const jobs = ctx.getService("job");
+        await jobs?.cancel?.(ESCALATION_JOB_NAME);
+      } catch {
+      }
+      this.escalationJobScheduled = false;
+    }
     if (this.engine) {
       try {
         unbindAllHooks(this.engine);
@@ -1913,6 +3170,7 @@ export {
   ApprovalService,
   ApprovalsServicePlugin,
   SysApprovalAction,
+  SysApprovalApprover,
   SysApprovalRequest,
   registerApprovalNode
 };