Writes receipt.json for one output: what it is, how it was made, what came out,
and where and when. The package supplies the values it knows; this function
computes everything that must agree byte for byte across implementations: the
recipe_id, each table's fingerprint, each part's size and SHA-256, and the
config files' SHA-256 (crate#43).
Arguments
- dir
Directory to write
receipt.jsoninto: the output's directory.partsare relative to it.- output, recipe, result, context
Named lists, one per block (see above).
- keys
Optional: the package's declaration, from
crt_receipt_keys(). When given, the tolerances come from it and the inputs, settings, config files and tables supplied must be exactly those it declares.- lockfile
Path to a lockfile whose SHA-256 is recorded in
context, orNULL. Defaults torenv.lockin the working directory when one exists.- publish
TRUEfor a receipt that will be published: leaves the host out.- file
The receipt's file name inside
dir: a bare name ending.json, with no path separator, so the receipt sits in the directory its parts are relative to. Name it after the output ("CH_rear_grades_receipt.json") where several outputs share a directory; the name is not part of the receipt (#47). A name that resolves to a file the receipt hashes (a part, a config file, the lockfile) is refused, since writing the receipt would replace those bytes.
Value
The SHA-256 of the bytes written, as 64 lower-case hex digits, invisibly.
The file is file.path(dir, file); read it with crt_receipt_read(). The digest
is what a STAC item's receipt asset carries as file:checksum
(crt_receipt_stac()): nothing else can compute it, since a receipt's own bytes
are not inside it, and taking it here means the caller never re-reads the file and
risks hashing another version of it (#60).
The blocks
output:name, and optionallyscope(the partition: a watershed group, a region) andschema(the crate schema the output conforms to).recipe:code, a list keyed by repository oflist(commit, version, dirty), withcommitthe full 40-character SHA;config, a list offiles(paths, hashed here; named to set the key, otherwise keyed by the path as given) andsettings(the resolved run settings, written verbatim: wrap a length-one vector inI()to keep it an array). A config file is hashed as its bytes, as checked out: a repo whose config entersrecipe_idshould pin its line endings (.gitattributes:*.yaml text eol=lf), or a CRLF checkout is another recipe;inputs, keyed by input name, each exactly one oflist(recipe_id = ),list(version_id = ),list(sha256 = )orlist(none = "why"); andseed, an integer orNULL.result:tables, a named list of data frames to fingerprint;parts, the output's files as paths relative todir, each named by the table it holds where it holds one (c(access_check = "access_check.csv", "map.tif")), so a comparison can tell a file whose bytes moved within its table's tolerance from one that changed;summary, named numbers such asrowsorkm_total; andtolerance,list(tables = list(<table> = list(<column> = 1e-9)), summary = list(<name> = 1e-6)).context: anything ofrun(identifiers),session,inputs(each input's own result, for reporting),toolchainandtime.timedefaults to now, in UTC;toolchainis filled with R's version and, when loaded, GDAL's, terra's, sf's and arrow's, and entries given here win. The host is recorded unlesspublish = TRUE.
Toolchain versions and every other part of context are never part of an
identity: a GDAL upgrade alone leaves recipe_id unchanged, and the comparison
decides from the result whether the output still agrees.
Examples
dir <- file.path(tempdir(), "evidence")
dir.create(dir, showWarnings = FALSE)
access <- data.frame(segment = c("s1", "s2"), km = c(12.3456789012, 7.25))
write.csv(access, file.path(dir, "access_check.csv"), row.names = FALSE)
digest <- crt_receipt_write(
dir,
output = list(name = "link_evidence", scope = "BULK"),
recipe = list(
code = list(link = list(commit = strrep("a", 40), version = "0.31.2", dirty = FALSE)),
config = list(settings = list(species = I("CO"))),
inputs = list(fwa = list(version_id = "3HL4kqtJlcpXroDTDmJ"))
),
result = list(
tables = list(access_check = access),
parts = c(access_check = "access_check.csv"),
summary = list(rows = 2L, km_total = sum(access$km)),
tolerance = list(tables = list(access_check = list(km = 1e-9)),
summary = list(km_total = 1e-6))
),
publish = TRUE
)
digest
#> [1] "37f1116f061bf4f14540f7d659377a81b3eb27f7cc3f9ba0943cdffda54cdbdb"
crt_receipt_read(dir)$recipe$recipe_id
#> [1] "b61eb32306d67d8bcef8c87fed32aeff3681251bb70464956787675e901cd09b"
