@@ 4.2
H 4.2.  format

P The string "stage-receipt/0.MINOR", where MINOR is a decimal string.
This revision describes minor 4.  Every member added after minor 1 is
OPTIONAL; Sections 4.11 to 4.20 and Section 6 define them, and a record
that does not hold one reads as a record written before it was added.
A verifier that encounters a different major version proceeds as
described in Section 14.

@@ 6.format
D format: The string "stage-receipt-chain/0.MINOR", where MINOR is the
minor of the run's receipts.

@@ 6.optional
P The manifest MAY carry other members.  It is itself digested in
canonical form when it is anchored or listed by a root over many
chains.  The following are OPTIONAL, and no digest in the chain
covers them:

D outputs_kept: "all" (each receipt's output files are kept beside the
run) or "none" (the run declares that it keeps none; its receipts
still record each output's digest and size).  With "none", every
receipt says so too, as "coverage.outputs_kept".  A verifier reads the
declaration only where the manifest and every receipt agree, and never
as files checked.

D edges: An array of objects with the members "from" and "to": the
node ids (Section 4.11) of each link the run recorded from an earlier
step to the step that read its receipt.

D declared_edges: The plan the run was approved under: an array of
objects with the members "from" and "to", stage names, and an OPTIONAL
"repeats", the string "true" for a loop.  A verifier checks that every
recorded edge, its node ids read as stage names, is a pair in
"declared_edges", and that an edge from a stage to itself is declared
with "repeats" "true".  An empty array is a plan that allows nothing.
Where "declared_edges" is absent, or a plan is declared and the run
records no edges, the plan check is NOT RUN, with that reason.

D auto: Section 4.19.

D rerun: A copy of the receipts' "rerun", read only where every
receipt carries the same (Section 4.13).

@@ 11.3.3
H 11.3.3.  States That Must Not Collapse

P The outcome class is one of the three permitted values.  An "error"
outcome carries status, body and origin (R06).  An empty array and an
absent member are distinguished, and the verifier reports which it
found.  So are: an absent "effect_label" and the value "unknown"
(Section 4.14); an absent "return_holds", which says the producer did
not check, and "[]", which says it checked and found nothing held
(Section 4.18); and an absent "empty" and the value "false"
(Section 4.17).

@@ 11.3.7
H 11.3.7.  Members of Minor 4

P A verifier that implements minor 4 also performs the checks of
Sections 4.12 to 4.19 on every record whose own "format" is
"stage-receipt/0.4" or later, and reports them as NOT RUN, with a
version reason, on a record of an earlier minor (Section 14).

@@ 12.1
H 12.1.  Diff

P Given two chains of the same pipeline, the diff pairs their steps by
node id (Section 4.11), in chain order, and reports the first at which
the paired receipts differ in any of: the digests of their inputs, the
instrument's "id", "version" or "config_digest", the "constants", the
recorded "children" in call order, or the digests of their outputs --
reported in that order, so that a changed input is not mistaken for a
changed instrument.  An absent "children" and "[]" are equal.
Timestamps, "run_id", "prev", and constants whose names begin
"onetrace." (Section 4.12) are excluded from the comparison.  Two
chains that differ nowhere but in those members ran the same pipeline
on the same bytes and produced the same bytes.

P A step whose children differ is not the same step, whatever its
outputs.  A first difference at a step called inside another is
reported at its outermost caller that also differs, found by walking up
the "parent" that both chains record for the step, and naming the first
differing child in call order.  Where the two chains record different
parents for the step, it is reported at itself, naming both parents.

P The close receipt and a check receipt (Sections 4.12 and 4.20) are
not steps.  They are set aside before the comparison, so the steps
compared are the same with and without them, and the first difference
is never one of them.  When one chain closed and the other did not, or
both closed with a different "onetrace.ended_by", the diff says so in
a line of its own, before any step difference.  A receipt that the
two-part rule does not identify is a step, whatever its name.

@@ 12.2
H 12.2.  Localize

P Given one chain, localization walks it in order and reports the first
receipt whose outcome class is not "ok"; whose declared output digest
is not the input digest the next receipt records for the same
artifact; or whose coverage records a gap or boundary.  The report
names the stage and which of the three conditions held.  The close
receipt and a check receipt are not steps, and the walk never reports
one.  A localization that reaches a declared boundary reports it and
asserts no cause across it (Section 8).  A boundary declared over steps
the producer did not observe, which every auto-recorded run declares
when it opens (Section 4.19), does not end the walk: localization
reports it and continues over the receipts recorded after it.  A reader
recognises that boundary as the one declared when the run opened, over
steps the producer did not observe, in a run whose manifest carries
"auto" (Section 4.19); any other boundary is reported as above.

@@ 12.3
H 12.3.  Reproduce

P Given one chain and the pipeline's code at the versions the receipts
pin, reproduction runs each stage whose instrument declares
"rederivable" as "true" from the artifacts its receipt records as
inputs, and reports per stage whether the output bytes' digest equals
the recorded output digest.  Stages declared not re-derivable are
reported as NOT RUN with the instrument's note as the reason.  A
reproduction that reaches an artifact it does not hold reports NOT
RUN for that stage.

P A counterfactual reproduction is the one that substitutes.  At one
named step it puts in place the output another run recorded there,
and at each step before it the run's own recorded output, each checked
against its digest before it is used.  Those steps are recorded with
the label of Section 4.14, never executed, and the new chain carries
"rerun" with "substituted" (Section 4.13).

P *The replay rule.*  A reproduction never executes, unless asked, a
step whose "effect_label" is "write" or "unknown", or whose "effects"
holds an entry.  It stops before the step, and the new chain's close
receipt says where and on what label (Section 4.12).  A reproduction
of the run's own steps MAY execute such steps when the person running
it asks it to, and then records "writes_allowed" "true"; a step with no
label it executes, as before minor 4, naming every such step before it
starts.  Every other kind of re-run also stops before a step with no
label, and has no way to be asked past a stop.  The producer's own
receipts are never executed and are never stopped on.

P Reproduction produces a new chain; it never rewrites the old one,
and a corrected run is a new version of the result, never an undo of
the previous one.

@@ 13.1
P A *conforming producer* emits receipts that contain the required
members with the value constraints of Section 4, and optional members
only as this document defines them or as Section 4.1 permits,
serialized as Section 5 requires, digested as Section 7 requires,
linked as Section 6 requires, with coverage derived rather than typed,
with an operator-declared emission policy, and with an anchor
declaration on every receipt.  It refuses to emit rather than emit a
receipt whose instrument it cannot name and pin.  Every receipt it
emits MUST verify, and it MUST NOT emit any of the ten rejection
vectors' defects.

@@ 14.add
P Minor 4 adds optional members only, marked in Sections 4.11 to 4.20
and Section 6, and reserves two stage names, "onetrace.close" and
"onetrace.check", and the constant prefix "onetrace.".  The
reservations bind producers from minor 4.  A reader identifies a
reserved receipt by the two-part rule of Section 4.12, so no record
written under an earlier minor reads differently.

@@ ref
V    [RFC6901]  Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed.,
V               "JavaScript Object Notation (JSON) Pointer", RFC 6901,
V               April 2013, <https://www.rfc-editor.org/info/rfc6901>.

@@ C
P Changes from -00.  This revision describes the members the format's
minor revisions added, through minor 4: nesting (Section 4.11), the
close receipt (Section 4.12), the re-run mark (Section 4.13), the
effect label (Section 4.14), expectations (Section 4.15), kept
configuration (Section 4.16), empty outputs (Section 4.17), return
holds (Section 4.18), auto-recorded steps (Section 4.19) and check runs
(Section 4.20); the manifest's optional members (Section 6); the
states of Section 11.3.3 and the checks of Section 11.3.7; Diff,
Localize and Reproduce, revised for nesting, the close receipt,
auto-recorded runs, substitution and the replay rule (Section 12);
Section 13's statement of the members a producer emits; and the
reserved names (Section 14).

P Not yet described: "coverage.optional_stages" and "refused.attempted",
which minor 3 added, and the optional "stage.instance" and the other
optional members the reference implementation writes.  Their text is
expected in the next revision.  The vectors of Appendix A are -00's,
unchanged; vectors for minor 4 are published with the reference
implementation's tests.
