@@ 4.12.  The Close Receipt
H 4.12.  The Close Receipt

P From minor 4, a producer ends every run with a close receipt, written
when the run closes, before its final manifest and before any
signature.  Its digest is the chain head, so a signature over the
chain head covers it.  It has:

B "stage.name" "onetrace.close", which the run declares as its last
stage, after its own stages;

B "instrument.id" "onetrace.close", "instrument.kind" "close", the
producer's own version, and "rederivable" "false";

B empty "inputs" and "outputs", and "outcome.class" "ok";

B in "assertions.constants", three members: "onetrace.closed", the
string "true"; "onetrace.steps", the number of receipts before it, as
a decimal string; and "onetrace.ended_by", exactly one of the five
forms below;

B no "effect_label" (Section 4.14), and, in a re-run, "rerun"
(Section 4.13), as every receipt of a re-run carries.

V      exit
V      unhandled exception: <class>
V      SIGTERM
V      re-run stopped before <node>: effect <value> (<basis>)
V      re-run stopped before <node>: effect not recorded

P "exit" says the producer's process exited normally, which a signal
handler of the pipeline's own can cause; it does not say that the
work ran to its end.  "SIGTERM" says the producer's own handler
received that signal.  The two "re-run stopped" forms are written by a
re-run stopped by the replay rule (Section 12.3), the second at a step
that has no effect label.  Such a re-run also declares a boundary
(Section 8) whose "kind" is "re-run stopped", whose "name" is the node
it stopped before, and whose "note" holds the same words as
"onetrace.ended_by".  A run whose producer stops recording at a
bound of its own declares a boundary at the step that reached it
(Section 8) and closes with "exit": a bound is not a sixth form.

P The stage name "onetrace.close" and the instrument kind "close" are
reserved from minor 4: a producer refuses a stage of that name that it
did not write itself.  Constants whose names begin "onetrace." are
reserved for the producer's own: a producer refuses a stage's constant
of that form, and every comparison (Section 12.1) leaves them out of a
step's settings, so a run that closed one way reads the same as a run
of the same pipeline that closed another way.

P "onetrace.close" is declared, so no receipt before it can read
"complete": only the close receipt can, and only when every declared
stage emitted and no boundary stands.  A verifier reads completeness
off the last receipt, as before, and adds no rule for it.

P *The two-part rule.*  A receipt is a close receipt only when its own
"format" is "stage-receipt/0.4" or later and its instrument is
"onetrace.close" of kind "close".  Before minor 4 the name was not
reserved, so a record written under an earlier minor can hold an
ordinary stage named "onetrace.close", and such a receipt is read as
the step it is.  The same rule, with "onetrace.check" and "check",
identifies a check receipt (Section 4.20).  Every reader applies it:
verifiers and the operations of Section 12 alike.

P A run with no close receipt was stopped without closing, or was
written before minor 4.  Its chain verifies to its last receipt.  A
verifier MUST NOT fail a run for lacking a close receipt unless it is
asked to require one; it SHOULD report the absence as NOT RUN, naming
the last receipt the record holds.  The report cannot tell a stopped
run from an earlier one, and says only that the record holds no close.

P A verifier that implements minor 4 MUST fail a close receipt that is
not the last receipt of its chain, a second close receipt, an
"onetrace.steps" that is not the number of receipts before it, and an
"onetrace.ended_by" outside its five forms.

@@ 4.13.  The Re-run Mark: rerun
H 4.13.  The Re-run Mark: rerun

P A run that re-runs a recorded run carries the OPTIONAL object
"rerun" in every receipt, the producer's own receipts included, and a
copy in its manifest (Section 6).  Its members are strings, except
"substituted":

D kind: Exactly one of "twin" (a re-run under another run's recorded
configuration), "counterfactual" (a re-run with one step's output put
in place from another run), "reproduce" (a re-run of the run's own
steps), and "check" (the run a check produced, Section 4.20).

