Skip to contents

Archive a Mode 3 framework spec into the run output directory

Source: R/framework_spec.R
archive_framework_spec.Rd

A Mode 3 run loads config$methodology$framework_spec_path into a typed FrameworkSpec but never copies the source spec into the run outputs. The HTML report's methodology stamp says "M3 - Framework Applied" but a reviewer cannot reconstruct WHICH framework was used (TPB? COM-B? TDF? a custom YAML?), what its citations are, or what its anomaly handling policy says. Without the archive, replay / methodology-paper provenance is broken.

Usage

archive_framework_spec(spec, run_dir, run_id = NULL)

Arguments

spec

A FrameworkSpec object (must carry a non-NA source_path). For built-in frameworks the source_path is the system.file() resolution at load time.

run_dir

Path to the run output directory. Created if missing.

run_id

Optional character: run id used for the AC4 methodology stamp prepended to the archive (YAML/JSON comment). The stamp was added later; run_id = NULL omits the | run: <id> portion of the stamp.

Value

Named list with path (path of the archived file under run_dir), hash (sha256 hex string of the ORIGINAL source spec – not the post-stamp archive bytes – so replay-equivalence is anchored to the source spec the user supplied), name (framework$name), epistemic_stance, anomaly_handling, n_constructs, schema_version, suitable to splat into init_run_state(...).

Details

This helper writes a verbatim copy of the source spec to outputs/<run>/framework_applied.yaml (or .json – preserved from source extension), computes a deterministic S of the file's bytes, and returns a metadata list suitable for stamping into run_metadata.json via init_run_state(...).

Per AC4 ("methodology stamped on every output"), the archive is mandatory for any Mode 3 run – absence of the archive is a coverage failure flagged by verify_run_integrity.

See also

load_framework_spec; init_run_state (consumes the metadata).

Examples

spec <- load_framework_spec("tpb")
tmp <- tempfile()
dir.create(tmp)
arch <- archive_framework_spec(spec, tmp)
#> INFO [2026-08-28 17:25:53] Mode 3 framework archived: framework_applied.yaml (sha256 b1de9ba7553e..., 5 constructs)
arch$relative_path  # "framework_applied.yaml"
#> [1] "framework_applied.yaml"
nchar(arch$hash) == 64L  # TRUE -- sha256 hex string
#> [1] TRUE
file.exists(arch$path)   # TRUE
#> [1] TRUE