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

package/dist/index.js

@@ -174,6 +174,55 @@ var init_en_objects_generated = __esm({
             label: "All"
           }
         }
+      },
+      sys_approval_delegation: {
+        label: "Approval Delegation",
+        pluralLabel: "Approval Delegations",
+        description: "Self-service out-of-office rule: route this user's approver slots to a delegate within a time window (#1322 M1).",
+        fields: {
+          id: {
+            label: "Delegation ID"
+          },
+          delegator_id: {
+            label: "Delegator",
+            help: "The user going out of office; their individually-routed approver slots are rerouted while active."
+          },
+          delegate_id: {
+            label: "Delegate",
+            help: "The backup who receives the delegator's approvals while this rule is active. Acts under their own identity."
+          },
+          valid_from: {
+            label: "Valid From",
+            help: "Rule is inactive before this instant. Null = active immediately. Enforced at resolution time via isGrantActive (ADR-0091 D2 predicate) \u2014 never by a background job."
+          },
+          valid_until: {
+            label: "Valid Until",
+            help: "Rule is inactive AT and AFTER this instant (half-open [from, until), UTC). Null = never expires."
+          },
+          reason: {
+            label: "Reason",
+            help: 'Why the delegation exists (e.g. "Annual leave 5/26\u20135/30"). Recorded on the substitution audit row.'
+          },
+          organization_id: {
+            label: "Organization",
+            help: "Tenant that owns this rule; null = applies across tenants for this delegator."
+          },
+          created_at: {
+            label: "Created At"
+          },
+          updated_at: {
+            label: "Updated At"
+          }
+        },
+        _views: {
+          active: {
+            label: "Active",
+            emptyState: {
+              title: "No delegations",
+              message: "Declare an out-of-office delegation so approvals route to a backup while you are away."
+            }
+          }
+        }
       }
     };
   }
@@ -328,6 +377,55 @@ var init_zh_CN_objects_generated = __esm({
             label: "\u5168\u90E8"
           }
         }
+      },
+      sys_approval_delegation: {
+        label: "\u5BA1\u6279\u59D4\u6D3E",
+        pluralLabel: "\u5BA1\u6279\u59D4\u6D3E",
+        description: "\u81EA\u52A9\u4E0D\u5728\u5C97\u89C4\u5219\uFF1A\u5728\u65F6\u95F4\u7A97\u5185\u628A\u8BE5\u7528\u6237\u7684\u5BA1\u6279\u4EBA\u69FD\u4F4D\u6539\u6D3E\u7ED9\u5019\u8865\u4EBA\uFF08#1322 M1\uFF09\u3002",
+        fields: {
+          id: {
+            label: "\u59D4\u6D3E ID"
+          },
+          delegator_id: {
+            label: "\u59D4\u6D3E\u4EBA",
+            help: "\u5373\u5C06\u4E0D\u5728\u5C97\u7684\u7528\u6237\uFF1B\u89C4\u5219\u751F\u6548\u671F\u95F4\uFF0C\u8DEF\u7531\u5230\u5176\u4E2A\u4EBA\u7684\u5BA1\u6279\u4EBA\u69FD\u4F4D\u5C06\u88AB\u6539\u6D3E\u3002"
+          },
+          delegate_id: {
+            label: "\u5019\u8865\u4EBA",
+            help: "\u89C4\u5219\u751F\u6548\u671F\u95F4\u63A5\u6536\u59D4\u6D3E\u4EBA\u5BA1\u6279\u7684\u5019\u8865\u4EBA\u3002\u4EE5\u5176\u672C\u4EBA\u8EAB\u4EFD\u884C\u4F7F\u3002"
+          },
+          valid_from: {
+            label: "\u751F\u6548\u65F6\u95F4",
+            help: "\u6B64\u523B\u4E4B\u524D\u89C4\u5219\u4E0D\u751F\u6548\u3002\u7559\u7A7A = \u7ACB\u5373\u751F\u6548\u3002\u5728\u89E3\u6790\u65F6\u901A\u8FC7 isGrantActive \u5F3A\u5236\uFF08ADR-0091 D2 \u5224\u5B9A\u5F0F\uFF09\u2014\u2014\u7EDD\u4E0D\u4F9D\u8D56\u540E\u53F0\u4EFB\u52A1\u3002"
+          },
+          valid_until: {
+            label: "\u5931\u6548\u65F6\u95F4",
+            help: "\u6B64\u523B\uFF08\u542B\uFF09\u53CA\u4E4B\u540E\u89C4\u5219\u4E0D\u751F\u6548\uFF08\u534A\u5F00\u533A\u95F4 [from, until)\uFF0CUTC\uFF09\u3002\u7559\u7A7A = \u6C38\u4E0D\u8FC7\u671F\u3002"
+          },
+          reason: {
+            label: "\u539F\u56E0",
+            help: "\u59D4\u6D3E\u5B58\u5728\u7684\u539F\u56E0\uFF08\u4F8B\u5982\u201C\u5E74\u5047 5/26\u20135/30\u201D\uFF09\u3002\u4F1A\u8BB0\u5165\u6539\u6D3E\u5BA1\u8BA1\u884C\u3002"
+          },
+          organization_id: {
+            label: "\u7EC4\u7EC7",
+            help: "\u62E5\u6709\u6B64\u89C4\u5219\u7684\u79DF\u6237\uFF1B\u7559\u7A7A = \u5BF9\u8BE5\u59D4\u6D3E\u4EBA\u8DE8\u79DF\u6237\u751F\u6548\u3002"
+          },
+          created_at: {
+            label: "\u521B\u5EFA\u65F6\u95F4"
+          },
+          updated_at: {
+            label: "\u66F4\u65B0\u65F6\u95F4"
+          }
+        },
+        _views: {
+          active: {
+            label: "\u751F\u6548\u4E2D",
+            emptyState: {
+              title: "\u6682\u65E0\u59D4\u6D3E",
+              message: "\u58F0\u660E\u4E00\u6761\u4E0D\u5728\u5C97\u59D4\u6D3E\uFF0C\u4F11\u5047\u671F\u95F4\u5BA1\u6279\u81EA\u52A8\u6539\u6D3E\u7ED9\u5019\u8865\u4EBA\u3002"
+            }
+          }
+        }
       }
     };
   }