D of_run: The "run_id" of the run re-run.

D of_chain_head: That run's chain head.

D config_of_run, config_of_chain_head: The "run_id" and chain head of
the run whose configuration was used.  REQUIRED for "twin"; present
for "check" when the check ran under that run's configuration; absent
otherwise.

D substituted: REQUIRED for "counterfactual", absent otherwise.  An
object whose members are all strings: "step" (the node id
substituted), "from_run" and "from_chain_head" (the run its output
came from), "from_receipt" (the digest of that run's receipt at the
step), and "output" and "output_digest" (the name and digest of the
output put in place).

D writes_allowed: REQUIRED for "reproduce", absent for every other
kind: "true" when the re-run was asked to execute steps recorded as
writing (Section 12.3), "false" otherwise.

D from_stage: REQUIRED for "check", absent for every other kind: the
node id the check started from.

P A producer marks only the run it opens at the top level of the
re-run's process: a run nested in another run's stage (Section 4.11)
is not the produced run, and carries no mark.

P The mark is in every receipt, under the chain, so a receipt read
alone shows it and a run cannot lose it without its chain being
re-linked.  The manifest's copy is read only where every receipt
carries the same "rerun": no digest covers the manifest's other
members, so the copy alone marks nothing.  A run whose receipts carry
no "rerun" is an original run as far as its record says.  A re-run is
never made a reference and is not counted as an original run.

P A verifier that implements minor 4 MUST fail a run whose receipts
disagree on "rerun", whose manifest copy disagrees with its receipts,
whose "kind" is outside the four, that lacks a member its kind
requires ("writes_allowed" for "reproduce" among them), or that
carries a member its kind does not allow (a "twin" carrying
"writes_allowed", or a "reproduce" carrying "from_stage", among them),
and a counterfactual whose substituted step's outputs do not hold
"substituted.output_digest".

@@ 4.14.  The Effect Label: effect_label
H 4.14.  The Effect Label: effect_label

P "effect_label" is an OPTIONAL object on a step's receipt that says
whether running the step again would act on the world.  Its members
are "value", exactly one of "read", "write" or "unknown", and "basis",
what the label rests on, exactly one of "declared on the stage",
"model call", "model call stored by the provider", "http method",
"not classified", or "substituted, not executed".  A step whose output
a re-run put in place without executing it (Section 12.3) carries
"read" with the basis "substituted, not executed".  A producer writes
the basis "declared on the stage" where the pipeline's code states the
stage's effect, as "read" or "write"; a stage whose code states none
carries no label.

P An absent label and the value "unknown" are different states
(Section 11.3.3).  Absent says no label was recorded, as on every step
written before minor 4; "unknown" says the producer could not classify
the call.  A reader's words for an absent label are "effect not
recorded".  The receipts a producer writes for itself, such as the
close receipt, carry no label: they are never executed as steps.

P A label is a claim about the kind of call, not about the external
system's behaviour.  A replay reads "unknown" as "write", and reads a
receipt whose "effects" (Section 4.10) holds any entry as "write",
whatever its label.

P A verifier that implements minor 4 MUST fail an "effect_label.value"
outside its three values, and a receipt labelled "read" whose
"effects" holds an entry.

@@ 4.15.  Expectations
H 4.15.  Expectations

P "expectations" is an OPTIONAL array on a step's receipt, one entry
for each expectation the stage declared about its own output.  Each
entry is an object with the members "name" (unique in the step),
"kind" (exactly one of "range", "unit", "relation", or "member"),
"target" (the output's name and a JSON Pointer [RFC6901] into it, as
"return.json#/value"), "declaration" (the kind's own members, every one
a string, such as "lo", "hi", "unit", "of", "op" and "within"),
"declaration_digest" (the digest of "declaration" in canonical form),
and "declared" ("with the run").  Every bound is a decimal string and
is compared as a decimal.

P Each kind's "declaration":

