Reproducibility

EnvironmentSnapshot

The bundle of metadata captured by capture_environment and persisted on an Iteration row by snapshot_environment!.

Fields

• julia_version::String: string(VERSION) at capture time.
• git_sha::String: HEAD commit SHA from the working tree, or "" if no git repo is reachable from the current directory.
• git_dirty::Bool: true when uncommitted changes were detected at capture time.
• entrypoint::String: PROGRAM_FILE (the script path), or "" for REPL sessions.
• project_toml::String: Verbatim contents of the active Project.toml. Empty when no active project is set (raw REPL with no --project).
• manifest_toml::String: Verbatim contents of the active Manifest.toml. Empty when no active project is set or the project has never been resolved.

RestoreResult

Materialised view returned by restore. Carries the on-disk location of the reconstructed project plus the surrounding lineage metadata so the caller can drive Pkg.instantiate (or invoke julia --project=…) and check the result against the captured git_sha / git_dirty / julia_version.

Fields

• project_path::String: Directory containing the materialised Project.toml and Manifest.toml. Activate it via Pkg.activate(project_path) to use it.
• julia_version::String: The Julia version recorded at capture time.
• git_sha::String: The HEAD commit SHA at capture time, or empty when no git state was captured.
• git_dirty::Bool: true when the working tree was dirty at capture time. A true value warns that the captured Manifest may not be reproducible from git_sha alone.
• entrypoint::String: The script that was the iteration's entrypoint, or empty for REPL sessions.

capture_environment(; entrypoint::AbstractString=PROGRAM_FILE)::EnvironmentSnapshot

Capture a snapshot of the calling Julia process's reproducibility-relevant state.

The function never throws: missing git repo, missing active project, and unreadable toml files all degrade gracefully to empty strings so a partial capture is preferable to a hard failure mid-iteration.

Arguments

• entrypoint::AbstractString: Override the captured script path. Defaults to PROGRAM_FILE, which is empty in REPL sessions.

Returns

An EnvironmentSnapshot.

snapshot_environment!(iteration_id::Integer; entrypoint=PROGRAM_FILE)::Type{<:UpsertResult}

Capture the calling process's reproducibility-relevant state via capture_environment and persist it on iteration iteration_id. Idempotent — re-running on the same iteration overwrites the previous snapshot.

Arguments

• iteration_id::Integer: The iteration to attach the snapshot to.
• entrypoint::AbstractString: Override the captured script path. Defaults to PROGRAM_FILE.

Returns

An UpsertResult — Updated on success, Unprocessable if the iteration does not exist.

snapshot_environment!(client::Client, id::Integer; entrypoint=PROGRAM_FILE)::Nothing

Capture the calling process's reproducibility state via capture_environment and POST it to POST /iteration/{id}/snapshot. Requires UpdatePermission on the iteration's project.

Capture happens locally — LibGit2 and Pkg operate on the client process's working tree, not the server's — and the resulting metadata is wired through to the iteration row.

restore(iteration_id::Integer; depot::AbstractString=mktempdir())::RestoreResult

Materialise the captured Pkg environment of iteration_id into a fresh directory under depot. Writes Project.toml and Manifest.toml from the iteration row; does not itself call Pkg.instantiate or activate the project — that's deliberately left to the caller so this function stays side-effect-free outside of the temp directory.

A typical workflow:

result = DearDiary.restore(iteration_id)
using Pkg
Pkg.activate(result.project_path)
Pkg.instantiate()
# ...then run `result.entrypoint` if one was captured.

Arguments

• iteration_id::Integer: The iteration whose environment to restore.
• depot::AbstractString: Directory under which to create the project subdirectory. Defaults to a fresh tempdir.

Returns

A RestoreResult.

Throws

• ArgumentError when the iteration does not exist.
• ArgumentError when the iteration has no captured manifest — i.e. snapshot_environment! was never invoked on it.