fix(approvals): auto-cancel a record's pending approvals when the record is deleted (#14061)

* fix(approvals): auto-cancel a record's pending approvals when the record is deleted

Deleting a record left its pending `sys_approval_request` rows in the
approvers' inbox — counted, openable, and pointing at a record id that no
longer resolves. Any object whose approval node declares `lockRecord` walks
the same path, because the lock makes "delete and recreate" the author's only
route to fixing a submitted record.

Per the maintainer ruling: pending requests now transition to a new terminal
`cancelled` status carrying a machine-readable `cancel_reason`, the rows are
KEPT as audit evidence, and they leave the pending count and the inbox's
default view (status write plus a `sys_approval_approver` index clear — the
index is what the approver filter actually resolves through).

The linkage is one global `afterDelete` hook beside the existing global
record-lock hook, so it is platform-level and every "approval + lockRecord"
combination benefits at once. It runs no flow node and mirrors no status back
onto the deleted record; the suspended run is reported and left to the
automation service. Terminal rows are untouched, and the delete itself is
never refused.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015adLit3ZYASJiXwxKG78Wi

* chore(audits): re-certify the tenant write-call-site census after the cancel path

`cancelForDeletedRecord` adds two write call sites (the append-only
`sys_approval_action` insert and the `sys_approval_request` status update), so
the generated census moves 215 -> 217 and its hand-written prose figures move
with it. Regenerated with `node scripts/tenant-audit-census.mjs --write`; the
prose numbers the gate holds to the census (215/143/97) are updated in place.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015adLit3ZYASJiXwxKG78Wi

* test(approvals): declare the new integration test's read options instead of erasing them

`check:query-options-erasure` counted 5 new sites (240 -> 245) from
record-delete-cancel.integration.test.ts. None of them is deliberately
off-contract — they are plain `where` + `context` reads — so the remedy the
gate names is to type them, not to spell them `as unknown as
EngineQueryOptions` (which would claim a contract bypass that is not
happening) and not to raise the ratchet.

Each of the five `engine.find` calls now carries `satisfies
EngineQueryOptions`. Verified it is a real check rather than decoration: the
file compiles clean under a tsconfig that includes it, and planting the #4674
shape the rule exists for (`direction: 'desc'`, an undeclared key) turns it
red with TS2353. The ratchet is back at its 240 ceiling, unraised.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015adLit3ZYASJiXwxKG78Wi

* docs(permissions): re-anchor the system-context census after the approvals insertions

`check-system-context-census` reported 20 problems (10 site-without-a-row + 10
anchor-is-not-a-read-site) across plugin-approvals. Triaged all 20 against
`origin/main` before touching anything: every one of the 10 sites exists
verbatim in main's copy of the same file, and the 10 stale anchors are exactly
main's line numbers for those same sites. So this is pure line rot from the
`cancelForDeletedRecord` / `RECORD_DELETE_CANCEL_LIMIT` / `bindRecordDeleteCancelHook`
insertions pushing existing reads down — zero new elevation reads on this
branch, which the gate confirms independently by holding the site count at 109.

