Command Line
All commands are subcommands of the fresh-salvage entry point
(equivalently python -m fresh_salvage), take a single YAML or JSON
config path as a positional argument, and share one flag convention:
--json— emit a deterministic, machine-readable JSON summary (sorted keys) instead of the Rich report. Failures also emit a structured JSON diagnostic and exit with code 1.
Conventions
Artifact layout. Run artifacts follow a stable layout under each
config’s output_root: data/ for tabular outputs (parquet plus csv
twins, or JSONL record streams), manifests/ for JSON run manifests
(config snapshot, input checksums, timing, diagnostics), and logs/ for
execution logs. File names are derived from the run_id (or
ensemble_id), so re-running a config overwrites its own artifacts.
Exit codes. Success exits 0. Any failure — config validation, boundary
parse, solver non-optimality, or a structured pipeline error — exits 1 with
a diagnostic. ensemble-run is the exception in detail: per-scenario
failures are recorded, not raised, so a partially failed ensemble still
exits 0 unless --strict is passed (see ensemble-run).
``–json`` shapes. On success the payload is
{"ok": true, "command": <name>, ...summary fields...} where the summary
fields are per-command (run ids, status, objectives, per-period/per-year
volumes, artifact paths, diagnostics). On failure the payload carries
"ok": false and "command" plus the flattened diagnostic fields
("diagnostic"/"message" text, "severity", the structured
"code", and a "context" map).
Structured error codes. Every pipeline layer raises one error class
carrying a machine-readable code (IngestError, WS3Error,
PrincipalError, AgentError, RHError, EnsembleError); codes
are snake_case and layer-prefixed (for example data_severity_unmatched,
ws3_solve_not_optimal, rh_state_duplicate_cohort). The CLI surfaces
the code in the failure diagnostic; Development covers the
convention for contributors.
ingest
Ingest the external WL_VFSL polygon layer into typed stand records for the full TSA.
fresh-salvage ingest examples/scenario_tsa29.yaml [--json]
Config (ScenarioRunConfig):
Field |
Default |
Meaning |
|---|---|---|
|
|
Run identifier; used to name the artifacts. |
|
(required) |
Path to the external WL_VFSL polygon layer CSV. Never vendored. |
|
(required) |
Output root for the artifact layout. |
|
|
Reserved fire-simulation defaults surface
( |
|
Unburned 0.0, Low 0.30, Moderate 0.60, High 0.85 |
Scenario-visible burn-severity ladder (FS-VAL-01). Fractions must lie in [0, 1]. |
|
|
Label normalization map; targets must be ladder labels and sources must not collide with them. |
|
calibrated defaults |
Optional partial override of the economic surface (prices, costs, stumpage, subsidy); see Model Semantics. |
|
|
Free-form run metadata. |
Artifacts: data/<run>-stands.parquet / .csv (246,957 stands on the
real layer), manifests/<run>-manifest.json (source SHA-256, row
drop/retention counts, effective severity ladder and economic parameters,
per-BEC-zone and per-development-type stand counts).
Notable failure codes: ingest_source_missing,
ingest_missing_columns, data_severity_unmatched,
data_coverage_denominator_invalid, data_coverage_numerator_invalid.
ws3-run
Rebuild the WS3 input files, compile the full-TSA model, and solve the wood-supply schedule.
fresh-salvage ws3-run examples/ws3_tsa29.yaml [--json] [--smoke]
--smoke— run the deterministic 3-period smoke profile (workers 2, base year 2025; fast regression gate; output underoutputs/ws3_smokeregardless of the configuredoutput_root).
Config (WS3RunConfig):
Field |
Default |
Meaning |
|---|---|---|
|
|
Run identifier. |
|
(required) |
Path to the WS3 bridge. Point it at the canonical femic bridge and the command first rebuilds the input files from the sibling femic stage-1 Woodstock CSVs (see Model Semantics for the adjustment); an already-rebuilt bridge is used as-is. |
|
(required) |
WS3 base year (2025 for TSA29). |
|
(required) |
Solve horizon in periods (3 smoke / 15 dev / 20 production / 30 validated). |
|
10 |
Years per WS3 period. |
|
999 |
WS3 model age ceiling; bridge ages outside the domain stop the run. |
|
64 |
WS3 tree-generation/build worker threads. Hold fixed for cross-run comparisons (±0.014% objective shift observed). |
|
true |
Compress initial-inventory ages to class midpoints. |
|
10 / 5 |
Smashing rule |
|
|
Harvest action code; constrained to operable ages [60, 300] and removed for never-merchantable curves. |
|
0.85 |
Utilized-volume fraction in the objective
( |
|
0.1 |
Even-flow tolerance (±10%) across periods. |
|
2,937,509 |
AAC ceiling; bounds each period at
|
|
(required) |
Output root. |
|
|
Free-form run metadata. |
Artifacts: data/<run>-schedule.parquet / .csv (columns period,
year, dtype_key, stratum, age_class, area_ha,
harvest_action, volume_m3, etype),
manifests/<run>-ws3-manifest.json (bridge checksums, LP row/column
counts, solve seconds, objective). The derived bridge is materialized
under <output_root>/derived/ws3_bridge_no_lu with the staged CSVs beside
it (<output_root>/derived/woodstock_no_lu_smashed).
volume_m3 is each row’s own harvested totvol. WS3 can emit several
rows (one per Model-I path) for the same (period, dtype_key, age_class,
harvest_action) group, and compile_product reports one total for that
group, so the total is split across the group’s rows by area share
(group_volume * area_ha / group_area; exact, since the rows share a
development type and age). Summing volume_m3 over rows therefore never
double-counts a group, and the manifest objective is utilization times
that sum.
Notable failure codes: ws3_bridge_missing, ws3_bridge_incomplete,
ws3_import_failed, femic_import_failed, ws3_stage1_incomplete,
invalid_age_values, invalid_area_values, area_conservation_failed,
ws3_bridge_age_unsmashed, ws3_action_absent, ws3_solve_failed,
ws3_solve_not_optimal, ws3_schedule_volume_without_area.
principal-run
Build and solve the principal offer LP over the bridge cohorts (standalone; the rolling-horizon engine embeds this layer).
fresh-salvage principal-run examples/principal_tsa29.yaml [--json]
Config (PrincipalRunConfig):
Field |
Default |
Meaning |
|---|---|---|
|
|
Run identifier. |
|
(required) |
Ingestion stands table (parquet or csv) — the DT burn-share and economics source. |
|
(required) |
Derived WS3 bridge ARE section (the cohort units). |
|
(required) |
femic stage-1 yields table (m3/ha by curve and age). |
|
10 |
1-year timesteps to solve (10 = one rolling-horizon step). |
|
2,937,509 |
Green-volume AAC ceiling per year. |
|
null (unbounded) |
Optional annual burned-volume offer cap. |
|
0.85 |
Annual retention of unsalvaged burned volume in the loss term. |
|
calibrated defaults |
Optional partial override of the economic surface. |
|
(required) |
Output root. |
|
|
Free-form run metadata. |
Artifacts: data/<run>-offers.parquet / .csv (per-cohort-year offer
fractions, zeros emitted explicitly; columns cohort_id, year,
offer_fraction), manifests/<run>-principal-manifest.json (input
SHA-256 digests, LP size, solve seconds, objective, per-year offered
volumes).
agent-run
Build and solve the agent harvest/salvage LP over offered cohorts (standalone; the rolling-horizon engine embeds this layer).
fresh-salvage agent-run examples/agent_tsa29.yaml [--json]
Config (AgentRunConfig): the same boundary inputs as the principal
(stands_path, are_path, yields_path, horizon,
decay_rate, economics, output_root, metadata), plus:
Field |
Default |
Meaning |
|---|---|---|
|
0.03 |
NPV discount rate; |
|
1.0 |
Uniform per-cohort-year offer when no offer table is given (1.0 = every cohort fully offered every year). |
|
null |
Optional principal offer table (parquet or csv with |
Artifacts: data/<run>-decisions.parquet / .csv (per-cohort-year
harvest_fraction/salvage_fraction plus m3 volumes, zeros emitted
explicitly), manifests/<run>-agent-manifest.json.
rh-run
Run the rolling-horizon principal-agent coordination loop.
fresh-salvage rh-run examples/rh_tsa29.yaml [--json]
Runs the coupled WS3 -> principal -> agent -> fire pipeline selected by the
config’s planning_mode: rolling_horizon (the default) re-plans every
step, single_pass runs single-pass-run’s whole-run baseline (they share
the dispatcher, so a config is enough to switch).
Config (RHRunConfig):
Field |
Default |
Meaning |
|---|---|---|
|
|
Run identifier. |
|
(required) |
Stands table, femic stage-1 yields, and WS3 bridge (rebuilt from the staging export once per run when canonical). |
|
2025 |
Calendar year of step 1. |
|
15 |
WS3 periods solved per step (15 dev / 20 production). |
|
10 |
Implemented years per step (1 is the degenerate annual alternative). |
|
10 |
Implemented rolling-horizon steps (10 x 10 years = 100 years). |
|
|
|
|
false |
Single pass only: drop the burned inventory at decade boundaries, mimicking the rolling-horizon boundary (D4). |
|
999 |
WS3 model age ceiling. |
|
64 |
Per-step WS3 worker threads (see the ±0.014% numerics caveat). |
|
enabled, width 10, midpoint 5 |
Same semantics as |
|
|
Same semantics as |
|
2,937,509 |
Green AAC ceiling passed to both WS3 and the principal LP. |
|
0.85 |
Burned-inventory annual retention. |
|
0.03 |
Agent NPV discount rate. |
|
null (unbounded) |
Optional principal burned-volume offer cap. |
|
3.0 |
Salvage subsidy ($/m3 of burned volume salvaged): a cost in the principal cashflow, revenue in the agent margin. |
|
calibrated table |
Flat grade-price map (13 canonical keys; must match exactly). |
|
0.65 |
Burned prices derive as green x discount. |
|
45.0 / 56.0 |
Harvest costs ($/m3). |
|
30.0 / 38.0 |
Haul costs ($/m3). |
|
15.0 / 0.25 |
Stumpage rates ($/m3). |
|
1.0 |
Scales every MFRI burn rate (the future-fire-pattern ensemble axis; 0.0 = fire-free counterfactual). |
|
(required) |
Output root. |
|
|
Free-form run metadata. |
The flat economic fields exist (instead of a nested economics section)
so the ensemble driver can vary any of them as a named axis.
Artifacts: data/<run>-steps.jsonl (one record per implemented step:
objectives, solve seconds, annual green/salvage volumes, area burned, wall
time; flushed incrementally so a failed run leaves its partial trajectory),
data/<run>-final-state.csv (terminal cohort table),
data/<run>-step-NN-schedule.csv / -offers.parquet /
-decisions.parquet per step, derived/rh_state/step_NN.are (canonical
injected cohort states), manifests/<run>-rh-manifest.json (run status
optimal/degraded, totals, source_sha256 digests, config
snapshot, embedded step records).
single-pass-run
Run the single-pass whole-run planning baseline: one WS3 solve at t=0 over
horizon periods (only periods 1..steps implemented), one principal and
one agent LP over steps * period_length years, and one lineage replay that
regenerates everything that leaves the live pool at each decade boundary.
This is the baseline rh-run (decadal re-planning) is compared against;
the full semantics — the interpretation guard (deterministic fire, so the
comparison measures re-planning and structural effects, not information
value), the decadal growth surface, the grade clock, the burned-stock
carry/reset, and the D7/D8 record-comparability rules — are in
Model Semantics.
fresh-salvage single-pass-run examples/single_pass_tsa29.yaml [--json]
Config: the same RHRunConfig as rh-run. The command forces
planning_mode: single_pass (the command name is the intent) through a
full re-validation, so the single-pass cross-field preconditions still fail
fast at this boundary:
planning_mode: single_passrequireshorizon >= steps— the one WS3 solve must cover every implemented period (D1).It also requires the P8.1 schedule age-lattice preconditions: age smashing enabled,
period_lengthdivisible by the smashing width, and the smashing midpoint off the WS3 regeneration residue (the 10/10/5 defaults satisfy them).burned_stock_reset: trueis accepted here (and rejected withrolling_horizon): it drops the burned inventory at decade boundaries, mimicking the rolling-horizon boundary (D4).
A minimal config (every other field takes the rh-run default):
run_id: tsa29-single-pass
stands_path: outputs/full_tsa/data/tsa29-full-stands.parquet
yields_path: /path/to/femic-tsa29/woodstock_yields.csv
bridge_path: /path/to/femic-tsa29/ws3_bridge
base_year: 2025
horizon: 15 # WS3 periods solved at t=0 (>= steps)
period_length: 10 # implemented years per decade
steps: 10 # 10 x 10 = 100 LP years
planning_mode: single_pass
burned_stock_reset: false
output_root: outputs/single_pass_100yr_dev
Artifacts: data/<run>-steps.jsonl (one record per replayed decade: the
annual green/burned arrays sliced from the 100-year agent result, the
replay’s area_burned_ha, per-decade objectives re-based to the decade
start and to the run base year; the WS3 fields are populated for decade 1
only, D8), data/<run>-final-state.csv, data/<run>-schedule.csv (the
one horizon-period schedule), data/<run>-offers.parquet /
-decisions.parquet (both steps * period_length years),
derived/rh_state/step_{k:02d}.are for k = 0..steps (the replay’s
decade-boundary states), and manifests/<run>-rh-manifest.json with
planning_mode="single_pass" plus the base-year run totals.
Notable failure codes: single_pass_failed (wraps any fatal layer error;
the inner code, such as ws3_solve_not_optimal or
rh_area_conservation_failed, is quoted in the message),
single_pass_run_failed (the command-level fallback, including config
parse and validation errors), the library guards
single_pass_planning_mode_required / single_pass_horizon_too_short
(the CLI’s forced re-validation normally reports these as config errors),
and the replay guards single_pass_invalid_shape,
single_pass_invalid_regeneration_age,
single_pass_schedule_shape_mismatch, single_pass_burn_rate_unknown,
single_pass_burn_rate_invalid,
single_pass_curve_age_cap_missing,
single_pass_fire_simulation_failed,
single_pass_state_empty_after_decade, single_pass_cohort_alignment,
and single_pass_objective_decomposition_missing.
Not comparable across modes: the WS3 objective (D8). Single pass solves the WS3 problem once and fills the WS3 fields on decade 1 only; rolling horizon solves one WS3 problem per step. Compare the principal/agent objectives (decade-start re-based in the records, base-year re-based in the manifest totals) instead, never a summed WS3 objective.
ensemble-run
Run a scenario ensemble of rolling-horizon runs in parallel.
fresh-salvage ensemble-run examples/ensemble_tsa29.yaml [--json] [--strict]
Config (EnsembleConfig):
Field |
Default |
Meaning |
|---|---|---|
|
|
Ensemble identifier; used to name the artifacts. |
|
|
Shared |
|
|
Named |
|
|
Alternative to |
|
4 |
Concurrent scenario processes (1 = sequential in-process debug profile). |
|
(required) |
Ensemble output root; each scenario writes under
|
|
|
Free-form metadata. |
Partial vs fatal semantics. A failed scenario is recorded with
status: failed and the structured error code (RHError.code or the
exception type name); it never aborts the ensemble, and a worker that dies
without returning is captured as ensemble_worker_crashed. The ensemble
status is ok (no failures), partial (some failed), or failed
(all failed) — all three exit 0. The command exits non-zero only on
fatal grid, input, or bridge failures before or around the scenario runs
(ensemble_axis_unknown, ensemble_axis_empty,
ensemble_duplicate_scenario, ensemble_field_reserved,
ensemble_scenario_invalid, ensemble_input_missing,
ensemble_bridge_failed).
``–strict`` exit-code gate. With --strict a completed ensemble
exits 0 only when the status is ok; partial or failed exits 1.
Without the flag, every completed ensemble exits 0 regardless of scenario
failures. Fatal grid/input/bridge failures exit 1 in both modes, and the
--json payload shape is unchanged — the flag gates the exit code only.
Artifacts: data/<ensemble>-scenarios.jsonl (one record per scenario in
deterministic grid order — name, overrides, status, error code, wall
seconds, per-scenario artifact paths), manifests/<ensemble>-ensemble-manifest.json
(grid config digest, input and bridge checksums, outcomes), the once-built
shared bridge under <output_root>/derived/ws3_bridge_no_lu, and
the full per-scenario rolling-horizon artifact set under
<output_root>/<scenario>/. See Scenario Ensembles for the parallelism
model, performance budgets, and a worked sweep.
sensitivity-run
Run one-at-a-time sensitivity sweeps and compare rolling-horizon outputs.
fresh-salvage sensitivity-run examples/sensitivity_tsa29.yaml [--json] [--strict]
Config (SensitivityConfig):
sensitivity_id— analysis identifier.base— sharedRHRunConfigfields.run_idandoutput_rootare assigned by the driver;bridge_pathmust be provided here.parameters— mapping ofRHRunConfigfield names to value lists.Each parameter is run independently and the baseline value is added when absent.
flip_point_search— optional adaptivesubsidy_rate_per_m3search run once for every setting of each non-subsidy parameter. It uses the samelower,upper,iterations,tolerance,threshold, andmetricfields as an ensemble binary search. These searches are sequential regardless ofmax_workers.max_workers— concurrent scenarios within each parameter sweep.output_root— root for sensitivity outputs and per-parameter runs.
Artifacts include reports/<id>-results.md with the effective settings,
examined scenarios, outcomes, and signed baseline changes;
data/<id>-observations.jsonl with scenario metrics;
data/<id>-comparisons.csv with baseline/range/direction analysis; and
when configured, data/<id>-flip-points.csv with the inactive/active
subsidy bracket for each non-subsidy setting; and
manifests/<id>-sensitivity-manifest.json. --strict returns exit code 1
when any scenario fails.
export
Reserved for the tabular export phase. The command currently exits 1 with
a not-implemented diagnostic, including under --json; do not build
workflows on it until the roadmap records the export phase.