control.version.lag_summary

Aggregate version-lag evidence rows into a deterministic summary

Overview

Property	Value
Workflow type	Atomic
Library	App-control
Version	1.0

Input Schema

Field	Type	Required	Default	Description
items	json	Yes	—	List of evidence objects or child workflow outputs. Examples include direct control.version.select_latest result objects or rows containing merge_row_evidence.result.
source_items	json	No	—	Optional full attempted row list; unmatched rows are reported as missing evidence.
evidence_paths	json	No	—	Ordered dotted paths used to unwrap child outputs, for example ["merge_row_evidence.result", "result", "state_data.result"].
identity_fields	json	No	—	Fields used to match evidence rows to source rows, for example ["package", "package_version"] or ["repository", "tag"].
name_fields	json	No	—	Fields used to choose display labels, for example package, image, repository, or service.
current_version_fields	json	No	—	Fields used to read the current/pinned version, for example package_version or tag.
latest_version_fields	json	No	—	Fields used to read the latest/target version, for example latest_version or target_version.
behind_field	string	No	—	Dotted path to the boolean lag flag in each evidence row; defaults to behind.
ahead_count_field	string	No	—	Dotted path to the integer number of newer candidate versions; defaults to ahead_count.

Output Schema

Field	Type	Required	Default	Description
items	json	No	—	Evidence row list echoed from input.
source_items	json	No	—	Attempted source row list echoed from input.
evidence_paths	json	No	—	Evidence unwrap paths used for child workflow outputs.
identity_fields	json	No	—	Fields used to match evidence rows to source rows.
name_fields	json	No	—	Fields used to choose row display labels.
current_version_fields	json	No	—	Fields used to read current or pinned versions.
latest_version_fields	json	No	—	Fields used to read latest or target versions.
behind_field	string	No	—	Dotted path used to read the boolean lag flag.
ahead_count_field	string	No	—	Dotted path used to read newer-version counts.
checked_count	integer	No	—	Number of evidence rows evaluated.
source_count	integer	No	—	Total attempted source rows when supplied, otherwise evidence row count.
behind_count	integer	No	—	Number of checked rows known to be behind.
current_count	integer	No	—	Number of checked rows known to be current.
unknown_count	integer	No	—	Number of checked rows whose lag status is unknown.
missing_count	integer	No	—	Number of source rows missing evidence.
max_ahead_count	integer	No	—	Largest ahead_count observed across checked rows.
total_ahead_count	integer	No	—	Sum of positive ahead_count values across checked rows.
checked_items	list	No	—	Normalized evidence rows that were checked.
behind_items	list	No	—	Checked rows known to be behind.
current_items	list	No	—	Checked rows known to be current.
unknown_items	list	No	—	Checked rows whose lag status is unknown.
missing_items	list	No	—	Source rows that did not produce matching evidence.
summary_text	string	No	—	Bounded deterministic prose summary for notifications and reports.
status	string	No	—	Aggregate status: current, lagging, partial, or unknown.
result	json	No	—	Typed envelope using schema control.version.lag_summary.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.lag_summary",
  "initial_data": {
    "items": "value"
  }
}