@@ -482,6 +580,55 @@ var init_ja_JP_objects_generated = __esm({
             label: "\u3059\u3079\u3066"
           }
         }
+      },
+      sys_approval_delegation: {
+        label: "Approval Delegation",
+        pluralLabel: "Approval Delegations",
+        description: "Self-service out-of-office rule: route this user's approver slots to a delegate within a time window (#1322 M1).",
+        fields: {
+          id: {
+            label: "Delegation ID"
+          },
+          delegator_id: {
+            label: "Delegator",
+            help: "The user going out of office; their individually-routed approver slots are rerouted while active."
+          },
+          delegate_id: {
+            label: "Delegate",
+            help: "The backup who receives the delegator's approvals while this rule is active. Acts under their own identity."
+          },
+          valid_from: {
+            label: "Valid From",
+            help: "Rule is inactive before this instant. Null = active immediately. Enforced at resolution time via isGrantActive (ADR-0091 D2 predicate) \u2014 never by a background job."
+          },
+          valid_until: {
+            label: "Valid Until",
+            help: "Rule is inactive AT and AFTER this instant (half-open [from, until), UTC). Null = never expires."
+          },
+          reason: {
+            label: "Reason",
+            help: 'Why the delegation exists (e.g. "Annual leave 5/26\u20135/30"). Recorded on the substitution audit row.'
+          },
+          organization_id: {
+            label: "Organization",
+            help: "Tenant that owns this rule; null = applies across tenants for this delegator."
+          },
+          created_at: {
+            label: "Created At"
+          },
+          updated_at: {
+            label: "Updated At"
+          }
+        },
+        _views: {
+          active: {
+            label: "Active",
+            emptyState: {
+              title: "No delegations",
+              message: "Declare an out-of-office delegation so approvals route to a backup while you are away."
+            }
+          }
+        }
       }
     };
   }
@@ -636,6 +783,55 @@ var init_es_ES_objects_generated = __esm({
             label: "Todas"
           }
         }
+      },
+      sys_approval_delegation: {
+        label: "Approval Delegation",
+        pluralLabel: "Approval Delegations",
+        description: "Self-service out-of-office rule: route this user's approver slots to a delegate within a time window (#1322 M1).",
+        fields: {
+          id: {
+            label: "Delegation ID"
+          },
+          delegator_id: {
+            label: "Delegator",
+            help: "The user going out of office; their individually-routed approver slots are rerouted while active."
+          },
+          delegate_id: {
+            label: "Delegate",
+            help: "The backup who receives the delegator's approvals while this rule is active. Acts under their own identity."
+          },
+          valid_from: {
+            label: "Valid From",
+            help: "Rule is inactive before this instant. Null = active immediately. Enforced at resolution time via isGrantActive (ADR-0091 D2 predicate) \u2014 never by a background job."
+          },
+          valid_until: {
+            label: "Valid Until",
+            help: "Rule is inactive AT and AFTER this instant (half-open [from, until), UTC). Null = never expires."
+          },
+          reason: {
+            label: "Reason",
+            help: 'Why the delegation exists (e.g. "Annual leave 5/26\u20135/30"). Recorded on the substitution audit row.'
+          },
+          organization_id: {
+            label: "Organization",
+            help: "Tenant that owns this rule; null = applies across tenants for this delegator."
+          },
+          created_at: {
+            label: "Created At"
+          },
+          updated_at: {
+            label: "Updated At"
+          }
+        },
+        _views: {
+          active: {
+            label: "Active",
+            emptyState: {
+              title: "No delegations",
+              message: "Declare an out-of-office delegation so approvals route to a backup while you are away."
+            }
+          }
+        }
       }
     };
   }
@@ -670,6 +866,7 @@ __export(index_exports, {
   ApprovalsServicePlugin: () => ApprovalsServicePlugin,
   SysApprovalAction: () => SysApprovalAction,
   SysApprovalApprover: () => SysApprovalApprover,
+  SysApprovalDelegation: () => SysApprovalDelegation,
   SysApprovalRequest: () => SysApprovalRequest,
   registerApprovalNode: () => registerApprovalNode
 });
