@objectstack/plugin-approvals 17.0.0-rc.6 → 17.1.0

package/dist/index.mjs

@@ -128,7 +128,7 @@ var init_en_objects_generated = __esm({
           },
           approval_reject: {
             label: "Reject",
-            confirmText: "Reject this request? A rejection is final for every approver.",
+            description: "Reject this request? A rejection is final for every approver.",
             successMessage: "Rejected.",
             params: {
               comment: {
@@ -181,7 +181,7 @@ var init_en_objects_generated = __esm({
           },
           approval_recall: {
             label: "Recall",
-            confirmText: "Recall this request? Approvers can no longer act on it and the record is unlocked.",
+            description: "Recall this request? Approvers can no longer act on it and the record is unlocked.",
             successMessage: "Recalled.",
             params: {
               comment: {
@@ -225,18 +225,18 @@ var init_en_objects_generated = __esm({
           action: {
             label: "Action",
             options: {
-              submit: "submit",
-              approve: "approve",
-              reject: "reject",
-              recall: "recall",
-              escalate: "escalate",
-              reassign: "reassign",
-              remind: "remind",
-              request_info: "request_info",
-              comment: "comment",
-              revise: "revise",
-              resubmit: "resubmit",
-              ooo_substitute: "ooo_substitute"
+              submit: "Submit",
+              approve: "Approve",
+              reject: "Reject",
+              recall: "Recall",
+              escalate: "Escalate",
+              reassign: "Reassign",
+              remind: "Remind",
+              request_info: "Request Info",
+              comment: "Comment",
+              revise: "Revise",
+              resubmit: "Resubmit",
+              ooo_substitute: "Out-of-Office Substitution"
             }
           },
           actor_id: {
@@ -449,7 +449,7 @@ var init_zh_CN_objects_generated = __esm({
           },
           approval_reject: {
             label: "\u62D2\u7EDD",
-            confirmText: "\u62D2\u7EDD\u8BE5\u8BF7\u6C42\uFF1F\u62D2\u7EDD\u5BF9\u6240\u6709\u5BA1\u6279\u4EBA\u7ACB\u5373\u751F\u6548\u3002",
+            description: "\u62D2\u7EDD\u8BE5\u8BF7\u6C42\uFF1F\u62D2\u7EDD\u5BF9\u6240\u6709\u5BA1\u6279\u4EBA\u7ACB\u5373\u751F\u6548\u3002",
             successMessage: "\u5DF2\u62D2\u7EDD\u3002",
             params: {
               comment: {
@@ -502,7 +502,7 @@ var init_zh_CN_objects_generated = __esm({
           },
           approval_recall: {
             label: "\u64A4\u56DE",
-            confirmText: "\u64A4\u56DE\u8BE5\u8BF7\u6C42\uFF1F\u64A4\u56DE\u540E\u5BA1\u6279\u4EBA\u5C06\u65E0\u6CD5\u7EE7\u7EED\u5904\u7406\uFF0C\u8BB0\u5F55\u968F\u5373\u89E3\u9501\u3002",
+            description: "\u64A4\u56DE\u8BE5\u8BF7\u6C42\uFF1F\u64A4\u56DE\u540E\u5BA1\u6279\u4EBA\u5C06\u65E0\u6CD5\u7EE7\u7EED\u5904\u7406\uFF0C\u8BB0\u5F55\u968F\u5373\u89E3\u9501\u3002",
             successMessage: "\u5DF2\u64A4\u56DE\u3002",
             params: {
               comment: {
@@ -770,7 +770,7 @@ var init_ja_JP_objects_generated = __esm({
           },
           approval_reject: {
             label: "\u5374\u4E0B",
-            confirmText: "\u3053\u306E\u30EA\u30AF\u30A8\u30B9\u30C8\u3092\u5374\u4E0B\u3057\u307E\u3059\u304B\uFF1F\u5374\u4E0B\u306F\u3059\u3079\u3066\u306E\u627F\u8A8D\u8005\u306B\u5BFE\u3057\u3066\u6700\u7D42\u6C7A\u5B9A\u306B\u306A\u308A\u307E\u3059\u3002",
+            description: "\u3053\u306E\u30EA\u30AF\u30A8\u30B9\u30C8\u3092\u5374\u4E0B\u3057\u307E\u3059\u304B\uFF1F\u5374\u4E0B\u306F\u3059\u3079\u3066\u306E\u627F\u8A8D\u8005\u306B\u5BFE\u3057\u3066\u6700\u7D42\u6C7A\u5B9A\u306B\u306A\u308A\u307E\u3059\u3002",
             successMessage: "\u5374\u4E0B\u3057\u307E\u3057\u305F\u3002",
             params: {
               comment: {
@@ -823,7 +823,7 @@ var init_ja_JP_objects_generated = __esm({
           },
           approval_recall: {
             label: "\u53D6\u308A\u4E0B\u3052",
-            confirmText: "\u3053\u306E\u30EA\u30AF\u30A8\u30B9\u30C8\u3092\u53D6\u308A\u4E0B\u3052\u307E\u3059\u304B\uFF1F\u627F\u8A8D\u8005\u306F\u64CD\u4F5C\u3067\u304D\u306A\u304F\u306A\u308A\u3001\u30EC\u30B3\u30FC\u30C9\u306E\u30ED\u30C3\u30AF\u304C\u89E3\u9664\u3055\u308C\u307E\u3059\u3002",
+            description: "\u3053\u306E\u30EA\u30AF\u30A8\u30B9\u30C8\u3092\u53D6\u308A\u4E0B\u3052\u307E\u3059\u304B\uFF1F\u627F\u8A8D\u8005\u306F\u64CD\u4F5C\u3067\u304D\u306A\u304F\u306A\u308A\u3001\u30EC\u30B3\u30FC\u30C9\u306E\u30ED\u30C3\u30AF\u304C\u89E3\u9664\u3055\u308C\u307E\u3059\u3002",
             successMessage: "\u53D6\u308A\u4E0B\u3052\u307E\u3057\u305F\u3002",
             params: {
               comment: {
@@ -1091,7 +1091,7 @@ var init_es_ES_objects_generated = __esm({
           },
           approval_reject: {
             label: "Rechazar",
-            confirmText: "\xBFRechazar esta solicitud? Un rechazo es definitivo para todos los aprobadores.",
+            description: "\xBFRechazar esta solicitud? Un rechazo es definitivo para todos los aprobadores.",
             successMessage: "Rechazada.",
             params: {
               comment: {
@@ -1144,7 +1144,7 @@ var init_es_ES_objects_generated = __esm({
           },
           approval_recall: {
             label: "Retirar",
-            confirmText: "\xBFRetirar esta solicitud? Los aprobadores ya no podr\xE1n actuar sobre ella y el registro se desbloquear\xE1.",
+            description: "\xBFRetirar esta solicitud? Los aprobadores ya no podr\xE1n actuar sobre ella y el registro se desbloquear\xE1.",
             successMessage: "Retirada.",
             params: {
               comment: {
@@ -1321,7 +1321,7 @@ var init_translations = __esm({
 
 // src/sys-approval-request.object.ts
 import { ObjectSchema, Field } from "@objectstack/spec/data";
-import { APPROVAL_STATUSES } from "@objectstack/spec/contracts";
+import { APPROVAL_STATUSES, APPROVAL_STATUS_LABELS } from "@objectstack/spec/contracts";
 var SysApprovalRequest = ObjectSchema.create({
   name: "sys_approval_request",
   label: "Approval Request",
@@ -1384,10 +1384,45 @@ var SysApprovalRequest = ObjectSchema.create({
   },
   fields: {
     id: Field.text({ label: "Request ID", required: true, readonly: true, group: "System" }),
+    // ⚠️ MEASURED DEFECT, cloud#1395 — read this before trusting the column.
+    //
+    // An approval request DOES belong to an organization: it is read through the
+    // organization wall by the approvals inbox, and on a shared-database
+    // deployment a row carrying no organization is not filtered BY that wall —
+    // it is either invisible to everyone or visible to everyone, decided by
+    // whatever filter each surface happens to apply rather than by the data.
+    //
+    // The value is resolved from the ACTING CONTEXT only (`openNodeRequest`'s
+    // `ctxOrg`), so it is NULL whenever the flow that opened the request ran
+    // without one — every schedule / time-relative / api triggered run, none of
+    // which sets a tenant. On a walled single-database HotCRM SaaS boot this
+    // measured 27 of 27 rows org-less, each naming an `object_name` /
+    // `record_id` owned by a specific customer.
+    //
+    // ⛔ Do NOT read that as "platform tables do not carry an organization".
+    // `sys_audit_log` (1669 rows) was correctly attributed on the SAME boot,
+    // because its writer takes the organization from the RECORD the row is
+    // about, with the session only as fallback (plugin-audit
+    // `resolveRecordOrganizationField`, #8707 honouring #8287's ruling). Two
+    // writers read the actor; a third reads the subject. That disagreement is
+    // the defect.
+    //
+    // Which of the two a side-table row should follow is an open contract
+    // question on cloud#1395 — the audit resolver is scope-pinned to audit
+    // stamping by the #8778 ruling, so this writer needs its own. The same
+    // `ctxOrg` also stamps `sys_approval_action` and `sys_approval_approver`,
+    // so all three move together.
     organization_id: Field.lookup("sys_organization", {
       label: "Organization",
       required: false,
       group: "System",
+      // ⛔ String unchanged on purpose: it is extracted into the generated i18n
+      // bundles (`translations/*.objects.generated.ts`, as `help`), so rewording
+      // it is a translation-regeneration change and not a comment. The
+      // correction it needs — it claims a propagation that measurably does not
+      // happen, and says "Tenant" where ADR-0120 §Terminology requires
+      // "organization" — rides the cloud#1395 write-side fix, which rewrites the
+      // sentence and regenerates the four locales in one pass.
       description: "Tenant that owns this approval request (propagated from submitter context)"
     }),
     process_name: Field.text({
@@ -1420,10 +1455,13 @@ var SysApprovalRequest = ObjectSchema.create({
       group: "Target"
     }),
     status: Field.select(
-      // Spread from the contract, not re-typed (#3786). `APPROVAL_STATUSES` is
+      // Derived from the contract, not re-typed (#3786). `APPROVAL_STATUSES` is
       // where the list and the reason for each entry live; `ApprovalStatus` is
-      // derived from it, so this column and the contract cannot disagree.
-      [...APPROVAL_STATUSES],
+      // derived from it, so this column and the contract cannot disagree. The
+      // authored English label per entry lives beside it in
+      // `APPROVAL_STATUS_LABELS` (#8543) — mapped here, never re-typed, so the
+      // `en` bundle regenerates from the contract's own text.
+      APPROVAL_STATUSES.map((value) => ({ value, label: APPROVAL_STATUS_LABELS[value] })),
       {
         label: "Status",
         required: true,
@@ -1528,6 +1566,28 @@ var SysApprovalRequest = ObjectSchema.create({
   // approving, rejecting, or reassigning it to a real approver. `viewer` is
   // attached by getRequest/listRequests; where it is absent the predicate fails
   // closed.
+  //
+  // Every predicate below is guarded for the SPARSE action face (#8990). This
+  // binding is a list row or a record read carrying only what the caller
+  // projected, and CEL aborts the whole expression at key resolution — so the
+  // unguarded `record.viewer.can_act` faulted (`No such key: viewer`) on any
+  // row without the block, and the button silently vanished, indistinguishable
+  // from "the gate said no". `materializeDeclaredFields`'s doc comment in
+  // `@objectstack/objectql` is the canonical statement of the guard rule; this
+  // file follows it and does not restate it.
+  //
+  // `viewer` is a NESTED block, which needs one measurement the canonical rule
+  // does not spell out. Measured against the `@objectstack/formula` CEL engine:
+  // `has(record.viewer) && record.viewer != null && record.viewer.can_act`
+  // still FAULTS on `{viewer: {}}` (`No such key: can_act`) and on
+  // `{viewer: {can_act: null}}` (`Logical operator requires bool operands`).
+  // Guarding the LEAF instead — `has(record.viewer) &&
+  // has(record.viewer.can_act) && record.viewer.can_act == true` — is total
+  // over every binding AND subsumes the parent `!= null` half, because `has()`
+  // on a path whose parent is null answers `false` rather than faulting. So the
+  // leaf `has()` plus the `== true` comparison is the MINIMAL safe form here,
+  // not a longer one: `== true` is load-bearing (a bare truthy read of a null
+  // leaf faults the logical operator), the parent `!= null` is not.
   actions: [
     {
       name: "approval_approve",
@@ -1547,7 +1607,7 @@ var SysApprovalRequest = ObjectSchema.create({
         // string[]`; the decision route persists them on `sys_approval_action`.
         { name: "attachments", label: "Attachments", type: "file", multiple: true, required: false }
       ],
-      visible: "record.viewer.can_act || record.viewer.can_override",
+      visible: "has(record.viewer) && has(record.viewer.can_act) && record.viewer.can_act == true || has(record.viewer) && has(record.viewer.can_override) && record.viewer.can_override == true",
       locations: ["record_section", "list_item"],
       successMessage: "Approved.",
       refreshAfter: true
@@ -1555,6 +1615,15 @@ var SysApprovalRequest = ObjectSchema.create({
     {
       name: "approval_reject",
       label: "Reject",
+      // The confirm question lives HERE, not in `confirmText`: this action
+      // collects params, so the console would otherwise chain a confirm dialog
+      // and then the param dialog for one decision — and the first one already
+      // reads as "the action ran" (#7278, maintainer ruling 2026-08-10). The
+      // param dialog renders this as its description, and nothing is POSTed
+      // until its own Confirm: one condition, one wording, one dialog.
+      // NB: the top-level action `description` (#7367), never `ai.description`
+      // — that one is the LLM-facing tool contract and is not shown to anyone.
+      description: "Reject this request? A rejection is final for every approver.",
       icon: "x-circle",
       // Destructive decision — rendered in the console's danger styling so it
       // reads as the irreversible action it is (objectui#2762 P1-5).
@@ -1566,8 +1635,7 @@ var SysApprovalRequest = ObjectSchema.create({
         { name: "comment", label: "Comment", type: "textarea", required: false },
         { name: "attachments", label: "Attachments", type: "file", multiple: true, required: false }
       ],
-      visible: "record.viewer.can_act || record.viewer.can_override",
-      confirmText: "Reject this request? A rejection is final for every approver.",
+      visible: "has(record.viewer) && has(record.viewer.can_act) && record.viewer.can_act == true || has(record.viewer) && has(record.viewer.can_override) && record.viewer.can_override == true",
       locations: ["record_section", "list_item"],
       successMessage: "Rejected.",
       refreshAfter: true
@@ -1588,7 +1656,7 @@ var SysApprovalRequest = ObjectSchema.create({
         { field: "submitter_id", name: "to", label: "New approver", required: true, helpText: "User to hand this step to" },
         { name: "comment", label: "Comment", type: "textarea", required: false }
       ],
-      visible: "record.viewer.can_act || record.viewer.can_override",
+      visible: "has(record.viewer) && has(record.viewer.can_act) && record.viewer.can_act == true || has(record.viewer) && has(record.viewer.can_override) && record.viewer.can_override == true",
       locations: ["record_section"],
       successMessage: "Reassigned.",
       refreshAfter: true
@@ -1607,7 +1675,7 @@ var SysApprovalRequest = ObjectSchema.create({
       params: [
         { name: "comment", label: "Reason", type: "textarea", required: false }
       ],
-      visible: "record.viewer.can_act",
+      visible: "has(record.viewer) && has(record.viewer.can_act) && record.viewer.can_act == true",
       locations: ["record_section"],
       successMessage: "Sent back for revision.",
       refreshAfter: true
@@ -1622,7 +1690,7 @@ var SysApprovalRequest = ObjectSchema.create({
       params: [
         { name: "comment", label: "What do you need?", type: "textarea", required: true }
       ],
-      visible: "record.viewer.can_act",
+      visible: "has(record.viewer) && has(record.viewer.can_act) && record.viewer.can_act == true",
       locations: ["record_section"],
       successMessage: "Information requested.",
       refreshAfter: true
@@ -1643,7 +1711,7 @@ var SysApprovalRequest = ObjectSchema.create({
       params: [
         { name: "comment", label: "Note", type: "textarea", required: false }
       ],
-      visible: 'record.status == "pending" && record.viewer.is_submitter',
+      visible: 'has(record.status) && record.status == "pending" && has(record.viewer) && has(record.viewer.is_submitter) && record.viewer.is_submitter == true',
       locations: ["record_section"],
       successMessage: "Reminder sent.",
       refreshAfter: true
@@ -1651,6 +1719,9 @@ var SysApprovalRequest = ObjectSchema.create({
     {
       name: "approval_recall",
       label: "Recall",
+      // Confirm question as the param dialog's description, not `confirmText`
+      // — same one-decision-one-dialog rule as `approval_reject` above (#7278).
+      description: "Recall this request? Approvers can no longer act on it and the record is unlocked.",
       icon: "undo-2",
       type: "api",
       method: "POST",
@@ -1660,8 +1731,7 @@ var SysApprovalRequest = ObjectSchema.create({
       ],
       // 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.",
+      visible: 'has(record.status) && (record.status == "pending" || record.status == "returned") && has(record.viewer) && has(record.viewer.is_submitter) && record.viewer.is_submitter == true',
       locations: ["record_section"],
       successMessage: "Recalled.",
       refreshAfter: true
@@ -1676,7 +1746,7 @@ var SysApprovalRequest = ObjectSchema.create({
       params: [
         { name: "comment", label: "What changed?", type: "textarea", required: false }
       ],
-      visible: 'record.status == "returned" && record.viewer.is_submitter',
+      visible: 'has(record.status) && record.status == "returned" && has(record.viewer) && has(record.viewer.is_submitter) && record.viewer.is_submitter == true',
       locations: ["record_section"],
       successMessage: "Resubmitted.",
       refreshAfter: true
@@ -1692,7 +1762,7 @@ var SysApprovalRequest = ObjectSchema.create({
 
 // src/sys-approval-action.object.ts
 import { ObjectSchema as ObjectSchema2, Field as Field2 } from "@objectstack/spec/data";
-import { APPROVAL_ACTION_KINDS } from "@objectstack/spec/contracts";
+import { APPROVAL_ACTION_KINDS, APPROVAL_ACTION_KIND_LABELS } from "@objectstack/spec/contracts";
 var SysApprovalAction = ObjectSchema2.create({
   name: "sys_approval_action",
   label: "Approval Action",
@@ -1771,11 +1841,14 @@ var SysApprovalAction = ObjectSchema2.create({
       group: "Target"
     }),
     action: Field2.select(
-      // Spread from the contract, not re-typed (#3786). `APPROVAL_ACTION_KINDS`
+      // Derived from the contract, not re-typed (#3786). `APPROVAL_ACTION_KINDS`
       // is where the list and the per-kind notes live (which kinds move the flow
       // and which are thread-only); `ApprovalActionKind` is derived from it, so
-      // this column and the contract cannot disagree.
-      [...APPROVAL_ACTION_KINDS],
+      // this column and the contract cannot disagree. The authored English label
+      // per kind lives beside it in `APPROVAL_ACTION_KIND_LABELS` (#8580 — the
+      // #7232 humanization pass missed this field) — mapped here, never
+      // re-typed, so the `en` bundle regenerates from the contract's own text.
+      APPROVAL_ACTION_KINDS.map((value) => ({ value, label: APPROVAL_ACTION_KIND_LABELS[value] })),
       {
         label: "Action",
         required: true,
@@ -2319,6 +2392,9 @@ var _ApprovalService = class _ApprovalService {
     this.messaging = opts.messaging;
     this.publicBaseUrl = (opts.publicBaseUrl ?? "").replace(/\/$/, "");
     this.tenancyPosture = opts.tenancyPosture;
+    this.recordReaderVisibleObjects = new Set(
+      (Array.isArray(opts.recordReaderVisibleObjects) ? opts.recordReaderVisibleObjects : []).map((n) => String(n ?? "").trim()).filter(Boolean)
+    );
   }
   /** Attach (or replace) the ADR-0105 D9 posture provider. */
   attachTenancyPosture(provider) {
@@ -2820,9 +2896,48 @@ var _ApprovalService = class _ApprovalService {
    * Position holders (ADR-0090 D3): `sys_user_position` is the platform-owned
    * assignment table, keyed by the position's machine name (ADR-0057 D4),
    * unioned with the better-auth membership string (`sys_member.role`) as a
-   * transition source — the same semantics as `PositionGraphService` in
-   * `plugin-sharing`, so an approval routes to exactly the users the sharing
-   * engine would expand for the same position.
+   * transition source.
+   *
+   * ⚠️ This is a ROUTING read (approver slates and escalation targets), and it
+   * is deliberately NOT the same read as `PositionGraphService` in
+   * `plugin-sharing`, whatever the shared method name suggests. Both answer
+   * "who holds position P"; this one reads the directory RAW — neither the
+   * ADR-0091 D2 validity window nor the `sys_position.active` catalogue flag is
+   * applied. Maintainer ruling, 2026-08-15 (#8710, inheriting #8613), verbatim:
+   *
+   * > Access-conferring paths filter deactivated positions; addressing paths
+   * > do not.
+   *
+   * Routing is an addressing path, so dropping a holder here is fail-OPEN, not
+   * fail-closed: an expansion that comes back empty does not narrow the slate,
+   * it falls through to the literal `position:` slot no user can ever act on —
+   * the permanently stuck request of #3807 / #3424. A step routing to nobody is
+   * worse than one routing to a lapsed holder, so the lapsed holder stays.
+   *
+   * Where the two implementations actually stand, per source. Both limbs are
+   * listed because a statement about one of them is not a statement about this
+   * method:
+   *
+   *  1. `sys_user_position` — sharing projects `valid_from` / `valid_until` and
+   *     drops rows on `isGrantActive` inside its own helper; we project
+   *     `user_id` alone, so an assignment that expired last month still routes.
+   *     This is the one real divergence, and it is the intended one.
+   *  2. `sys_member.role` — raw on BOTH sides (`TeamGraphService.expandRoleUsers`
+   *     projects `user_id` too). The table carries no window columns at all and
+   *     `isGrantActive` reads an absent bound as unbounded, so there is nothing
+   *     a filter could do here; membership tier names have no `sys_position`
+   *     row either (#8710's "a name with no row is untouched" fallback), so no
+   *     catalogue flag either. This limb cannot be brought into parity by
+   *     adding a filter — see {@link expandMembershipTierUsers}.
+   *  3. `sys_position.active` — the sharing engine's gate for it lives at the
+   *     RULE EVALUATOR's call site (`positionConfersAccess` in
+   *     `sharing-rule-service.ts`), not inside `PositionGraphService`; the same
+   *     ruling gives it no counterpart on this path.
+   *
+   * The omission is per-READ, not a missing dependency: `isGrantActive` is
+   * imported in this file and IS applied to `sys_approval_delegation` in
+   * {@link lookupActiveDelegation}. ⛔ So do not "fix" this by adding the window
+   * filter here — that is the option #8710 rejected, on the reasoning above.
    */
   async expandPositionUsers(positionName, organizationId) {
     if (!positionName) return [];
@@ -2850,6 +2965,13 @@ var _ApprovalService = class _ApprovalService {
    * 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.
+   *
+   * Read RAW, like every routing read here, and with nothing available to
+   * filter even if it were not: `sys_member` carries no ADR-0091 D2 window
+   * columns, and a tier name has no `sys_position` row to read `active` off.
+   * {@link expandPositionUsers} carries the ruling both reads inherit
+   * (#8613 / #8710) — this method is also the second limb of that union, so a
+   * change here changes position routing too.
    */
   async expandMembershipTierUsers(tier, organizationId) {
     if (!tier) return [];
@@ -4386,10 +4508,14 @@ var _ApprovalService = class _ApprovalService {
    * class of failure stayed silent.
    *
    * It also could not have answered the question even if it looked: its
-   * liveness oracle is `getRun`, which reads the execution LOG, and after a
-   * restart that returns `null` for a perfectly ALIVE suspended run. It treats
-   * `null` as alive (conservative, correct) — but that means it has no way to
-   * say "this run is really gone".
+   * liveness oracle is `getRun`, which treats both `null` and `paused` as alive
+   * (conservative, correct) — so it has no way to say "this run is really
+   * gone". (Until #8050 that oracle was weaker still: after a restart it
+   * returned `null` for a perfectly ALIVE suspended run, so "alive" and
+   * "unknown" were the same answer. It now reports such a run as `paused`,
+   * which does not change any branch here — both already meant "leave alone" —
+   * but it is why the sweep below needs `hasSuspendedRun` as a second oracle
+   * rather than a sharper reading of the first.)
    *
    * So this uses BOTH oracles, and a row must fail both to be reported:
    *
@@ -5075,7 +5201,7 @@ var _ApprovalService = class _ApprovalService {
    * is a plain membership test over the resolved ids). So this cannot hide a
    * request from someone who could actually act on it.
    */
-  async visibleRequestIds(context, tenantOrg) {
+  async visibleRequestIds(context, tenantOrg, target) {
     if (this.isOverrideActor(context, tenantOrg)) return null;
     const uid2 = context?.userId != null ? String(context.userId) : "";
     if (!uid2) return /* @__PURE__ */ new Set();
@@ -5117,8 +5243,90 @@ var _ApprovalService = class _ApprovalService {
         error: err instanceof Error ? err.message : String(err)
       });
     }
+    await this.addRecordReaderVisibleIds(ids, context, tenantOrg, target);
     return ids;
   }
+  /**
+   * [#8652] Read-only approval visibility derived from READ ACCESS TO THE
+   * TARGET BUSINESS RECORD.
+   *
+   * Maintainer ruling 2026-08-15: a user who can read the target record may
+   * view that record's approval requests and full action history, read-only,
+   * behind a switch that is default OFF, anchored on the EXISTING record-read
+   * permission. The rejected alternative was a host-injected visibility hook —
+   * a security predicate the platform could neither constrain nor audit.
+   *
+   * ## How the anchor is evaluated
+   *
+   * By asking the engine to read the record AS THE CALLER. That is the whole
+   * check: `engine.find(object, { where: { id }, context })` runs the ordinary
+   * ObjectQL middleware — object CRUD read, then RLS — so a denial throws and a
+   * row the caller may not see comes back empty. Both mean "no". No new
+   * permission, role or grant type is invented, and no second copy of the
+   * access rule exists to drift from the first.
+   *
+   * ⚠️ The caller's context is load-bearing. Probing with {@link SYSTEM_CTX} —
+   * the context every other read in this service uses — would read exactly like
+   * a permission check while admitting every authenticated user in the tenant.
+   *
+   * ## Why it needs a NAMED TARGET, and what that deliberately excludes
+   *
+   * The rule is anchored on one record, so it can only be evaluated where a
+   * record is named: a list filtered by `object` + `recordId` (what a record
+   * page's approval tab sends), or a request loaded by id (whose own row names
+   * its target). An UNTARGETED list — the inbox — is left exactly as it was:
+   * answering it under this tier would mean probing every request in the tenant
+   * for read access, which is unbounded, and would turn a work queue into a
+   * browse surface. The confirmed consumer is the record page; the inbox is not
+   * part of the ruling and is not widened here.
+   *
+   * ## What becomes visible (stated plainly, because the switch is an opt-in)
+   *
+   * The request row — including its `payload` snapshot of the record at
+   * submission time — plus the full action history: actor, decision, timestamp,
+   * the action's COMMENT text, and (through the same gate, via
+   * {@link ApprovalService.authorizeFileRead}) any decision attachments. The
+   * comment text is the ruling's "full action history" read literally; it is
+   * flagged on the card as the one granularity edge worth a second look.
+   *
+   * Read-only is not enforced here and must not be: the decision paths
+   * (`decideNode` / `reassign` / `recall` / `comment`) authorize on the pending
+   * approver slate, the submitter, or {@link ApprovalService.isOverrideActor},
+   * none of which this tier touches. Seeing a request confers nothing.
+   */
+  async addRecordReaderVisibleIds(ids, context, tenantOrg, target) {
+    if (this.recordReaderVisibleObjects.size === 0) return;
+    const object = String(target?.object ?? "").trim();
+    const recordId = String(target?.recordId ?? "").trim();
+    if (!object || !recordId) return;
+    if (!this.recordReaderVisibleObjects.has(object)) return;
+    const uid2 = context?.userId != null ? String(context.userId) : "";
+    if (!uid2) return;
+    try {
+      const readable = await this.engine.find(object, {
+        where: { id: recordId },
+        fields: ["id"],
+        limit: 1,
+        context
+      });
+      if (!Array.isArray(readable) || readable.length === 0) return;
+      const orgWhere = tenantOrg ? { organization_id: tenantOrg } : {};
+      const rows = await this.engine.find("sys_approval_request", {
+        where: { object_name: object, record_id: recordId, ...orgWhere },
+        fields: ["id"],
+        limit: _ApprovalService.APPROVER_INDEX_CAP,
+        context: SYSTEM_CTX2
+      });
+      for (const r of Array.isArray(rows) ? rows : []) {
+        if (r?.id != null) ids.add(String(r.id));
+      }
+    } catch (err) {
+      this.logger?.debug?.("[approvals] record-reader visibility probe declined", {
+        object,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
   /** Intersect an existing `where.id` constraint with the participant set. */
   applyVisibility(where, visible) {
     if (!visible) return true;
@@ -5142,7 +5350,10 @@ var _ApprovalService = class _ApprovalService {
       if (ids.length === 0) return [];
       where.id = ids.length === 1 ? ids[0] : { $in: ids };
     }
-    if (!this.applyVisibility(where, await this.visibleRequestIds(context, tenantOrg))) return [];
+    if (!this.applyVisibility(where, await this.visibleRequestIds(context, tenantOrg, {
+      object: filter?.object,
+      recordId: filter?.recordId
+    }))) return [];
     const findOpts = {
       where,
       orderBy: [{ field: "created_at", order: "desc" }],
@@ -5168,7 +5379,10 @@ var _ApprovalService = class _ApprovalService {
       if (ids.length === 0) return 0;
       where.id = ids.length === 1 ? ids[0] : { $in: ids };
     }
-    if (!this.applyVisibility(where, await this.visibleRequestIds(context, tenantOrg))) return 0;
+    if (!this.applyVisibility(where, await this.visibleRequestIds(context, tenantOrg, {
+      object: filter?.object,
+      recordId: filter?.recordId
+    }))) return 0;
     const countFn = this.engine.count;
     if (typeof countFn === "function") {
       try {
@@ -5214,7 +5428,10 @@ var _ApprovalService = class _ApprovalService {
     });
     if (!Array.isArray(rows) || !rows[0]) return null;
     if (enforceVisibility) {
-      const visible = await this.visibleRequestIds(context, tenantOrg ?? null);
+      const visible = await this.visibleRequestIds(context, tenantOrg ?? null, {
+        object: rows[0].object_name,
+        recordId: rows[0].record_id
+      });
       if (visible && !visible.has(String(rows[0].id))) return null;
     }
     const row = rowFromRequest(rows[0]);
@@ -5974,6 +6191,9 @@ var ApprovalsServicePlugin = class {
       engine,
       logger: ctx.logger,
       publicBaseUrl: this.options.publicBaseUrl,
+      // [#8652] Read-only record-reader visibility. Default OFF — an absent
+      // declaration reaches the service as an empty set and changes nothing.
+      recordReaderVisibleObjects: this.options.recordReaderVisibleObjects,
       // [ADR-0105 D9] Cross-organization approver targeting is a `group`-posture
       // capability. Read LAZILY (not captured at start) because the tenancy
       // service resolves its posture during its own start, which may not have