control.version.select_latest

Select the latest comparable version and compute current-version lag evidence

Overview

Property	Value
Workflow type	Atomic
Library	App-control
Version	1.0

Input Schema

Field	Type	Required	Default	Description
versions	json	Yes	—	List of candidate version strings or row objects. Examples: ["1.0.0", "1.2.0"] or [{"package": "api", "package_version": "1.2.0"}].
current_version	string	No	—	Current pinned/tagged version to compare against candidates, for example 1.1.0.
version_field	string	No	—	Optional dotted path for object candidates, for example package_version or metadata.tag. When omitted, common fields such as version, package_version, tag, and name are tried.
include_prereleases	boolean	No	—	Whether prerelease candidates such as 2.0.0a1 can be selected as latest.
strict_candidates	boolean	No	—	Strict mode: fail when any candidate row is missing a version, invalid, or excluded as a prerelease.
strict_current	boolean	No	—	Strict mode: fail when current_version is present but cannot be parsed as a comparable version.

Output Schema

Field	Type	Required	Default	Description
versions	json	No	—	Candidate version list echoed from input.
current_version	string	No	—	Current version echoed from input.
version_field	string	No	—	Candidate version path echoed from input.
include_prereleases	boolean	No	—	Whether prerelease candidates were eligible.
strict_candidates	boolean	No	—	Whether skipped candidates were treated as hard failures.
strict_current	boolean	No	—	Whether an invalid current_version was treated as a hard failure.
latest_version	string	No	—	Latest comparable candidate in original string form, or null when unknown.
latest_normalized_version	string	No	—	PEP 440 normalized latest version, or null when unknown.
latest_item	json	No	—	Original candidate item that supplied the latest version.
current_normalized_version	string	No	—	PEP 440 normalized current version, or null when absent or invalid.
ahead_count	integer	No	—	Number of comparable candidates newer than current_version, or null when unknown.
is_current_latest	boolean	No	—	True only when a valid current_version is at latest among comparable candidates.
behind	boolean	No	—	True only when comparable candidates are newer than current_version.
comparable_count	integer	No	—	Count of candidate versions that parsed and were eligible.
skipped_count	integer	No	—	Count of candidates skipped as missing, invalid, or excluded prereleases.
ordered	list	No	—	Comparable candidates sorted from oldest to newest.
skipped	list	No	—	Skipped candidate records with reason metadata.
result	json	No	—	Typed envelope using schema control.version.select_latest.v1.
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "control.version.select_latest",
  "initial_data": {
    "versions": "value"
  }
}