@@ -683,7 +880,7 @@ var SysApprovalRequest = import_data.ObjectSchema.create({
   pluralLabel: "Approval Requests",
   icon: "inbox",
   isSystem: true,
-  managedBy: "system",
+  managedBy: "engine-owned",
   description: "Live approval instance tracked per submission",
   displayNameField: "id",
   nameField: "id",
@@ -864,7 +1061,172 @@ var SysApprovalRequest = import_data.ObjectSchema.create({
     // human-readable CSV source of truth only.
     { fields: ["status", "updated_at"] },
     { fields: ["submitter_id", "status"] }
-  ]
+  ],
+  // Server-declared decision actions (objectui#2678 P2-4). The console's
+  // generic action runtime renders and executes these wherever this object is
+  // surfaced — the approvals inbox included — so new decision capabilities
+  // (and their params) ship as metadata, not as hand-written buttons. Each
+  // targets the existing approvals REST route; `{id}` resolves from the row
+  // and `actorId` defaults to the caller server-side. The service remains the
+  // authority on who may act; `visible` gates on the server-computed
+  // per-viewer block (#3310): approver actions on `record.viewer.can_act`
+  // (the caller is a current pending approver — same check the service
+  // authorizes a decision with, so position/team approvers resolve correctly),
+  // submitter actions on `record.viewer.is_submitter`. `viewer` is attached by
+  // getRequest/listRequests; where it is absent the predicate fails closed.
+  actions: [
+    {
+      name: "approval_approve",
+      label: "Approve",
+      icon: "check-circle",
+      type: "api",
+      method: "POST",
+      target: "/api/v1/approvals/requests/{id}/approve",
+      params: [
+        { name: "comment", label: "Comment", type: "textarea", required: false },
+        // Decision attachments (#3266). The console renders `type:'file'` params
+        // through the shared upload widget and POSTs the resolved `attachments:
+        // string[]`; the decision route persists them on `sys_approval_action`.
+        { name: "attachments", label: "Attachments", type: "file", multiple: true, required: false }
+      ],
+      visible: "record.viewer.can_act",
+      locations: ["record_section", "list_item"],
+      successMessage: "Approved.",
+      refreshAfter: true
+    },
+    {
+      name: "approval_reject",
+      label: "Reject",
+      icon: "x-circle",
+      type: "api",
+      method: "POST",
+      target: "/api/v1/approvals/requests/{id}/reject",
+      params: [
+        { name: "comment", label: "Comment", type: "textarea", required: false },
+        { name: "attachments", label: "Attachments", type: "file", multiple: true, required: false }
+      ],
+      visible: "record.viewer.can_act",
+      confirmText: "Reject this request? A rejection is final for every approver.",
+      locations: ["record_section", "list_item"],
+      successMessage: "Rejected.",
+      refreshAfter: true
+    },
+    {
+      name: "approval_reassign",
+      label: "Reassign",
+      icon: "arrow-right-left",
+      type: "api",
+      method: "POST",
+      target: "/api/v1/approvals/requests/{id}/reassign",
+      params: [
+        // Field-backed on `submitter_id` (the object's only `sys_user` lookup):
+        // the console resolves its lookup config (`reference_to: sys_user`) so the
+        // dialog renders a real user picker, while `name: 'to'` overrides the
+        // request-body key to the `to` the reassign route expects. This is a
+        // config-borrow, not a submitter pre-fill (`defaultFromRow` stays off).
+        { field: "submitter_id", name: "to", label: "New approver", required: true, helpText: "User to hand this step to" },
+        { name: "comment", label: "Comment", type: "textarea", required: false }
+      ],
+      visible: "record.viewer.can_act",
+      locations: ["record_section"],
+      successMessage: "Reassigned.",
+      refreshAfter: true
+    },
+    // ── Approver secondary decisions ────────────────────────────────
+    // Send back for revision / request more info (ADR-0044). Both are approver
+    // actions, so `visible` gates on `record.viewer.can_act` (a current pending
+    // approver) — same as approve/reject. The service stays the authority.
+    {
+      name: "approval_send_back",
+      label: "Send back",
+      icon: "corner-up-left",
+      type: "api",
+      method: "POST",
+      target: "/api/v1/approvals/requests/{id}/revise",
+      params: [
+        { name: "comment", label: "Reason", type: "textarea", required: false }
+      ],
+      visible: "record.viewer.can_act",
+      locations: ["record_section"],
+      successMessage: "Sent back for revision.",
+      refreshAfter: true
+    },
+    {
+      name: "approval_request_info",
+      label: "Request info",
+      icon: "help-circle",
+      type: "api",
+      method: "POST",
+      target: "/api/v1/approvals/requests/{id}/request-info",
+      params: [
+        { name: "comment", label: "What do you need?", type: "textarea", required: true }
+      ],
+      visible: "record.viewer.can_act",
+      locations: ["record_section"],
+      successMessage: "Information requested.",
+      refreshAfter: true
+    },
+    // ── Submitter continuity actions ────────────────────────────────
+    // Remind / recall (pending) and resubmit / recall (returned). These are the
+    // submitter's own levers, so `visible` gates on `record.viewer.is_submitter`
+    // (server-computed on the current viewer). The service re-checks ownership;
+    // the predicate keeps a non-submitter from ever seeing a button they cannot
+    // use.
+    {
+      name: "approval_remind",
+      label: "Send reminder",
+      icon: "bell-ring",
+      type: "api",
+      method: "POST",
+      target: "/api/v1/approvals/requests/{id}/remind",
+      params: [
+        { name: "comment", label: "Note", type: "textarea", required: false }
+      ],
+      visible: 'record.status == "pending" && record.viewer.is_submitter',
+      locations: ["record_section"],
+      successMessage: "Reminder sent.",
+      refreshAfter: true
+    },
+    {
+      name: "approval_recall",
+      label: "Recall",
+      icon: "undo-2",
+      type: "api",
+      method: "POST",
+      target: "/api/v1/approvals/requests/{id}/recall",
+      params: [
+        { name: "comment", label: "Comment", type: "textarea", required: false }
+      ],
+      // Recall applies while the request is live for the submitter — pending
+      // (withdraw) or returned (abandon the revision instead of resubmitting).
+      visible: '(record.status == "pending" || record.status == "returned") && record.viewer.is_submitter',
+      confirmText: "Recall this request? Approvers can no longer act on it and the record is unlocked.",
+      locations: ["record_section"],
+      successMessage: "Recalled.",
+      refreshAfter: true
+    },
+    {
+      name: "approval_resubmit",
+      label: "Resubmit",
+      icon: "refresh-cw",
+      type: "api",
+      method: "POST",
+      target: "/api/v1/approvals/requests/{id}/resubmit",
+      params: [
+        { name: "comment", label: "What changed?", type: "textarea", required: false }
+      ],
+      visible: 'record.status == "returned" && record.viewer.is_submitter',
+      locations: ["record_section"],
+      successMessage: "Resubmitted.",
+      refreshAfter: true
+    }
+  ],
+  enable: {
+    // [ADR-0103] Engine-owned: the approval engine owns the request lifecycle
+    // (SYSTEM_CTX); users act via domain actions (Submit/Approve/Recall), never
+    // generic CRUD. Reads stay open.
+    apiMethods: ["get", "list"]
+  }
 });
 
 // src/sys-approval-action.object.ts
