@@ 4.2.  format
H 4.2.  format

P The string "stage-receipt/0.MINOR", where MINOR is a decimal string.  This revision describes minor 5.  Every member added after minor 1 is OPTIONAL; Sections 4.7 and 4.11 to 4.26, and Sections 6, 8 and 9, 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.

@@ 4.7.  inputs and outputs
H 4.7.  inputs and outputs

P Each is an array, possibly empty, of artifact references.  An empty array is a statement that the stage consumed, or produced, nothing -- the declared-none state of Section 3 -- and is distinct from the member being absent, which is invalid.  The third golden receipt records a stage that produced no output and says so with an empty array and a "refused" outcome.

P An artifact reference is an object with the REQUIRED members:

D name: A string naming the artifact within the stage.

D media_type: The artifact's media type as a string.

D bytes: The artifact's size in bytes, as a decimal string.

D digest: The digest of the artifact's stored bytes, computed as Section 7 requires for the artifact's kind.

D trust_class: Exactly one of "operator-authored" (content the pipeline's operator or its code constructed), "model-generated" (content produced by a model), or "externally-sourced" (content that arrived from outside the pipeline, including user input and retrieved documents).  Any other value, or the member's absence, MUST be refused.

P The trust class does not make externally-sourced content safe.  It makes its origin visible to every downstream reader, human or model, which is the most a record format can promise.  A consumer that feeds artifact content to a model SHOULD carry the trust class with it.

P An output of one stage that is an input of the next SHOULD appear in both receipts with the same digest; the difference between the two, when there is one, is itself a finding (Section 12.2).

P *Outputs kept as a digest only.*  From minor 5, a run or a step MAY declare a size cap.  An output over the cap is kept only as its digest: its reference leaves "outputs" and goes in the OPTIONAL array "outputs_digest_only" of the same receipt, with the members "name", "digest", "bytes", "media_type" and "trust_class" as above, and "kept", the string "digest only: over the cap of <n> bytes", where <n> is the cap as a decimal.  No file is kept for it.  An output hashed in parts as it is written has the digest it would have if it were written whole.

P An output is in "outputs" or in "outputs_digest_only", never in both.  A reader that implements minor 4 reads a step with such an output as a step that wrote no such output (Section 14): it is not told the output was held back.  A reference and a comparison that implement minor 5 read both lists.  An expectation (Section 4.15) on such an output reads NOT RUN, "the output was not kept".

P A verifier that implements minor 5 reports each entry as PASS, "<name> <bytes>: digest only, over the cap", and MUST fail an entry out of form, a name that is also in "outputs", and a kept file found for it.

P A digest-only output cannot be checked against its bytes, and a reference that compares it compares digests.

@@ 4.11.  Nesting: parent and children
H 4.11.  Nesting and Cross-Service Links

P A record links steps and runs in three ways: a step called inside another step of the same run, a run opened inside a step of another run in the same process (Section 4.11.1), and a run started by a request from another service (Sections 4.11.2 and 4.11.3).  The last is apart from the first two: it is recorded in a receipt of each side, and the manifest holds only copies.

H 4.11.1.  Steps and Runs in One Process

P A stage may run inside another stage of the same run: a step the pipeline's code calls from within a step.  The receipt of such a step MAY carry "parent", a string: the node id of the step that called it.  The caller's receipt MAY carry "children", an array of strings: the node ids of the steps it called, in call order.  A node id is the stage's "name", followed by "#" and the stage's instance where the receipt's "stage" records one as "instance".  Both members are absent at the top level and on a step that called nothing.

P Nesting records structure, not data.  A child's return that the caller used in its own work is not recorded as one of the caller's inputs.  Section 4.18 records the one thing a producer can observe at the caller's end.

P A run opened inside a step of another run, in the same process, is a nested run.  Its manifest carries "parent_run" and "parent_stage", strings: the enclosing run's "run_id" and the node id of the step it was opened in.  The enclosing step records the nested run's chain head as one entry of its "inputs" whose "name" is "run:" followed by the nested run's "run_id" and whose "digest" is that chain head, in the form of Section 4.20.  A manifest with "parent_run" and "parent_stage" whose first receipt holds no "parent_link" is a nested run in this sense.

H 4.11.2.  The Cross-Service Link

P A run started by a request from another service records the link in its own first receipt, and the step that sent the request records the call in its receipt.  Two records under two chains then name each other, and the manifest's copies are read only where they equal the receipts.  The members are:

D parent_link: An OPTIONAL object on the callee's first receipt only.  Either it holds "run" (the caller's "run_id"), "stage" (the node id of the calling step), "head" (the caller's chain head when the request was sent), "origin" (the origin run id, as received, below) and, where the request carried a well-formed "traceparent" field, "traceparent"; or it holds "status" alone, "unreadable: " followed by the parse rule's words (Section 4.11.3), where the "onetrace-parent" field was present and did not parse.

D parent_run, parent_stage, origin_run: Members of the callee's manifest: copies of "parent_link.run", "parent_link.stage" and "parent_link.origin", read as a cross-service link only where the first receipt holds a "parent_link" that equals them (Section 6).

D calls: An OPTIONAL array on the calling step's receipt, one entry for each call, in call order.  Each entry holds "status", and "traceparent" where one was sent; an entry whose "status" is "head returned" also holds "child_run" (the callee's "run_id") and "child_head" (the callee's chain head as the response gave it), and no other entry holds either.

P "calls[].status" is exactly one of:

B "head returned": the response held a readable "onetrace-child" field;

B "called, head not returned": the request was sent, and the response held no such field;

B "unreadable: <reason>": the response's field did not parse, by the rules of Section 4.11.3;

B "not sent: <reason>": no field was sent, with the reason "longer than 1024 bytes" or "host not on ONETRACE_PROPAGATE" (Section 16).

P A call never guesses a head.  In the record, a head is a chain digest: "parent_link.head" and "calls[].child_head" are "sha256:" followed by the 64 hexadecimal digits the field carried, so they compare as strings with the digests of Section 6, or the one character "-" where the field carried "-".

P *The origin.*  The origin is the "run_id" of the run where the whole request started, copied unchanged to every hop.  A caller sends, as the origin: the "origin" of its own run's "parent_link", where it has one; otherwise, for a run nested in-process (Section 4.11.1), the origin of its in-process parent, by the same rule, up to the outermost run; otherwise its own "run_id".  A run with no parent of either kind is its own origin.  A run with no "parent_link" writes neither "parent_link.origin" nor "origin_run".  A producer refuses a parent given to it by hand without an origin, naming the field.

P *"calls" is not an input.*  A callee's run id and head differ on every call, so as an input they would make the calling step differ in every comparison.  An entry of "calls" is not one of the step's inputs, and the two fields of Section 4.11.3 are not recorded among a step's HTTP inputs, so they read as no difference.

P *What a callee takes from the field.*  A field is a claim from whoever sent the request.  Its values go only into "parent_link".  They name no file, no folder and no run id of the callee's.

P *When a head goes back.*  The callee sets "onetrace-child" when the response starts, and only on a request that carried "onetrace-parent", so a run id is not given to every caller.  A response's fields are sent before a streamed body ends and before the request's run closes, so the head a caller receives is usually an earlier receipt of the callee's chain, not its final head.  The check below reads it as such.

P *The check.*  A verifier that implements minor 5 reads a link only between folders it is given, and reports one row, "linked runs match", for each linked run it holds, read from the caller's side and from the callee's.  It reports PASS with one of:

V      <child run>: names <caller run> at <step>, and its head is the
V        head returned, origin <origin run>
V      <child run>: names <caller run> at <step>; the head returned is
V        its receipt <n> of <m>, origin <origin run>
V      <child run>: names <caller run> at <step>; it held no receipt
V        when the response started, origin <origin run>

P each one line, shown here on two.  The second is for a callee that wrote more receipts after the response started; the third is for a "child_head" of "-".  It MUST fail:

B "<child run> names <run> at <stage>, not <caller run> at <step>";

B "the head returned is not in <child run>'s chain";

B "the head <caller run> gave is not in its own chain", on a "parent_link.head" other than "-", where both folders are held;

B "<child run> names origin <x>, but <caller run>'s origin is <y>", where both folders are held: a caller's origin is its own "parent_link.origin", or, where it has none, the origin the rule above gives it, read for a nested caller as below;

B a "parent_link" that holds "run", "stage" and "head" and no "origin";

B a manifest's "origin_run" that differs from the first receipt's "parent_link.origin", and any other copy of Section 6 that differs from the receipt it copies;

B a "calls" entry out of form: a "status" outside the four, "child_run" or "child_head" on any status but "head returned", or either missing on it, or a head that is neither "sha256:" followed by 64 lowercase hexadecimal digits nor "-".

P It reports NOT RUN, with the reason "<child run>: its folder was not given"; "<step>: called, head not returned"; "<step>: unreadable: <reason>"; "<step>: not sent: <reason>"; and "no link recorded", only where a linked run was given.  A "parent_link" that holds "status" alone has no origin to check, and reads NOT RUN with its status.  A run with no link, checked with no linked run given, gains no row.

P *The origin of a nested caller.*  Where the caller is a run nested in-process and holds no "parent_link", a verifier reads its origin in this order: first, from the nested run's own manifest, where it carries the origin; otherwise, from the outer run's folder, where the check is given it, by the rule above; otherwise, the origin's check reads NOT RUN, with the reason "<child run>: <caller run>'s origin is its outer run's, and <outer run>'s folder was not given".  At minor 5 a nested run's manifest does not carry its origin ("origin_run" is written only with a "parent_link"), so a run of minor 5 is read by the second step or the third.

P What a link does not show:

B A cross-service link shows that two records agree on their parent and child.  It does not show the services ran as recorded, or that the network delivered the request unaltered.

B The parent link is a claim from the request's sender until the caller's record is held and agrees.

B A head returned is one receipt of the callee's chain at the response's start.  It is not the callee's final head, and it says nothing about what the callee did after.

B A service that does not record, or a proxy that strips a field, is a gap the record shows as a gap: "called, head not returned".

B A link and a recorded trace id are equality of recorded values.  They say nothing of how one service's work affected the other's.

B The origin is what the chain of callers sent.  Where every folder is held and agrees, the records agree on where the request started.  That does not show the origin run was not itself called by a service that does not record.

H 4.11.3.  The HTTP Fields

P The link travels in two HTTP fields, each sent as one field line, in ASCII.  Their names are written in lowercase here and are case-insensitive on the wire:

V      onetrace-parent: 1.<run>.<stage>.<head>.<origin>
V      onetrace-child:  1.<run>.<head>

D 1: The version, exactly the one byte "1".

D <run>: The run id's UTF-8, in base64url with no padding [RFC4648], Section 5.

D <stage>: The calling step's node id's UTF-8, encoded in the same way.

D <head>: The chain head at that moment: the 64 lowercase hexadecimal digits of its digest, without "sha256:"; or the one byte "-" where the run has no receipt yet.

D <origin>: The origin run id's UTF-8 (Section 4.11.2), encoded as <run> is.

P A run id can hold ":" and ".", and a node id almost any character, so both are sent encoded; "." is not in the base64url alphabet.  For a first hop from run "r-1", step "approve_payment#2", a head of 64 hexadecimal digits written here in part, the caller's own run being its origin:

V      onetrace-parent: 1.ci0x.YXBwcm92ZV9wYXltZW50IzI.abab...abab.ci0x

P and the callee's answer, for its run "r-2":

V      onetrace-child: 1.ci0y.cdcd...cdcd

P In ABNF [RFC5234]:

V      onetrace-parent = "1" "." b64u "." b64u "." head "." b64u
V      onetrace-child  = "1" "." b64u "." head
V      b64u            = 1*( ALPHA / DIGIT / "-" / "_" )
V      head            = 64( DIGIT / %x61-66 ) / "-"

P A field value is at most 1024 bytes.  A producer leaves out a field it would make longer, and records "not sent: longer than 1024 bytes" on the step's call.  A reader checks the length before it decodes anything.

P A reader applies the following rules in order.  Each failure gives "parent_link.status", or on a response "calls[].status", "unreadable: " followed by the rule's words.  A parse failure never raises and never fails a request.

N 1. More than one field line, or a value with a comma: "more than one value".

N 2. Longer than 1024 bytes after optional whitespace is trimmed: "longer than 1024 bytes".

N 3. What comes before the first "." is not "1": "version " followed by its first 8 bytes, escaped.  A later version is not read, whatever its form, and is not an error of the record.

N 4. Not exactly five parts split on "." (three for "onetrace-child"): "not its form".

N 5. A part that is not canonical base64url (padded, in the standard alphabet, or with non-zero trailing bits), found by decoding, re-encoding and comparing: "not canonical base64url".

N 6. A decoded part that is empty, is not UTF-8, or holds a control character: "not text".

N 7. A <head> in neither form: "not a head".

@@ 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 can also follow a signal handler of the pipeline's own; 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 A run stopped by an expectation (Section 4.15) closes with the second form, its text fixed as one line, shown here on two:

V      unhandled exception: ExpectationStopped at <node>: expect
V        <name>: <detail>

P where <node> is the failing step, <name> the expectation's name, and <detail> the value and the rule, as "900 is outside [0, 500] kPa".  Control characters in it are escaped, and the whole is at most 1024 characters, cut at the end of <detail> with U+2026 HORIZONTAL ELLIPSIS.  On a run that keeps no outputs the value is withheld (Section 4.15).  "onetrace.ended_by" still has five forms.

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), and, with "stage-receipt/0.5" or later and the kind "close-recovered", a recovered close receipt (below).  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.

