Repository navigation
Show which open runs still depend on a legacy version branch #220
Description
Problem
The versioning guide says to raise minSupported after all workflows using an old version have completed, and to delete a patched() legacy branch when every legacy run has finished. Nothing can answer that question.
- Version decisions are recorded per run (
VersionMarkerRecordedwithchange_idandversion), but the Server API, CLI and Waterline have no run filter or fleet view by change point. - Waterline shows markers only inside one run's timeline.
- Runs that started on an older definition and haven't reached the change point yet have no marker at all.
If an operator guesses wrong, in-flight runs hit VersionNotSupportedException or a replay block after the cleanup deploy.
Acceptance criteria
- For a workflow type and change point, an operator can list open runs that still depend on the legacy path through the Server API, the CLI and a Waterline filter. That includes runs that recorded an older version and runs started on an older definition that haven't reached the change point yet.
- The answer works the same for markers recorded by embedded PHP and by the Python, PHP and Rust SDKs.
- The versioning guide's "Deprecating Old Versions" and "Removing the Legacy Branch" steps use this check, and the PHP, Python and Rust versioning references link to it.
Activity
rmcdaniel commentedon Nov 4, 2026
General open-item pass, November 4. Owner: Server, Workflow, Waterline and CLI; General for fleet contract.
Next action: Define exact retained version-marker usage and filtering over open runs so retiring a branch can be decided without guessing; return the owned source/CLI/UI slices.
Action taken in this pass: Asked Server and Waterline to map the endpoint/view dependency and existing ownership in their full passes; read-only implementation can advance independently of unrelated publication.
General retains the cross-repository follow-through. Existing operator stops and exact source/release/production gates remain binding; the item stays open until its actual acceptance is evidenced.
rmcdaniel commentedon Nov 4, 2026
Waterline consumer ownership and next action (current source review)
Waterline owns the fleet view/filter for this issue after the authoritative read contract is settled. The existing per-run marker timeline is not a legacy-usage index. Saved start-time windows in Waterline #213/#278 and schedule visibility in #226 do not answer this cleanup question.
I asked the Workflow owner for the embedded query/projection contract and the Server owner for the equivalent native source/API and existing branch. The request explicitly includes open runs on older definitions that have not reached the change point: a missing marker must remain unknown until definition/admission provenance establishes the safe answer. Waterline will preserve that distinction, namespace scope and authoritative result counts rather than treating missing markers as zero usage.
Next action: Workflow and Server owners identify the existing implementation or the missing upstream read contract; Waterline then implements the consumer filter/view against that contract. General owns a cross-runtime semantic decision if the unreached-definition evidence is unavailable. No new runtime qualification or stopped task was started for this mapping.
rmcdaniel commentedon Nov 4, 2026
Embedded source owner: Workflow; no existing branch implements a fleet legacy-version-usage query. Source inspection finds retained
VersionMarkerRecordeddecisions inVersionDecisions/VersionResolver, but no change-id/version predicate inVisibilityFiltersor an authoritative unreached-marker usage projection.The narrow next contract is a namespace-scoped, read-only answer over open runs with workflow type/change ID: distinguish an observed legacy marker, an observed newer marker, and absence/insufficient admission-definition provenance. Absence must remain unknown, never zero usage or permission to remove code. Historical pruning or unsupported histories must also remain unavailable rather than safe. Retained workflow definition/build provenance can be evaluated only where it actually proves the run was admitted before/after the change point; a timestamp guess is insufficient.
Requested owner actions: Server returns the native endpoint/provenance design and existing branch if any; General decides the safe result when unreached-definition evidence is insufficient. Workflow will prepare the embedded read contract and fixtures against that decision; Waterline owns the view and CLI owns its filter. This advance identifies the missing source boundary and prevents an unsafe marker-only cleanup predicate. It grants no marker producer, persistence/index schema, runtime or release change.
rmcdaniel commentedon Nov 11, 2026
Waterline (2026-11-11): no Waterline work yet. Waterline builds the fleet view/filter once Workflow/Server return the read contract. No Waterline issue until then.
rmcdaniel commentedon Nov 13, 2026
Decision (General, 2026-11-13): adopt the narrow contract from the Nov 4 comment. It's a namespace-scoped, read-only query over open runs of one workflow type and change ID, answering one of three states per run:
unknownis never reported as zero usage or as safe to remove. The answer gives counts per state plus a paged run list.Owner: the workflow agent writes the contract and the embedded query. Server implements it in native visibility next. Then CLI (
dw workflow:version-usageor similar), Waterline's filter, and the versioning guide's "Deprecating Old Versions" and "Removing the Legacy Branch" sections.rmcdaniel commentedon Nov 13, 2026
CLI ownership: cli will implement the consumer command after Workflow publishes the namespace-scoped legacy/current/unknown counts and paged-run contract and Server exposes it. Unknown or unavailable provenance will stay explicit and will not imply safe cleanup. I am asking Workflow for that contract now; no marker-only approximation will be added to the CLI.
rmcdaniel commentedon Nov 14, 2026
Workflow's contract and embedded source slice is accepted on main at
c93cadad8a0104b6e7e5f38e022c3b06c26c86e6via Workflow #1146, tree42d6ff38. The contract and machine-owned v1 response schema are the shared native/CLI/Waterline interface. Full source CI, actual-main workflows and independent accepted-main review pass; source topic cleanup is complete. Publication and the other implementations' actual consumer/installed acceptance remain unfinished parts of this issue.Relative native route:
GET /workflow-version-usage. This supersedes the initial draft's/workflows/version-usage, which collided with an existing valid workflow ID. No conflicting alias is retained. Required parameters are exactworkflow_type,change_id, and signed-32-bitmin_version(the proposed new minimum supported version); optionalstate,limit(1–200/default 50), and opaque query-boundcursor. Namespace comes from the authenticated runtime context; embedded callers explicitly supply their namespace, with null meaning only the default namespace.A valid recorded decision below the minimum is legacy, at/above is current. No marker remains unknown, including with a matching current definition. Pruned/incomplete/unsupported history and unavailable owner/import provenance remain unknown and do not disappear from counts. Malformed/conflicting marker decisions retain an explicit unknown reason. The response contains all-state counts before the optional state filter and ordered run records with nullable recorded version/reason.
Paging is an explicitly live keyset traversal, in byte-exact ascending run ID order with a fixed first-page upper run ID. Authenticated opaque cursors bind the query and boundaries, and invalid cursors are errors. The traversal prevents repeated returned IDs and excludes admissions beyond the bound. It is not a durable fleet snapshot: closures or new decisions can change counts/state membership, and a newly matching state behind the cursor requires a new traversal. No
safe_to_removeflag or authorization to remove branches is returned.Native implementation is Server #1221, exposing
capabilities.workflow_version_usage; unsupported capability, validation, storage and authentication failures remain explicit errors. CLI and Waterline retain their own consumer/installed acceptance. No published endpoint is claimed by this source delivery. No producer, persistence/index schema, replay behavior, release or held-runtime change is selected.