Golden-output scientific regression framework — golden

Stores canonical scientific outputs with explicit comparison semantics, tolerances, approval metadata, deterministic serialization, and SHA256 integrity verification.

Usage

new_golden_spec(id, mode = "exact", absolute_tolerance = 0,
  relative_tolerance = 0, role = "gating", metadata = list())

new_golden_entry(
  spec, value, approved_by = NA_character_,
  approval_reason = NA_character_,
  created_at = format(Sys.time(), tz = "UTC", usetz = TRUE)
)

new_golden_store(entries = list(), metadata = list())

register_golden_entry(store, entry, replace = FALSE)

validate_golden_entry(x)

compare_golden_outputs(observed, store, ids = names(store$entries))

golden_output_table(x)

write_golden_store(store, path, overwrite = FALSE)

read_golden_store(path, verify = TRUE)

verify_golden_store(path)

Arguments

id: Stable output identifier.
mode: Comparison mode: exact, numeric, matrix, eigenspace, q_matrix, or manifest.
absolute_tolerance, relative_tolerance: Nonnegative comparison tolerances.
role: Either gating or diagnostic.
metadata: Additional named metadata.
spec: A golden specification.
value: Canonical output object.
approved_by, approval_reason: Approval metadata required for intentional replacement.
created_at: UTC timestamp.
entries: Optional list of golden entries.
store: A golden store.
entry: A golden entry.
replace: Permit an explicitly approved replacement.
x: A golden entry, store, or result.
observed: Named list of observed outputs.
ids: Optional identifiers to compare.
path: Golden-store directory.
overwrite: Permit replacement of an existing directory.
verify: Verify SHA256 checksums while reading.

Value

Constructors return validated S3 objects. Comparison returns a PopgenVCFGoldenResult whose status is "failed" when any gating golden fails, errors, or has no observed output, or when a requested identifier has no golden entry; only diagnostic goldens may be "skipped". Table conversion returns a data table. Store writing returns the normalized path invisibly; reading returns the validated store; verification returns TRUE invisibly.