Skip to content

Commit a426d36

Browse files
fix(plugin-approvals): a revise-window recall on a batch item resumes the batch (#28228)
<!-- claude-projects-attribution: {"github_login":"os-elon-musk"} --> _Requested by **Elon** · [project thread](https://claude.ai/code/project/chan_01WedDzV26nniwxv7jC88B9D?thread=cmsg_01WedDzV26nniwxv7jC88B9D66UdUaGFca5mMDQCSjqRhX)_ domain:server#4 · os-elon-musk · session_016WV4d13k5TVyAhqhiKKgN3 Fixes #28183 Clause-②: no (a batch run that nothing could wake after the recall now continues, in the shape the cancelled-item ruling already set; no schema, accept set, error code or result field changes) Metadata-protocol: none ## 维护者速读 - 改了什么:批量签批(map 逐项审批)里,提交人在修改窗口(revise window)撤回某一项后,撤回现在会顺手恢复停在这一项上的批次 run;map 按 #28176 的形状把该项记成 `{ $status: 'cancelled', $itemRunId }`,`count` 不算它,然后开下一项或走完。 - 为什么改:实测 main(3a2f4c00):撤回只对该项 `cancelRun`,批次 run 一直停在 `map:<该项 run>`,第 2 项的审批永远不开,除非运维手动用批次 run id 恢复。按分诊与裁决 A(6523833308)的形状修,不新增标记或错误码。 - 风险与回滚:只在“修改窗口内撤回、`cancelRun` 确实取消了、且有 run 停在内置 `map` 节点上等这一项”时多做一次恢复;pending 撤回、无批次的撤回、全部决定完的批次不变(对照钉子)。回滚即 revert 本 PR。 - 先看:`packages/plugins/plugin-approvals/src/approval-service.ts` 的 `recall` 修改窗口分支与新私有方法 `resumeBatchOfRecalledItem`。 - 两分钟验证:`pnpm --filter @objectstack/plugin-approvals exec vitest run src/batch-item-recall-resumes-batch.test.ts`,预期 5 passed。 - 需要你做的:无,席位在 CI 绿后按落地授权落地。 ## What changes - **`packages/plugins/plugin-approvals/src/approval-service.ts`.** In `recall`'s revise-window branch, when `cancelRun` answers `true` (it really cancelled the item's run), the new private `resumeBatchOfRecalledItem(itemRunId, requestId)` looks for the run parked on `map:<itemRunId>` (`listSuspendedRunsDurable`, a member the surface already declares), checks through `getFlow` that the node it is parked at is the built-in `map`, and resumes that run with `serviceResume(batchRunId, {})`. The engine's existing parent-id resume (PR #28176) does the rest: it reads the item's `cancelled` history, records the marker in the item's slot, leaves it out of `count`, and the map opens its next item or runs on. No `service-automation` change. - **Failures are told as the recall tells its own.** The withdrawal stands whatever happens to the batch. A refused batch resume (for example `409 RESUME_CHILD_PENDING` when the item's history cannot be read) or a lookup that throws fills `resumeError` and logs at `error`; the engine's stranded exit, and a strand bubbled to a subflow parent above the batch, also fill `resumeFailure` with `RESUME_FAILED`, the one code this package's ledger row admits. `resumed` still describes the recalled request's own run, which was cancelled, so it stays `false`. - **Nothing is woken without proof.** No `listSuspendedRunsDurable` or `getFlow` on the attached engine, no run parked on that item, or a parked node that is not the built-in `map`: the recall answers exactly as before. A home-grown node that parks on a `map:` link is never re-run, because the engine records the cancelled item only for the built-in `map`, and re-running another node would advance it past the item with nothing recorded. - **`packages/plugins/plugin-approvals/src/batch-item-recall-resumes-batch.test.ts`** (new). The real `AutomationEngine` with the built-in nodes and the approval node, a `release_signoff` batch (`map` over `task_signoff`, an approval with a revise window), the showcase's `showcase_release_signoff` → `showcase_one_task_signoff` shape. - **`scripts/engine-double-contract.pinned.json`.** Two generated rows (`delete`, `update`) for the new test's engine double, written by `check-engine-double-contract.mjs --write`. - **`.changeset/28183-batch-item-recall-resumes-batch.md`.** `@objectstack/plugin-approvals` patch. ## Why ### Before (measured at `origin/main` `3a2f4c00`) Two tasks; item 1 sent back by the approver, then recalled by the submitter from the revise window: | | Before | After | |:---|:---|:---| | item 1's run | `cancelled` | `cancelled` | | batch run | parked on `signoffs`, correlation `map:<item 1's run>`, history `paused` | parked on `signoffs`, correlation `map:<item 2's run>` | | item 2's request | none | `pending` | | recall answer | `resumed: false`, no `resumeError` | `resumed: false`, no `resumeError` | | after item 2 is approved | (never reached) | batch `completed`; `signoffResults` = `[{ $status: 'cancelled', $itemRunId }, { decision: 'approved' }]`, `count` 1 | ### Why this path Triage 6527285884 routed the card to ruling A (6523833308): a cancelled item records `cancelled` and the map moves on, and the recall follows the same shape by resuming the parent with the cancelled marker. PR #28176 already built that resume behind the batch run's own id; the only thing missing was a caller. So the fix stays in the recall path and reuses that resume as is: no new marker shape, no new code, no `packages/spec` edit. ## Tests `batch-item-recall-resumes-batch.test.ts`, 5 cells: 1. the recall resumes the batch: item 1's slot is the marker, `count` 1, item 2's request opens, and the batch completes after item 2 is approved (red on `main`); 2. CONTROL: a revise-window recall on an approval with no batch above it is unchanged, and a batch parked beside it is untouched; 3. CONTROL: a recall while `pending` resumes the item down `reject`, and the map records `{ decision: 'rejected' }`; 4. CONTROL: a batch whose every item is decided (one through a send-back and resubmit round) records both outputs, `count` 2; 5. CONTROL: a run parked on a `map:` link at a node other than the built-in `map` is not woken. Ablations through `scripts/ablation-replace.mjs`, each restored to the HEAD blob with `git diff HEAD` empty: | Ablation | Red | |:---|:---| | A1: drop the batch resume after `cancelRun` | cell 1 | | A2: match any `map:` parent, not this item's | cell 2 | | A3b: a `pending` recall takes the cancel path | cell 3 | | A4: the decide door always resumes down `approve` | cell 4 | | A5: drop the built-in `map` node check | cell 5 | (A3, the batch resume also issued on the `pending` path, stayed green: by then the item has completed and the map has moved to item 2, so no run is parked on item 1 and the lookup finds nothing. Harmless, so not a guard.) ## Verification Head `acae6743`, after a whole-tree `turbo run build` and fetching the teardown self-test's pinned commit. - `pnpm --filter @objectstack/plugin-approvals exec vitest run`: 106 files, 1357 passed. `pnpm --filter @objectstack/plugin-approvals run typecheck`: exit 0, test layer held at its ledger. - `dispatch-gates --commands` (re-derived after the second commit): 71 families, all exit 0. `--ran`: 71 derived, 71 run, 0 NOT-MEASURED, 0 UNRUN. The first sweep caught the test double (`check:engine-double-contract`, `check:objectql-double-limit`); the second commit routes it through the dispatch asserts and adds its two generated ledger rows. - `pnpm lint`: exit 0. `check-commit-card-trailers --range origin/main..HEAD`: exit 0. ## Out of scope - `listSuspendedRunsDurable` reads a durable store's deployment-wide page (`ObjectStoreSuspendedRunStore.list()`, 1000 rows). Past 1000 parked runs the batch run may not be on that page, and the recall then answers as it did before this PR (the batch stays parked, nothing is told). A precise lookup needs an engine member (the item run's `$parentRunId`), which is outside this card's surface. - `content/docs/automation/flows.mdx`'s cancelled-item paragraph and `approvals.mdx`'s revise-window paragraph do not yet say that a recall wakes the batch. Docs were outside the claimed surface. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_016WV4d13k5TVyAhqhiKKgN3 --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 001c04b commit a426d36

6 files changed

Lines changed: 430 additions & 3 deletions

File tree

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
'@objectstack/plugin-approvals': patch
3+
---
4+
5+
fix(plugin-approvals): a revise-window recall on a batch sign-off item resumes the batch, which records the item as cancelled and goes on
6+
7+
Clause-②: no (a batch run that nothing could wake after the recall now continues, in the shape the cancelled-item ruling already set; no schema, accept set, error code or result field changes)
8+
Metadata-protocol: none
9+
10+
A batch sign-off is a `map` node over the items, and each item's run parks on its own `approval`. When the submitter recalled an item from the revise window, the recall cancelled the item's run with `cancelRun`, which never touches the parent. The batch run stayed parked on that item with no request open for the next one, and nothing woke it short of an operator resuming the batch run by hand.
11+
12+
- **Now.** After the cancel, the recall resumes the batch run parked on that item. The map records the item's slot as `{ $status: 'cancelled', $itemRunId }`, leaves it out of `count`, and opens the next item, or runs on past the map when it was the last one.
13+
- **Only the built-in `map`.** A run is woken only when it is parked at a `map` node on that item's run. Any other node parked on such a link is left alone, because nothing records the cancelled item for it.
14+
- **Failures are told the way the recall tells its own.** A batch resume the engine refuses or strands does not fail the recall: the withdrawal stands, `resumeError` says which run did not move and why, and an engine-stranded batch is reported on `resumeFailure` with code `RESUME_FAILED`.
15+
- **Unchanged.** A recall while the request is still `pending` (the item resumes down `reject` and the map records its output), a revise-window recall with no batch above it, and a batch whose items are all decided.

‎content/docs/automation/approvals.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -735,7 +735,11 @@ flow's `revise` edge. The submitter reworks the record and `resubmit`s (a fresh
735735
round opens for all approvers) or `recall`s (abandons it). Past the node's
736736
`maxRevisions` budget (default 3) a send-back **auto-rejects** instead. The
737737
flow's approval node must declare a `revise` edge, and that edge must target an
738-
`approval_revise` node, for send-back to be available.
738+
`approval_revise` node, for send-back to be available. A recall from the revise
739+
window cancels the run; when that run is an item of a batch sign-off (a `map`
740+
over approval items), the recall also wakes the batch, which records the item's
741+
slot as the cancelled marker `{ $status: 'cancelled', $itemRunId }` and moves on
742+
to its next item or its end.
739743

740744
The window is deliberately **not** an ordinary `wait`: `resubmit` is what
741745
authorizes (submitter-only), orders (latest round) and records (an audit row) the

‎content/docs/automation/flows.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1525,7 +1525,10 @@ success: the node's `count` is the items that ran. A downstream step reads it
15251525
where it reads the results — `signoffResults[i]['$status'] == 'cancelled'` (a
15261526
child flow's output keys never start with `$`, so no real output looks like
15271527
it). An item whose run is gone *without* a `cancelled` entry in its run history
1528-
is refused with the same 409: the map has nothing true to record for it.
1528+
is refused with the same 409: the map has nothing true to record for it. A
1529+
submitter's recall of a batch item from its revise window does this itself: the
1530+
recall cancels the item's run and resumes the batch, so the item's slot holds
1531+
the cancelled marker and the next item opens.
15291532

15301533
v1 is sequential and
15311534
fail-fast (the first item whose subflow fails fails the map). Concurrent fan-out (all items at once) is the

‎packages/plugins/plugin-approvals/src/approval-service.ts‎

Lines changed: 66 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5277,14 +5277,18 @@ export class ApprovalService implements IApprovalService {
52775277
if (runId) {
52785278
resumeError = this.missingRunCapability(runId, requestId, 'the recall', 'cancelRun');
52795279
if (!resumeError) {
5280+
let cancelled: unknown;
52805281
try {
5281-
await this.automation!.cancelRun!(runId, `approval request ${requestId} recalled during revision`);
5282+
cancelled = await this.automation!.cancelRun!(runId, `approval request ${requestId} recalled during revision`);
52825283
} catch (err: any) {
52835284
resumeError = err?.message ?? String(err);
52845285
this.logger?.error?.('[approvals] cancelRun after revise-window recall failed — the run may be stranded', {
52855286
request: requestId, run: runId, error: resumeError,
52865287
});
52875288
}
5289+
// [#28183] `cancelRun` never touches a parent, so a batch whose
5290+
// `map` item this was would stay parked with nothing to wake it.
5291+
if (cancelled === true) ({ resumeError, resumeFailure } = await this.resumeBatchOfRecalledItem(runId, requestId));
52885292
}
52895293
}
52905294
} else if (runId) {
@@ -5366,6 +5370,67 @@ export class ApprovalService implements IApprovalService {
53665370
};
53675371
}
53685372

5373+
/**
5374+
* [#28183] Wake the batch above a run a revise-window recall just cancelled.
5375+
*
5376+
* On a batch sign-off the cancelled run is a `map` item, and its batch run is
5377+
* parked on `map:<itemRunId>`. `cancelRun` never touches that parent, so
5378+
* before this the batch waited for an operator's parent-id resume that
5379+
* nothing prompted. This issues that same resume: the engine reads the
5380+
* item's `cancelled` run history, records the item's slot as its cancelled
5381+
* marker (outside `count`) and moves the map on to its next item or its end
5382+
* — the shape the cancelled-item ruling (6523833308) set. No new shape and
5383+
* no new code: a resume the engine refuses or strands is told exactly as
5384+
* this door's own resume is.
5385+
*
5386+
* Only a run parked at the built-in `map` node on that item is woken: the
5387+
* engine records the marker for no other node, and re-running any other
5388+
* node would advance it past the item with nothing recorded. Whatever is
5389+
* missing to prove that — no `listSuspendedRunsDurable`, no `getFlow`, no
5390+
* such parent — leaves things exactly as they were before, which for a
5391+
* recall with no batch above it is the whole answer.
5392+
*/
5393+
private async resumeBatchOfRecalledItem(
5394+
itemRunId: string,
5395+
requestId: string,
5396+
): Promise<{ resumeError?: string; resumeFailure?: ResumeFailureReport }> {
5397+
if (typeof this.automation?.listSuspendedRunsDurable !== 'function') return {};
5398+
if (typeof this.automation.getFlow !== 'function') return {};
5399+
let batchRunId: string | undefined;
5400+
try {
5401+
const parent = (await this.automation.listSuspendedRunsDurable())
5402+
.find(r => r.correlation === `map:${itemRunId}`);
5403+
if (!parent) return {};
5404+
const flow: any = await this.automation.getFlow(parent.flowName);
5405+
const node = Array.isArray(flow?.nodes) ? flow.nodes.find((n: any) => n?.id === parent.nodeId) : undefined;
5406+
if (node?.type !== 'map') return {};
5407+
batchRunId = parent.runId;
5408+
const bubbleStrand = await this.serviceResume(batchRunId, {});
5409+
if (!bubbleStrand) return {};
5410+
// The batch advanced; a run above it (a subflow parent) did not.
5411+
return {
5412+
resumeError:
5413+
`RESUME_FAILED: the recall was recorded on request ${requestId} and cancelled its run '${itemRunId}', ` +
5414+
`and the batch run '${batchRunId}' above it resumed, but the subflow parent above that — run ` +
5415+
`'${bubbleStrand.runId}' — consumed its suspension and is now stranded: ${bubbleStrand.error}`,
5416+
resumeFailure: { code: 'RESUME_FAILED', runId: bubbleStrand.runId, status: 'stranded', repairable: bubbleStrand.repairable },
5417+
};
5418+
} catch (err: any) {
5419+
const message = err?.message ?? String(err);
5420+
this.logger?.error?.('[approvals] resuming the batch after a revise-window recall of its item failed — the batch may stay parked', {
5421+
request: requestId, run: itemRunId, batchRun: batchRunId, error: message,
5422+
});
5423+
const at = batchRunId ? `resuming the batch run '${batchRunId}' above it` : 'looking up the batch run above it';
5424+
return {
5425+
resumeError: `the recall was recorded on request ${requestId} and cancelled its run '${itemRunId}', but ${at} failed: ${message}`,
5426+
// Only the engine's own stranded exit is told in fields, as in `recall`.
5427+
...(batchRunId && ApprovalService.resumeStatusOf(err) === 'stranded'
5428+
? { resumeFailure: { code: 'RESUME_FAILED' as const, runId: batchRunId, status: 'stranded' as const, repairable: true } }
5429+
: {}),
5430+
};
5431+
}
5432+
}
5433+
53695434
// ── Record-delete lifecycle linkage (#13568) ─────────────────
53705435

53715436
/**

0 commit comments

Comments
 (0)