P *The recovered close receipt.*  From minor 5, where a run's process ended without closing and a later process recovers the run from its journal (Section 9), the later process writes a recovered close receipt, chained after the last receipt the journal confirms.  It has:

B "stage.name" "onetrace.close", and "stage.index" the next after the gaps recovery records;

B "instrument.id" "onetrace.close", "instrument.kind" "close-recovered", "version" the recovering process's producer version, "config_digest" the digest of the empty object, as a close's is, "manifest_digest" the base receipt's (Section 9), "rederivable" "false", and "rederivable_note" "written by a later process that found the journal";

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

B in "assertions.constants", exactly three members: "onetrace.recovered", the string "true"; "onetrace.last_confirmed", the node id of the last confirmed receipt, or "none"; and "onetrace.steps", the number of receipts in the chain before it, gaps not counted;

B "time.started" and "time.ended" both from the recovering process's clock;

B "coverage" with the base receipt's "declared_stages", the last confirmed receipt's "emitting_stages" with "onetrace.close" added (or "onetrace.close" alone where none is confirmed), the base receipt's "boundaries" with the boundary of kind "recovered" added (Section 8), and "completeness" "incomplete";

B "emission" with the base receipt's "gaps" and the gaps recovery records added, and the base receipt's "policy" and "queue";

B "format", "run_id" and "anchor" the base receipt's.

P It never carries "onetrace.closed" or "onetrace.ended_by": "onetrace.recovered" says how the record ends, and "onetrace.ended_by" keeps its five forms.  A reader that implements only minor 4 reads the receipt as an ordinary step, by the two-part rule, and the run as one that holds no close; no reader reads a recovered run as closed by its own process.

P A verifier that implements minor 5 reports a recovered close receipt as PASS, "recovered: last confirmed <node>", and never as "closed".  It MUST fail a "close-recovered" receipt that is not the last receipt of its chain, one carrying "onetrace.closed" or "onetrace.ended_by", an "onetrace.steps" other than the number of receipts before it, and a "completeness" of "complete" on it.  A verifier asked to require a close receipt MUST fail a recovered run, "not closed by its own process: recovered".

P A recovered close receipt shows that a later process found the journal.  It was not written by the run.  It does not show how the run ended, or what happened after the last confirmed step: "onetrace.recovered" is the record's whole statement.

@@ 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".

P *What a re-run took: rerun_from.*  From minor 5, a re-run that took parts of a run's configuration, or its code from another run (Section 12.3), carries the OPTIONAL object "rerun_from" beside "rerun", in every receipt of the re-run, equal in each, and a copy in its manifest.  No member is added inside "rerun", and "rerun.kind" stays one of the four.  Its members are:

D config_parts: The part names taken from the run whose configuration was used, sorted: those named, or, where all parts but some were asked for, the parts that resulted.

D code_of_run, code_of_chain_head: The "run_id" and chain head of the run whose code was used.

D code_commit: The commit run, in hexadecimal.

D environment: "today", always.

D lock_differs: "true", with "lock_name" and "lock_digest", where the dependency lock that run recorded (Section 4.26) differs from the one here; "false"; or "not observed".

D config_of_run, config_of_chain_head: As in "rerun", on a kind that may not hold them there.

P Which kind and which members a combination gives:

B a run's whole configuration: "twin", "rerun" as before, and no "rerun_from";

B parts of a run's configuration: "twin", with "config_parts";

B another run's code alone: "reproduce", with "writes_allowed" in "rerun", and "code_of_run", "code_of_chain_head", "code_commit", "environment" and "lock_differs";

B parts of a configuration and another run's code: "twin", with "config_parts" and the code members;

B a substitution and another run's code: "counterfactual", with the code members;

B a substitution and a configuration, whole or in parts: "counterfactual", with "config_of_run", "config_of_chain_head" and "config_parts", and the code members where code was also taken.

P Minor 4 refused a substitution with a configuration, as two kinds of re-run; minor 5 records the pair as "counterfactual" with "rerun_from" holding the configuration.

P A verifier that implements minor 5 reports "rerun_from" as PASS, "<parts> from <run>; code from <run> at <commit>, environment today", and MUST fail receipts that disagree on "rerun_from", a manifest copy that differs from them, a "rerun_from" on a run with no "rerun", "config_parts" with no "config_of_run" in "rerun" or in "rerun_from", a "code_commit" that is not hexadecimal, and an "environment" other than "today".

@@ 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.  From minor 5, it reads a receipt whose "state_writes" (Section 4.21) holds any entry as "write" in the same way.

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.

P *Vector stores.*  Minor 5 adds no basis: "effect_label" keeps its six.  A vector query is labelled "read" with the basis "not classified", and a vector upsert or delete "write" with "not classified", each with its own basis beside it in "step.effect_basis" (Section 4.22): "vector query" or "vector change".  A reader that implements minor 5 reads "step.effect_basis" first.  A reader that implements minor 4 reads the label as "read" or "write", "not classified", which stays true of the step: a change never reads "read".  The bases a framework-recorded step carries are those of Section 4.19.

P A verifier that implements minor 5 MUST fail a receipt labelled "read" whose "state_writes" holds an entry, with the words "labelled read and records a state write"; and an "effect_basis" with no "effect_label", or beside a basis other than "not classified", "vector query" beside a value other than "read", and "vector change" beside a value other than "write".

@@ 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.

P *Checked during the run.*  From minor 5, a run MAY ask for its expectations to be checked as each step returns.  There are three modes: "off", "record" and "stop".  A mode is set on the run, on a stage, or on one expectation, and the narrowest wins.  "off" is the default, and it writes nothing: a run that does not ask writes the same receipts as a run of minor 4.

P An expectation checked in "record" or "stop" carries the OPTIONAL object "checked", beside "declaration", so "declaration_digest" does not change and a mode is not a changed expectation.  Its members are strings:

D when: "during the run", the one value.

D mode: "record" or "stop".

D outcome: "PASS", "FAIL" or "NOT-RUN".

D detail: The reading's own words, as a verifier gives them; a value appears in them only where the run keeps outputs (below).

D reader: The version of the code that read it, as "onetrace-verify <version>".

P The check acts at a step's return only.  The stage's body returns and its outputs are staged and hashed.  For each expectation not "off", the producer runs the reading of this section over the bytes it is about to record, read as a verifier reads them, not over the value the code returned: a binary floating-point value and the JSON number written for it can differ in their last digits.  It writes the receipt with each result in "checked".  If an expectation in "stop" read FAIL, the producer raises a stop before the step returns to its caller, and so before the next stage can be entered.

P The stop holds for the rest of the run: every later stage call raises it again before its body and writes no receipt, as it never started.  The stage that called the failing stage gets a receipt with "outcome.class" "error" and "status" "ExpectationStopped", and the run closes with the form of Section 4.12.  Where several calls run at once, those already running finish and each writes its receipt, no new stage body starts, and the stop names the first failing step in the order the calls were given.  A step recorded by a hook (Section 4.19) declares no expectations and is never stopped by one.

P The check never fails the step on its own fault.  An output it cannot read, or a value that is not a decimal, reads "NOT-RUN" with its reason, as the verifier's reading gives it, and a "stop" expectation does not stop on "NOT-RUN".  Any other fault in the check writes "NOT-RUN", "the check could not run: <class>", and the step returns as usual.

P *A batch threshold.*  An expectation over many documents of one output MAY carry a threshold, recorded not in "expectations" but in the OPTIONAL array "expectations_batch": its entries are as those of "expectations", with "batch" beside "declaration", an object with "over" (a JSON Pointer with a wildcard, as "/docs/*") and "more_than" (a decimal string).  Its "checked" also holds "failed" and "of", decimal counts of the documents that failed and of those read.  "outcome" is "FAIL" where "failed" is more than "more_than", and "PASS" otherwise.  Each document's result is not written, only the count.  A threshold is an option the pipeline asks for, never a default.

P *A value withheld.*  On a run whose "outputs_kept" is "none" (Section 6), a value in "checked.detail" or in "onetrace.ended_by" would be the one place the run's data appears in plain.  On such a run both read "<the value is not kept> is outside <rule>", and the outcome stands.

P A verifier that implements minor 5 re-reads every expectation as before, and adds:

D <step>.<name> as checked during the run: PASS, "the result written during the run equals this reading: <outcome>"; FAIL, "written <outcome> by <reader>, read <outcome> by <this reader>", naming the expectation and both readers; NOT RUN, "the output was not kept; written <outcome>, not re-read".  What is compared is "outcome", not "detail", so a change of words between two verifier versions is not a difference.

D <step>.<name> checked: FAIL where "checked" is out of form: a "when", "mode" or "outcome" outside its values.

D <step>.<name> batch: PASS, "<failed> of <of> failed, more than <more_than> stops"; FAIL, "written <failed> of <of> by <reader>, read <n> of <m> by <this reader>", an "outcome" other than the count gives, a "failed", "of" or "more_than" that is not a decimal, a "failed" more than "of", an "over" that names no array, and, in "record", more than "more_than" failed: "<n> of <m> failed, more than <more_than>, in record"; NOT RUN, "the output was not kept; written <failed> of <of>, not re-read".

