Docs / Check and compare

References: a sealed record of a known-good run

A reference is a sealed record of a run you vouch for, or of selected steps of it: per step, the output digests, the settings, the data inputs and a timing range, with the rule for the step. A later run is checked against it with onetrace verdict, which gives each step one word and the run its own. A reference is its own file, format onetrace-reference/1; it is never a receipt and never part of a run's chain.

Making one

onetrace reference make RUN… --out FILE [--steps NODE …] [--mask FILE] [--sign FILE | --sign-env NAME]
onetrace reference show FILE

prints a reference as text: its seal, its signature, the runs it was made from, and per step the outputs, inputs, settings and timing range.

What a step holds

field what it is
outputs the step's output digests, by name
inputs the step's data inputs by digest (not the receipt: links to earlier steps, which are the run's structure)
settings the instrument's configuration digest and the stage's own constants (onetrace's own onetrace.* constants are not settings)
timing_ms the range {min, max} across the runs given, when more than one gave a readable time
rule exact (the default), or a mask

The rule

The default rule is exact: a step's output digests, its settings and its data inputs must match the reference. --mask FILE (an onetrace-mask/0.1 file) names settings not to count as a difference; the reference records the rule in full, so a reader sees exactly what was not counted. Outputs are always compared by digest — a reference holds digests, which a value mask has nothing to act on — so a tolerance on a numeric output waits for the per-step values a later release records, not this one.

A pipeline may hold several

A pipeline's golden set is its references — one per release, say. Each is a separate file; a run is checked against whichever one you name.

What a reference does not claim