Promote a sweep candidate to a committed run

Replays a selected sweep candidate through ledgr_run() so the result becomes a durable experiment-store run artifact.

Usage

ledgr_promote(
  exp,
  candidate,
  run_id,
  note = NULL,
  require_same_snapshot = TRUE
)

Arguments

exp

A ledgr_experiment.

candidate

A ledgr_sweep_candidate.

run_id

Non-empty run identifier for the committed run.

note

Optional plain-text note. Stored by the promotion-context ticket.

require_same_snapshot

Logical. If TRUE, require the candidate provenance snapshot hash to match exp. Defaults to TRUE; train/test promotion must opt into cross-snapshot execution with FALSE.

Value

A committed ledgr_backtest.

Details

ledgr_promote() commits a selected sweep candidate by calling ledgr_run() with the candidate strategy params, feature params, and exact execution_seed. This is the slow/materialized path: the sweep keeps only compact candidate summaries and the reproduction key available through ledgr_candidate_reproduction_key(), while promotion explicitly pays the cost to create durable ledger, equity, telemetry, and promotion-context artifacts. Runs created this way store durable promotion context that can be read with ledgr_promotion_context() or ledgr_run_promotion_context(). Hash fields carried from the candidate into promotion evidence are summarized in ledgr_identity_fields. Promotion replays the selected candidate's cost model and risk chain even when exp was configured with different cost_model or risk_chain values.

The default require_same_snapshot = TRUE protects same-snapshot replay. For train/test evaluation, pass a candidate selected on the train snapshot to a test-snapshot experiment and set require_same_snapshot = FALSE deliberately.

Articles

Exploratory sweeps and promotion: vignette("sweeps", package = "ledgr") system.file("doc", "sweeps.html", package = "ledgr")