D the run's stop: PASS, "stopped at <node>: expect <name>"; FAIL where "onetrace.ended_by" names a step or expectation with no "checked" FAIL in "stop", in "expectations" or "expectations_batch"; where a "stop" FAIL is held and a stage other than the close, and other than a step recorded by a hook, started after that step ended; and where "onetrace.ended_by" is in the stop's form with no such expectation.

P A run with no "checked" gains no row.  A "FAIL" in "record" fails the run like any other FAIL.

P What a check during the run does not show:

B A run that was not stopped shows that no "stop" expectation failed at a step's return.  It does not show the outputs were right.

B A stop guards the steps after it, never the step that failed.  What the failing step did has already happened.

B It is not a policy check before an action.  A decision recorded at the step (Section 4.25) is that.

B "checked" says what the reading gave over the bytes recorded at that moment, under "reader"'s version.

B Code the pipeline runs after catching the stop, or outside any stage, is not stopped.

B On a run that keeps no outputs, the result written during the run cannot be re-read.  It is the producer's word, under the chain.

B A batch's count is written, not which documents failed.  A batch that did not stop shows no more than "more_than" failed.

@@ 4.19.  Auto-Recorded Steps
H 4.19.  Auto-Recorded Steps

P A producer MAY record steps it observed through a library's calls, in place of steps the pipeline declared in its code.  Such a step's receipt carries the OPTIONAL object "auto", whose members are "declared", always "false"; "call", the library's public method name; "library", the distribution's name; and, for an HTTP call, "target", an object with "host", "method", "query_names" and exactly one of "path_digest" (the digest of the request path, the default) or "path"; for a model call, "target", an object with "host" alone, the host the model client's request went to; and, on a step recorded from a thread that did not carry the run's context, "context", the string "thread without the run's context".  A receipt without "auto" is a declared step, as every receipt written before minor 4 is.

P A run the producer opens itself to hold such steps is an auto-recorded run.  Its manifest carries the OPTIONAL object "auto": "boundary" ("process" or "request"), "key" (what keyed a run per request), and "hooks", an array of objects with "library", "status" and "version", where "version" is present only when the entry's "status" is "hooked".  Every auto-recorded run declares a boundary when it opens, over the steps outside the libraries observed, of "kind" "not observed", its "note" naming those steps, so its coverage never reads "complete" (Section 8).

P A run the pipeline declared in its code MAY also hold such steps, at its top level or as children of its own steps.  It is not an auto-recorded run: its manifest carries no "auto", it declares no boundary for them, and it keeps its own declared coverage, so its close receipt can read "complete".  It gains each such step's stage name in "declared_stages" (Section 8) the first time a step of that stage is recorded, before its last declared stage; no name is removed or reordered.  Each receipt's "declared_stages" is the list as known when the receipt was written, so an earlier receipt may list fewer names than a later one, and the close receipt's list is the run's whole list.

P A step recorded from an HTTP call has two outputs: "status", the canonical JSON object {"status": "<code>"}, and "response", the response body's bytes.  A call that followed redirects is one step, whose "status" is the final response's and whose "response" is the final body; a producer MAY add the number of hops to "status", as {"redirects": "<n>", "status": "<code>"}.  A streamed response is hashed as it passes and has its "response" output where the producer observed the body; one it did not observe has "status" alone.  A status that differs is thus an output that differs, whatever the body.

P What an auto-recorded step did not observe or did not write is said in constants of the producer's own (Section 4.12), which every comparison leaves out of a step's settings: "onetrace.http.body", "not observed: streamed", where the response was streamed, not observed, and there is no "response" output; "onetrace.http.request", "not observed: streamed", where the request body was streamed and there is no "request" input, or "not observed: the text cannot be encoded as it will be sent", where the body's text cannot be encoded as the library will send it; and "onetrace.model_call", "not written: the hook did not see the client's request", where a model step wrote no model-call record.  A record of minor 4 can also hold "not written: embeddings have no record format in this release"; from minor 5 an embeddings call writes an embedding-call record.

P An auto-recorded step always carries "effect_label" (Section 4.14).  A verifier that implements minor 4 MUST fail an "auto.declared" other than "false", an "auto.context" other than "thread without the run's context", and a receipt with "auto" and no "effect_label"; it checks that the label's basis is one the producer documents for that library.  It checks that an auto-recorded run holding a receipt with "auto" has the manifest's "auto" and the boundary, and it knows an auto-recorded run by either: the manifest's "auto", or that boundary in the manifest or in any receipt's coverage.  It makes no claim about an auto-recorded run rewritten without both and re-linked, which reads as a run declared in code, nor about a run declared in code that declares that boundary itself, which reads as an auto-recorded run.  Within one chain, a later receipt's "declared_stages" MAY hold more names than an earlier receipt's only where each added name is the stage of a receipt with "auto" in the chain, and every earlier name keeps its place; a verifier MUST fail a removal, a reorder, or any other added name.

P *Libraries added in minor 5.*  A step MAY be recorded from four more libraries: "anthropic", a model call whose "target" holds "host" alone; "httpx2", an HTTP call as above; and "langchain" and "langgraph", whose steps the producer records from the frameworks' own callbacks, with no "target".  A reader that implements minor 4 and does not document a library's bases reads that step's label check as NOT RUN, "<library>: no documented bases" (Section 14).

P *Framework steps.*  An auto-recorded run declares a fixed list of stage names, so two runs compare cleanly, and a node's own name is an instance, not a stage name.  "<n>" counts from 1 within the name in the run:

D langgraph.node: "auto.call" "node"; instance "<node name>.<n>", as the node id "langgraph.node#agent.1".  A graph node.

D langchain.chat_model: "auto.call" "chat_model"; instance "<n>", as "langchain.chat_model#2".  A chat model call, with its model-call record, of kind "model call".

D langchain.llm: "auto.call" "llm"; instance "<n>".  A completion model call, with its model-call record, of kind "model call".

D langchain.tool: "auto.call" "tool"; instance "<tool name>.<n>", as "langchain.tool#add.1".  A tool call, with "tool_call" (Section 4.22), of kind "tool call".

D langchain.retriever: "auto.call" "retriever"; instance "<n>".  A retrieval, of kind "retrieval".

P A call that is not a graph node and not a subgraph opens no step: its calls nest under the enclosing step.  A call that ends in error closes its step with "outcome.class" "error".  A subgraph is a nested run (Section 4.11.1), told apart by the depth of its namespace, and its head is an input of the enclosing node.  Nodes that run in one superstep are chained in the order they finished, so two runs of the same work may differ in that order.  A graph invocation at the top level of a process is one run.

P The labels the producer documents for these libraries are: for "langchain", "read" with "model call" on a chat model or completion model step, and "read" with "not classified" on a retriever step, beside "step.effect_basis" "vector query" (Section 4.14); for "langchain" and "langgraph", "read" or "write" with "declared on the stage" on a tool or node that declares its effect in the framework's own metadata, and "unknown" with "not classified" on a tool or node that declares nothing.  A node's "step.kind" is the one it declares, or "other".

P *A call is never recorded twice.*  While a framework model step is open, a lower hook (an HTTP or model client hook) records no step for the call it sees, and adds to the framework step the OPTIONAL object "step.lower_hook" (Section 4.22): "library", the lower hook's library, and "note", "already recorded by the framework hook".  A call a node or a tool makes outside a framework model step is recorded by the lower hook as minor 4 records it, nested under the node or the tool.

P A framework step whose callback could not finish recording carries "framework_error", the string "not recorded: " followed by what was not recorded; the pipeline's own call goes on.  A graph run's first receipt MAY carry "thread_id", the framework's thread id as its metadata gives it, and the manifest a copy (Section 6).  The manifest's "auto.hooks" gains entries for "langchain-core" and "langgraph", each with "library", "status" and "version" as above.  Checkpoints are recorded as state (Section 4.21), of "store_kind" "langgraph".

P A verifier that implements minor 5 checks a framework step's label against the table above, and MUST fail a label outside its library's rows; a "step.lower_hook" with a member other than its two, a "note" other than its one value, or on a step whose kind is not "model call"; a "framework_error" not of its form; a framework step whose "parent" names a step that ended before it began, where every framework step's parent is an open node or the run; two steps under one node with the same request digest, one carrying "step.lower_hook" naming a library and the other an auto-recorded step of that library; and a manifest "thread_id" that differs from the first receipt's.

P What a framework-recorded run does not show:

B It is complete only for the events the framework's callbacks deliver, at the versions in "auto.hooks".

B Code a node runs outside the framework's calls is seen only through the lower hooks, or a declared stage.

B A model step's request is what the callback delivered, not the bytes sent.  "step.lower_hook" shows a lower hook saw a call during that step.  It does not compare the two.

B A node's agent identity (Section 4.22) is the graph's own name for it.

B A subgraph told apart by namespace depth reads what the framework reports there.

B An open coverage boundary stands, as on every auto-recorded run.

@@ 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.

H 4.21.  State: state_reads and state_writes

P A step MAY record the store data it touched as state, apart from its inputs and outputs: what it read or wrote, and at what version.  "state_reads" and "state_writes" are OPTIONAL arrays on a step's receipt, one entry for each read and for each write.  Absent says state was not recorded; "[]" says it was recorded and nothing was read, or nothing written.  An entry is an object with these members, all strings but "as_of":

D store: The store's name, as the pipeline declares it, as "orders_db.orders"; no control character.

D store_kind: Exactly one of the kinds listed below.

D key_digest: "sha256:" over the key's bytes; the default.

D key: The key in plain, in place of "key_digest", only where the pipeline asks for it (Section 17).  Exactly one of "key" and "key_digest" is present.

D version: The store's own revision, as a string as the store gives it, or the literal "not observed".  A write's version is the revision the store gave that write, where it gives one.

D version_kind: What "version" is, as listed below, or "declared"; absent with "not observed".

D digest: "sha256:" over the canonical form "digest_form" names.

D digest_form: One of the forms below.

D digest_status: "not observed: " followed by the reason, as for a streamed body the step did not read whole.

D found: "false" on a read that found nothing; absent otherwise.

D as_of: An object of "newest" and "oldest": the "last modified" times among the results, as the store gives them, never from the producer's clock; absent where the store gives none.

D ids_digest: On a vector query only: "sha256:" over the ids alone, in order.

D kept: "true" where the value's bytes are kept (below); absent otherwise.

P Exactly one of "digest", "digest_status" and "found" is present.

P *Versions.*  Where a store has no revision, "version" is "not observed".  A producer never makes one up: no counter, no hash of what was read, no clock.  Lineage then rests on the digest alone.  A pipeline that keeps its own revision gives it with "version_kind" "declared", and the record then says whose it is.  The kinds, and what "version_kind" each gives on a read and on a write:

B "langgraph" (a framework checkpointer): "checkpoint"; at open, the thread's latest.

B "postgres" (Postgres, pgvector): "lsn", on a read the value of pg_current_wal_lsn() at the read, on a write the commit's; at open, the LSN at open.

B "mysql": "gtid-set" on a read, "gtid" on a write; at open, the executed set.

B "sqlite": "data-version", within one connection only; at open, not observed.

