Extract stored strategy source for a run

Inspects strategy provenance stored in a ledgr experiment store. By default this function returns source text and metadata only. It does not parse, evaluate, or execute the stored source unless trust = TRUE. Stored source hash mismatches abort in all modes because a mismatch means the stored artifact is corrupt.

Usage

ledgr_extract_strategy(snapshot, run_id, trust = FALSE)

Arguments

snapshot

A sealed ledgr_snapshot object. Use ledgr_snapshot_load(db_path, snapshot_id) to resume from a durable DuckDB file in a new R session.

run_id

Run identifier.

trust

Logical scalar. If FALSE, return source text and metadata only. If TRUE, verify the stored source hash before parsing/evaluating the source into a function object. Hash verification proves stored-text identity, not safety. Stored source hash mismatches abort even when trust = FALSE.

Value

A ledgr_extracted_strategy object, a list with fields:

run_id

Run identifier.

strategy_source_text

Stored strategy source text, or NA if no source is available.

strategy_source_hash

Stored source hash, or NA if unavailable.

strategy_params

Decoded strategy parameter list.

strategy_params_hash

Stored strategy parameter hash.

reproducibility_level

Stored reproducibility tier.

strategy_type

Stored strategy type.

strategy_source_capture_method

How source was captured.

R_version

R version recorded with the run.

ledgr_version

ledgr version recorded with the run.

dependency_versions

Decoded dependency-version metadata.

trust

Whether trusted recovery was requested.

hash_verified

Whether stored source matched its stored hash.

warnings

Character vector of provenance warnings.

strategy_function

Recovered function object. Present only when trust = TRUE succeeds.

Details

trust = FALSE is the safe provenance-inspection path. It can tell you which source text and parameter artifacts produced a completed run without running that source. trust = TRUE is a recovery path for experiment stores you already trust and intentionally want ledgr to parse/evaluate: it verifies source identity before parsing/evaluating the stored text, but hash verification proves identity only; it is not a code-safety guarantee. Legacy/pre-provenance runs and strategy types without capturable source may return NA for strategy_source_text.

Articles

Durable experiment stores: vignette("experiment-store", package = "ledgr") system.file("doc", "experiment-store.html", package = "ledgr")

Reproducibility model: vignette("reproducibility", package = "ledgr") system.file("doc", "reproducibility.html", package = "ledgr")

Strategy authoring: vignette("strategy-development", package = "ledgr") system.file("doc", "strategy-development.html", package = "ledgr")

Examples

bars <- subset(ledgr_demo_bars, instrument_id == "DEMO_01")
snapshot <- ledgr_snapshot_from_df(utils::head(bars, 10))
strategy <- function(ctx, params) {
  targets <- ctx$flat()
  targets["DEMO_01"] <- params$qty
  targets
}
exp <- ledgr_experiment(snapshot, strategy, opening = ledgr_opening(cash = 1000))
bt <- ledgr_run(exp, params = list(qty = 1), run_id = "qty-1")
ledgr_extract_strategy(snapshot, bt$run_id, trust = FALSE)
#> ledgr Extracted Strategy
#> ========================
#> 
#> Run ID:          qty-1
#> Reproducibility: tier_1
#> Source Hash:     6921e40ec402d0dc2a0d601bdd1a0e53eb33d2add8fd5755579bfd0f9e8433f4
#> Params Hash:     2ce454e7ccd92c56d4b2e92966197efbe2173e3580ce60a9b0e6f6a827de2f03
#> Hash Verified:   TRUE
#> Trust:           FALSE
#> Source Available:TRUE
close(bt)
ledgr_snapshot_close(snapshot)