Concepts and terminology¶
This page defines the terms used by reprotrail. They describe different parts of a recorded run rather than additional services that must all be deployed.
Provenance record¶
A provenance record is the versioned JSON document written for one command. It describes what ran, when it ran, its completion status, trusted software state, selected inputs, and available runtime information. Provenance helps answer how a result was produced; it does not by itself guarantee that the command is deterministic or that external data remains available.
Product and sidecar¶
A product is the durable file or directory produced by a run, such as a
NetCDF file or Zarr store. A sidecar is a separate metadata file stored next
to a product. Reprotrail sidecars can include a provenance record and checksum,
README, license notice, and ro-crate-metadata.json.
Runtime snapshot¶
A runtime snapshot is a normalized description of the environment used by a command. With Pixi, it includes the lockfile hash, selected environment, package versions and source information, platform identity, and relevant editable dependency Git state. It is evidence about an environment, not a copy of every installed file.
Dependency epoch¶
A dependency epoch is an accepted runtime snapshot for a run root. When the
snapshot changes, reprotrail epoch check requires an explicit acceptance
reason before work continues. The term “epoch” is convenient shorthand for a
period in which the accepted dependencies are unchanged; it is not a calendar
or package-manager concept.
Run root¶
The run root is the directory that groups one logical workflow run and its
provenance contract. Product path markers can help infer it. For example, if
products is configured as a marker, the record
results/run/products/a/a.prov.json belongs to results/run.
Trusted and diagnostic repositories¶
Trusted runtime repositories are source checkouts that can affect the executed code: the project repository and active external editable or path dependencies. Dirty trusted repositories block execution by default.
Diagnostic repositories are additional configured checkouts that are useful
to observe but are not active runtime sources. Their state is recorded under
configured_repos; it does not satisfy runtime provenance and does not block a
run when dirty.
Pixi¶
Pixi is a project and environment manager that creates a
cross-platform lockfile. Reprotrail reads Pixi state and invokes the external
pixi executable for environment inspection, freshness checks, and
reproduction. Pixi is not installed by the PyPI package.
RO-Crate¶
RO-Crate is a JSON-LD format for describing research data packages and their relationships. Reprotrail uses it to connect products with inputs, software, attribution, and license evidence.
SPDX¶
SPDX provides standardized identifiers and expressions for
software and data licenses, such as MIT or CC-BY-4.0. Reprotrail validates
explicit product license expressions but never chooses a product license for
the user.
CF/xarray history¶
The Climate and Forecast metadata conventions define a history attribute for
recording processing steps. Reprotrail can create compact history lines and
attach them to xarray-like objects. These lines complement the richer JSON
provenance record.
DVC and Git LFS¶
DVC and Git LFS track data or large files through small repository metadata. When detected, reprotrail records their relevant identifiers. It does not upload, download, or guarantee access to the underlying data.