B "iceberg": "snapshot"; at open, the current snapshot id.

B "delta": "table-version"; at open, the current version.

B "object" (S3, GCS, Azure Blob): "version-id" or "generation", else "etag"; at open, not observed.

B "search" (Elasticsearch, OpenSearch): "seq-no", written "<_primary_term>/<_seq_no>", for a document; for a search, not observed; at open, not observed.

B "document" (MongoDB): "cluster-time"; at open, not observed.

B "vector" (Pinecone, Chroma, most hosted indexes): not observed, on a read, a write and at open.

B "kv" (Redis, memcached): not observed, on a read, a write and at open.

B "git" (a git-backed store): "commit"; at open, the head commit.

B "other": as the pipeline gives it.

P *Digests.*  "JCS" below is the canonical form of [RFC8785] with every scalar a string, as in a receipt: a driver's integer or decimal is its decimal string as the driver renders it, a boolean is "true" or "false", a null is JSON null, bytes are {"b64": <base64url>}, a time is the driver's own string, and a binary floating-point value is written in the number form of [RFC8785], then as a string.  The forms:

D sql-rows/1: A SQL table read or query: JCS({"columns": [the names, sorted], "rows": [[the cells in that order], ...]}), the rows sorted by each row's JCS bytes, so a row order the query never fixed does not read as a difference.

D sql-rows-ordered/1: The same, with the rows in result order, where the pipeline says order matters.

D bytes/1: An object, a file, or a key-value value given as bytes: the bytes themselves.

D json/1: A key-value value, or any value the pipeline declares, that is not bytes: JCS(value).

D docs/1: A document store: JCS([{"id": <id>, "doc": <the document>}, ...]) in result order, with Extended JSON for BSON types.  A search's scores are not hashed.

D vector-query/1: A vector query: JCS([{"id": <id>, "score": <score>}, ...]), in returned order; "ids_digest" beside it is over JCS([ids]).

D vector-change/1: An upsert or delete: JCS([{"id": <id>, "vector": <sha256 of the raw little-endian vector, or null on a delete>, "metadata": <sha256 of JCS(metadata), or null>}, ...]), sorted by id.

D checkpoint/1: A framework checkpoint: no digest by default, and "digest_status" "not observed: a checkpoint's values are the framework's own"; the checkpoint id is the version, and lineage rests on it.

P *Keys.*  A SQL query's key is JCS({"query": <text>, "params": [<cells>]}), so two queries with other parameters have other keys.  An object's key is its path.  A key-value entry's is its key, and a namespace's its name.  A vector query's key is JCS({"index": <name>, "filter": <filter or null>, "top_k": <k>, "query_digest": <sha256 of the query vector or text>}).

P *The cap.*  A step keeps its first 1000 entries on each side, and counts the rest in "state_cut", a decimal string.  Absent, none was left out.  A step with a cut never reads as having told the whole of its state.

P *A kept value* is the exact bytes "digest" is over, in the file "state/<receipt stem>/reads/<n>" or "state/<receipt stem>/writes/<n>", where <n> is the entry's place in its array from 1.  It sits beside "artifacts/", as a kept configuration does (Section 4.16), so it never reads as a step's output.  It is kept only where the pipeline asks, never on a run whose "outputs_kept" is "none", and, past the size cap of Section 4.7, with no file and no "kept".

P *State at open.*  A run's first receipt MAY carry "state_at_open", an array of objects with "store", "version" and "version_kind": the revision each store reported when the run opened.  It is written only from a store that gives a cheap whole-store revision; a producer never reads a store whole to compute one.  The manifest holds a copy (Section 6).

P A step holding an entry in "state_writes" is a write to every re-run, whatever its label (Section 4.14).

P A verifier that implements minor 5 reports a step's state entries as PASS, "N read, M written, each in form", and MUST fail: a member outside the table; a "store_kind" outside the list; a digest out of form; both "key" and "key_digest", or neither; not exactly one of "digest", "digest_status" and "found"; "digest" with no "digest_form", or a "digest_form" outside the list; no "version"; a "version" other than "not observed" with no "version_kind"; a "version_kind" beside "not observed"; and a "found" other than "false".  It reads each kept value as PASS, "<store>: the kept value recomputes", or NOT RUN, "the value was not kept", and MUST fail a kept file whose SHA-256 is not "digest", "kept" with no file, "kept" on an entry with no "digest", and a file under "state/" for an entry with no "kept".  It reads "state at open" as PASS, "N stores", and MUST fail a manifest copy that differs from the first receipt's, and a "state_at_open" on any receipt but the first.  A reader cannot recompute a digest from a store it does not hold, so these checks read form, and bytes only where kept.

P What state does not show:

B Lineage is equality of recorded digests or versions.  It says run B read what run A wrote.  It does not say that data made B behave as it did.

B A version is the store's own report.  A producer does not check that a store's versions are consistent, and reports a pair with the same version and different digests as it finds it.

B A Postgres read's version is the LSN at the read, not a snapshot the read is proved to have used.

B A store reached without a hook or a declaration is not seen.

B Source age is the store's own "last modified", not when the data was true.

B A sorted "sql-rows/1" digest says which rows came back, not in what order.

B "state_at_open" is a revision the store reported at open, not a statement of the store's content.

H 4.22.  Step Kind, Tool Calls and Agents

P "step" is an OPTIONAL object on a step's receipt with a closed list of members: "kind" (below), "effect_basis" (Section 4.14) and "lower_hook" (Section 4.19).

D step.kind: Exactly one of "model call", "tool call", "retrieval", "decision", "state read", "state write", "transform" and "other".  Absent says the kind was not recorded, never "other".  The list is fixed: a new kind needs a new minor revision.  "step.kind" is apart from "instrument.kind" (Section 4.6), which stays free-form.

P *Informative: who sets the kind.*  A declared stage carries the kind its code declares, or none; a producer refuses a value outside the list where the stage is declared, naming it.  A model client's hook writes "model call", an embeddings call included.  An HTTP client's hook writes "other": it sees a method and a host, not what the call is for.  The framework hook writes the kinds of Section 4.19.  A store's hook, or a state declaration, writes "state read", "state write", or "retrieval" for a vector query.  The producer's own receipts carry none.

P *The tool-call record.*  "tool_call" is an OPTIONAL object, only on a step of kind "tool call", of strings:

D name: The tool's name, as the code or the framework gives it.

D arguments_digest: "sha256:" over the arguments' canonical JSON; absent, with "arguments_status", where they cannot be canonicalized.

D arguments_status: "not observed: " followed by the reason; absent where the digest is present.

D result_digest: "sha256:" over the result's canonical JSON; absent, with "result_status", on a tool that raised or a result that cannot be canonicalized.

D result_status: As "arguments_status", for the result.

D call_id: The id the framework or the model gave this call, where there is one.

D requested_by: An object of "step", the node id of the model step that asked for the call, and "call_id"; absent for a tool no model asked for.

P Arguments and results follow the run's keep rules: a digest always, the bytes only where the run keeps them, the arguments as "arguments.json" with the step's kept inputs and the result as the step's output "result.json".  The model-call record holds no tool request, so a reader finds the request in the model step's kept output "response", at:

B stage "openai.chat.completions.create": "choices[*].message.tool_calls[*].id";

B stage "openai.responses.create": "output[*].call_id", where "type" is "function_call";

B library "anthropic": "content[*].id", where "type" is "tool_use";

B stage "langchain.chat_model": "generations[*][*].message.tool_calls[*].id";

B any other step, a streamed "response" among them: no path is named.

P *Agents.*  "agent" is an OPTIONAL object on a step's receipt naming the agent that ran it: "name", required in the object, what the code declares, or a graph node's name; "role", free text; and "runs_on", an object of "kind" ("model" or "framework"), "name" and, where known, "version".  "run_agent" is an OPTIONAL object, the run's agent, with the same members, equal in every receipt of the run, the producer's own receipts included; the manifest holds a copy as "agent" (Section 6).  A step's "agent" is absent where it equals the run's, and a reader then takes the run's.

P A verifier that implements minor 5 reports, only on a record that holds the member:

D step: PASS, "effect basis <basis>", where it holds one; FAIL on a member outside "kind", "effect_basis" and "lower_hook", and an "effect_basis" other than its two, and as Section 4.14 gives.

D step kind: no PASS line, the kind counted in the summary; FAIL, "'<value>' is outside the eight".

D step kind against its record: FAIL on kind "state write" with an "effect_label" of "read", "labelled read and of kind state write", and on "tool_call" on a step of another kind, "a tool-call record on a step of kind '<kind>'"; NOT RUN on kind "tool call" with no "tool_call", "no tool-call record".

D tool_call: PASS, "tool <name>: arguments and result digests in form"; FAIL on a member outside the list, a digest not "sha256:" and 64 hexadecimal digits, and both a digest and its status, or neither.

D tool_call requested_by: PASS, "<step>'s kept output holds a request with <call_id>"; FAIL where "<step> is not an earlier step of this run", where it is not of kind "model call", and "<step>'s kept output holds no request with <call_id>"; NOT RUN, "the model step's output was not kept" and "no path is named for <step>'s output".

D agent: PASS, "agent <name>"; FAIL on no "name", a member outside the list, and a "runs_on.kind" outside the two.

D run agent: PASS, "run agent <name>"; FAIL where the receipts disagree on "run_agent", where the manifest's copy disagrees with them, and on a manifest "agent" with none in the receipts.

P A comparison names the agent with the step.  A changed kind or agent is noted, and changes no verdict: neither is among a step's settings.

P What these do not show:

B A step's kind and an agent's identity are what the code declares, or what a hook read of the call.  They are bound to the record by the chain.  They are not a proof of which model or tool answered.

B "tool_call.requested_by" shows the record names a request with that id.  It does not show the tool ran with what the model asked for, unless the arguments are compared by a reader that holds both.

B An absent kind says nothing about the step.

H 4.23.  Messages

P A step MAY record the messages it sent to another agent, a node, or a state channel, and the messages it took in.  "messages" is an OPTIONAL array on a step's receipt, what the step sent, in call order.  Each entry is an object of strings:

D seq: A decimal, from "1" within the step, in call order.

D from: The sender: the step's agent's name (Section 4.22), else its node id, unless the code names another.

D to: The receiver, as the code names it: an agent's name, a node's, or a key of a framework's shared state, as "state:messages".

D kind: A string the pipeline chooses, 1 to 64 characters, no control character.

D digest: "sha256:" over the body's bytes: bytes as given, a string as its UTF-8, any other value in canonical form; a value that cannot be is refused, naming it.

D bytes: The body's length in bytes.

D media_type: Where given or known; absent, not recorded.

D kept: "true" where its bytes are kept, as "messages/<receipt stem>/<seq>", by the run's rule for keeping outputs; absent, not kept.

