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

package/src/approval-service.ts

@@ -3,6 +3,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import {
   APPROVAL_BRANCH_LABELS,
+  canonicalApproverType,
   type ApprovalNodeConfig,
 } from '@objectstack/spec/automation';
 import type {
@@ -20,6 +21,7 @@ import type {
   ApprovalStatus,
   SharingExecutionContext,
 } from '@objectstack/spec/contracts';
+import { isGrantActive } from '@objectstack/core';
 
 /**
  * Node-era approval runtime (ADR-0019).
@@ -99,6 +101,23 @@ export type ActionTokenOutcome =
 
 const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;
 
+/**
+ * Max hops when following an OOO delegation chain (#1322 M1): A out → B, B out
+ * → C, … Bounds the walk so a mis-configured chain can't loop or resolve
+ * unboundedly; a cycle or self-reference also stops it early.
+ */
+const OOO_MAX_CHAIN = 8;
+
+/** One OOO delegation hop applied while resolving an approver (#1322 M1/M4). */
+interface OooSubstitution {
+  /** The approver who was skipped (out of office). */
+  from: string;
+  /** The delegate the slot was routed to. */
+  to: string;
+  /** The delegator's declared reason, if any. */
+  reason: string | null;
+}
+
 function uid(prefix: string): string {
   const g: any = globalThis as any;
   if (g.crypto?.randomUUID) return `${prefix}_${g.crypto.randomUUID()}`;
@@ -186,6 +205,10 @@ function rowFromAction(row: any): ApprovalActionRow {
     action: row.action,
     actor_id: row.actor_id ?? undefined,
     comment: row.comment ?? undefined,
+    // Decision attachments (#3266). The column shipped in #3268 but this
+    // contract mapping didn't — the raw engine row carried the fileIds while
+    // every consumer of listActions saw none (caught by browser verification).
+    attachments: Array.isArray(row.attachments) && row.attachments.length ? row.attachments.map(String) : undefined,
     created_at: row.created_at ?? undefined,
   };
 }
@@ -249,8 +272,20 @@ export class ApprovalService implements IApprovalService {
   }): Promise<number> {
     const audience = input.audience.filter(a => a && !a.includes(':'));
     if (!this.messaging || !audience.length) return 0;
+    // Deep-link the inbox (#2678 P1.5): a notification about one request should
+    // land on that request, not the bare inbox. Rewritten centrally so every
+    // call site — and any future one — inherits it; the query param is read by
+    // the console inbox to auto-open the drawer.
+    let payload = input.payload;
+    if (
+      payload?.actionUrl === '/system/approvals'
+      && input.source?.object === 'sys_approval_request'
+      && input.source.id
+    ) {
+      payload = { ...payload, actionUrl: `/system/approvals?request=${encodeURIComponent(input.source.id)}` };
+    }
     try {
-      await this.messaging.emit({ severity: 'info', ...input, audience });
+      await this.messaging.emit({ severity: 'info', ...input, payload, audience });
       return audience.length;
     } catch (err: any) {
       this.logger?.warn?.('[approvals] notification failed', {
@@ -274,10 +309,10 @@ export class ApprovalService implements IApprovalService {
 
   /**
    * Expand the approvers on an Approval node into user IDs by querying the
-   * graph tables for `team:` / `department:` / `position:` / `role:` /
-   * `manager:` approver types. Falls back to a prefixed literal
-   * (`type:value`) when graph lookups produce nothing — so existing fixtures
-   * and flows that rely on substring matching keep working.
+   * graph tables for `team:` / `department:` / `position:` /
+   * `org_membership_level:` / `manager:` approver types. Falls back to a
+   * prefixed literal (`type:value`) when graph lookups produce nothing — so
+   * existing fixtures and flows that rely on substring matching keep working.
    *
    * **Graph semantics:**
    *   - `team`       → flat members of `sys_team` (better-auth; no BFS)
@@ -285,46 +320,109 @@ export class ApprovalService implements IApprovalService {
    *                    → members of every descendant via `sys_business_unit_member`
    *   - `position`   → holders via `sys_user_position` ∪ `sys_member.role`
    *                    transition source (ADR-0090 D3 / ADR-0057 D4)
-   *   - `role`       → users with `sys_member.role = value` in tenant — the
+   *   - `org_membership_level`
+   *                  → users with `sys_member.role = value` in tenant — the
    *                    better-auth MEMBERSHIP TIER (owner/admin/member), not a
    *                    position; author `position` for org positions
    *   - `manager`    → `sys_user.manager_id` of `record[value] ?? record.owner_id`
    *   - `field`      → literal user id stored in `record[value]`
    *   - `user`       → literal value
+   *
+   * `role` is accepted as the deprecated spelling of `org_membership_level`
+   * (ADR-0090 D3) for one window: it resolves identically and logs a warning.
+   *
+   * **Out-of-office (#1322 M1):** individually-routed approvers — the ones that
+   * resolve to a specific person (`user` / `field` / `manager`) — are passed
+   * through {@link ApprovalService.applyOooDelegation}, which reroutes them onto
+   * an active delegate when the resolved user has declared OOO. Group/graph
+   * approvers (`team` / `department` / `position` / `org_membership_level`) are
+   * left untouched: a group still has its other members, and position-routed
+   * leave is already covered by ADR-0091 job delegation. Pass an `opts.now` /
+   * `opts.substitutions` collector to record the hops for audit + notification.
    */
-  private async expandApprovers(step: any, record?: any, organizationId?: string | null): Promise<string[]> {
+  private async expandApprovers(
+    step: any,
+    record?: any,
+    organizationId?: string | null,
+    opts?: { now?: number; substitutions?: OooSubstitution[]; groups?: Record<string, string[]> },
+  ): Promise<string[]> {
     if (!step || !Array.isArray(step.approvers)) return [];
+    const now = opts?.now ?? this.clock.now().getTime();
     const out: string[] = [];
-    for (const a of step.approvers) {
+    const specs: any[] = step.approvers;
+    for (let idx = 0; idx < specs.length; idx++) {
+      const a = specs[idx];
       if (!a) continue;
-      if (a.type === 'user') { out.push(String(a.value)); continue; }
-      if (a.type === 'field' && record) { out.push(String((record as any)[a.value] ?? '')); continue; }
-      try {
-        if (a.type === 'team') {
-          const users = await this.expandTeamUsers(String(a.value));
-          if (users.length) { for (const u of users) out.push(u); continue; }
-        } else if (a.type === 'department' || a.type === 'business_unit' || a.type === 'bu') {
-          const users = await this.expandBusinessUnitUsers(String(a.value), organizationId);
-          if (users.length) { for (const u of users) out.push(u); continue; }
-        } else if (a.type === 'position') {
-          const users = await this.expandPositionUsers(String(a.value), organizationId);
-          if (users.length) { for (const u of users) out.push(u); continue; }
-        } else if (a.type === 'role') {
-          const users = await this.expandRoleUsers(String(a.value), organizationId);
-          if (users.length) { for (const u of users) out.push(u); continue; }
-        } else if (a.type === 'manager' && record) {
-          const subject = (record as any)[a.value] ?? (record as any).owner_id;
-          if (subject) {
-            const mgr = await this.lookupManager(String(subject));
-            if (mgr) { out.push(mgr); continue; }
-          }
-        }
-      } catch { /* fall through */ }
-      out.push(`${a.type}:${a.value}`);
+      const ids = await this.resolveApproverSpec(a, record, organizationId, now, opts?.substitutions);
+      // per_group (#3266): tag each resolved id with this spec's group. An
+      // approver without an explicit `group` forms its own group keyed by
+      // position, so a plain per-approver list still behaves predictably.
+      const groupKey = a.group != null && String(a.group) !== '' ? String(a.group) : `#${idx}`;
+      for (const u of ids) {
+        if (!u) continue;
+        out.push(u);
+        if (opts?.groups) (opts.groups[u] ??= []).push(groupKey);
+      }
     }
     return out.filter(Boolean);
   }
 
+  /**
+   * Resolve ONE approver spec to concrete approver identities, applying OOO
+   * substitution (#1322) to individually-routed types. Extracted from
+   * {@link ApprovalService.expandApprovers} so the caller can tag each spec's
+   * resolved ids with a group (#3266) without duplicating the resolution logic.
+   * Returns the `type:value` literal as a single-element fallback when a graph
+   * lookup yields nothing — same behaviour as before the extraction.
+   */
+  private async resolveApproverSpec(
+    a: any,
+    record: any,
+    organizationId: string | null | undefined,
+    now: number,
+    substitutions?: OooSubstitution[],
+  ): Promise<string[]> {
+    // ADR-0090 D3: `role` is the deprecated spelling of `org_membership_level`.
+    // Resolve on the canonical type, but keep the AUTHORED spelling in the
+    // `type:value` fallback below — stored `sys_approval_approver` rows and
+    // `pending_approvers` slots from 15.x carry the old literal.
+    const type = canonicalApproverType(String(a.type));
+    if (type !== a.type) {
+      this.logger?.warn?.(
+        `[approvals] approver type '${a.type}' is deprecated (ADR-0090 D3) — author '${type}' instead`,
+        { deprecated: a.type, canonical: type },
+      );
+    }
+    if (type === 'user') {
+      return this.applyOooDelegation(String(a.value), now, organizationId, substitutions);
+    }
+    if (type === 'field' && record) {
+      return this.applyOooDelegation(String((record as any)[a.value] ?? ''), now, organizationId, substitutions);
+    }
+    try {
+      if (type === 'team') {
+        const users = await this.expandTeamUsers(String(a.value));
+        if (users.length) return users;
+      } else if (type === 'department' || type === 'business_unit' || type === 'bu') {
+        const users = await this.expandBusinessUnitUsers(String(a.value), organizationId);
+        if (users.length) return users;
+      } else if (type === 'position') {
+        const users = await this.expandPositionUsers(String(a.value), organizationId);
+        if (users.length) return users;
+      } else if (type === 'org_membership_level') {
+        const users = await this.expandMembershipTierUsers(String(a.value), organizationId);
+        if (users.length) return users;
+      } else if (type === 'manager' && record) {
+        const subject = (record as any)[a.value] ?? (record as any).owner_id;
+        if (subject) {
+          const mgr = await this.lookupManager(String(subject));
+          if (mgr) return this.applyOooDelegation(mgr, now, organizationId, substitutions);
+        }
+      }
+    } catch { /* fall through */ }
+    return [`${a.type}:${a.value}`];
+  }
+
   /** Flat team — `sys_team` is better-auth's collaboration grouping (no hierarchy). */
   private async expandTeamUsers(teamId: string): Promise<string[]> {
     if (!teamId) return [];
@@ -406,14 +504,23 @@ export class ApprovalService implements IApprovalService {
         if (uid) users.add(uid);
       }
     } catch { /* table may not exist on minimal stacks — union source below still applies */ }
-    for (const uid of await this.expandRoleUsers(positionName, organizationId)) users.add(uid);
+    // ADR-0057 D4 transition source: pre-migration stacks still carry the
+    // position name in better-auth's `sys_member.role` column, so the same
+    // lookup serves a position name here and a membership tier for
+    // `org_membership_level` — the column is one, the two concepts are not.
+    for (const uid of await this.expandMembershipTierUsers(positionName, organizationId)) users.add(uid);
     return Array.from(users);
   }
 
-  /** better-auth org-membership tier (`sys_member.role`) — NOT positions. */
-  private async expandRoleUsers(roleName: string, organizationId?: string | null): Promise<string[]> {
-    if (!roleName) return [];
-    const filter: any = { role: roleName };
+  /**
+   * better-auth org-membership tier (`sys_member.role`: owner/admin/member) —
+   * NOT positions. Named for the projection (`org_membership_level`, ADR-0057
+   * D7 / ADR-0090 D3), not for better-auth's column: the column name is theirs
+   * and stays, the platform-facing word does not.
+   */
+  private async expandMembershipTierUsers(tier: string, organizationId?: string | null): Promise<string[]> {
+    if (!tier) return [];
+    const filter: any = { role: tier };
     if (organizationId) filter.organization_id = organizationId;
     let rows: any[] = [];
     try {
@@ -432,6 +539,74 @@ export class ApprovalService implements IApprovalService {
     } catch { return null; }
   }
 
+  /**
+   * Out-of-office auto-skip (#1322 M1). Given an individually-routed approver
+   * id, follow any active `sys_approval_delegation` chain and return the id the
+   * slot should actually go to — the delegate acts under their own identity, so
+   * no impersonation is involved. Returns `[userId]` unchanged when there is no
+   * active delegation. Each hop is appended to `collector` (when supplied) so
+   * the caller can audit + notify (M4).
+   *
+   * The chain (A out → B, B out → C, …) is bounded by {@link OOO_MAX_CHAIN} and
+   * stops on a self-reference or a cycle, so a mis-declared loop degrades to the
+   * last reachable delegate rather than hanging.
+   */
+  private async applyOooDelegation(
+    userId: string,
+    now: number,
+    organizationId?: string | null,
+    collector?: OooSubstitution[],
+  ): Promise<string[]> {
+    const start = String(userId ?? '').trim();
+    if (!start) return [];
+    let current = start;
+    const visited = new Set<string>([current]);
+    for (let hop = 0; hop < OOO_MAX_CHAIN; hop++) {
+      const del = await this.lookupActiveDelegation(current, now, organizationId);
+      if (!del) break;
+      const to = String(del.delegate_id ?? '').trim();
+      if (!to || to === current || visited.has(to)) break; // no-op / self / cycle
+      collector?.push({ from: current, to, reason: del.reason != null ? String(del.reason) : null });
+      visited.add(to);
+      current = to;
+    }
+    return [current];
+  }
+
+  /**
+   * The active OOO delegation for a delegator at `now`, or null. Validity is the
+   * shared `isGrantActive` half-open window (ADR-0091 D2), enforced here at
+   * resolution time — never by a background job. When several rows are active,
+   * the one expiring soonest wins (the most specific coverage window).
+   */
+  private async lookupActiveDelegation(
+    delegatorId: string,
+    now: number,
+    organizationId?: string | null,
+  ): Promise<any | null> {
+    if (!delegatorId) return null;
+    let rows: any[] = [];
+    try {
+      rows = await this.engine.find('sys_approval_delegation', {
+        filter: { delegator_id: delegatorId },
+        fields: ['id', 'delegator_id', 'delegate_id', 'valid_from', 'valid_until', 'reason', 'organization_id'],
+        limit: 50,
+        context: SYSTEM_CTX,
+      } as any);
+    } catch { return null; } // table absent on minimal stacks — no OOO, resolve as-is
+    const active = (rows ?? []).filter((r: any) =>
+      isGrantActive(r, now)
+      // A null-org rule applies across tenants; a scoped rule only within its tenant.
+      && (organizationId == null || r.organization_id == null || String(r.organization_id) === String(organizationId)));
+    if (!active.length) return null;
+    active.sort((a: any, b: any) => {
+      const au = a.valid_until ? Date.parse(String(a.valid_until)) : Number.POSITIVE_INFINITY;
+      const bu = b.valid_until ? Date.parse(String(b.valid_until)) : Number.POSITIVE_INFINITY;
+      return au - bu;
+    });
+    return active[0];
+  }
+
   /** Mirror a request status onto a business-object field, if configured. */
   private async mirrorStatusField(object: string, recordId: string, field: string, status: string): Promise<void> {
     try {
@@ -486,9 +661,19 @@ export class ApprovalService implements IApprovalService {
     }
 
     const ctxOrg = (context as any)?.organizationId ?? (context as any)?.tenantId ?? input.organizationId ?? null;
-    const approvers = await this.expandApprovers({ approvers: input.config.approvers }, input.record, ctxOrg);
+    const nowDate = this.clock.now();
+    // OOO auto-skip (#1322 M1): reroute individually-routed approvers who are
+    // out of office. Collected hops drive the audit + notification below (M4).
+    const substitutions: OooSubstitution[] = [];
+    // Group membership per resolved approver (#3266) — snapshotted so quorum /
+    // per_group finalization is decided against the slate resolved at OPEN time
+    // (OOO-substituted), not re-resolved live at each decision.
+    const groups: Record<string, string[]> = {};
+    const approvers = await this.expandApprovers(
+      { approvers: input.config.approvers }, input.record, ctxOrg, { now: nowDate.getTime(), substitutions, groups },
+    );
 
-    const now = this.clock.now().toISOString();
+    const now = nowDate.toISOString();
     const id = uid('areq');
     const processName = `flow:${input.flowName ?? input.nodeId}`;
     // Display labels ride the config snapshot (no schema migration needed);
@@ -496,6 +681,10 @@ export class ApprovalService implements IApprovalService {
     const configSnapshot: any = { ...input.config };
     if (input.flowLabel) configSnapshot.__flowLabel = input.flowLabel;
     if (input.nodeLabel) configSnapshot.__nodeLabel = input.nodeLabel;
+    // Snapshot the resolved approver→group map for quorum/per_group tallying.
+    if (input.config.behavior === 'quorum' || input.config.behavior === 'per_group') {
+      configSnapshot.__approverGroups = groups;
+    }
     // ADR-0044 round numbering: rounds of a revise loop share the run — count
     // this (run, node)'s prior requests; the new one is round N+1. Stamped on
     // the snapshot (precedent: __flowLabel), so no schema migration.
@@ -532,6 +721,42 @@ export class ApprovalService implements IApprovalService {
       actor_id: input.submitterId ?? context.userId ?? null, comment: null, created_at: now,
     }, { context: SYSTEM_CTX });
 
+    // OOO substitution audit + notification (#1322 M4). Each hop that rerouted
+    // an approver away from an out-of-office user is recorded on the request's
+    // audit trail (a system action, no human actor) and notified to both the
+    // delegate — who now owns the slot — and the skipped approver.
+    for (const sub of substitutions) {
+      await this.engine.insert('sys_approval_action', {
+        id: uid('aact'), request_id: id, organization_id: ctxOrg,
+        step_name: input.nodeId, step_index: 0, action: 'ooo_substitute',
+        actor_id: null,
+        comment: `${sub.from} → ${sub.to}${sub.reason ? ` — ${sub.reason}` : ''}`,
+        created_at: now,
+      }, { context: SYSTEM_CTX });
+      await this.notify({
+        topic: 'approval.ooo_substituted',
+        audience: [sub.to],
+        source: { object: 'sys_approval_request', id },
+        dedupKey: `approval-ooo-${id}-${sub.to}`,
+        payload: {
+          title: 'Approval routed to you (out-of-office cover)',
+          message: `You are covering an approval on ${input.object}/${input.recordId} while ${sub.from} is out of office.`,
+          actionUrl: '/system/approvals',
+        },
+      });
+      await this.notify({
+        topic: 'approval.ooo_skipped',
+        audience: [sub.from],
+        source: { object: 'sys_approval_request', id },
+        dedupKey: `approval-ooo-skip-${id}-${sub.from}`,
+        payload: {
+          title: 'Approval routed to your delegate',
+          message: `An approval on ${input.object}/${input.recordId} was routed to ${sub.to} while you are out of office.`,
+          actionUrl: '/system/approvals',
+        },
+      });
+    }
+
     // Record lock (when `lockRecord !== false`) is enforced by the beforeUpdate
     // hook keyed on the now-pending request; no extra write needed here.
     if (input.config.approvalStatusField) {
@@ -542,15 +767,54 @@ export class ApprovalService implements IApprovalService {
   }
 
   /**
-   * Record a decision on a node-driven request. Honours the node's `unanimous`
-   * behavior (holds until every approver has approved). When the request
-   * finalizes, returns the suspended run id + node id so the caller (or
-   * {@link ApprovalService.decide}) can resume the flow down the matching
-   * branch.
+   * True when the approve tally satisfies the node's `behavior` (#3266):
+   *  - `unanimous` — every resolved approver approved.
+   *  - `quorum` — at least `minApprovals` distinct approvals (default = all).
+   *  - `per_group` — every group reached `minApprovals` approvals (default 1).
+   * Thresholds are clamped to the resolvable count / group size, so a mis-set
+   * value can never deadlock a request.
+   */
+  private isApprovalSatisfied(
+    behavior: string,
+    config: ApprovalNodeConfig,
+    original: string[],
+    groupMap: Record<string, string[]>,
+    approved: Set<string>,
+  ): boolean {
+    if (behavior === 'unanimous') {
+      return original.length > 0 && original.every(a => approved.has(a));
+    }
+    if (behavior === 'quorum') {
+      const n = original.length || 1;
+      const need = Math.min(Math.max(1, config.minApprovals ?? n), n);
+      // Count distinct approvals (robust to OOO/reassign changing who holds a slot).
+      return approved.size >= need;
+    }
+    if (behavior === 'per_group') {
+      const perGroupNeed = Math.max(1, config.minApprovals ?? 1);
+      const size: Record<string, number> = {};
+      for (const gs of Object.values(groupMap)) for (const g of gs) size[g] = (size[g] ?? 0) + 1;
+      const groups = Object.keys(size);
+      if (!groups.length) return true; // nothing to gate
+      const got: Record<string, number> = {};
+      for (const a of approved) for (const g of (groupMap[a] ?? [])) got[g] = (got[g] ?? 0) + 1;
+      return groups.every(g => (got[g] ?? 0) >= Math.min(perGroupNeed, size[g]));
+    }
+    return true; // first_response and unknown → first approval finalizes
+  }
+
+  /**
+   * Record a decision on a node-driven request. Honours the node's `behavior`
+   * (#3266): `first_response` finalizes on the first approval; `unanimous`,
+   * `quorum`, and `per_group` hold the request open until their tally is met
+   * (see {@link ApprovalService.isApprovalSatisfied}). A rejection always
+   * finalizes the node (one veto). When the request finalizes, returns the
+   * suspended run id + node id so the caller (or {@link ApprovalService.decide})
+   * can resume the flow down the matching branch.
    */
   async decideNode(
     requestId: string,
-    input: { decision: 'approve' | 'reject'; actorId: string; comment?: string },
+    input: { decision: 'approve' | 'reject'; actorId: string; comment?: string; attachments?: string[] },
     context: SharingExecutionContext,
   ): Promise<{ request: ApprovalRequestRow; runId: string | null; nodeId: string | null; finalized: boolean; decision: 'approve' | 'reject' }> {
     if (!requestId) throw new Error('VALIDATION_FAILED: requestId is required');
@@ -578,24 +842,43 @@ export class ApprovalService implements IApprovalService {
     const runId: string | null = raw.flow_run_id ?? null;
     const now = this.clock.now().toISOString();
 
-    // Audit the decision first so the unanimous tally below sees it.
+    // Audit the decision first so the quorum/per_group tally below sees it.
     await this.engine.insert('sys_approval_action', {
       id: uid('aact'), request_id: requestId, organization_id: org,
       step_name: nodeId, step_index: 0, action: input.decision,
-      actor_id: input.actorId, comment: input.comment ?? null, created_at: now,
+      actor_id: input.actorId, comment: input.comment ?? null,
+      attachments: input.attachments?.length ? input.attachments : null,
+      created_at: now,
     }, { context: SYSTEM_CTX });
 
-    // Unanimous approve: advance only once every approver has approved.
-    if (input.decision === 'approve' && config.behavior === 'unanimous') {
-      const original = await this.expandApprovers(
-        { approvers: config.approvers }, parseJson(raw.payload_json, undefined), org,
-      );
+    // Multi-approver aggregation on approve (#3266). A rejection always
+    // finalizes the node (one veto), so only the approve path can hold it open.
+    // `first_response` finalizes on the first approval (falls straight through).
+    const behavior = config.behavior ?? 'first_response';
+    if (input.decision === 'approve' && behavior !== 'first_response') {
       const acts = await this.engine.find('sys_approval_action', {
-        where: { request_id: requestId, step_index: 0, action: 'approve' }, limit: 500, context: SYSTEM_CTX,
+        where: { request_id: requestId, step_index: 0, action: 'approve' }, limit: 1000, context: SYSTEM_CTX,
       });
       const approved = new Set<string>((acts ?? []).map((a: any) => String(a.actor_id ?? '')).filter(Boolean));
-      const stillPending = original.filter(a => !approved.has(a));
-      if (stillPending.length > 0) {
+
+      // quorum / per_group tally against the OPEN-time snapshot (already
+      // OOO-substituted). unanimous re-resolves for back-compat with requests
+      // opened before the snapshot existed.
+      const snapshotGroups = (config as any).__approverGroups as Record<string, string[]> | undefined;
+      let original: string[];
+      let groupMap: Record<string, string[]>;
+      if (snapshotGroups && (behavior === 'quorum' || behavior === 'per_group')) {
+        groupMap = snapshotGroups;
+        original = Object.keys(snapshotGroups);
+      } else {
+        original = await this.expandApprovers(
+          { approvers: config.approvers }, parseJson(raw.payload_json, undefined), org,
+        );
+        groupMap = {};
+      }
+
+      if (!this.isApprovalSatisfied(behavior, config, original, groupMap, approved)) {
+        const stillPending = original.filter(a => !approved.has(a));
         await this.engine.update('sys_approval_request', {
           id: requestId, pending_approvers: stillPending.join(','), updated_at: now,
         }, { context: SYSTEM_CTX });
@@ -1038,8 +1321,21 @@ export class ApprovalService implements IApprovalService {
       step_name: raw.flow_node_id ?? raw.current_step ?? null, step_index: 0, action: 'reassign',
       actor_id: input.actorId, comment: input.comment ?? `${from} → ${to}`, created_at: now,
     }, { context: SYSTEM_CTX });
+    // per_group / quorum (#3266): carry the delegated slot's group membership to
+    // the new approver in the snapshot, so their approval still counts for the
+    // original group.
+    let configPatch: Record<string, unknown> = {};
+    try {
+      const cfg = parseJson<any>(raw.node_config_json, null);
+      const groups = cfg?.__approverGroups as Record<string, string[]> | undefined;
+      if (groups && groups[from] && !groups[to]) {
+        groups[to] = groups[from];
+        delete groups[from];
+        configPatch = { node_config_json: JSON.stringify(cfg) };
+      }
+    } catch { /* snapshot left untouched on parse failure */ }
     await this.engine.update('sys_approval_request', {
-      id: requestId, pending_approvers: next.join(','), updated_at: now,
+      id: requestId, pending_approvers: next.join(','), updated_at: now, ...configPatch,
     }, { context: SYSTEM_CTX });
     await this.syncApproverIndex(requestId, next, raw.organization_id ?? null, now);
 
@@ -1285,7 +1581,7 @@ export class ApprovalService implements IApprovalService {
   /** Free-form reply on the thread (submitter or any pending approver). */
   async comment(
     requestId: string,
-    input: { actorId: string; comment: string },
+    input: { actorId: string; comment: string; attachments?: string[] },
     context: SharingExecutionContext,
   ): Promise<{ request: ApprovalRequestRow }> {
     if (!input?.actorId) throw new Error('VALIDATION_FAILED: actorId is required');
@@ -1301,7 +1597,9 @@ export class ApprovalService implements IApprovalService {
     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,
+      actor_id: input.actorId, comment: input.comment.trim(),
+      attachments: input.attachments?.length ? input.attachments : null,
+      created_at: now,
     }, { context: SYSTEM_CTX });
 
     // Notify the other side of the thread.
@@ -1876,6 +2174,7 @@ export class ApprovalService implements IApprovalService {
     const rows = await this.engine.find('sys_approval_request', findOpts);
     const list = Array.isArray(rows) ? rows.map(rowFromRequest) : [];
     await this.enrichRows(list);
+    this.attachViewers(list, context);
     return list;
   }
 
@@ -1922,9 +2221,77 @@ export class ApprovalService implements IApprovalService {
     const row = rowFromRequest(rows[0]);
     await this.enrichRows([row]);
     await this.attachFlowSteps(row);
+    await this.attachDecisionProgress(row, rows[0]);
+    this.attachViewers([row], context);
     return row;
   }
 
+  /**
+   * Server-computed decision aggregation progress (#3266 / objectui#2678 P1.5).
+   * Single-read enrichment only (like {@link ApprovalService.attachFlowSteps}):
+   * for a PENDING request whose behavior aggregates multiple approvals
+   * (`unanimous` / `quorum` / `per_group`), expose
+   * `decision_progress: { behavior, got, need, groups? }` so any client renders
+   * "2 of 3" or per-group ticks without re-deriving the engine's tally rules.
+   * `first_response` requests carry no progress (one approval finalizes).
+   * Display-only and best-effort — errors leave the row untouched.
+   */
+  private async attachDecisionProgress(row: ApprovalRequestRow, raw: any): Promise<void> {
+    try {
+      if (row.status !== 'pending') return;
+      const cfg = parseJson<any>(raw.node_config_json, undefined);
+      const behavior = cfg?.behavior ?? 'first_response';
+      if (behavior !== 'unanimous' && behavior !== 'quorum' && behavior !== 'per_group') return;
+
+      const acts = await this.engine.find('sys_approval_action', {
+        where: { request_id: row.id, step_index: 0, action: 'approve' }, limit: 1000, context: SYSTEM_CTX,
+      });
+      const approved = new Set<string>((acts ?? []).map((a: any) => String(a.actor_id ?? '')).filter(Boolean));
+
+      const snapshot = cfg?.__approverGroups as Record<string, string[]> | undefined;
+      const slate = snapshot ? Object.keys(snapshot) : [...approved, ...(row.pending_approvers ?? [])];
+      const total = slate.length || 1;
+
+      const progress: any = { behavior, got: approved.size, need: total };
+      if (behavior === 'quorum') {
+        progress.need = Math.min(Math.max(1, cfg?.minApprovals ?? total), total);
+      } else if (behavior === 'per_group' && snapshot) {
+        const perGroupNeed = Math.max(1, cfg?.minApprovals ?? 1);
+        const size: Record<string, number> = {};
+        for (const gs of Object.values(snapshot)) for (const g of gs) size[g] = (size[g] ?? 0) + 1;
+        const got: Record<string, number> = {};
+        for (const a of approved) for (const g of (snapshot[a] ?? [])) got[g] = (got[g] ?? 0) + 1;
+        progress.groups = Object.keys(size).sort().map(g => {
+          const need = Math.min(perGroupNeed, size[g]);
+          return { group: g, got: Math.min(got[g] ?? 0, need), need, satisfied: (got[g] ?? 0) >= need };
+        });
+        progress.got = progress.groups.filter((g: any) => g.satisfied).length;
+        progress.need = progress.groups.length;
+      }
+      (row as any).decision_progress = progress;
+    } catch { /* display-only enrichment */ }
+  }
+
+  /**
+   * Attach the per-viewer capability block (#3310) from the caller's context.
+   * `can_act` mirrors the exact authorization the decision methods enforce — the
+   * caller's user id is in the resolved `pending_approvers` while the request is
+   * still `pending` (position/team/manager approvers are already resolved to
+   * concrete user ids at open time, so a plain membership test is faithful).
+   * `is_submitter` is a straight owner check. System/tokenless contexts get a
+   * both-false block. Cheap + synchronous — safe on list reads.
+   */
+  private attachViewers(rows: ApprovalRequestRow[], context: SharingExecutionContext): void {
+    const uid = (context as any)?.userId != null ? String((context as any).userId) : null;
+    for (const row of rows) {
+      const pending = row.pending_approvers ?? [];
+      (row as any).viewer = {
+        can_act: row.status === 'pending' && !!uid && pending.includes(uid),
+        is_submitter: !!uid && row.submitter_id != null && String(row.submitter_id) === uid,
+      };
+    }
+  }
+
   /**
    * Derive approval-step progress from the owning flow's graph (single-read
    * enrichment only — list reads skip it). Walks from the start node