Repository navigation
Document compatible evolution of long-lived signal payloads #259
Description
Long-running workflows need a documented way to evolve application signal payloads without breaking old senders, old runs or replay. The current signal guide explains declared arguments and admission, but does not give an old/new payload compatibility recipe.
Validated public source:
- At docs main
e1ac63c3ccd93cbf7c6d0f6e94820af50531f545, Signals documents named signals and argument validation. The Avro Value protocol uses a fixed recursive value schema and requires explicit adapters for domain objects and dataclasses. It is not an application schema registry. - At Workflow main
67833a7938b65e8ec663b4a63b25b4ac1b0beeef, RunCommandContract reads the run's recorded command contract and reconstructs admitted arguments/defaults from that contract. WorkflowStub uses that admission contract. Changing a current function signature is therefore not a sufficient compatibility explanation for an existing run.
Priority P3, documentation. No payload-corruption or replay defect has been reproduced.
Acceptance:
- Give a small versioned map/value payload example showing how an application handles a missing optional field and preserves meaning for old senders. Distinguish application decoding from the fixed Avro wire schema.
- Explain the actual old-run/new-run command-contract boundary and compatibility routing. Do not promise that changing the current signal signature changes an already-started run's contract.
- Validate old sender/new handler and new sender/old run behavior, including rejected incompatible input, against a named published SDK/runtime baseline. Identify language-specific limits instead of assuming Python dataclass defaults or rest-parameter behavior.
- Preserve an old-run/replay fixture while documenting an additive payload change. Keep any runnable example consistent with the supported PHP, Python and Rust value adapters; unsupported combinations should be stated explicitly.
Validation so far is static source and documentation review. The compatibility fixtures above are required follow-through, not tests claimed to have run. This task is separate from sender attribution/authorization documentation in #258.
Activity
rmcdaniel commentedon Oct 20, 2026
Related need from source review: the same old/new compatibility recipe applies to activity inputs and results. They are recorded in history at schedule time, and a retried or replayed activity can reach newer activity code with an older argument shape. The guide could cover both with the single-wrapper-value pattern and explicit adapters, so a separate issue is not needed.
rmcdaniel commentedon Oct 20, 2026
Product review:
Keep as documentation of actual payload/command evolution. Existing runs retain their admitted contracts; a versioned value wrapper and explicit adapters can evolve application payloads without inventing a schema registry or rewriting history. Require old/new sender and replay controls. Server #518 is the distinct confirmed code-upgrade/claim defect; this guide cannot be used as its workaround-only resolution.
rmcdaniel commentedon Oct 20, 2026
Accepted as a genuine authoring/reference gap after product review. Draft source will use a stable single-map signal contract, explicit supported application fields/defaults and retained old readers. It will distinguish wire-schema compatibility, runtime admission and application acceptance, and will not present the current Server's changed-source workflow routing restriction as solved. Actual published-artifact old/new sender/handler and cold-read controls remain qualification work. All seven translated guides will be updated with the final English source.
rmcdaniel commentedon Oct 20, 2026
Signal payload guide qualification is ready for review in PR #310, exact head 08ab98a / tree ed0a8643359524d75e51a53026b36c27ecfbe656.
All eight language guides include the same verified map example and complete translated semantics. Six fresh published Server 2.9.7 / normally installed Python 2.6.1 originals pass the old/new sender-reader, cold replay, optional Unicode field, incompatible-input and immutable-default controls. Stopped SQL independently proves 6 completed runs, 12 first-attempt tasks, 48 events, 0 repairs and original 30-second deadlines; unchanged DB hash and canonical recorded-default decoding pass. PHP Core 2.7.2 syntax plus 8 exact decoder-body vectors pass, without a full embedded-run claim. Focused source/translation checks pass; normal rendered-site qualification remains pending.
The original setup/observer failures and API shutdown 137/no OOM remain explicit in the PR. The recorded source fence remains a separate #518/#525 product issue; the docs do not claim edited-code replay. All owned runtime/dependency/database/raw/container/network state was actually removed at 10:03:26 UTC, ahead of 10:30. Borrowed/shared images and foreign resources preserved.
rmcdaniel commentedon Oct 20, 2026
Delivered through #310 at c096f4c, whole tree 772b2177f6633fdac275dc0d3fc4b1f46933f2ea, identical to the reviewed and qualified final candidate.
evolve-a-signal-payloadsection with its translated heading, both decoder/sender examples, and the correctSignalReceivedevent. The inheritedWorkflowExecutionSignaledlabel is absent. This is actual HTTP/content acceptance, not a browser-layout claim.The original six real published-artifact compatibility runs and their stopped-state audit remain scoped to the component recorded above. Immutable original declarations/defaults, Server 2.9.7's source-routing restriction and the unsuccessful setup/observer/API-shutdown limits remain explicit. This closes the documentation need; it does not deliver or close Server #518, Server #525 or the shared clock feature (.github #215).
The temporary UID1000 HTTP-reader container was actually removed at 11:28:48 UTC, with no files, dependencies, databases or new image created. Earlier substantive runtime cleanup remains final. The merged clean worktree is being retired; all foreign resources are preserved.