P A message's id is "<node id>:<seq>", split at its last ":", since a node id can hold ":".  "messages_received" is an OPTIONAL array on a step's receipt, each entry an object of "from_step" (the sending step's node id), "seq" and "digest" for a message this step took in, or of "digest" alone where no sending step is known.

P Kept bytes sit beside "artifacts/", as a kept configuration does (Section 4.16), so a kept message never reads as a step's output.  A message is not an output and not a setting: "messages" changes no verdict, and a comparison reports it apart.  It names the first message that differs, by step in chain order and then "seq", and a message on one side only.

P *Informative: framework messages.*  Under a graph framework, a message a node adds to its message state is recorded with "kind" the message's type ("human", "ai", "system" or "tool"), "from" the node's name, "to" "state:<channel>", and "seq" its place in the node's returned list; its digest is over the message as the producer's framework encoding writes it, with every field but "id", "response_metadata" and "usage_metadata".  A message in the state a node starts from, added earlier, is in that node's "messages_received", by digest and by position.  A model's tool call is recorded as "kind" "tool request", from the model step's agent to the tool's name, its digest over JCS({"name", "args", "id"}); a tool's result as "kind" "tool result", from the tool's name to the agent that asked, or to "state:<channel>".  "to" under such a framework is the state channel: a node returns state, and the graph routes it after the node has returned, so when the receipt is written no receiver is known.  A tool result carries the id of the tool call it answers, so these records and "tool_call.requested_by" (Section 4.22) name one id.

P A verifier that implements minor 5 reports, on a record that holds the members:

D messages: PASS, "N messages, in order, each in form"; FAIL on a member outside the list, a "seq" that is not "1" to "N" in order, a digest out of form, and a "bytes" that is not a decimal.

D messages kept: PASS, "<seq>: the kept bytes match"; FAIL on a kept file with another digest or length, and "kept" with no file; NOT RUN, "the bytes were not kept", once for each run.

D messages_received: PASS, "N received, each from an earlier step"; FAIL on a "from_step" not earlier in the chain, no message at that "seq", and a digest that differs from the sender's; NOT RUN, "<digest>: no sending step named".

P What a message record does not show:

B A message record shows what was sent.  It does not show that the receiver acted on it.

B "messages_received" shows the receiving step's code said it took the message in, or that a framework's state held it when the node started.  It does not show the node read it.

B "to" is what the code declared.  Under a graph framework it is a channel, not a route.

B A message passed with no declaration and no framework hook is not seen.

H 4.24.  Model-Call Members

P What a model call adds beyond its model-call record (Section 4.19) is recorded in the receipt, beside the record, which does not change: a record stays in its format, byte for byte, in every run.  Each entry of the members below names its record by its output's name, as "model_call.json" or "model_call.2.json", since a step can hold more than one.  A value object below is the record's own form: "status", "value" and "source", with the record's states.

D model_usage: An OPTIONAL array, each entry an object of "record", and, where the provider's response has a place for them, "input_tokens", "output_tokens" and "total_tokens", value objects whose values are decimal strings, "observed", whose source is the provider's response field, or "not observed" where it gives none; and "cost", a value object whose value is an object of "value" and "currency" as the provider reports it, "observed", or "not observed" where it reports none.  A cost is never computed from a price list.

D model_call_attempts: An OPTIONAL array, each entry an object of "record", "retries" and "attempts".  "retries" is a value object, a decimal string, the attempts past the first the client made within this call, "observed" where the hook saw each attempt at the client's public request method, else "not observed".  "attempts" is an array of objects of "status" (the HTTP status as a decimal, or "no response") and "request_digest", in order.

D model_call_failed: An OPTIONAL array, each entry an object of "record" and "failed", where a call failed after its request was sent: "failed" is a value object whose value is the exception's class, "observed", with the source "the call failed after post".

D tokenizer_digest_method: An OPTIONAL array, each entry an object of "record", "form", "keys" and "files", saying how the record's tokenizer digest was made, so a reader can rebuild it from named files: "form" "sha256-of-canonical-name-map/1", SHA-256 over the canonical JSON of an object mapping each file's name to its SHA-256; "keys" "the name the adapter's file list gives"; and "files", the names, sorted, without their folders.  No file's contents are recorded.  Where the digest was given by the caller, no entry is written.

P A call that fails after its request was sent writes a model-call record under the step, whose outcome stays "error".  It holds what the hook saw go out, the request's digest, with the output members "not observed" and the source "the call failed after post".  Its attempts are in "model_call_attempts".

P A verifier that implements minor 5 reports, on a record that holds the member:

D model_usage: PASS, "<record>: N tokens, as the provider reported"; FAIL on a "total_tokens" less than a part where all three are "observed", a value not a decimal, and a member outside the list.

D model_call_attempts: PASS, "<record>: <n> attempts"; FAIL on a "retries" that is not one less than the number of "attempts", where it is "observed".

D model_call_failed: PASS, "<record>: failed after post: <class>"; FAIL on an entry on a step whose outcome is "ok".

D tokenizer_digest_method: PASS, always "<record>: the method's files are named; the files are not held", for an entry in form, since a verifier holds no tokenizer; FAIL on a member outside the four.

P Each of the four also FAILs a "<record>" that is not an output of the receipt, one that names an output that is not a model-call record, read from the kept file's own format where it is kept, and a second entry for one record.  A reader that implements minor 4 reads none of these members, and reads the record as before.  A rebuild of the tokenizer digest from named files is a tool's work, not a verifier's.

P What these do not show:

B Usage and cost are what the provider reported.  They are not checked against a bill or a tokenizer.

B "retries" counts the attempts the hook saw through the client's public request method.  A retry below that, in a transport, is not seen.

B A failed call's record shows what the hook saw go out.  It does not show what the provider did with it.

B "tokenizer_digest_method" says how the digest was made.  It does not show those files were what the model loaded.

H 4.25.  Authorization and the Recipient Confirmation

P "authorization" is an OPTIONAL object on the receipt of a gated step.  From earlier minors it carries "decisions", an array of the decisions the pipeline's code recorded at the step; an entry MAY carry "action_digest", the digest of the action the decision permitted, and a decision recorded with its permit records the permit token verbatim in the receipt.  The rest of that block is not yet described here (Appendix C).

P From minor 5, a gated step MAY also record the permit it presented to a recipient and the confirmation the recipient returned after it checked the permit and acted, in these members of "authorization", all strings but "request":

D permit_digest: "sha-256=:" followed by the base64 of SHA-256 over the permit token's ASCII bytes, as given, untrimmed, and ":", the form of [RFC9530].

D permit_iss, permit_jti, permit_aud: The permit's claims.

D permit_exp: Its "exp", a decimal.

D permit_status: "could not be read", where the token did not parse; the step then records "permit_digest" alone.  Absent, it was read.

D request: An object of "content_digest" and "signature_base_digest", each in the "sha-256=:...:" form, and "keyid", the presenter's key thumbprint, as in its "Signature-Input" [RFC9421].  Only the digest of the signature base is recorded.

D confirmation_digest: "sha256:" over the confirmation token's ASCII bytes, as a kept file's digest.  Absent, no confirmation was recorded.

P The confirmation token is always kept, as the file "authorization/<receipt stem>/confirmation.jwt", beside "artifacts/" as a kept configuration is.  The permit token is not kept by default; the run's rule for keeping inputs can keep it.  No request body and no key is recorded, only digests and thumbprints.  A producer reads a permit's claims without checking its signature.  One presentation is recorded for each step, and a second is refused, naming it: a retry is a stage of its own.  The step's outcome is what the producer records for every step, "ok" or not "ok".

P *The checks.*  The confirmation's format is not specified in this revision: its token, its members, the order in which its problems are named and its outcome table are to be specified separately (Appendix C).  The checks below read a confirmation by that format, and by the twelve readings below where it leaves a case open.  A verifier that implements minor 5 runs five checks, each on its own, shown only for a step that recorded a presented permit; a run with no such step gains no row.

B The request check, "confirmation: request": PASS, "N confirmation(s) checked against the request its step sent", with " (K by date only)" and " (K with no decision digest)"; FAIL, "<step>: the recipient confirmed a different request body", "... a different signature base", "... a different action", and "<step>: the confirmation is dated outside the step (iat N s after it ended)", or "(iat N s before it started)"; NOT RUN, "no confirmation recorded" and "no readable confirmation".

B The permit check, "confirmation: permit": PASS, "N confirmation(s) checked against the permit its step presented", with " (K by recipient only)"; FAIL, "<step>: confirmed by <iss>, but the permit is for <permit_aud>" and "<step>: the confirmation cites another permit"; NOT RUN, as the request check, and "<step>: the permit could not be read".

B The recipient key check, "confirmation: recipient key": PASS, "N confirmation(s), each verifying under the recipient's listed key", with "; unknown member(s) ignored: <names>"; FAIL, "<step>: not a recipient confirmation (typ '<typ>')" or "(typ absent)", "<step>: unknown critical header parameter(s): <names>", "<step>: malformed confirmation (<problem>)", the first problem of the format's table in its order, and "<step>: the confirmation does not verify under the recipient's listed key"; NOT RUN, "no recipient list given (pass --recipients)", "<step>: recipient <iss> is not on the list", "<step>: key <first 8 characters of kid>... is not listed for <iss>", and "the signature check needs the [crypto] extra" where the verifier has no signature implementation.

B The single use check, "confirmation: single use": PASS, "N permit(s) cited, none confirmed as effected twice", with " (K byte-identical repeat[s])"; FAIL, "permit <iss> <jti> confirmed as effected twice: <step>, <step>"; NOT RUN, "no confirmation cites a permit".

B The outcome check, "confirmation: outcome": PASS, "N step(s), each outcome consistent with its confirmation"; FAIL, "<step>: reported ok, but the recipient says 'refused' (<reason>, step <n>)", "... could not check (<dependency>)", "... says 'effect-unknown'", and "<step>: reported <outcome>, but the recipient says it acted (<id>)"; NOT RUN, "<step>: presented a permit; no confirmation recorded", "<step>: the confirmation could not be read" and "<step>: the confirmation is malformed".

P The window is the step's recorded start and end, widened by 60 seconds each way.  A request or permit PASS whose steps include one the key check did not pass ends with "; signature not verified for: <step>, ...".  Steps combine as FAIL if any FAILs, else NOT RUN if any is, else PASS.  A count reads "its" for one and "their" for more.  The key check reads in the order: readable, "typ", "crit", "alg" and shape, the list, the signature.  An "outcome" none of the three reads PASS on the outcome check, as the key check fails it.  The other checks read a "permit" or "request" that is not an object as absent.  The request check compares "iat" only where it is an integer.  A confirmation whose "outcome" is "refused" with a "dependency" is a could-not-check.

P *The recipients' keys* come from a list the person running the verifier names, a JSON object of the form:

V      {"format": "onetrace-recipient-trust/1",
V       "issuers": [{"issuer": "<iss>", "alg": "ed25519",
V                    "public_key": "<64 lowercase hex>"}]}

P with exactly these members.  The file holds no "kid": the verifier derives each entry's as the key's thumbprint [RFC7638], so a confirmation whose "kid" is not that thumbprint reads NOT RUN, not listed.  A recipient or key not on the list reads NOT RUN.  The list holds one key for each recipient, and a repeated "issuer" is refused.  The checks make no network calls and ask no recipient anything.

P *The twelve readings*, where the confirmation's format leaves a case open:

N 1. A "permit" missing "iss", "jti" or "digest" FAILs the key check, "malformed confirmation (permit.<member> missing)", in the format's member order, after "permit missing".  The permit check compares the members present, and an empty "permit" adds "by recipient only".  A dependency refusal requires none of them, so it is not malformed for one.

N 2. An "action_digest" that is not a string, a null among them, FAILs the key check, "malformed confirmation (action_digest not a string)", after the check for a "permit" or "request" member; the request check still reads it as present: "a different action".  An empty "request" reads as no "request" object, by date only.

N 3. A step with no decision action digest compares none, and the request PASS adds " (K with no decision digest)".  A step with several compares the last permitting decision's only.

N 4. Any "crit" member FAILs the key check, at its place in the order; one that is empty or not a list reads "malformed confirmation (crit not a non-empty list)", and a list prints its names.

N 5. Two "permit" or "request" members that are not strings: the first in the format's member order is named.

N 6. An unreadable token other than a duplicate member reads "malformed confirmation (not a compact JWS)" or "malformed confirmation (header or payload is not a JSON object)".

N 7. No "typ" reads "not a recipient confirmation (typ absent)"; no "kid" reads "malformed confirmation (kid missing)", after "alg".

N 8. Where the verifier has no signature implementation, the key check reads NOT RUN, "the signature check needs the [crypto] extra", and the other checks still run.

N 9. A malformed refusal on an "ok" step reads NOT RUN on the outcome check, "<step>: the confirmation is malformed".  Any other malformed confirmation reads by the format's outcome table.

N 10. Where several steps fail one check, other than single use, the details are joined by "; ", in chain order, each prefixed by its step.

N 11. A permit recorded as "could not be read" reads NOT RUN on the permit check, "<step>: the permit could not be read"; the other checks run, and single use counts by the confirmation's own "permit" members.

N 12. A confirmation that holds "mandate_verdict": no check prints it.

P What a confirmation does not show:

B A confirmation shows the recipient said it acted.  It does not show the effect happened in the world; that is the recipient's word, signed.

B A "refused" confirmation is likewise the recipient's word that it did not act, signed.

B A trusted key means the key is on the list given.  The verifier does not decide whom to trust.

B The checks other than the key check compare what a confirmation says, whether or not its signature verified.  A request or permit PASS beside a key FAIL or NOT RUN is a match with an unauthenticated statement.

B The request digests are the ones the record wrote when the step sent the request.  A match shows the recipient confirmed what the step says it sent.  It does not show what went on the wire, and the presenter's own request signature is not checked: no body or key is kept.

B In a refusal at the recipient's signature or issuer step, the permit's issuer and id are what the recipient read, not what it authenticated.

B Single use is checked across the records given to one verifier run, not across every record that exists.  A byte-identical repeat is counted once, so a second effect behind a reused token cannot be seen.

B A confirmation's "iat" is the recipient's own clock.  "mandate_verdict" is recorded, not checked.  Unknown members are named, not checked.

B The checks read the record as the producer wrote it.  Recording a confirmation's digest in a step does not discharge the "present_bound" obligation of the Bound Permits draft [BOUND-PERMITS]: that is the presenter's own report.

B With a durable store at the recipient, a reservation the recipient opened and never completed holds for good; an in-memory store loses it when the recipient restarts.  No check reads it.

H 4.26.  Code Version: code

P A run MAY record the version of the code it ran.  Its first receipt then carries the OPTIONAL object "code", and its manifest a copy (Section 6).  It is written only where the run asks for it, so a run that does not ask writes the same receipts as before.  Its members are strings:

D commit: The 40 or 64 hexadecimal characters of the commit checked out in the git repository holding the run's code file, read once when the run opens; or "not observed: " followed by the reason, where there is none.

D dirty: "true" or "false": whether the tracked files differ from the commit; absent with "not observed".

D lock_name: The dependency lock's file name: the first of "uv.lock", "poetry.lock" and "requirements.txt" beside the code file or at the repository's root; absent where there is none.

D lock_digest: "sha256:" over its bytes; absent where there is none.

P A failure to read it is "not observed", and it never stops the run.  The code file's bytes at a recorded commit are checked against "instrument.manifest_digest", which every stage records (Section 12.3).

P A verifier that implements minor 5 reports "code" as PASS, "commit <commit>", and MUST fail a "commit" out of form, a "dirty" other than its two values, and a manifest copy that differs from the first receipt's.  Given the repository, it reports whether the code matches its commit, PASS "<file> at <commit> is <manifest_digest>" or FAIL where the bytes differ; not given it, NOT RUN, "the repository was not given".

P A recorded commit is what git reported when the run opened.  "instrument.manifest_digest" covers the code file the run names, not every file that commit holds.  "dirty" "false" says the tracked files matched; untracked files are not read.

@@ 6.  The Chain Manifest
H 6.  The Chain Manifest

P A run's receipts are listed by a chain manifest: a JSON object in canonical form with the REQUIRED members:

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

D run_id: The run identifier, equal to that of every receipt listed.

D chain: An array of objects in receipt order, each with the members "index" (decimal string), "stage" (the stage name), "file" (a path relative to the manifest, using "/" as separator) and "digest" (the digest of that file's bytes).

D chain_head: The digest of the last receipt in "chain".

D anchor: An anchor declaration for the chain as a whole, in the form of Section 10.

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).

D rerun_from: A copy of the receipts' "rerun_from", read in the same way (Section 4.13).

D parent_run, parent_stage: For a nested run, the enclosing run and step (Section 4.11.1); for a run with a cross-service link, copies of "parent_link.run" and "parent_link.stage" (Section 4.11.2).

D origin_run: A copy of the first receipt's "parent_link.origin" (Section 4.11.2).

D state_at_open: A copy of the first receipt's "state_at_open" (Section 4.21).

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

D thread_id: A copy of the first receipt's "thread_id" (Section 4.19).

D code: A copy of the first receipt's "code" (Section 4.26).

P *The copy rule.*  No digest covers a manifest member other than the chain and its head, so a member that must be bound to the record is in a receipt, and the manifest's copy is read only where it equals that receipt's member: the first receipt's, or, for a member in every receipt, every receipt's where they agree.  A copy with nothing beside it in the receipts marks nothing.  A verifier that implements minor 5 MUST fail a copy that differs from the member it copies, and a manifest "agent" with no "run_agent" in the receipts.

P While a run is in progress, its manifest may be up to the run's manifest interval behind its receipts (Section 9).  The journal and the receipts are current.  The manifest is rewritten when the run closes and when it is recovered.

P The chain is valid when, for every receipt, "prev" equals the digest listed for the preceding receipt (null for the first), the listed digest equals the digest of the file's bytes, and "chain_head" equals the digest of the last receipt.  A chain with a missing receipt is not a chain with a gap; it is a chain that fails, and the emission declaration (Section 9) is how a producer records an absence it knew about rather than leaving a verifier to discover one.

@@ 8.  Coverage and Boundaries
H 8.  Coverage and Boundaries

P "coverage" is an object with the REQUIRED members:

D declared_stages: The ordered names of the stages the pipeline manifest expects the run to emit.

D emitting_stages: The names of the stages that have emitted a receipt in this run, as known at the time this receipt was emitted.

D boundaries: An array, possibly empty, of objects each naming a point beyond which the chain does not see: a stage that runs outside the producer's instrumentation, an upstream system whose output is taken on trust, a downstream consumer that is not receipted.  Each has the REQUIRED members "name" and "kind" (a string; values not enumerated here) and MAY carry "note".

D completeness: Exactly one of "complete" or "incomplete".  Never absent.

P "complete" is a claim and a verifier checks it: every declared stage MUST appear among the emitting stages, and "boundaries" MUST be empty.  A receipt that asserts "complete" while a declared stage is missing is lying about its own edges, and a verifier MUST fail it (vector R07), not warn.

P Coverage is derived by the producer from the manifest and the run, never typed by hand.  Its purpose is the following rule, which binds every consumer of these records: *where coverage is "incomplete", no consumer may assert a root cause across an undeclared boundary.* A tool that cannot see the edge of its own chart will eventually report confidently about something it never observed.  The claim this document permits a producer to make of a chain is, accordingly, bounded: for the receipted portion of a workflow, an independent verifier can determine whether the executed topology and component versions matched the approved manifest -- and nothing about the unreceipted portion.

P A run may legitimately be "incomplete": a pipeline with a non-linear region (Section 1.1) declares it as a boundary and receipts the linear portions on either side.  That is the honest shape.  Flattening the region into a sequence that did not run is not.

P The kinds a producer of this format writes are not enumerated, but minor 4 and minor 5 give some their words: "re-run stopped" (Section 4.12) and "not observed" (Section 4.19), and from minor 5 two more:

D queue full: A step the writer's queue could not take (Section 9): "name" the stage, and "note" "receipt not written: " followed by the gap's reason.  It makes every later receipt "incomplete", so a run with a dropped step never reads "complete".

D recovered: The boundary a recovery adds (Section 9).  It has no index: "name" "onetrace.close", and "note" "recovered by a later process", with "; its journal ended in a torn entry" added where it did.  The recovered close receipt's "coverage.boundaries" and the manifest's "boundaries" hold it.

@@ 9.  Emission Semantics
H 9.  Emission Semantics

P "emission" is an object with the REQUIRED members:

D policy: Exactly one of "fail-closed" (the stage does not run, or its result is discarded, if its receipt cannot be written) or "fail-open" (the stage runs and its result stands even if its receipt cannot be written).

D gaps: An array, possibly empty, of objects each recording a receipt the producer knows it failed to write: the REQUIRED members "stage" (the name), "index" (decimal string) and "reason" (a string).

P The policy is chosen by the operator at configuration time and MUST be declared; a producer MUST NOT default it.  A policy the operator did not choose is a policy they cannot be held to.

P Under either policy an absence is recorded as a declared gap, in the next receipt that is written and in the manifest.  Fail-open does not mean that errors disappear; it means the pipeline continued and the record says where it did so unreceipted.  A gap makes the run's coverage "incomplete" (Section 8) with the gap as a boundary.

P *The writer's queue.*  From minor 5, "emission" MAY carry "queue", the string "drop", in every receipt of a run that declared it.  Absent reads "block", which is the default.  A producer builds each receipt in order on the thread that ran the stage: it hashes the outputs, allocates the index, builds the receipt's bytes, takes its digest and advances "prev".  It then hands the bytes to a writer, which writes them in batches.  With "block", no member changes: a run's receipts are the same bytes in the same order whether the writer is queued or not, and only when they reach the disk differs.  Under "fail-closed" the stage returns once its receipt's batch is durable, and a write that fails discards the result and raises; under "fail-open" it returns once its receipt is queued, and a full queue blocks it.  A producer refuses "drop" with "fail-closed" when the run opens: fail-closed says a stage's result is discarded if its receipt cannot be written, and a dropped step keeps its result with no receipt.

P *A dropped step.*  With "drop", a step the queue cannot take is dropped before its receipt is built.  The producer allocates its index, records a gap at that index, its "reason" "dropped: the writer's queue was full at <node>", and a boundary of kind "queue full" (Section 8), and moves the step's staged outputs to "artifacts/_unreceipted/<node id>/".  "prev" does not move, so the chain has no hole.  The gap reaches the next receipt written and the manifest, and the run still closes.

P *A write that fails with receipts queued behind it.*  A queued receipt already names the one before it as "prev", and its bytes cannot change.  So the producer records a gap for the receipt whose write failed and for every receipt queued behind it, each at its own index, with the reason "receipt could not be written: <error>", and sets "prev" back to the last durable receipt.  Their outputs move to "artifacts/_unreceipted/".  No written receipt ever names one that is not there.

P *The manifest's interval.*  The writer rewrites the manifest at most once per manifest interval, in seconds, "1.0" by default, and always after the run's first batch, at close and at recovery.  An interval of "0" rewrites it after every batch.  Between rewrites the journal and the receipts are current, and a recovery builds the manifest from them.

P *The journal.*  A producer with a writer keeps a journal, the file ".journal" in the run's folder.  It is local and operational, like the folder's lock file: it is never in the chain, never sent with the run's files, and removed when the run closes.  Its form:

V      onetrace-journal/1 <host digest> <pid> <process start time>
V      <decimal length> <64 hex sha256> <receipt file name>
V      <the receipt's bytes>
V      ... and so on, each line ending in LF

B <host digest> is "sha256:" over the UTF-8 of the host's name; <process start time> is the process's start tick as the system gives it, a decimal, or "-" where it gives none, and a recovery then reads by process id alone.  A process id reused by a live process then leaves the journal unrecovered.

B An entry is appended on the thread that ran the stage, before it is queued, so a killed process loses no receipt already built.  The writer makes the journal durable with each batch, so power loss loses at most the batch in flight.

B A torn tail ends it: a reader stops at the first entry whose length or digest does not hold.

B It holds receipts, and the gaps the writer knows of: a step dropped, a receipt that could not be written, and a gap the producer declared each have an entry of their own, whose name is "gap" and whose bytes are the canonical JSON of the gap and the boundary declared with it, so a recovery after a kill before the next receipt still carries the gap.  Output files are in staging.

P *Recovery.*  On a producer's next start, it looks in its runs folder for a folder holding ".journal" whose process is gone: the journal's first line names it, its host digest equals this host's, and the process is absent or has another start time.  The same can be asked for by hand, and the scan can be turned off.  The lock file cannot say whose it is, so a recovery also removes it.  The base receipt is the last receipt the journal confirms, else the first entry it holds whole.  A recovery checks each receipt entry's outputs against the receipt's digests, and the first entry whose files do not hold ends what it confirms.  It then:

N 1. writes the receipts the journal confirms that are not yet on disk, byte for byte;

N 2. records a gap for each later entry the journal holds whole, its "index" and "stage" as its receipt gives them, its "reason" "recovered: its outputs did not hold" on the first and "recovered: an earlier entry did not hold" on each after it; a torn entry's index and stage cannot be read, so it has no gap; and adds each gap the journal holds that the base receipt does not carry, with its boundary;

N 3. adds the boundary of kind "recovered" (Section 8);

N 4. writes the recovered close receipt (Section 4.12), chained after the last confirmed receipt;

N 5. writes the manifest, its "edges" derived from the receipts now in the chain and its gaps and boundaries as above, and removes ".journal".

P Where the journal holds no entry whole, there is nothing to close: no receipt and no manifest is written, the lock file is removed, and ".journal" is kept, renamed ".journal.empty", its bytes as they were, as the only trace that the run started; one line goes to the producer's error output, "onetrace: <folder>: the journal holds no whole entry; kept as .journal.empty".  Where the journal holds entries and confirms none, its first receipt's outputs not holding or it holding gaps and no receipt, no close is written either: a close chained after no receipt would fail every verifier.  The folder is renamed "<run>.unrecoverable", as it was found, with a short "UNRECOVERABLE.txt" saying what was found, and one line goes to the error output, "onetrace: <folder>: <what>; kept as <run>.unrecoverable, with UNRECOVERABLE.txt".  The scan does not take up either again.

P A verifier that implements minor 5 reports the writer's queue as PASS, "drop declared; N steps dropped", and MUST fail an "emission.queue" other than "drop" and receipts that disagree on it.  It counts gaps in its summary, "N gaps, M of them dropped", and MUST fail a dropped gap's index that a receipt holds, a drop with no boundary, and a drop on a run that reads "complete".

P What the writer does not change, and what its record does not show:

B A dropped step ran with no receipt.  What it did is not in the record, beyond its stage name and its place.

B "block" under "fail-open" returns before the receipt is durable.  Power loss can lose the batch in flight, and then the record ends earlier, as a killed run's does.

B A journal is as trusted as the folder it is in.  Recovery rewrites what it holds, and does not make it more than that.

B ".journal.empty" shows what its first line says: a host's digest, a process id and a start time.  It does not show what the run did.

B While a run is in progress, its manifest may be up to the manifest interval behind its receipts.  The journal and the receipts are current.

@@ 11.3.7.  Members of Minor 4
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).

