From d5e6e63a9ccf49343bb032000576098c95e08960 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Thu, 19 Nov 2026 18:02:45 +0000 Subject: [PATCH 1/2] Prepare Python SDK 2.20.0 release Ships signal-with-start (#347, .github#222) and durable signal-external (#346, .github#223). Both need native Server 3.15.0 or later; they are capability-gated, so the supported Server baselines stay unchanged and the requirement is documented in the CHANGELOG and docs. Retargets the installed retry-cap qualification cell to the 2.20.0 candidate on native Server 3.15.0 (index sha256:f7f84884..., source fdb6c4f6, amd64 sha256:0d0db083...). Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 4 ++-- CHANGELOG.md | 8 ++++++-- docs/reference/workflow.md | 2 +- docs/sdk-reference.md | 23 ++++++++++++++++++++++- pyproject.toml | 6 +++--- scripts/ci/activity-retry-cap.md | 2 +- scripts/ci/activity_acceptance_release.py | 2 +- tests/fixtures/published-retry-cap.json | 10 +++++----- tests/test_activity_retry_cap_cell.py | 2 +- 9 files changed, 42 insertions(+), 17 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 617a79d..475734d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -97,7 +97,7 @@ jobs: id: retry-candidate env: GH_TOKEN: ${{ github.token }} - run: python .github/scripts/promote_release.py resolve --version 2.19.1 + run: python .github/scripts/promote_release.py resolve --version 2.20.0 - name: Download the approved candidate handoff if: inputs.retry_cap_artifact_source == 'candidate' uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 @@ -110,7 +110,7 @@ jobs: archive: false - name: Verify candidate archive and distribution bytes if: inputs.retry_cap_artifact_source == 'candidate' - run: python .github/scripts/promote_release.py extract --version 2.19.1 + run: python .github/scripts/promote_release.py extract --version 2.20.0 - name: Bootstrap patched pip trust uses: durable-workflow/.github/.github/actions/bootstrap-patched-pip@75587fc33ff40c34f32ef777293dad56bb6f48c7 # clean-trust with: diff --git a/CHANGELOG.md b/CHANGELOG.md index 9f6569e..e73e98c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,12 +6,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.20.0] - 2026-11-19 + +Both additions need **native Server 3.15.0 or later**, the first Server release that advertises `capabilities.signal_with_start` and the `signal_external_workflow` worker command. Each is discovered from the Server's capabilities and refused before anything is sent on an older Server, so the SDK's supported Server baselines are unchanged and every other feature keeps working on older Servers. Worker protocol (1.20) and control-plane (2) versions are unchanged. + ### Added -- `Client.signal_with_start()` (and the sync client's) starts a workflow or reuses its open run and records one signal on it in a single Server transaction, so the run cannot close between a separate start and signal (durable-workflow/.github#222, server#1133). It needs a Server that advertises `capabilities.signal_with_start` (native Server) and raises `RuntimeCapabilityUnsupported` before sending otherwise. An open run, including the newest run after continue-as-new, is reused with its input and deadlines unchanged (`start_outcome == "returned_existing_active"`); `duplicate_policy="fail"` refuses it. A closed run is refused with `run_not_active` unless `closed_run_policy="start_new_run"`, which starts a fresh run after it. `request_id` is the signal's command key (generated as `sdk-python-signal-with-start-` when omitted): a retry returns the original receipt, even after the run closed. Every refusal raises the new `SignalWithStartFailed` (a `SignalFailed`) with the Server's `reason`, and nothing was written. +- `Client.signal_with_start()` (and the sync client's) starts a workflow or reuses its open run and records one signal on it in a single Server transaction, so the run cannot close between a separate start and signal (durable-workflow/.github#222, server#1133). It needs a Server that advertises `capabilities.signal_with_start` (native Server 3.15.0 or later) and raises `RuntimeCapabilityUnsupported` before sending otherwise. An open run, including the newest run after continue-as-new, is reused with its input and deadlines unchanged (`start_outcome == "returned_existing_active"`); `duplicate_policy="fail"` refuses it. A closed run is refused with `run_not_active` unless `closed_run_policy="start_new_run"`, which starts a fresh run after it. `request_id` is the signal's command key (generated as `sdk-python-signal-with-start-` when omitted): a retry returns the original receipt, even after the run closed. Every refusal raises the new `SignalWithStartFailed` (a `SignalFailed`) with the Server's `reason`, and nothing was written. - Workflow code can signal another workflow durably with `ctx.signal_external_workflow(workflow_id, signal_name, args=None, *, run_id=None)` (durable-workflow/.github#223, durable-workflow/server#1134). Yielding it sends the `signal_external_workflow` command and resumes with an `ExternalSignalResult` (`outcome`, `reason`, `target_run_id`, `target_command_id`, `target_signal_id`, `retained`, `delivered`). A missing, closed or refusing target is a returned outcome (`target_not_found`, `target_closed` or `rejected` with the Server's reason), not an exception, because the Server records it as a result and workflow code decides what to do. Arguments travel as an inline Avro payload envelope, like child workflow arguments. A signal name the Server would refuse (blank, a control character below U+0020 or U+007F, more than 191 characters or more than 255 UTF-8 bytes) raises the new `InvalidSignalName` (a `ValueError` with `reason`) in workflow code when the command is created, so nothing is sent and the task does not fail with a 422. The command is yielded on its own; a parallel group or selection member is refused. - **Replay safety:** replay matches `ExternalSignalRequested` at the command's sequence and returns the outcome from the following `ExternalSignalDelivered` or `ExternalSignalFailed`. A recorded signal is never sent again, including on a cold replacement worker and while its outcome is not yet recorded. A different target, run, signal name or arguments at that sequence raises `NonDeterministicReplayError`. Existing histories are unchanged. - - **Server requirement:** the Worker submits the command only when the Server advertises `signal_external_workflow` in `worker_protocol.server_capabilities` (and lists it in `supported_workflow_task_commands` when that list is present). Otherwise it fails the workflow task with `signal_external_workflow_unavailable` before submitting, so the signal is never sent outside history. + - **Server requirement:** native Server 3.15.0 or later. The Worker submits the command only when the Server advertises `signal_external_workflow` in `worker_protocol.server_capabilities` (and lists it in `supported_workflow_task_commands` when that list is present). Otherwise it fails the workflow task with `signal_external_workflow_unavailable` before submitting, so the signal is never sent outside history. ## [2.19.1] - 2026-11-18 diff --git a/docs/reference/workflow.md b/docs/reference/workflow.md index db9032b..ba8204b 100644 --- a/docs/reference/workflow.md +++ b/docs/reference/workflow.md @@ -73,7 +73,7 @@ another workflow durably. The yield resumes with an `ExternalSignalResult` whose `outcome` is `delivered`, `target_not_found`, `target_closed` or `rejected`. Undelivered signals are returned values, not exceptions. The signal is recorded once in history and replay never sends it again. It needs -a Server that advertises `signal_external_workflow`. +native Server 3.15.0 or later, which advertises `signal_external_workflow`. Yield a list for deterministic parallel composition. Lists may nest and may mix activity, child-workflow, and timer commands; the resolved value has the diff --git a/docs/sdk-reference.md b/docs/sdk-reference.md index 77e279e..76cfb5e 100644 --- a/docs/sdk-reference.md +++ b/docs/sdk-reference.md @@ -799,6 +799,18 @@ dispatch-rate limits, so automation can detect whether local worker slots, queue caps, namespace caps, or downstream dispatch budget groups are constraining throughput. +## Signal-with-start + +`Client.signal_with_start(workflow_id, signal_name, *, workflow_type=..., +task_queue=..., input=..., signal_args=...)` (and the sync client's) starts the workflow or reuses its open run and records one +signal on that run in a single Server transaction, so the run cannot close +between a separate start and signal. It needs native Server 3.15.0 or later, +which advertises `capabilities.signal_with_start`; against an older Server it +raises `RuntimeCapabilityUnsupported` before sending anything. Refusals raise +`SignalWithStartFailed` (a `SignalFailed`) with the Server's `reason`, and +nothing is written. See the method docstring for `duplicate_policy`, +`closed_run_policy` and `request_id` retries. + ## Signal another workflow Workflow code can signal another workflow in its namespace with @@ -842,7 +854,7 @@ needs delivery. Yield the command on its own: it cannot be a member of a parallel group or a durable selection. The connected Server must advertise -`signal_external_workflow` (native Server, server#1134). Against a Server that +`signal_external_workflow` (native Server 3.15.0 or later, server#1134). Against a Server that does not, the Worker fails the workflow task with `signal_external_workflow_unavailable` before submitting anything, so the signal is never sent outside history and the workflow is not failed. @@ -1613,6 +1625,15 @@ The top-level server `version` is build identity only. The worker checks these protocol manifests at startup and fails closed when compatibility is missing, unknown, or undiscoverable. +Some features need a newer Server than the SDK's supported baseline. They are +discovered from the Server's capabilities and refused before anything is sent +when the Server does not advertise them, so the rest of the SDK keeps working: + +| Feature | Needs | +| --- | --- | +| `Client.signal_with_start()` | native Server 3.15.0 or later (`capabilities.signal_with_start`) | +| `ctx.signal_external_workflow()` | native Server 3.15.0 or later (`signal_external_workflow` worker command) | + Carriers and support tooling can validate `auth_composition_contract` with `parse_auth_composition_contract()` before resolving connection, namespace, token, TLS, profile, and redacted effective-configuration diagnostics. diff --git a/pyproject.toml b/pyproject.toml index c13b683..7c66848 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "durable-workflow" -version = "2.19.1" +version = "2.20.0" description = "Python client and worker SDK for Durable Workflow Cloud and self-hosted Server" readme = "README.md" requires-python = ">=3.10" @@ -79,8 +79,8 @@ durable-workflow-replay-conformance = "durable_workflow.replay_conformance:main" durable-workflow-workflow-updates-conformance = "durable_workflow.workflow_updates_conformance:main" [tool.durable-workflow] -product-train = "2.19.1" -registry-version = "2.19.1" +product-train = "2.20.0" +registry-version = "2.20.0" supported-server-versions = "2.8.0" supported-server-release-baselines = { "2" = "2.8.0", "3" = "3.0.0" } worker-protocol-version = "1.20" diff --git a/scripts/ci/activity-retry-cap.md b/scripts/ci/activity-retry-cap.md index 57f5548..1989561 100644 --- a/scripts/ci/activity-retry-cap.md +++ b/scripts/ci/activity-retry-cap.md @@ -1,4 +1,4 @@ -The retry-cap case qualifies the exact reviewed 2.19.1 wheel on the published +The retry-cap case qualifies the exact reviewed 2.20.0 wheel on the published Server/Python tuple in `tests/fixtures/published-retry-cap.json`. It uses the existing internal two-container profile, complete hash lock, captured no-site entry, before/after installed inventory and independent ID/label cleanup. diff --git a/scripts/ci/activity_acceptance_release.py b/scripts/ci/activity_acceptance_release.py index 868b4f7..fb7708e 100644 --- a/scripts/ci/activity_acceptance_release.py +++ b/scripts/ci/activity_acceptance_release.py @@ -8,7 +8,7 @@ from scripts.ci.activity_acceptance_entry import captured_file -VERSION = "2.19.1" +VERSION = "2.20.0" WHEEL = f"durable_workflow-{VERSION}-py3-none-any.whl" SDIST = f"durable_workflow-{VERSION}.tar.gz" diff --git a/tests/fixtures/published-retry-cap.json b/tests/fixtures/published-retry-cap.json index 7589c13..d434eac 100644 --- a/tests/fixtures/published-retry-cap.json +++ b/tests/fixtures/published-retry-cap.json @@ -1,10 +1,10 @@ { "schema": "sdk-python.published-activity-acceptance/v1", - "sdk_version": "2.19.1", - "server_image": "ghcr.io/durable-workflow/server@sha256:30ccaf2cea6810a92915a9eb389f1a63ea870818a74c9cc1a321379b07b2d25c", - "server_source": "2d1244be4611e1bc4aa4f0d856c708bed17937b4", - "server_amd64_manifest": "sha256:6cdcb909b1ca46d10410d7f659fcbd292dbf02be0c337d989b886153c0f3ee56", - "server_qualification": "https://github.com/durable-workflow/server/releases/tag/3.13.0", + "sdk_version": "2.20.0", + "server_image": "ghcr.io/durable-workflow/server@sha256:f7f84884ff178e36b6536237f9f31eb006ed050feac3028106af736bc01d19de", + "server_source": "fdb6c4f63d0e1923b4b93a253699fc12d064bb10", + "server_amd64_manifest": "sha256:0d0db083943ab6d56ba66010f2fea1fe1dbebbede60b87f7bde2d5f9cd28e709", + "server_qualification": "https://github.com/durable-workflow/server/releases/tag/3.15.0", "python_image": "docker.io/library/python@sha256:935c3c5b12357a7e10caa9c1e6ca5692344d97cf229832ef584be2cec9fc03df", "python_amd64_manifest": "sha256:0f086103b026048cc50cb5da25ec435c023c5241a83fc44daea593377abc61c4", "python_version": "3.12.16" diff --git a/tests/test_activity_retry_cap_cell.py b/tests/test_activity_retry_cap_cell.py index 17bbb00..1c05906 100644 --- a/tests/test_activity_retry_cap_cell.py +++ b/tests/test_activity_retry_cap_cell.py @@ -84,7 +84,7 @@ def approval(digest="a" * 64): def test_effective_lock_adds_only_the_approved_sdk_to_the_fixed_dependencies(): result, digest = release.lock(b"pytest==1 --hash=sha256:" + b"c" * 64 + b"\n", approval()) - assert result.endswith(f"durable-workflow==2.19.1 --hash=sha256:{digest}\n".encode()) + assert result.endswith(f"durable-workflow==2.20.0 --hash=sha256:{digest}\n".encode()) assert result.count(b"durable-workflow") == 1 From 6bf7cf46358545c53b7b0bcabd409a094f195b5a Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Thu, 19 Nov 2026 18:10:15 +0000 Subject: [PATCH 2/2] Approve the reviewed 2.20.0 release candidate Records build-only run 44583674899 (attempt 1) at d5e6e63a: its dist-handoff.tar artifact and the exact wheel and sdist reviewed against the source and qualified on native Server 3.15.0. Co-Authored-By: Claude Opus 5.5 --- .github/release-candidates/2.20.0.json | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .github/release-candidates/2.20.0.json diff --git a/.github/release-candidates/2.20.0.json b/.github/release-candidates/2.20.0.json new file mode 100644 index 0000000..63c4682 --- /dev/null +++ b/.github/release-candidates/2.20.0.json @@ -0,0 +1,14 @@ +{ + "schema": "sdk-python.reviewed-release/v1", + "version": "2.20.0", + "source_commit": "d5e6e63a9ccf49343bb032000576098c95e08960", + "source_tree": "cfdd443d98dcca187338107b983c4813c4b06533", + "run_id": 44583674899, + "run_attempt": 1, + "artifact_id": 14559796844, + "artifact_sha256": "18620e7c696359d0642acecd466512f1ed430154262ae099be95903a335a2a6e", + "files": { + "durable_workflow-2.20.0-py3-none-any.whl": "e97aae2f3895165dd97817f0abc29ead23d48b81e228d3fa7491ef01cc293989", + "durable_workflow-2.20.0.tar.gz": "50e9c0ddc840f4af6fe8de759f761a5d5108dc83fcfc793075b57ca09123e8c7" + } +}