D range: "lo", "hi", or both, and an optional "unit", a label of the
bounds that the comparison does not read.  The value at "target" is at
least "lo" and at most "hi".

D unit: "unit".  The member at "target" equals it.

D relation: "op", exactly one of "difference", "sum" or "ratio"; "of",
two JSON Pointers into the target's own output, joined by one space;
and "within".  The value at "target" is within "within" of the first
value less the second, the two added, or the first divided by the
second.

D member: no members.  The output holds a value at "target".

P Where the stage gives no "name", a producer names the expectation
"<target> <kind>", the target as the stage gave it.

P An expectation written after the run is never added to its
receipts.  It lives in an expectations file of its own: a JSON object
in canonical form whose "format" is "onetrace-expectations/1", whose
"expectations" array holds entries with the members above, "declared"
set to "after the run", and a "step" member naming the node each
applies to, and whose "seal" is the digest (Section 5) of the object
with the members "seal" and "signature" left out: SHA-256 over that
object's canonical bytes, written as "sha256:" followed by 64
lowercase hexadecimal digits.  A
report names every row read from such a file as declared after the
run.  An expectation declared after the run says nothing about what
was expected when the run was made.

P An expectation that holds shows the declared rule held, not that the
output was right.

P A verifier that implements minor 4 reports one row for each entry:
PASS, FAIL naming the value and the rule, or NOT RUN.  An entry reads
NOT RUN where its output was not kept or is not readable as JSON.

P A decimal string, as a bound and as a value, is an optional "-",
then an integer part, "0" or a digit from "1" to "9" followed by any
digits, then optionally "." and one or more digits.  It has no "+", no
leading zero, no exponent and no other character: "-1.50" is one, and
"+1", "01", "1.", ".5" and "1e-7" are not.  A value is read as a
decimal from its JSON text, never through a binary floating-point
value, and exactly, at any length:

B a JSON string is a decimal where it holds a decimal string;

B a JSON number is the decimal its token writes, by the number grammar
of [RFC8259], an exponent included: the number 1e-7 is the decimal
0.0000001, while the string "1e-7" is not a decimal;

B "true", "false", "null", an object and an array are not decimals.

P Each kind then reads:

D range: NOT RUN where the target names no value or its value is not a
decimal; otherwise PASS where the value is within the bounds, FAIL
where it is not, compared exactly, with no rounding.

D unit: NOT RUN where the target names no value; otherwise PASS where
the value is the string "unit" gives, FAIL where it is anything else.
The value is compared as a string and never read as a decimal.

D relation: NOT RUN where the target, or either of the two values
"of" names, names no value or is not a decimal.  The difference, sum
or ratio of the two values is rounded to 100 significant digits,
rounding half to even, and so is the difference between the target's
value and it; that difference's magnitude is then compared with
"within" exactly.  A value of more than 100 significant digits is
still read exactly, and the rounding applies to what is computed from
it, so a relation over such values can FAIL where exact arithmetic
would hold.  A ratio whose second value is zero FAILs, as does a
result whose magnitude is 10 to the power 1000000 or more.

D member: FAIL where the target names no value, PASS where it names
one.

P An entry of an expectations file FAILs where the run records no
step of its "step", or where an earlier entry of the file has the same
"name" for the same "step": the first such entry is read as above, and
each later one FAILs.  A verifier MUST fail an entry whose
"declaration_digest" does not recompute, and an expectations file
whose "seal" does not recompute.

@@ 4.20.  Check Runs
H 4.20.  Check Runs