H 11.3.8.  Members of Minor 5

P A verifier that implements minor 5 also performs the checks minor 5 adds, in Sections 4.7, 4.11 to 4.15, 4.19, 4.21 to 4.26, 6 and 9, on every record whose own "format" is "stage-receipt/0.5" or later, and reports them as NOT RUN, with a version reason, on a record of an earlier minor (Section 14).  Each check is reported only for a record that holds the member it reads, and a record that holds none of them gains no row.  The checks across runs, the cross-service link (Section 4.11.2) and single use (Section 4.25), read only the records the verifier is given.

P It also keeps apart, as Section 11.3.3 does: an absent "state_reads" or "state_writes" and "[]" (Section 4.21); a read with "found" "false" and a read with a digest; a "version" of "not observed" and a version the store gave; an absent "step.kind" and the kind "other" (Section 4.22); a recovered close receipt and a close receipt (Section 4.12); and an output kept as a digest only and an output not written (Section 4.7).

@@ 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" or "state_writes" 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.  The rule holds by kind whatever parts a re-run takes (below): a "reproduce" that takes another run's code alone follows the first rule, and a "twin" or "counterfactual", with any parts, the second.

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.

P *Parts taken separately.*  From minor 5, a re-run of run A MAY take its data, its configuration and its code each from a different run, and records what it took in "rerun_from" (Section 4.13).  A part of a configuration is named "<node id>.<key>": <node id> a step of the run the configuration comes from, with its instance where it has one, as "fetch#2", and <key> a dotted path in that step's kept configuration (Section 4.16), as "answer.sampling.top_p".  Stage names and keys can both hold dots, so a name is split by matching that run's node ids, the longest first; where two splits both name a value in its kept configuration, the name is refused as ambiguous.  A key that itself holds a dot cannot be named.

