feat(plugin-approvals): excludeSubmitter keeps the submitter from approving their own request

.changeset/25573-exclude-submitter-runtime.md

@@ -0,0 +1,18 @@
+---
+'@objectstack/plugin-approvals': patch
+'@objectstack/spec': patch
+---
+
+feat(plugin-approvals): an approval step's `excludeSubmitter: true` keeps the submitter from approving their own request
+
+Clause-②: no
+Metadata-protocol: none
+
+- **Before.** `excludeSubmitter` was declared on the approval node config and its describe opened with `[PLANNED — not yet enforced]`: the approval engine parsed it and read nothing, so a category manager who submitted their own admission was step 1's `field` approver and approved it.
+- **At the open.** The submitter (the run's trigger user, `sys_approval_request.submitter_id`) is taken off the resolved slate, whatever approver type produced them, by their user id or their account's email, an out-of-office hop that lands on them included. Everyone else stays on it, per_group tags included. A slate this empties takes the node's `onEmptyApprovers` route: the organization's administrators by default, the declared `fallbackApprovers` under `'fallback'`, or the `NO_APPROVERS` refusal under `'fail'`, which now names the exclusion. The fallback slate and the administrators' slate are screened the same way, so an organization whose only administrator is the submitter opens the request on the slate that names no one.
+- **On the record.** A request whose slate lost its submitter carries a system note on its timeline naming the route it took (the remaining approvers, the fallback approvers, the administrators, or no one), rendered in the reader's language by the approvals door. The administrators' routing note says the only approver was the submitter instead of "no approver resolved to a person".
+- **After the open.** An approval decided by the submitter is refused with `FORBIDDEN`, the privileged override included; their rejection stands. A reassign to the submitter, or to a position only they hold, is refused with `VALIDATION_FAILED`. An SLA escalation that reassigns leaves them off the new slate, and one whose only target is the submitter is not applied: the pending approvers keep the request and are told the SLA lapsed.
+- **Spec.** The describe drops the `[PLANNED — not yet enforced]` marker and its last sentence; nothing else in the schema changes.
+- **Unchanged.** With the option off or omitted (the default), every slate, timeline, decision, reassign and escalation behaves as before.
+
+What to do: nothing to migrate. A step that set `excludeSubmitter: true` now enforces it; an `expression` approver or validation rule added by hand to keep the submitter off can be removed.

content/docs/permissions/tenant-audit-census.mdx

@@ -132,7 +132,7 @@ are reported as `undecidable` rather than assumed either way.
 
 The same holds twice over for the context. An options argument spelled as a
 literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
-forwarding shim cannot, and **51 of the 238 sites are spelled that way**. A
+forwarding shim cannot, and **51 of the 239 sites are spelled that way**. A
 context resolved from an inline literal or a local `const` can be tested for
 `isSystem`; one arriving from a helper call cannot.
 
@@ -197,10 +197,10 @@ reproduce them. Where it disagrees, it disagrees on the page:
 
 | carried figure | where it survives | this census |
 | :--- | :--- | ---: |
-| 175 write call sites | quoted in the merged changeset | **238** |
+| 175 write call sites | quoted in the merged changeset | **239** |
 | 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **29** more whose options argument is unreadable |
-| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **162 of 238** decidable, **76** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 135 decidably elevated, 0 decidably not, 95 undecidable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **163 of 239** decidable, **76** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 136 decidably elevated, 0 decidably not, 95 undecidable |
 | 141 and 132, two independent re-derivations | the card that filed this work | — |
 
 **The differences are not reconciled, and deliberately so.** The old census's
@@ -217,11 +217,11 @@ would report a smaller number and would not say so.
 
 The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
 figure has no surviving corroboration anywhere in the tree.** This census reads
-135 of 238 (57%) as decidably elevated, with 95 more whose elevation is a
+136 of 239 (57%) as decidably elevated, with 95 more whose elevation is a
 run-time fact — so the claim is neither confirmed nor refuted, and the honest
 answer is that a static reading cannot settle it.
 
-⇒ **Cite `2 / 238`, and say what it is**: the sites whose options argument was
+⇒ **Cite `2 / 239`, and say what it is**: the sites whose options argument was
 READ and holds no tenant context, against a decidably tenancy-enabled object.
 That is the control's provable yield surface. ⛔ Do not cite it as "the sites
 without tenant context" — **29 further sites** have an options argument this
@@ -233,28 +233,28 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **238** |
-| …whose object name is statically decidable | 162 |
+| write call sites on the application surface | **239** |
+| …whose object name is statically decidable | 163 |
 | …whose object name is chosen at run time | 76 |
-| …against an object with tenancy ENABLED | 161 |
+| …against an object with tenancy ENABLED | 162 |
 | …against an object that declares tenancy off | 1 |
-| threading a tenant context | 179 |
+| threading a tenant context | 180 |
 | PROVABLY carrying none (options read, no context key) | **8** |
 | …of those, against a decidably tenancy-enabled object | **2** |
 | options argument UNREADABLE — may or may not carry one | 51 |
 | …of those, against a decidably tenancy-enabled object | 29 |
-| threading a decidably ELEVATED (`isSystem`) context | 135 |
+| threading a decidably ELEVATED (`isSystem`) context | 136 |
 | threading a context that is decidably NOT elevated | 0 |
 | threading a context whose elevation is a run-time fact | 95 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
-| receiver carried a readable engine type | 183 |
+| receiver carried a readable engine type | 184 |
 | receiver erased, placed by the object NAME | 45 |
 | receiver erased, placed by an `object: string` PARAMETER | 5 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
 
-| object name spelled inline | 111 |
+| object name spelled inline | 112 |
 | object name spelled through a `const` | 51 |
 | object name is an `object: string` parameter | 7 |
 | object name is some other run-time expression | 69 |
@@ -307,13 +307,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-23 at `487d57fed`.
+Measured on 2026-10-24 at `28b6d27e7`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 723 |
+| tracked non-test sources scanned | 767 |
 | engine-shaped types recognised | 87 |
 | declared objects in the registry | 117 |
-| same-named calls subtracted as non-engine | 174 |
+| same-named calls subtracted as non-engine | 176 |
 
 {/* END GENERATED: tenant-audit-census */}

content/docs/references/automation/approval.mdx

@@ -69,7 +69,7 @@ const result = ApprovalDecision.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **approvers** | `{ type: Enum<'manager' \| 'position' \| 'department' \| 'team' \| 'field' \| 'expression' \| …>; value?: string; resolveAs?: Enum<'user' \| 'department' \| 'position' \| 'team'>; group?: string; … }[]` | ✅ | Allowed approvers for this node |
-| **excludeSubmitter** | `boolean` | optional | [PLANNED — not yet enforced] Segregation of duties for this step: when true, the request's submitter (the user whose action started the flow run, recorded on the approval request as `submitter_id`) is removed from the slate `approvers` resolves to, whatever approver type produced them. If that leaves nobody, the request takes the node's `onEmptyApprovers` route (`admin_rescue` by default, or `fallbackApprovers` under `'fallback'`) and never passes silently, and the approval record shows that the exclusion changed the route. `onEmptyApprovers: 'auto_approve'` is refused beside `excludeSubmitter: true`, because it would approve exactly the request this option exists to stop; choose `'admin_rescue'`, `'fail'` or `'fallback'`. Omitted or false (the default), the slate stays as resolved. The approval engine does not read this key yet, so today the submitter is NOT removed: keep any guard you rely on (an `expression` approver or a validation rule) until it does. |
+| **excludeSubmitter** | `boolean` | optional | Segregation of duties for this step: when true, the request's submitter (the user whose action started the flow run, recorded on the approval request as `submitter_id`) is removed from the slate `approvers` resolves to, whatever approver type produced them. If that leaves nobody, the request takes the node's `onEmptyApprovers` route (`admin_rescue` by default, or `fallbackApprovers` under `'fallback'`) and never passes silently, and the approval record shows that the exclusion changed the route. `onEmptyApprovers: 'auto_approve'` is refused beside `excludeSubmitter: true`, because it would approve exactly the request this option exists to stop; choose `'admin_rescue'`, `'fail'` or `'fallback'`. Omitted or false (the default), the slate stays as resolved. |
 | **behavior** | `Enum<'first_response' \| 'unanimous' \| 'quorum' \| 'per_group'>` | optional (default: `"first_response"`) | How to combine multiple approvers |
 | **minApprovals** | `integer` | optional | Approvals required — total (quorum) or per group (per_group). Omitted ⇒ all resolvable approvers for quorum, 1 per group for per_group |
 | **lockRecord** | `boolean` | optional (default: `true`) | Lock the record from editing while pending |

docs/audits/2026-08-tenant-audit-write-call-sites.counts.md

@@ -33,17 +33,17 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
 
 | Measure | Value |
 |---|---:|
-| Write call sites | 238 |
-| Object name statically decidable | 162 |
+| Write call sites | 239 |
+| Object name statically decidable | 163 |
 | Object name chosen at run time | 76 |
-| Against a tenancy-enabled object | 161 |
+| Against a tenancy-enabled object | 162 |
 | Against an object declaring tenancy off | 1 |
-| Threading a tenant context | 179 |
+| Threading a tenant context | 180 |
 | Provably carrying none | 8 |
 | …and decidably tenancy-enabled | 2 |
 | Options argument unreadable | 51 |
 | …and decidably tenancy-enabled | 29 |
-| Threading a decidably elevated context | 135 |
+| Threading a decidably elevated context | 136 |
 | Threading a decidably non-elevated context | 0 |
 | Threading a context of undecidable elevation | 95 |
 
@@ -90,14 +90,14 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-23 at `487d57fed`.
+Measured on 2026-10-24 at `28b6d27e7`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 723 |
+| tracked non-test sources scanned | 767 |
 | engine-shaped types recognised | 87 |
 | declared objects in the registry | 117 |
-| same-named calls subtracted as non-engine | 174 |
+| same-named calls subtracted as non-engine | 176 |
 
 ## Every site
 
@@ -106,7 +106,7 @@ Measured on 2026-10-23 at `487d57fed`.
 | `packages/plugins/organizations/src/claim-org-seed-ownership.ts` | `update` | `schema.name` | undecidable | elevated | 1 |
 | `packages/plugins/plugin-approvals/src/action-slot-backfill.ts` | `update` | `sys_approval_action` | enabled | elevated | 2 |
 | `packages/plugins/plugin-approvals/src/approval-service.ts` | `update` | `object` | undecidable | context, elevation undecidable | 1 |
-| `packages/plugins/plugin-approvals/src/approval-service.ts` | `insert` | `sys_approval_action` | enabled | elevated | 15 |
+| `packages/plugins/plugin-approvals/src/approval-service.ts` | `insert` | `sys_approval_action` | enabled | elevated | 16 |
 | `packages/plugins/plugin-approvals/src/approval-service.ts` | `delete` | `sys_approval_approver` | enabled | elevated | 2 |
 | `packages/plugins/plugin-approvals/src/approval-service.ts` | `insert` | `sys_approval_approver` | enabled | elevated | 2 |
 | `packages/plugins/plugin-approvals/src/approval-service.ts` | `insert` | `sys_approval_request` | enabled | elevated | 1 |

packages/plugins/plugin-approvals/src/admin-rescue-note.ts

@@ -59,6 +59,12 @@ export interface AdminRescueNote {
   readonly abandoned: readonly string[];
   /** Set when the node declared `onEmptyApprovers: 'fallback'` and it did not help. */
   readonly fallback?: AdminRescueFallback;
+  /**
+   * [#25573] Set when the slate named a person, the request's submitter, and
+   * the node's `excludeSubmitter: true` removed them: the slate named no one
+   * else, which "no approver resolved to a person" would misstate.
+   */
+  readonly submitter_excluded?: true;
 }
 
 /** One catalog sentence and its params. */
@@ -73,8 +79,15 @@ export type ApprovalSentenceRender = (
   params: Readonly<Record<string, string>>,
 ) => string | undefined;
 
-/** The reason's clauses: one per abandoned `type:value` slot, then the fallback's. */
-function reasonClauses(abandoned: readonly string[], fallback: AdminRescueFallback | undefined): Clause[] {
+/**
+ * The reason's clauses: one per abandoned `type:value` slot, then the
+ * submitter's exclusion, then the fallback's.
+ */
+function reasonClauses(
+  abandoned: readonly string[],
+  fallback: AdminRescueFallback | undefined,
+  submitterExcluded?: boolean,
+): Clause[] {
   const clauses: Clause[] = abandoned
     .filter((slot) => !!slot && slot.includes(':'))
     .map((slot): Clause => {
@@ -85,6 +98,7 @@ function reasonClauses(abandoned: readonly string[], fallback: AdminRescueFallba
         ? { id: 'approvalAdminRescuePositionUnheld', params: { value } }
         : { id: 'approvalAdminRescueSlotUnresolved', params: { type, value } };
     });
+  if (submitterExcluded) clauses.push({ id: 'approvalAdminRescueSubmitterExcluded', params: {} });
   if (!clauses.length) clauses.push({ id: 'approvalAdminRescueNoApprover', params: {} });
   if (fallback === 'resolved_to_no_one') clauses.push({ id: 'approvalAdminRescueFallbackUnresolved', params: {} });
   if (fallback === 'not_declared') clauses.push({ id: 'approvalAdminRescueFallbackUndeclared', params: {} });
@@ -97,8 +111,13 @@ const english = (clause: Clause): string => interpolate(enMessages[clause.id], c
  * Why the slate named no one, in English: the audit snapshot's
  * `admin_rescue:reason` and the log lines.
  */
-export function adminRescueReason(abandoned: readonly string[], fallback: AdminRescueFallback | undefined): string {
-  return reasonClauses(abandoned, fallback).map(english).join(enMessages.approvalAdminRescueReasonSeparator);
+export function adminRescueReason(
+  abandoned: readonly string[],
+  fallback: AdminRescueFallback | undefined,
+  submitterExcluded?: boolean,
+): string {
+  return reasonClauses(abandoned, fallback, submitterExcluded)
+    .map(english).join(enMessages.approvalAdminRescueReasonSeparator);
 }
 
 /**
@@ -115,7 +134,7 @@ export function adminRescueNoteText(
   note: Omit<AdminRescueNote, 'action_id'>,
   render?: ApprovalSentenceRender,
 ): string | undefined {
-  const clauses = reasonClauses(note.abandoned, note.fallback);
+  const clauses = reasonClauses(note.abandoned, note.fallback, note.submitter_excluded);
   if (!render) {
     const reason = clauses.map(english).join(enMessages.approvalAdminRescueReasonSeparator);
     return interpolate(enMessages.approvalAdminRescueNote, { reason });
@@ -136,9 +155,12 @@ export function adminRescueNoteOf(snapshot: unknown): AdminRescueNote | undefine
   if (!snapshot || typeof snapshot !== 'object') return undefined;
   const note = (snapshot as Record<string, unknown>)[ADMIN_RESCUE_NOTE_SNAPSHOT_KEY];
   if (!note || typeof note !== 'object') return undefined;
-  const { action_id, abandoned, fallback } = note as Record<string, unknown>;
+  const { action_id, abandoned, fallback, submitter_excluded } = note as Record<string, unknown>;
   if (typeof action_id !== 'string' || !action_id) return undefined;
   if (!Array.isArray(abandoned) || !abandoned.every((slot) => typeof slot === 'string')) return undefined;
   if (fallback !== undefined && fallback !== 'not_declared' && fallback !== 'resolved_to_no_one') return undefined;
-  return { action_id, abandoned, ...(fallback ? { fallback } : {}) };
+  if (submitter_excluded !== undefined && submitter_excluded !== true) return undefined;
+  return {
+    action_id, abandoned, ...(fallback ? { fallback } : {}), ...(submitter_excluded ? { submitter_excluded } : {}),
+  };
 }