Skip to contents

Bundle a bayesgrove project for reproducible handoff

Source: R/handoff.R
bg_bundle.Rd

Creates a portable .tar.gz archive of the project, including the structural graph, decision log, job history, configuration, attached data, and cached artifacts. Model fit artifacts are optional.

Usage

bg_bundle(project, path = NULL, include_fits = FALSE)

Arguments

project

A bg_handle.

path

File path where the bundle should be saved (default: a temp file). Relative paths are resolved from the current working directory.

include_fits

Logical, whether to package the large model fit artifacts.

Value

The file path to the generated bundle.

Details

Portable source policy

External files referenced by approved node params are copied into the archive and their references relocated, so a restored project works after the original files (and machine) are gone:

  • Approved keys: stan_file. The referenced Stan program is copied together with every file reachable through #include directives, bare, quoted, or angle-bracketed (resolved relative to the including file, as stanc3 does). The key list is grounded in what the executors actually read.

  • References into the installed bayesgrove package (e.g. system.file("stan", ...) models) are rewritten to a machine-stable package reference (bayesgrove:stan/<model>.stan) instead of being copied: the installed package already carries the bytes on every machine, and the sentinel path no longer depends on where the library lives, so restored projects resolve it anywhere and their fingerprints are comparable across machines. Only a package upgrade (recorded in the environment and reproducibility manifests) can change these sources.

  • Nothing else is copied. Executor dependencies (persisted separately as inert source and restored only through the trust-gated bg_restore_executors()), external data (attach it with bg_set_node_data() so it travels through the CAS), secrets, and unreferenced siblings of a referenced file all stay outside the archive. Directories are never copied wholesale.

  • A referenced file that is missing at bundle time produces a warning and the reference is left as-is.

Relocation happens at bundle time: files are archived under bundle_sources/ inside the project directory, the archived graph stores the archived paths relative to the project root, and .bayesgrove/bundle_manifest.json records a source_policy section with the policy name and version, the approved keys, and a relocation table keyed by the raw param value, each entry carrying the resolved original path, the archived path, and a SHA-256 per copied file. Restoring therefore executes no project code: untar and bg_open() as usual. Relative stan_file params resolve against the project root at bundling, fingerprinting, and execution time, so a project bundles and runs identically from any working directory.

Because the params hash covers the path string, relocated references change fingerprints and restored fit nodes rerun by default (include_fits is FALSE by default, so cached fits do not travel anyway).