Run walk-forward evaluation — ledgr_walk

ledgr_walk_forward() orchestrates fold-local train sweeps, deterministic scalar candidate selection, and selected-candidate test runs over the existing ledgr_sweep() and ledgr_run() execution machinery. The returned object carries a degradation table that compares the selected train score to the selected test score before secondary result surfaces.

Usage

ledgr_walk_forward(
  exp,
  grid,
  folds,
  selection_rule,
  seed = NULL,
  opening_state_policy = c("carry_test_state", "flat_test_state"),
  no_selection = c("previous", "fail"),
  workers = 1L,
  worker_packages = NULL,
  ...
)

Arguments

exp: A ledgr_experiment.
grid: An ordinary rectangular data frame, a ledgr_strategy_grid, or a ledgr_executable_grid.
folds: A ledgr_fold_list.
selection_rule: A rule created by ledgr_rule_argmax() or ledgr_rule_argmin().
seed: Optional master seed for deterministic per-row execution seeds.
opening_state_policy: Either "carry_test_state" or "flat_test_state". The default carries selected test-run terminal state into the next test run and requires contiguous test windows (see Details). Flat-test state is an explicit cold-start opt-in.
no_selection: What a fold does when no training candidate has a finite, DONE selection metric. "previous" (the default) runs the test window with the parameters most recently selected from a training window, or, before any training window has selected, runs no test window and leaves the carried opening unchanged. "fail" stops the session with ledgr_walk_forward_no_selection. Each fold records its selection_source ("train", "previous" or "none"), and the policy is part of the session identity.
workers: Whole-number worker count used by each fold's training sweep. The default 1 is sequential; 2 uses the supported staged local-worker path. Larger counts run but are not part of the measured history-worker support claim. Worker count is not research identity.
worker_packages: Optional character vector of packages to attach on parallel training workers for unqualified package calls in strategy code.
...: Reserved for later walk-forward options.

Value

A ledgr_walk_forward_results list with folds, scores, selected, degradation, and selected test-run handles.

Details

v1 walk-forward scores scalar train-window candidates, selects one candidate per fold, and runs only that selected candidate on the matching test window. It is not PBO, CSCV, CPCV, DSR, benchmark-relative diagnostics, OMS, paper/live trading, or a selection-integrity correction. Walk-forward evidence is only as survivorship-safe as the sealed snapshot and universe semantics it evaluates.

With the default opening_state_policy = "carry_test_state", test windows are path-dependent: each completed selected test run can seed the next test opening state. Per-fold test metrics are therefore not independent. Carrying needs test windows in time order that touch exactly: when a trading day lies between two consecutive test windows, positions would cross it unvalued, and when a test window starts before the previous one ends (overlap or reverse order), it would open from that window's later state. The call refuses both before running anything, with ledgr_walk_forward_gapped_carry or ledgr_walk_forward_overlapping_carry. Use folds whose step equals test_window, or "flat_test_state", which accepts any layout.

Rerunning a session with the same arguments reuses its finished test runs as recorded and resumes a test run that an interruption left unfinished. Fold boundaries on the snapshot's first or last date resolve to its first or last session; a date outside the snapshot refuses. Anchored fold definitions intentionally grow the train window over time, so compute cost grows with later folds and larger candidate grids. metric_diff_abs is test_metric_value - train_metric_value; whether a positive value indicates improvement or degradation depends on the selection rule direction.

In an availability-aware session every training and test window reads feature, mark and entitlement history from the data start (the first session of the snapshot) through one shared causal preparation; windows only bound decisions. Under "carry_test_state" the test windows form one economic chain: each window except the last executes its final decision at the following session's open, and the next window opens from the resulting cash, positions, FIFO lots, unsettled corporate-action entitlements and frozen holdings. Strategy state does not cross a window. The chain equals one run with the selected parameters switching at the same decision pulses. The last window, "flat_test_state" windows and standalone runs keep the terminal rule: a final decision is recorded but not executed. Dense sessions keep their per-window feature start. This is separate from cold_start_distorted, which concerns opening positions, not features.