Run Records Capability

wf.run-records defines inspection of retained runs, independently of Durable execution and Replay. A claim MUST include Core Executor conformance and provide all three operations below. The capability has no Workfile syntax or activation predicate and MUST NOT be inferred as a workflow requirement. This section defines a document representation and operation semantics, not a transport, authentication mechanism, or service binding.

Record Identity and Retention

The executor MUST assign each workflow an opaque, nonempty string identity, stable across its runs and revisions in the deployment while any of their records remain retained. Distinct workflows with retained records MUST have distinct identities, and an identity MUST NOT be reassigned in a way that conflates their records. Construction, cross-deployment portability, and human readability are not prescribed; the stable-identity obligation is the one under Identity and Metadata.

The executor MUST document its visibility scope, workflow continuity policy (including moves and replacement), record retention and eviction policy, and how callers can observe completed runs before eviction. Process-lifetime retention is permitted, but the policy MUST provide an opportunity to inspect each completed run and MUST preserve mandatory record facts until the run record is evicted. Optional payload retention does not weaken any applicable execution or history obligation.

Run Record Document

A run record document MUST be a JSON object with the members below, serialized using Canonical JSON Value Serialization after the typed-value encoding below. Document, run, summary, step, and entry maps admit only their defined members and x- extensions; other structural maps admit only their defined members, while user-value maps admit arbitrary string keys. The run record schema checks structure; canonical spelling, completeness, and agreement with execution remain semantic requirements.

Member	Requirement
record, standard	REQUIRED: integer 1 and the exact Standard revision governing the run.
run	REQUIRED: the run summary below, plus required nonnegative integer generation (zero without recovery), and code, step, and reason when the run’s failure, hold, or stop supplies them. An optional predecessor identifies a Replay successor’s source run; it does not replace call parentage.
steps	REQUIRED: a map from step paths to step records in the current logical view. It includes every determined step outcome and every begun step still lacking an outcome; known pending occurrences may also appear. Uninstantiated iterations are not invented.
payloads	REQUIRED: the run payload inventory below.
pins	OPTIONAL: a map from artifact identities to recorded digests under Digests; definition denotes the Workfile document digest. When Durable execution is claimed, pins.definition is REQUIRED. Digests describe executed content and are not workflow selectors.
entries	REQUIRED when Durable execution is claimed; otherwise OPTIONAL. The ordered projection below.

A summary MUST contain id, workflow, status, started_at, dry_run, and parent, using the recorded run metadata; parent is null for a root run, and the recorded workflow name is included exactly when declared. status MUST be one of the terminal Run Outcomes, or active, suspended, or held for a nonterminal run; started_at uses canonical timestamp form in UTC. A summary contains no payloads. A queued activation for which no run has begun is not a run record.

A step record MUST contain its path, nonnegative integer generation, status (pending, active, or ended), and payloads; outcome is present exactly when status is ended and uses Step Outcomes. It MUST state the applicable classified code and branch decision when determined: {case: string} for a route case, {arm: int} for a zero-based choose arm, or {else: true} for an explicit or implicit else branch. A map key MUST equal its step record’s path; generations identify the execution that produced the facts, so independently reused steps can precede the run’s current generation. An unfinished held invocation has no step outcome; active does not assert that its work is currently executing.

Record Payloads

An inventory MUST identify each applicable payload slot, including dry-run partial bindings and outputs, even when its value is unavailable; an absent slot means no such payload was produced or evaluated, not that a value was lost. Run slots are inputs, trigger, and outputs; step slots are arguments, result, details, binding, and event. A step’s attempt-dependent slots describe its latest attempt in the reported generation; entries preserve earlier attempts when present. inputs and trigger have class inputs, arguments has class arguments, result, details, and binding have class results, event has class events, and outputs has class outputs. An empty input map is still an input payload; outputs are applicable only once a successful workflow result exists.