P A part takes effect only through a parameter of the re-run's runner that reads that step's configuration at that key: a part named is read from the run it comes from, and every other parameter from A.  A part no parameter reads is refused, so a part is never recorded as taken with nothing to carry it.  Where only some parts are taken, the code must match A's, unless the code is also taken from another run; a re-run of a whole configuration keeps the rule of minor 4.

P *Informative: the reference implementation's options.*  "--config-of REF" takes REF's whole configuration; with "--only", a comma-separated list of parts that may be repeated, only those parts; with "--except", every part of REF's kept configuration but those named, exclusive with "--only".  A node id holding a comma is given in an "--only" of its own and matched whole first.  "--code-of B" takes run B's code: it checks B's recorded commit out into a temporary working tree of its own, runs the runner there, and removes that tree after a success, a failure or a signal; it never touches the person's working tree, branch or uncommitted changes.  "--substitute STEP --from C" with "--config-of" is a counterfactual (Section 4.13).

P Before anything runs, a re-run with parts is refused, with nothing run, where: a part names nothing in the configuration run's kept configuration; that run did not keep its configuration at the step, or kept the key only in part; A did not keep a part a parameter reads from A; parts are named with no configuration run; the code run recorded no code version (Section 4.26), or a commit "not observed"; its commit cannot be reached in the repository; it ran with "dirty" "true"; the code file at that commit does not match its "instrument.manifest_digest", which every stage of that run recorded; or it is itself a re-run.  A recorded commit is a statement, and that digest is the check on it: a wrong commit is refused before anything runs.

P What a re-run with parts does not show:

B It shows what that combination does today, with today's services and model.  External services may answer differently than they did.

B Code from B with today's environment is not B's run.

B "lock_differs" compares two files' digests.  It does not say which package differs, or what that did.

B A part named and taken is a value handed to the code through a parameter.  It does not show the code used it.

@@ 14.  Versioning
H 14.  Versioning

P The "format" member carries "stage-receipt/MAJOR.MINOR".  Within a major version, a minor revision MAY add optional members, permitted values of unenumerated strings, and required checks that only fail on records the earlier minor already forbade; it MUST NOT remove a required member, change a member's type, or change the canonical form.  A verifier MUST accept any minor version of the major it implements and MUST report NOT RUN, with a version reason, for any check the record's minor version did not define.  A major revision MAY change required semantics.

P A verifier that encounters a record whose "format" is a major version it does not implement -- including the pre-standard value "stage-receipt/0.0-preview", which corresponds to this document's golden chain before its format string was assigned -- MUST report NOT RUN with the version as the reason.  It MUST NOT report PASS, since it did not check the record against the rules the record claims, and it MUST NOT report FAIL, since the record contradicted nothing the verifier knows.

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.

P Minor 5 adds optional members only, marked in Sections 4.7, 4.11, 4.12, 4.13, 4.15, 4.19, 4.21 to 4.26, 6, 8 and 9.  It adds only what a verifier that implements minor 4 reads as before: such a verifier reads a minor 5 record with the same overall result as the same record without the minor 5 members, and no check that passes on a minor 4 record reads otherwise, though its words may quote other recorded values.  Checks that verifier adds for a receipt minor 4 would not write are allowed.  There are two exceptions:

B a step of a library whose bases that verifier does not document (Section 4.19) reads NOT RUN on its label check, "<library>: no documented bases", as a step of any undocumented library does, with the overall result unchanged;

B an output kept only as a digest (Section 4.7) has no output checks under that verifier, as for a step that wrote no such output, with the overall result unchanged.

P To hold that rule, minor 5 adds no form of "onetrace.ended_by", no basis of "effect_label" and no third member in it, no member inside "rerun", no member inside a model-call record and no new format for one, no output left in "outputs" without its file, and no constant of a new name beginning "onetrace." on an auto-recorded step.  A member that must be bound to the record is in a receipt, and the manifest holds a copy (Section 6).  A run's agent (Section 4.22) and its cross-service link (Section 4.11.2) follow that rule.

P Minor 5 reserves the instrument kind "close-recovered" with the stage name "onetrace.close" (Section 4.12), identified by the two-part rule, and the constants "onetrace.recovered" and "onetrace.last_confirmed" within the prefix minor 4 reserved.  It gives words to the boundary kinds "queue full" and "recovered" (Section 8), and names the folders "state/", "messages/" and "authorization/" beside "artifacts/", none of which holds a step's output.  The list of "step.kind" values is closed: a new kind needs a new minor.  These bind producers from minor 5.

@@ 15.  IANA Considerations
H 15.  IANA Considerations

P This document has no IANA actions.  A later revision may register the media type "application/stage-receipt+json" for receipts and "application/stage-receipt-chain+json" for chain manifests; nothing in this revision depends on such registration.

P The HTTP fields "onetrace-parent" and "onetrace-child" (Section 4.11.3) are not registered in the HTTP Field Name Registry by this revision.  A later revision may register them; nothing in this revision depends on such registration.

@@ 16.  Security Considerations
H 16.  Security Considerations