P A check run records one check a tool ran against two recorded runs.
It has one declared stage, "onetrace.check", whose instrument is
"onetrace.check" of kind "check", and the close receipt.  What the
check ran and what came back are ordinary constants and assertions of
that receipt: the constants "verb", "argv", "timeout_seconds",
"candidate", "claim" and "predicted", and, where the verb has them,
"baseline", "stage", "runner_digest" and "rerun_plan" (the last two
for "reproduce" only); the outputs "stdout.txt", the verb's own report
"report.json", and "stderr_tail.txt"; and the assertions "exit",
"result" and "came_back".  "result" is the verb's own word.
"came_back" is the check's outcome: "as predicted", "otherwise", or
"did not run: " followed by the reason, decided from "predicted" by a
fixed rule, never by reading the output's text.  A check of
"reproduce" records the run it produced as one entry of "inputs"
(Section 4.7) that names a run, not a file: its "name" is "run:"
followed by that run's "run_id", its "digest" that run's chain head,
its "bytes" "0", its "media_type" "application/json" and its
"trust_class" "operator-authored", and no artifact is kept for it.
Its constants are fixed in the checking process before the command
runs; the record does not show that order, as the receipt is written
after the command has ended.  The stage name and the instrument kind are reserved
from minor 4, and a check receipt is identified by the two-part rule of
Section 4.12.  The run a check produced by re-running a stage carries
"rerun" of kind "check" (Section 4.13).

P A check run's constants can hold local paths, and its outputs a
command's output.  The rule of Section 7 on secrets covers them as it
covers any record.

P *Informative: declaring the command.*  In the reference
implementation, a check of "reproduce" runs a command its user
declares in a configuration file, one table for each pipeline,
"[[runner]]", with the members "code", "command", "cwd" and
"timeout_seconds".  The table used for a run is the one whose "code"
file's digest equals every step's "instrument.manifest_digest".
"command" is an array of arguments, never handed to a shell, whose
only placeholders are "{stage}", the node id the check starts from,
and "{run}", the path of the run re-run.  The command runs in a
process group of its own, which is stopped when "timeout_seconds" is
reached.  The table is not part of the record: the check run records
its digest as "runner_digest".  Before the command starts, the replay
rule of Section 12.3 is read from the record, and a step from the
check's stage on that is not recorded "read" stops the check before
any process starts.

@@ 12.3.  Reproduce
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).  A check that re-runs a
run from one of its stages (Section 4.20) puts in place, in the same
way, the run's own recorded output at each step before that stage.

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; there, a step runs only
where every label that applies says "read": the label each record the
re-run reads gives the step (a twin reads two, the run it re-runs and
the run whose configuration it uses), and the label the pipeline's
code declares at the call.  The producer's own
receipts are never executed and are never stopped on.

P The replay rule reaches only the steps a record holds and the calls
a producer's hooks record.  Code that runs outside any stage or hook
is neither seen nor stopped, and a step labelled "read" whose code
writes is executed again: the rule reads labels, not what the code
does.

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.

@@ C
P Changes from -01.  This revision states "writes_allowed" as
REQUIRED for "reproduce", that a verifier fails a member a kind does
not allow, and that only the top-level run of a re-run is marked
(Section 4.13); the boundary a stopped re-run declares (Section
4.12); when a producer writes the basis "declared on the stage"
(Section 4.14); each expectation kind's declaration, the default name,
the expectations file and its seal, and how each kind reads (Section
4.15); a check run's outputs, its "run:" input, which constants each
verb gives and when they are fixed, with an informative note on
declaring the command (Section 4.20); and how a check puts earlier
steps in place, which labels a re-run reads, and what the replay rule
does not reach (Section 12.3).

P Implementation status.  The reference implementation writes the
close receipt; "effect_label" on a declared stage and on a step put in
place; "rerun" of all four kinds of Section 4.13, "reproduce", "check",
"twin" and "counterfactual", with "substituted" for a counterfactual;
the two "re-run stopped" forms; "config_kept" (Section 4.16);
expectations, with the run and in an expectations file; and check runs.
With its companion package onetrace-auto, it writes the auto-recorded
members of Section 4.19 and "effect_label" with the hook bases "model
call", "model call stored by the provider" and "http method".  The
comparison of a step's children in Section 12.1 is not yet built: its
comparisons do not read children.