@@ -942,8 +1304,9 @@ var SysApprovalAction = import_data2.ObjectSchema.create({
       // Keep in sync with `ApprovalActionKind` (spec/contracts). reassign /
       // remind / request_info / comment are thread interactions — they never
       // move the flow. revise / resubmit (ADR-0044) DO move it: send back for
-      // revision and the later resubmission.
-      ["submit", "approve", "reject", "recall", "escalate", "reassign", "remind", "request_info", "comment", "revise", "resubmit"],
+      // revision and the later resubmission. ooo_substitute (#1322 M1) is a
+      // system-recorded reroute of an out-of-office approver — no flow movement.
+      ["submit", "approve", "reject", "recall", "escalate", "reassign", "remind", "request_info", "comment", "revise", "resubmit", "ooo_substitute"],
       {
         label: "Action",
         required: true,
@@ -956,6 +1319,13 @@ var SysApprovalAction = import_data2.ObjectSchema.create({
       group: "Action"
     }),
     comment: import_data2.Field.textarea({ label: "Comment", required: false, group: "Action" }),
+    attachments: import_data2.Field.file({
+      label: "Attachments",
+      required: false,
+      multiple: true,
+      group: "Action",
+      description: "Files supporting this action \u2014 e.g. a signed contract or evidence (#3266)."
+    }),
     created_at: import_data2.Field.datetime({
       label: "Created At",
       required: true,
@@ -967,7 +1337,12 @@ var SysApprovalAction = import_data2.ObjectSchema.create({
   indexes: [
     { fields: ["request_id", "created_at"] },
     { fields: ["request_id", "step_index", "action"] }
-  ]
+  ],
+  enable: {
+    // [ADR-0103] Engine-owned append-only decision log: appended by the approval
+    // engine (SYSTEM_CTX). Reads stay open.
+    apiMethods: ["get", "list"]
+  }
 });
 
 // src/sys-approval-approver.object.ts
@@ -978,7 +1353,7 @@ var SysApprovalApprover = import_data3.ObjectSchema.create({
   pluralLabel: "Approval Approvers",
   icon: "users",
   isSystem: true,
-  managedBy: "system",
+  managedBy: "engine-owned",
   description: "Normalized pending-approver rows for indexed inbox queries",
   displayNameField: "id",
   nameField: "id",
@@ -1018,18 +1393,125 @@ var SysApprovalApprover = import_data3.ObjectSchema.create({
     { fields: ["approver", "organization_id"] },
     // Sync path: rewrite all rows of one request on each approver-set change.
     { fields: ["request_id"] }
-  ]
+  ],
+  enable: {
+    // [ADR-0103] Engine-owned: approver rows are rewritten by the approval
+    // engine (SYSTEM_CTX) on each approver-set change, never via generic CRUD.
+    apiMethods: ["get", "list"]
+  }
+});
+
+// src/sys-approval-delegation.object.ts
+var import_data4 = require("@objectstack/spec/data");
+var SysApprovalDelegation = import_data4.ObjectSchema.create({
+  name: "sys_approval_delegation",
+  label: "Approval Delegation",
+  pluralLabel: "Approval Delegations",
+  icon: "user-clock",
+  isSystem: true,
+  managedBy: "system",
+  // [ADR-0103] Admin/user-writable DATA on a platform-defined schema: a user
+  // authors their own out-of-office delegation. Affordance only (matches the
+  // full-CRUD apiMethods below) — RLS/permission sets are the authz; opening it
+  // keeps the system write guard from rejecting the self-service write.
+  userActions: { create: true, edit: true, delete: true },
+  description: "Self-service out-of-office rule: route this user's approver slots to a delegate within a time window (#1322 M1).",
+  titleFormat: "{delegator_id} \u2192 {delegate_id}",
+  highlightFields: ["delegator_id", "delegate_id", "valid_from", "valid_until"],
+  listViews: {
+    active: {
+      type: "grid",
+      name: "active",
+      label: "Active",
+      data: { provider: "object", object: "sys_approval_delegation" },
+      columns: ["delegator_id", "delegate_id", "valid_from", "valid_until", "reason"],
+      sort: [{ field: "valid_until", order: "asc" }],
+      pagination: { pageSize: 50 },
+      emptyState: {
+        title: "No delegations",
+        message: "Declare an out-of-office delegation so approvals route to a backup while you are away."
+      }
+    }
+  },
+  fields: {
+    id: import_data4.Field.text({ label: "Delegation ID", required: true, readonly: true, group: "System" }),
+    delegator_id: import_data4.Field.lookup("sys_user", {
+      label: "Delegator",
+      required: true,
+      group: "Delegation",
+      description: "The user going out of office; their individually-routed approver slots are rerouted while active."
+    }),
+    delegate_id: import_data4.Field.lookup("sys_user", {
+      label: "Delegate",
+      required: true,
+      group: "Delegation",
+      description: "The backup who receives the delegator's approvals while this rule is active. Acts under their own identity."
+    }),
+    valid_from: import_data4.Field.datetime({
+      label: "Valid From",
+      required: false,
+      group: "Delegation",
+      description: "Rule is inactive before this instant. Null = active immediately. Enforced at resolution time via isGrantActive (ADR-0091 D2 predicate) \u2014 never by a background job."
+    }),
+    valid_until: import_data4.Field.datetime({
+      label: "Valid Until",
+      required: false,
+      group: "Delegation",
+      description: "Rule is inactive AT and AFTER this instant (half-open [from, until), UTC). Null = never expires."
+    }),
+    reason: import_data4.Field.text({
+      label: "Reason",
+      required: false,
+      maxLength: 500,
+      group: "Delegation",
+      description: 'Why the delegation exists (e.g. "Annual leave 5/26\u20135/30"). Recorded on the substitution audit row.'
+    }),
+    organization_id: import_data4.Field.lookup("sys_organization", {
+      label: "Organization",
+      required: false,
+      group: "System",
+      description: "Tenant that owns this rule; null = applies across tenants for this delegator."
+    }),
+    created_at: import_data4.Field.datetime({
+      label: "Created At",
+      defaultValue: "NOW()",
+      readonly: true,
+      group: "System"
+    }),
+    updated_at: import_data4.Field.datetime({
+      label: "Updated At",
+      defaultValue: "NOW()",
+      readonly: true,
+      group: "System"
+    })
+  },
+  indexes: [
+    // Resolution-time lookup: "active delegations for this delegator".
+    { fields: ["delegator_id", "organization_id"] },
+    { fields: ["delegate_id"] },
+    { fields: ["valid_until"] }
+  ],
+  enable: {
+    trackHistory: true,
+    searchable: true,
+    apiEnabled: true,
+    apiMethods: ["get", "list", "create", "update", "delete"],
+    trash: true,
+    mru: false
+  }
 });
 
 // src/approval-service.ts
 var import_node_crypto = require("crypto");
 var import_automation = require("@objectstack/spec/automation");
+var import_core = require("@objectstack/core");
 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, positions: [], permissions: [] };
+var OOO_MAX_CHAIN = 8;
 function uid(prefix) {
   const g = globalThis;
   if (g.crypto?.randomUUID) return `${prefix}_${g.crypto.randomUUID()}`;
@@ -1102,6 +1584,10 @@ function rowFromAction(row) {
     action: row.action,
     actor_id: row.actor_id ?? void 0,
     comment: row.comment ?? void 0,
+    // 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) : void 0,
     created_at: row.created_at ?? void 0
   };
 }
@@ -1126,8 +1612,12 @@ var _ApprovalService = class _ApprovalService {
   async notify(input) {
     const audience = input.audience.filter((a) => a && !a.includes(":"));
     if (!this.messaging || !audience.length) return 0;
+    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) {
       this.logger?.warn?.("[approvals] notification failed", {
@@ -1152,10 +1642,10 @@ var _ApprovalService = class _ApprovalService {
   }
   /**
    * 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)
@@ -1163,66 +1653,90 @@ var _ApprovalService = class _ApprovalService {
    *                    → 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.
    */
-  async expandApprovers(step, record, organizationId) {
+  async expandApprovers(step, record, organizationId, opts) {
+    var _a;
     if (!step || !Array.isArray(step.approvers)) return [];
+    const now = opts?.now ?? this.clock.now().getTime();
     const out = [];
-    for (const a of step.approvers) {
+    const specs = 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;
+      const ids = await this.resolveApproverSpec(a, record, organizationId, now, opts?.substitutions);
+      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) ((_a = opts.groups)[u] ?? (_a[u] = [])).push(groupKey);
       }
-      if (a.type === "field" && record) {
-        out.push(String(record[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[a.value] ?? record.owner_id;
-          if (subject) {
-            const mgr = await this.lookupManager(String(subject));
-            if (mgr) {
-              out.push(mgr);
-              continue;
-            }
-          }
+    }
+    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.
+   */
+  async resolveApproverSpec(a, record, organizationId, now, substitutions) {
+    const type = (0, import_automation.canonicalApproverType)(String(a.type));
+    if (type !== a.type) {
+      this.logger?.warn?.(
+        `[approvals] approver type '${a.type}' is deprecated (ADR-0090 D3) \u2014 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[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[a.value] ?? record.owner_id;
+        if (subject) {
+          const mgr = await this.lookupManager(String(subject));
+          if (mgr) return this.applyOooDelegation(mgr, now, organizationId, substitutions);
         }
-      } catch {
       }
-      out.push(`${a.type}:${a.value}`);
+    } catch {
     }
-    return out.filter(Boolean);
+    return [`${a.type}:${a.value}`];
   }
   /** Flat team — `sys_team` is better-auth's collaboration grouping (no hierarchy). */
   async expandTeamUsers(teamId) {
@@ -1314,13 +1828,18 @@ var _ApprovalService = class _ApprovalService {
       }
     } catch {
     }
-    for (const uid2 of await this.expandRoleUsers(positionName, organizationId)) users.add(uid2);
+    for (const uid2 of await this.expandMembershipTierUsers(positionName, organizationId)) users.add(uid2);
     return Array.from(users);
   }
-  /** better-auth org-membership tier (`sys_member.role`) — NOT positions. */
-  async expandRoleUsers(roleName, organizationId) {
-    if (!roleName) return [];
-    const filter = { 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.
+   */
+  async expandMembershipTierUsers(tier, organizationId) {
+    if (!tier) return [];
+    const filter = { role: tier };
     if (organizationId) filter.organization_id = organizationId;
     let rows = [];
     try {
@@ -1344,6 +1863,62 @@ var _ApprovalService = class _ApprovalService {
       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.
+   */
+  async applyOooDelegation(userId, now, organizationId, collector) {
+    const start = String(userId ?? "").trim();
+    if (!start) return [];
+    let current = start;
+    const visited = /* @__PURE__ */ new Set([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;
+      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).
+   */
+  async lookupActiveDelegation(delegatorId, now, organizationId) {
+    if (!delegatorId) return null;
+    let rows = [];
+    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
+      });
+    } catch {
+      return null;
+    }
+    const active = (rows ?? []).filter((r) => (0, import_core.isGrantActive)(r, now) && (organizationId == null || r.organization_id == null || String(r.organization_id) === String(organizationId)));
+    if (!active.length) return null;
+    active.sort((a, b) => {
+      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. */
   async mirrorStatusField(object, recordId, field, status) {
     try {
@@ -1377,13 +1952,24 @@ var _ApprovalService = class _ApprovalService {
       throw new Error(`DUPLICATE_REQUEST: a pending approval already exists for ${input.object}/${input.recordId}`);
     }
     const ctxOrg = context?.organizationId ?? context?.tenantId ?? input.organizationId ?? null;
-    const approvers = await this.expandApprovers({ approvers: input.config.approvers }, input.record, ctxOrg);
-    const now = this.clock.now().toISOString();
+    const nowDate = this.clock.now();
+    const substitutions = [];
+    const groups = {};
+    const approvers = await this.expandApprovers(
+      { approvers: input.config.approvers },
+      input.record,
+      ctxOrg,
+      { now: nowDate.getTime(), substitutions, groups }
+    );
+    const now = nowDate.toISOString();
     const id = uid("areq");
     const processName = `flow:${input.flowName ?? input.nodeId}`;
     const configSnapshot = { ...input.config };
     if (input.flowLabel) configSnapshot.__flowLabel = input.flowLabel;
     if (input.nodeLabel) configSnapshot.__nodeLabel = input.nodeLabel;
+    if (input.config.behavior === "quorum" || input.config.behavior === "per_group") {
+      configSnapshot.__approverGroups = groups;
+    }
     try {
       const prior = await this.engine.find("sys_approval_request", {
         where: { flow_run_id: input.runId, flow_node_id: input.nodeId },
@@ -1425,17 +2011,83 @@ var _ApprovalService = class _ApprovalService {
       comment: null,
       created_at: now
     }, { context: SYSTEM_CTX });
+    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} \u2192 ${sub.to}${sub.reason ? ` \u2014 ${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"
+        }
+      });
+    }
     if (input.config.approvalStatusField) {
       await this.mirrorStatusField(input.object, input.recordId, input.config.approvalStatusField, "pending");
     }
     return rowFromRequest(row);
   }
   /**
-   * 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.
+   */
+  isApprovalSatisfied(behavior, config, original, groupMap, approved) {
+    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);
+      return approved.size >= need;
+    }
+    if (behavior === "per_group") {
+      const perGroupNeed = Math.max(1, config.minApprovals ?? 1);
+      const size = {};
+      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;
+      const got = {};
+      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;
+  }
+  /**
+   * 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, input, context) {
     if (!requestId) throw new Error("VALIDATION_FAILED: requestId is required");
@@ -1469,22 +2121,33 @@ var _ApprovalService = class _ApprovalService {
       action: input.decision,
       actor_id: input.actorId,
       comment: input.comment ?? null,
+      attachments: input.attachments?.length ? input.attachments : null,
       created_at: now
     }, { context: SYSTEM_CTX });
-    if (input.decision === "approve" && config.behavior === "unanimous") {
-      const original = await this.expandApprovers(
-        { approvers: config.approvers },
-        parseJson(raw.payload_json, void 0),
-        org
-      );
+    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,
+        limit: 1e3,
         context: SYSTEM_CTX
       });
       const approved = new Set((acts ?? []).map((a) => String(a.actor_id ?? "")).filter(Boolean));
-      const stillPending = original.filter((a) => !approved.has(a));
-      if (stillPending.length > 0) {
+      const snapshotGroups = config.__approverGroups;
+      let original;
+      let groupMap;
+      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, void 0),
+          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(","),
@@ -1918,10 +2581,22 @@ var _ApprovalService = class _ApprovalService {
       comment: input.comment ?? `${from} \u2192 ${to}`,
       created_at: now
     }, { context: SYSTEM_CTX });
+    let configPatch = {};
+    try {
+      const cfg = parseJson(raw.node_config_json, null);
+      const groups = cfg?.__approverGroups;
+      if (groups && groups[from] && !groups[to]) {
+        groups[to] = groups[from];
+        delete groups[from];
+        configPatch = { node_config_json: JSON.stringify(cfg) };
+      }
+    } catch {
+    }
     await this.engine.update("sys_approval_request", {
       id: requestId,
       pending_approvers: next.join(","),
-      updated_at: now
+      updated_at: now,
+      ...configPatch
     }, { context: SYSTEM_CTX });
     await this.syncApproverIndex(requestId, next, raw.organization_id ?? null, now);
     await this.notify({
@@ -2166,6 +2841,7 @@ var _ApprovalService = class _ApprovalService {
       action: "comment",
       actor_id: input.actorId,
       comment: input.comment.trim(),
+      attachments: input.attachments?.length ? input.attachments : null,
       created_at: now
     }, { context: SYSTEM_CTX });
     const audience = isSubmitter ? pending : [String(raw.submitter_id ?? "")].filter(Boolean);
@@ -2683,6 +3359,7 @@ var _ApprovalService = class _ApprovalService {
     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;
   }
   async countRequests(filter, context) {
@@ -2723,8 +3400,74 @@ var _ApprovalService = class _ApprovalService {
     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.
+   */
+  async attachDecisionProgress(row, raw) {
+    try {
+      if (row.status !== "pending") return;
+      const cfg = parseJson(raw.node_config_json, void 0);
+      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: 1e3,
+        context: SYSTEM_CTX
+      });
+      const approved = new Set((acts ?? []).map((a) => String(a.actor_id ?? "")).filter(Boolean));
+      const snapshot = cfg?.__approverGroups;
+      const slate = snapshot ? Object.keys(snapshot) : [...approved, ...row.pending_approvers ?? []];
+      const total = slate.length || 1;
+      const progress = { 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 = {};
+        for (const gs of Object.values(snapshot)) for (const g of gs) size[g] = (size[g] ?? 0) + 1;
+        const got = {};
+        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) => g.satisfied).length;
+        progress.need = progress.groups.length;
+      }
+      row.decision_progress = progress;
+    } catch {
+    }
+  }
+  /**
+   * 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.
+   */
+  attachViewers(rows, context) {
+    const uid2 = context?.userId != null ? String(context.userId) : null;
+    for (const row of rows) {
+      const pending = row.pending_approvers ?? [];
+      row.viewer = {
+        can_act: row.status === "pending" && !!uid2 && pending.includes(uid2),
+        is_submitter: !!uid2 && row.submitter_id != null && String(row.submitter_id) === uid2
+      };
+    }
+  }
   /**
    * Derive approval-step progress from the owning flow's graph (single-read
    * enrichment only — list reads skip it). Walks from the start node
@@ -2786,26 +3529,26 @@ _ApprovalService.APPROVER_INDEX_CAP = 1e4;
 var ApprovalService = _ApprovalService;
 
 // src/sys-approval-token.object.ts
-var import_data4 = require("@objectstack/spec/data");
-var SysApprovalToken = import_data4.ObjectSchema.create({
+var import_data5 = require("@objectstack/spec/data");
+var SysApprovalToken = import_data5.ObjectSchema.create({
   name: "sys_approval_token",
   label: "Approval Action Token",
   pluralLabel: "Approval Action Tokens",
   icon: "key",
   isSystem: true,
-  managedBy: "system",
+  managedBy: "engine-owned",
   description: "Single-use tokens behind actionable approval links",
   displayNameField: "id",
   nameField: "id",
   // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   fields: {
-    id: import_data4.Field.text({ label: "Token ID", required: true, readonly: true, group: "System" }),
-    organization_id: import_data4.Field.lookup("sys_organization", {
+    id: import_data5.Field.text({ label: "Token ID", required: true, readonly: true, group: "System" }),
+    organization_id: import_data5.Field.lookup("sys_organization", {
       label: "Organization",
       required: false,
       group: "System"
     }),
-    token_hash: import_data4.Field.text({
+    token_hash: import_data5.Field.text({
       label: "Token Hash",
       required: true,
       maxLength: 100,
@@ -2813,20 +3556,20 @@ var SysApprovalToken = import_data4.ObjectSchema.create({
       description: "SHA-256 hex of the raw token \u2014 the raw value is never stored",
       group: "Token"
     }),
-    request_id: import_data4.Field.text({
+    request_id: import_data5.Field.text({
       label: "Request",
       required: true,
       maxLength: 100,
       readonly: true,
       group: "Token"
     }),
-    action: import_data4.Field.select(["approve", "reject"], {
+    action: import_data5.Field.select(["approve", "reject"], {
       label: "Action",
       required: true,
       readonly: true,
       group: "Token"
     }),
-    approver_id: import_data4.Field.text({
+    approver_id: import_data5.Field.text({
       label: "Approver",
       required: true,
       maxLength: 200,
@@ -2834,18 +3577,18 @@ var SysApprovalToken = import_data4.ObjectSchema.create({
       description: "Identity the token is bound to; the decision is audited as this approver",
       group: "Token"
     }),
-    expires_at: import_data4.Field.datetime({
+    expires_at: import_data5.Field.datetime({
       label: "Expires At",
       required: true,
       readonly: true,
       group: "Lifecycle"
     }),
-    consumed_at: import_data4.Field.datetime({
+    consumed_at: import_data5.Field.datetime({
       label: "Consumed At",
       required: false,
       group: "Lifecycle"
     }),
-    created_at: import_data4.Field.datetime({
+    created_at: import_data5.Field.datetime({
       label: "Created At",
       required: true,
       defaultValue: "NOW()",
@@ -2856,7 +3599,12 @@ var SysApprovalToken = import_data4.ObjectSchema.create({
   indexes: [
     { fields: ["token_hash"] },
     { fields: ["request_id"] }
-  ]
+  ],
+  enable: {
+    // [ADR-0103] Engine-owned: one-time email-approval tokens are minted and
+    // consumed by the approval engine (SYSTEM_CTX), never via the data API.
+    apiMethods: ["get", "list"]
+  }
 });
 
 // src/action-link-pages.ts
@@ -2980,6 +3728,40 @@ function bindApprovalLockHook(engine, logger) {
   }, { packageId: APPROVALS_HOOK_PACKAGE, priority: 50 });
   logger?.info?.("[approvals] record-lock hook bound");
 }
+var DELEGATION_OBJECT = "sys_approval_delegation";
+function bindDelegationWriteGuard(engine, logger) {
+  const makeGuard = (isInsert) => async (ctx) => {
+    const session = ctx?.session ?? {};
+    if (session.isSystem) return;
+    const roles = session.roles ?? [];
+    if (Array.isArray(roles) && roles.includes("admin")) return;
+    const userId = session.userId != null ? String(session.userId) : "";
+    const data = ctx?.input?.data;
+    const rows = Array.isArray(data) ? data : data && typeof data === "object" ? [data] : [];
+    const deny = () => {
+      const err = new Error(
+        "FORBIDDEN: you may only manage out-of-office delegations where you are the delegator" + (userId ? ` ('${userId}')` : "")
+      );
+      err.code = "FORBIDDEN";
+      err.statusCode = 403;
+      throw err;
+    };
+    for (const row of rows) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      const has = Object.prototype.hasOwnProperty.call(row, "delegator_id");
+      const supplied = has ? String(row.delegator_id ?? "") : "";
+      if (isInsert && (!has || supplied === "")) {
+        if (!userId) deny();
+        row.delegator_id = userId;
+        continue;
+      }
+      if (has && supplied !== userId) deny();
+    }
+  };
+  engine.registerHook("beforeInsert", makeGuard(true), { object: DELEGATION_OBJECT, packageId: APPROVALS_HOOK_PACKAGE, priority: 50 });
+  engine.registerHook("beforeUpdate", makeGuard(false), { object: DELEGATION_OBJECT, packageId: APPROVALS_HOOK_PACKAGE, priority: 50 });
+  logger?.info?.("[approvals] delegation write-guard bound");
+}
 function unbindAllHooks(engine) {
   return engine.unregisterHooksByPackage(APPROVALS_HOOK_PACKAGE);
 }
@@ -3075,7 +3857,7 @@ var ApprovalsServicePlugin = class {
       scope: "system",
       defaultDatasource: "cloud",
       namespace: "sys",
-      objects: [SysApprovalRequest, SysApprovalAction, SysApprovalApprover, SysApprovalToken],
+      objects: [SysApprovalRequest, SysApprovalAction, SysApprovalApprover, SysApprovalToken, SysApprovalDelegation],
       // ADR-0029 D7 — contribute the Approvals entries into the Setup app's
       // `group_approvals` slot. This plugin owns these objects (K2.b), so it
       // ships their menu too; when the plugin isn't installed the slot is empty.
@@ -3086,7 +3868,8 @@ var ApprovalsServicePlugin = class {
           priority: 100,
           items: [
             { id: "nav_approval_requests", type: "object", label: "Requests", objectName: "sys_approval_request", icon: "inbox", requiresObject: "sys_approval_request" },
-            { id: "nav_approval_actions", type: "object", label: "Action History", objectName: "sys_approval_action", icon: "history", requiresObject: "sys_approval_action" }
+            { id: "nav_approval_actions", type: "object", label: "Action History", objectName: "sys_approval_action", icon: "history", requiresObject: "sys_approval_action" },
+            { id: "nav_approval_delegations", type: "object", label: "Delegations (OOO)", objectName: "sys_approval_delegation", icon: "user-clock", requiresObject: "sys_approval_delegation" }
           ]
         }
       ]
@@ -3132,8 +3915,9 @@ var ApprovalsServicePlugin = class {
       try {
         unbindAllHooks(engine);
         bindApprovalLockHook(engine, ctx.logger);
+        bindDelegationWriteGuard(engine, ctx.logger);
       } catch (err) {
-        ctx.logger.warn?.("[approvals] failed to bind record-lock hook", { error: err?.message });
+        ctx.logger.warn?.("[approvals] failed to bind approval hooks", { error: err?.message });
       }
     }
     ctx.registerService("approvals", this.service);
@@ -3251,6 +4035,7 @@ var ApprovalsServicePlugin = class {
   ApprovalsServicePlugin,
   SysApprovalAction,
   SysApprovalApprover,
+  SysApprovalDelegation,
   SysApprovalRequest,
   registerApprovalNode
 });