P *Consistency is not originality.* The central security property of this format is stated in Section 10 and is repeated here, as it is the one most likely to be misread: a chain that verifies is consistent with itself and nothing more.  An operator can rewrite an unanchored chain without detection.  A reader who treats verification as proof of history has been misled by the reader, not the record, and the format's defence is to require every record and every verifier to say so out loud.  The anchor cadence is the tamper window; a producer choosing a cadence is choosing how long a rewrite can go unnoticed.

P *Digests are commitments.* A published digest of a secret, a credential, or a personal record is a commitment to bytes that can never be withdrawn; anyone who later obtains the bytes can prove they existed at anchoring time.  Artifacts MUST be reviewed as publishable before their digests are anchored, and secrets are never digested into anything (Section 7).  Low-entropy artifacts -- a short answer, a yes-or-no field, a small set of candidates -- can be recovered from their digests by enumeration; a producer that needs to record such a value without disclosing it MUST use a keyed or salted construction outside this document and record the construction's identity in "constants".

P *Records are data, not instructions.* Artifact contents, names, notes and reasons in a receipt are written by the producer and, through externally-sourced inputs, by parties the producer does not control.  A consumer that feeds any of them to a model MUST treat them as untrusted content and SHOULD carry the trust class alongside them.  The trust class makes origin visible; it does not make content safe.

P *The verifier is a target.* A verifier parses attacker-controlled bytes.  It MUST bound the size of what it reads, MUST NOT follow paths in a manifest outside the manifest's directory, and MUST NOT execute, fetch, or resolve anything a record names.  The constraint that it requires no network is also a defence: a verifier that cannot reach anything cannot be made to.

P *An incoming parent field is a claim.*  An "onetrace-parent" field (Section 4.11.3) is written by whoever sent the request.  A callee records its values only in "parent_link", never as a file, a folder or a run id of its own, checks its length before it decodes it, and never fails a request on a field that does not parse.  An incoming "traceparent" is recorded where it is well formed and otherwise left out.  The link is a claim until the caller's record is held and agrees (Section 4.11.2).

P *Whom a producer tells.*  The parent field names the caller's run and step to whoever receives the request.  A producer's hooks send it only to hosts on an allow-list the operator sets, "ONETRACE_PROPAGATE" in the reference implementation, a comma-separated list of exact hosts, which is empty by default, so a model provider or another third party is not told either with no one having asked.  A call to a host not on the list records "not sent: host not on ONETRACE_PROPAGATE".  A field the pipeline's code adds itself needs no list.  The callee returns "onetrace-child" only to a request that carried the parent field.

P *The journal's trust.*  A journal (Section 9) is as trusted as the folder it is in.  Recovery writes what it holds, after checking each entry's length and digest and each receipt's outputs, and does not make it more than that.  A recovery adds a receipt to a folder an operator may be holding as evidence of the kill; the recovered close is marked, and the chain before it is unchanged.  A recovery acts only on a journal whose host digest is this host's and whose process is gone.

P *Signatures are not specified.* This revision binds no record to an actor.  A signature envelope and a key lifecycle are recognized requirements, sequenced behind actor identity (Appendix B).  Until they exist, a receipt's "instrument" and a manifest's "anchor" say what ran and where the head was committed, not who vouches for either.

P *What is not defended.* The format is tamper-evident to the extent of its anchoring and not tamper-resistant at all.  It does not prevent a producer from emitting false records; it makes a false record cost a consistent lie across every later record and every anchor, and it makes the absence of an anchor visible.  Deployment isolation between tenants, the integrity of the host, and the honesty of the operator are outside what any record can establish.

@@ 17.  Privacy Considerations
H 17.  Privacy Considerations

P A receipt carries digests, sizes, names, media types, timestamps and operator-written notes; it does not carry artifact content.  Names and notes are free text and a producer MUST NOT place personal data in them.  Timestamps at millisecond precision, combined with stage names, can identify a person's interaction with a system; a producer that publishes chains SHOULD consider whether the run identifiers and times it publishes are themselves personal data.

P An anchored digest of an artifact that contains personal data is a permanent commitment to that data's existence, which may conflict with an obligation to erase it.  Erasure of the artifact does not erase the commitment.  Producers subject to such obligations SHOULD NOT anchor digests of artifacts that may need to be erased, or SHOULD digest them through a keyed construction whose key can be destroyed, recording the construction in "constants" so that the record remains self-describing.

P *What the link fields tell a callee.*  An "onetrace-parent" field tells the receiving service the caller's run id, the calling step's node id, the caller's chain head and the origin run id; an "onetrace-child" field tells the caller the callee's run id and a head.  Both are sent only as Section 16 gives.

P *State keys.*  A state entry (Section 4.21) records a key's digest by default.  A key in plain, which can hold a query's text and its parameters, is written only where the pipeline asks for it, the rule an HTTP path has (Section 4.19).  A kept state value, a kept message body and a kept confirmation token are files beside the run, kept as Sections 4.21, 4.23 and 4.25 give.

P *A value withheld from a stop.*  On a run that keeps no outputs, the value that failed an expectation checked during the run is not written in "checked.detail" or in "onetrace.ended_by" (Section 4.15): a receipt is made to be shared, and that would be the one place the run's data appears in plain.

@@ 18.1.  Normative References
H 18.1.  Normative References

V    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
V               Requirement Levels", BCP 14, RFC 2119, March 1997,
V               <https://www.rfc-editor.org/info/rfc2119>.
V
V    [RFC3339]  Klyne, G. and C. Newman, "Date and Time on the Internet:
V               Timestamps", RFC 3339, July 2002,
V               <https://www.rfc-editor.org/info/rfc3339>.
V
V    [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
V               Encodings", RFC 4648, October 2006,
V               <https://www.rfc-editor.org/info/rfc4648>.
V
V    [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
V               Specifications: ABNF", STD 68, RFC 5234, January 2008,
V               <https://www.rfc-editor.org/info/rfc5234>.
V
V    [RFC6234]  Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms
V               (SHA and SHA-based HMAC and HKDF)", RFC 6234, May 2011,
V               <https://www.rfc-editor.org/info/rfc6234>.
V
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>.
V
V    [RFC7638]  Jones, M. and N. Sakimura, "JSON Web Key (JWK)
V               Thumbprint", RFC 7638, September 2015,
V               <https://www.rfc-editor.org/info/rfc7638>.
V
V    [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
V               2119 Key Words", BCP 14, RFC 8174, May 2017,
V               <https://www.rfc-editor.org/info/rfc8174>.
V
V    [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
V               Interchange Format", STD 90, RFC 8259, December 2017,
V               <https://www.rfc-editor.org/info/rfc8259>.
V
V    [RFC8792]  Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,
V               "Handling Long Lines in Content of Internet-Drafts and
V               RFCs", RFC 8792, June 2020,
V               <https://www.rfc-editor.org/info/rfc8792>.
V
V    [RFC9421]  Backman, A., Ed., Richer, J., Ed., and M. Sporny, "HTTP
V               Message Signatures", RFC 9421, February 2024,
V               <https://www.rfc-editor.org/info/rfc9421>.
V
V    [RFC9530]  Polli, R. and L. Pardue, "Digest Fields", RFC 9530,
V               February 2024, <https://www.rfc-editor.org/info/rfc9530>.

@@ 18.2.  Informative References
H 18.2.  Informative References

V    [BOUND-PERMITS]
V               Saha, S., "Action-Bound Permits for the Agent Action
V               Decision Protocol (AADP): Carrying a Per-Action Decision
V               Across a Trust Boundary", Work in Progress,
V               Internet-Draft, draft-saha-aadp-bound-permit-00, 29
V               September 2026, <https://datatracker.ietf.org/doc/
V               draft-saha-aadp-bound-permit/>.
V
V    [INTOTO]   Torres-Arias, S., Afzali, H., Kuppusamy, T. K., Curtmola,
V               R., and J. Cappos, "in-toto: Providing farm-to-table
V               guarantees for bits and bytes", Proceedings of the 28th
V               USENIX Security Symposium, August 2019,
V               <https://www.usenix.org/conference/usenixsecurity19/
V               presentation/torres-arias>.
V
V    [OTEL-GENAI]
V               "OpenTelemetry GenAI semantic conventions", accessed
V               8 November 2026, <https://github.com/open-telemetry/
V               semantic-conventions-genai>.
V
V    [PROV-DM]  Moreau, L., Ed. and P. Missier, Ed., "PROV-DM: The PROV
V               Data Model", W3C Recommendation, April 2013,
V               <https://www.w3.org/TR/prov-dm/>.
V
V    [RFC6962]  Laurie, B., Langley, A., and E. Kasper, "Certificate
V               Transparency", RFC 6962, June 2013,
V               <https://www.rfc-editor.org/info/rfc6962>.
V
V    [RFC8785]  Rundgren, A., Jordan, B., and S. Erdtman, "JSON
V               Canonicalization Scheme (JCS)", RFC 8785, June 2020,
V               <https://www.rfc-editor.org/info/rfc8785>.

@@ C
P Changes from -02.  This revision describes minor 5.  It adds: outputs kept as a digest only (Section 4.7); runs nested in-process, the cross-service link with its origin, the "calls" record, and the HTTP fields "onetrace-parent", in five parts, and "onetrace-child", with their ABNF and parse rules (Section 4.11); the stop's form inside "unhandled exception:" and the recovered close receipt of kind "close-recovered" (Section 4.12); "rerun_from" beside "rerun", and a substitution with a configuration (Section 4.13); the two vector pairs, "step.effect_basis", and "state_writes" read as a write (Section 4.14); expectations checked during the run, their modes, "checked" and "expectations_batch" (Section 4.15); the libraries "anthropic", "httpx2", "langchain" and "langgraph", the framework stage names, "step.lower_hook", "framework_error", "thread_id" and the new "auto.hooks" entries (Section 4.19); state (Section 4.21); "step", "tool_call", "agent" and "run_agent" (Section 4.22); messages (Section 4.23); the four model-call members (Section 4.24); "authorization" and the recipient confirmation (Section 4.25); "code" (Section 4.26); the manifest's new copies and the copy rule (Section 6); the boundary kinds "queue full" and "recovered" (Section 8); the writer's queue, a drop's gap, the manifest's interval, the journal and recovery (Section 9); the checks of minor 5 (Section 11.3.8); parts of a configuration and another run's code in a re-run (Section 12.3); the minor 5 rule and its two exceptions, and the values minor 5 reserves (Section 14); the HTTP fields, not registered (Section 15); the security and privacy text for the parent field, the allow-list, the journal, plain state keys and a withheld value (Sections 16 and 17); the normative references [RFC4648], [RFC5234], [RFC7638], [RFC9421] and [RFC9530] (Section 18.1); and the informative references [BOUND-PERMITS] and [OTEL-GENAI] (Section 18.2).

P Not yet described.  The recipient confirmation's format is to be specified separately.  How the members of Sections 4.22 to 4.24 map to the OpenTelemetry GenAI semantic conventions [OTEL-GENAI] is not described here.  The members of "authorization" that earlier minors write, beyond "decisions" and "action_digest", are not yet described (Section 4.25).  The comparisons that read the new members (Section 12.1) are not revised here.  Under single use (Section 4.25), a "permit" missing "iss" or "jti" prints "None" in its place beside the key check's FAIL; that reading is left open, as is a recipient's second key.  The vectors of Appendix A are unchanged; no vector for minor 5 is added to this document.