Each slot MUST contain class and one state: present (with a required typed value), removed (discarded by retention reduction), withheld (export prohibited by sensitive-field rules), or not-recorded (the executor did not record this payload). An unavailable slot MUST NOT contain value; sensitive withholding takes precedence over other unavailable states, and an actual null is a present typed value. A projection containing a sensitive field is withheld as a whole; independently retained public projections may remain present. Dry-run partial values MUST additionally carry suppressed, a nonempty list of paths to suppressed components (each path is a list of map keys or zero-based list indices, and an empty path denotes the whole value), preserving the recorded suppression independently of payload availability. These paths traverse the runtime value, not its encoding envelopes.

A typed value MUST be {kind, value}, recursively encoded by the following table; wrappers distinguish runtime kinds and ordinary user maps from record markers. Numeric tokens MUST preserve their Workfile runtime kind, exact integer value, and signed zero; structural counters use integer tokens.

kind	Encoded value
null, bool, int, float, string	The corresponding JSON scalar in the Workfile domain.
list, map	A list of typed values, or a string-keyed map of typed values; objects use map.
timestamp	{instant, zone}: canonical UTC timestamp and the recorded display zone (Z, numeric offset, or IANA zone identity).
duration	Signed integer milliseconds.
file	The carrier members under The file Type, preserving the reference and metadata; no content is embedded and availability of the reference does not assert availability of its content.

Ordered Record Entries

Entries MUST have consecutive integer seq values starting at one, nonnegative integer generation, and a kind from the table below, in the recorded order; this order does not assert a causal order between independent concurrent work. Each entry contains the required fields specified for its kind and may contain payloads using the same slots and availability rules; absent inventories denote no payload slots at that entry.

kind	Required content and occurrence
start	First entry, generation zero; represents run start.
step	step: a step record whenever an occurrence acquires an outcome. Active occurrences may also be reported.
invoke	path, positive integer attempt, operation (action operation key), artifact (the recorded connector-manifest digest), dispatch: not-dispatched or ambiguous (dispatched, no definite result). Each dispatched action-step attempt is represented, including auxiliary actions with reserved step paths.
result	path, attempt, dispatch: ambiguous, failed, or succeeded; code when classified. Each accepted action attempt result is represented.
child	path, child: the actual child run identifier, for each child started.
recovery	supersedes: sequence numbers of earlier entries removed from active consideration on entering this generation. Each generation transition is represented, including an empty discarded suffix.
conclude	status: terminal run outcome, plus applicable path, code, and reason. Last entry for a terminal run.

The projection MUST include every applicable occurrence specified in the table, preserve superseded entries, and keep current step facts consistent with active entries; a later result cannot rewrite an earlier generation’s facts. A recovery entry’s references MUST identify earlier work entries (not start or recovery), and its generation MUST be the preceding active generation plus one. An exported record is not necessarily sufficient for Replay or resumption; Abstract Run History retains its complete logical obligations independently of this bounded projection.

Run Record Operations

All operations MUST observe retained data without evaluating workflow logic, dispatching work, or changing run state, and each successful result MUST represent one coherent snapshot within the documented visibility scope. Separate calls need not share a snapshot.

Operation	Input	Successful result
List runs	Optional workflow identity	All retained visible run summaries, without duplicates; omission selects all workflows. An unknown workflow selects an empty list.
Get run record	Run identifier	One run record document.
Get step record	Run identifier and step path	The corresponding step record from the current run-record view, including its payload inventory.

The executor MUST implement these selection and result rules, including retained child runs: a workflow selector matches the child’s own workflow identity, not its ancestors’ identities. Listing order is unspecified; filtering by status, pagination, and service bindings are not defined. A successful listing MUST NOT be silently truncated; inability to produce a complete result follows Resource Limits.

Lookup refusal MUST distinguish run-not-found, run-not-retained when retained evidence establishes prior existence and eviction, and step-not-found for a path with no occurrence in an available run; malformed step paths are invalid requests, not unknown occurrences. After all evidence is deleted, run-not-found is permitted; no tombstone lifetime is imposed. A known pending or active occurrence MUST return a step record without an outcome, and unavailable payloads MUST be reported inside the record rather than refusing lookup. Authorization and transport errors remain binding-specific.