Skip to contents

Promote a sweep candidate to a committed run

Source: R/sweep.R
ledgr_promote.Rd

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.

Promotion compares the candidate's strategy, feature-set, universe, valuation-policy, corporate-action-policy and opening identities with the promoting experiment's. It does not refuse a difference: it warns with ledgr_promote_identity_mismatch, naming the differing identities, and records both sides in the promotion context's identity_check. A walk-forward candidate, or a sweep saved before these identities were recorded, compares only the strategy and feature set and lists the rest as not_recorded.

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")