Correct service-mode cancellation claims and add cooperative request parity

[rmcdaniel]

Problem

The stable service-mode POST /workflows/{id}/cancel route calls Workflow's terminal attemptCancel() and immediately closes the run, cancels open tasks/timers, and revokes leases. It is not the separate cooperative request path shipped for embedded Laravel in workflow#483 / Workflow 2.2.0. A real-Server Python integration case in sdk-python#69 confirms that an in-flight local activity's next heartbeat loses the lease and no local completion is committed.

Published Python/Rust SDK docstrings and the language-neutral docs call cancel_workflow cooperative/graceful and imply workflow cleanup runs. That claim is false for the current service-mode route and could cause customers to skip external cleanup or reconciliation.

Immediate correction

• Audit the PHP, Python, Rust SDK guides/API docs and main service-mode docs. State plainly that current cancel is terminal; terminate is also terminal with a distinct outcome/reason. Neither guarantees workflow-code finally cleanup. Do not change stable endpoint semantics under a documentation fix.
• Preserve the accurate embedded-Laravel cooperative-request guidance and clearly label its deployment mode.
• Verify rendered/public guidance after publication with focused link/content checks. Do not turn this into a site-wide screenshot pass.

Additive parity work

• Design a separate service-mode cooperative cancellation request using the already shipped Workflow engine primitive without repurposing /cancel. Expose the request/observable pending state in Server and PHP/Python/Rust SDKs only after one shared protocol/conformance contract is qualified.
• Cover request-before/after task claim, waiting runs, bounded cleanup, duplicate requests, worker loss/replay, termination during cleanup, SDK task cancel_requested delivery, and local/remote activity fencing. External effects remain at-least-once and need idempotency/reconciliation.
• Publish capability claims only after exact published Server + SDK artifacts pass cross-language conformance. Keep terminal cancel behavior and compatibility intact.

This is a confirmed product/docs contract gap, not a request to reopen the completed embedded feature. Own the immediate correction first; the additive protocol work follows current accepted release commitments. No private Cloud or customer data belongs here.

[rmcdaniel]

Immediate factual correction is in review:

• Main docs: Correct service-mode cancellation guidance durable-workflow.github.io#139
• PHP SDK: Clarify PHP service-mode cancellation outcome sdk-php#74
• Python SDK: Correct Python cancellation and cleanup docs sdk-python#70
• Rust SDK: Correct Rust cancellation API docs sdk-rust#48
• CLI: Clarify terminal workflow cancellation in CLI cli#32

Focused local verification passed: docs production build, Python 239 tests and Ruff, CLI 18 tests, and public-boundary scans. CI is running. The separate additive service-mode cooperative request remains open; none of these PRs changes the existing terminal route.

[rmcdaniel]

Immediate contract correction is merged: docs#139, sdk-php#74, sdk-python#70, sdk-rust#48, and cli#32. Main docs are live and show the terminal service-mode behavior. The CLI 2.1.1 patch release has been dispatched to ship corrected installed help/output; publication verification is pending. Service-mode cooperative request parity remains a separate additive protocol task in this issue.

[rmcdaniel]

Immediate factual correction is delivered: main docs#139, sdk-php#74, sdk-python#70, sdk-rust#48, and cli#32 merged; their public documentation pages were spot-checked after deployment. CLI 2.1.2 is published with the corrected installed workflow:cancel help and the repaired default upgrade path (cli#33 / PR#34; docs manifest PR#140). Published binary/checksum/installer/upgrade dry-run checks passed. The separate additive service-mode cooperative cancellation request remains open here; no existing /cancel behavior changed.

[rmcdaniel]

Service-mode implementation triage: Workflow already persists CooperativeCancellationRequested and a bounded cleanup deadline through WorkflowStub::attemptRequestCancellation(). Server currently exposes only terminal /cancel (and run-scoped terminal cancel); its workflow-task poll payload does not deliver the pending cancel_requested state that Python workers consume, so adding a request route alone would not make cleanup cooperative. The additive path needs a distinct request endpoint, durable pending-state delivery on claimed/replayed workflow tasks, deadline/fencing behavior across worker loss and termination, and one shared PHP/Python/Rust contract test. Preserve existing /cancel semantics. Next implementation should start at the Server request/poll boundary, then qualify the published Server + SDK tuple before advertising parity.

[rmcdaniel]

Portable implementation audit (2026-09-24): WorkflowStub::attemptRequestCancellation() already persists the request, deadline, history event and a ready task when no open task exists. Embedded WorkflowExecutor::run() checks that deadline and performs terminal cleanup. In contrast, Server WorkflowTaskPoller::taskPayload()/refreshCachedTaskPayload() do not project the pending cancellation flag or deadline, and the portable DefaultWorkflowTaskBridge has no cancellation-deadline path. PHP/Python/Rust workers already consume a task-level cancel_requested flag, but Server currently supplies it only for closed-run rejections, not an active cooperative request. A new HTTP route by itself would therefore be an incomplete and misleading feature, especially for a request arriving after task claim or a worker lost during cleanup. The first coherent implementation must couple the distinct request endpoint with durable task delivery (including cached/reclaimed leases) and a portable deadline/fencing transition; then test before/after claim, restart, duplicates, deadline expiry and terminal cancel/terminate races on one published tuple. Preserve existing /cancel semantics. No service-mode parity claim is made from this audit.

[rmcdaniel]

Immediate customer-facing contract correction is shipped. PHP SDK #74, Python SDK #70, Rust SDK #48, and main docs #139 already corrected the terminal service-mode cancel claim. I found one remaining false claim in the embedded child-workflow guide: ParentClosePolicy::RequestCancel actually invokes terminal attemptCancel(), not cooperative requestCancellation(). Docs #142 corrected it and removed a misleading Rust-guide link. Its checks and Pages deployment passed.

Focused live-content checks now show the terminal/no-cleanup contract on the PHP failures/retries page, Python workflow reference, Rust Client API, main Server API reference, and the corrected child-workflow page. These checks validate published wording, not service-mode cooperative behavior.

Leave this issue open for the additive service-mode cooperative-request contract and cross-language conformance; do not repurpose the stable /cancel endpoint. The current documented request_cancel parent-close policy remains terminal despite its name, which must be accounted for in any later API design.