In particular `lifecycle-hooks.ts:570` is NOT new code: it is the pre-existing
`bindDelegationWriteGuard` system bypass (#1322 / #4839), main line 440.

Repaired with the sanctioned `node scripts/check-system-context-census.mjs --fix`
— anchors only. No `isSystem` check was deleted, weakened or re-worded, and no
row's prose changed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015adLit3ZYASJiXwxKG78Wi

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/approval-auto-cancel-on-record-delete.md

@@ -0,0 +1,85 @@
+---
+'@objectstack/spec': minor
+'@objectstack/plugin-approvals': minor
+---
+
+fix(approvals): a deleted record's pending approvals auto-cancel instead of stranding in the inbox (#13568)
+
+Deleting a record left every `pending` approval it had opened sitting in the
+approvers' inbox — counted in the pending total, openable, and pointing at a
+`record_id` that resolves to nothing. Nothing about it was module-specific:
+an approval node that declares `lockRecord` blocks the EDIT, so "delete and
+recreate" is the only route left to an author who needs to fix a submitted
+record, and every such delete added another orphan. Maintainer ruling
+2026-08-31 (`总监席第 5 场决裁批 #5`, verbatim 「同意」): pending requests
+auto-cancel on record delete — status `cancelled` plus a machine-readable
+reason, rows KEPT for audit, out of the pending count and the inbox's default
+view.
+
+**Graded `minor`, and deliberately not `patch`.** The repair itself is a
+defect fix, but it lands by WIDENING two published vocabularies and adding a
+declared column, and this repo's convention grades a shipped service's
+accept-set/behaviour move as `minor`. **No `BREAKING` banner**: nothing is
+narrowed and no metadata that used to be accepted is now refused — the one
+consequence a consumer can feel is that `ApprovalStatus` and
+`ApprovalActionKind` each gained a member, so an exhaustive `switch` with no
+default, or a `satisfies Record<ApprovalStatus, …>` map outside this repo,
+now has a case to add. That is the same shape `returned` had when ADR-0044
+landed it.
+
+**Spec (`@objectstack/spec/contracts/approval-service`)**
+
+- `APPROVAL_STATUSES` gains `cancelled` (+ its `APPROVAL_STATUS_LABELS`
+  entry). Its own terminal state rather than a re-use of `recalled`: a recall
+  is an ACT by the submitter, and filing a platform-initiated void as one
+  attributes a withdrawal to a person who never performed it.
+- New `APPROVAL_CANCEL_REASONS` / `ApprovalCancelReason` /
+  `APPROVAL_CANCEL_REASON_LABELS`, single entry `record_deleted`. A
+  VOCABULARY, not free text, because the reason has a non-human consumer (the
+  inbox and the tombstone presentation branch on it) — and a CLASS, per the
+  ruling's wording, so the next platform-initiated cancellation cause extends
+  this list instead of minting a second terminal status for itself.
+- `APPROVAL_ACTION_KINDS` gains `cancel` — the only kind with no human actor,
+  by construction.
+- `ApprovalRequestRow.cancel_reason` declared, optional-nullable.
+
+**Plugin (`@objectstack/plugin-approvals`)**
+
+- `sys_approval_request.cancel_reason`, a select derived from the contract
+  vocabulary and never re-typed (the #3786 rule the `status` column already
+  follows). On the row rather than on the audit entry, so a plain list view
+  can read WHY without joining the append-only action log.
+- `bindRecordDeleteCancelHook` — a GLOBAL `afterDelete` registration beside
+  the existing global record-lock hook, so one platform-level linkage covers
+  every "approval + `lockRecord`" object at once. It needs no row-set
+  plumbing: the engine binds the deleted row's pre-image on the by-id path
+  and fans `afterDelete` out per matched row on a predicate delete, so a bulk
+  delete is covered by the same handler. The approvals tables are excluded at
+  registration, so they do not pay the delete-side pre-image read.
+- `ApprovalService.cancelForDeletedRecord` writes the transition: one
+  append-only `sys_approval_action` row (`action: 'cancel'`, no actor),
+  `status: 'cancelled'` + `cancel_reason: 'record_deleted'` +
+  `completed_at`, and a `sys_approval_approver` index clear — that last one
+  is not optional garnish, it is what actually empties the inbox, because the
+  approver filter resolves through that index rather than through `status`.
+- The `Completed` list view now includes `cancelled`, so a kept audit row is
+  visible in the one curated terminal view rather than only under `All`.
+- ⛔ **No flow resume and no status mirror-back.** A cancellation is a status
+  write plus a reason, not a decision, so there is no branch to resume down.
+  The mirror-back is skipped by construction rather than by a swallowed
+  error: it is an `update_record` against the row that was just deleted — the
+  exact write this card's forensics caught failing elsewhere. The suspended
+  run the request gated is reported at `warn` with its id and otherwise left
+  alone; what becomes of it belongs to the automation service.
+- ⛔ **The delete is never refused.** The "forbid delete while an approval is
+  pending" direction was vetoed in the same ruling — `lockRecord` already
+  blocks the edit, and blocking the delete too locks an author onto a record
+  they cannot fix. Nothing in the hook throws; a failure degrades to the
+  pre-existing state (the stale row) and is logged.
+- Terminal rows are untouched. `approved` / `rejected` / `recalled` /
+  `returned` requests about the deleted record keep their recorded outcome —
+  history stays history, and rendering their now-dead record reference is a
+  separate console-side change.
+
+zh-CN / ja-JP / es-ES bundles carry authored translations for the new leaves
+(已作废 / 無効化済み / Anulada), not source fills.

content/docs/permissions/system-context.mdx

@@ -143,9 +143,9 @@ The largest single consumer — **20 of the 109 sites**.
 
 | # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
 |:--|:---|:---|:---|:---|
-| 40 | **Approval record lock released** — a locked record is writable | plugin-approvals | Get: engine self-writes (the status mirror) pass. Lose: the lock that stops edits while an approval is live. Note there is deliberately **no admin exemption** here — only `isSystem` | `lifecycle-hooks.ts:333` |
-| 41 | Delegation write guard bypassed | plugin-approvals | Get: service / seed / import may write delegation rows naming another delegator | `lifecycle-hooks.ts:440` |
-| 42 | Approval actor / submitter / pending-approver checks bypassed (8 sites) | plugin-approvals | Get: approve, reject, recall, reassign without being a pending approver or the submitter | `plugin-approvals/src/approval-service.ts:931`, `:1040`, `:2997`, `:3143`, `:3310`, `:3381`, `:3570`, `:3610` |
+| 40 | **Approval record lock released** — a locked record is writable | plugin-approvals | Get: engine self-writes (the status mirror) pass. Lose: the lock that stops edits while an approval is live. Note there is deliberately **no admin exemption** here — only `isSystem` | `lifecycle-hooks.ts:347` |
+| 41 | Delegation write guard bypassed | plugin-approvals | Get: service / seed / import may write delegation rows naming another delegator | `lifecycle-hooks.ts:570` |
+| 42 | Approval actor / submitter / pending-approver checks bypassed (8 sites) | plugin-approvals | Get: approve, reject, recall, reassign without being a pending approver or the submitter | `plugin-approvals/src/approval-service.ts:950`, `:1059`, `:3163`, `:3309`, `:3476`, `:3547`, `:3736`, `:3776` |
 | 43 | Saved-report ownership is **assignable**, and an update may reassign it | plugin-reports | Get: `ownerId` from input is honoured. A non-system caller always owns what it creates and can never reassign | `plugin-reports/src/report-service.ts:404`, `:425` |
 | 44 | Saved-report access / export / mutation gates bypassed | plugin-reports | Get: read, bulk-export and overwrite any report | `plugin-reports/src/report-service.ts:343`, `:372`, `:447`, `:684` |
 | 45 | Attachment access hooks return early (insert + update + delete, and the read AST) | service-storage | Lose: attachment visibility scoping | `attachment-access-hooks.ts:300`, `:349`, `:448`, `:524` |

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

@@ -98,7 +98,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 **67 of the 215 sites are spelled that way**. A
+forwarding shim cannot, and **67 of the 217 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.
 
@@ -147,10 +147,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 | **215** |
+| 175 write call sites | quoted in the merged changeset | **217** |
 | 24 carrying no tenant context | quoted in the merged changeset | **9** provable and tenancy-enabled; **32** more whose options argument is unreadable |
-| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **143 of 215** decidable, **72** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 97 decidably elevated, 0 decidably not, 101 undecidable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **145 of 217** decidable, **72** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 99 decidably elevated, 0 decidably not, 101 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
@@ -167,11 +167,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
-97 of 215 (45%) as decidably elevated, with 101 more whose elevation is a
+99 of 217 (45%) as decidably elevated, with 101 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 `9 / 215`, and say what it is**: the sites whose options argument was
+⇒ **Cite `9 / 217`, 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" — **32 further sites** have an options argument this
@@ -183,28 +183,28 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **215** |
-| …whose object name is statically decidable | 143 |
+| write call sites on the application surface | **217** |
+| …whose object name is statically decidable | 145 |
 | …whose object name is chosen at run time | 72 |
-| …against an object with tenancy ENABLED | 143 |
+| …against an object with tenancy ENABLED | 145 |
 | …against an object that declares tenancy off | 0 |
-| threading a tenant context | 131 |
+| threading a tenant context | 133 |
 | PROVABLY carrying none (options read, no context key) | **17** |
 | …of those, against a decidably tenancy-enabled object | **9** |
 | options argument UNREADABLE — may or may not carry one | 67 |
 | …of those, against a decidably tenancy-enabled object | 32 |
-| threading a decidably ELEVATED (`isSystem`) context | 97 |
+| threading a decidably ELEVATED (`isSystem`) context | 99 |
 | threading a context that is decidably NOT elevated | 0 |
 | threading a context whose elevation is a run-time fact | 101 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
-| receiver carried a readable engine type | 170 |
+| receiver carried a readable engine type | 172 |
 | receiver erased, placed by the object NAME | 19 |
 | receiver erased, placed by an `object: string` PARAMETER | 15 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 11 |
 
-| object name spelled inline | 106 |
+| object name spelled inline | 108 |
 | object name spelled through a `const` | 37 |
 | object name is an `object: string` parameter | 19 |
 | object name is some other run-time expression | 53 |
@@ -224,7 +224,7 @@ 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-08-31 at `fc8858a24`.
+Measured on 2026-09-01 at `d3ebf3b55`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |

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

@@ -29,17 +29,17 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
 
 | Measure | Value |
 |---|---:|
-| Write call sites | 215 |
-| Object name statically decidable | 143 |
+| Write call sites | 217 |
+| Object name statically decidable | 145 |
 | Object name chosen at run time | 72 |
-| Against a tenancy-enabled object | 143 |
+| Against a tenancy-enabled object | 145 |
 | Against an object declaring tenancy off | 0 |
-| Threading a tenant context | 131 |
+| Threading a tenant context | 133 |
 | Provably carrying none | 17 |
 | …and decidably tenancy-enabled | 9 |
 | Options argument unreadable | 67 |
 | …and decidably tenancy-enabled | 32 |
-| Threading a decidably elevated context | 97 |
+| Threading a decidably elevated context | 99 |
 | Threading a decidably non-elevated context | 0 |
 | Threading a context of undecidable elevation | 101 |
 
@@ -52,7 +52,7 @@ 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-08-31 at `fc8858a24`.
+Measured on 2026-09-01 at `d3ebf3b55`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
@@ -66,11 +66,11 @@ Measured on 2026-08-31 at `fc8858a24`.
 | file | verb | object | tenancy | tenant context | n |
 |---|---|---|---|---|---:|
 | `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 | 13 |
+| `packages/plugins/plugin-approvals/src/approval-service.ts` | `insert` | `sys_approval_action` | enabled | elevated | 14 |
 | `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/approval-service.ts` | `update` | `sys_approval_request` | enabled | elevated | 8 |
+| `packages/plugins/plugin-approvals/src/approval-service.ts` | `update` | `sys_approval_request` | enabled | elevated | 9 |
 | `packages/plugins/plugin-approvals/src/approval-service.ts` | `insert` | `sys_approval_token` | enabled | elevated | 1 |
 | `packages/plugins/plugin-approvals/src/approval-service.ts` | `update` | `sys_approval_token` | enabled | elevated | 1 |
 | `packages/plugins/plugin-approvals/src/backfill-platform-row-organizations.ts` | `update` | `objectPlan.object` | undecidable | context, elevation undecidable | 1 |