Architecture

fresh-salvage implements a linear principal-agent salvage-subsidy pipeline for the Williams Lake Timber Supply Area (TSA29). The predecessor Gurobi binary stand-level models are re-implemented as continuous linear programs solved with HiGHS through highspy; the durable source of truth is typed data records, compiled WS3 schedules, explicit LP formulations, and verification evidence — not one-off script chains.

Data Flow

external VRI polygon layer (WL_VFSL)          femic TSA29 package
(246,957 stands; 2025 severity layer)         (stage-1 Woodstock CSVs +
             |                                 validated WS3 bridge)
             v                                          |
(1) data: ingestion, typed stand records                v
     severity ladder, coverage scaling,        (2) ws3: bridge rebuild
     economic surface at the boundary                (1,608 aggregated cohorts),
             |                                   full-TSA schedule solve under
             |                                   the 2,937,509 m3/yr AAC ceiling
             +----------------+-------------------------+
                              v
                 (3) principal: offer-fraction LP
                     (1-year timesteps, green AAC ceiling)
                              v
                 (4) agent: harvest/salvage LP
                     (annual MFRI fire dynamics, NPV)
                              v
                 (5) rh: rolling-horizon engine
                     (10 decadal steps, in-memory inventory injection,
                      fire replay, area-conserving transitions)
                     single_pass: whole-run baseline
                     (one t=0 WS3 solve, one principal/agent LP over
                      steps x period_length years, one lineage replay)
                     ensemble: scenario-grid driver
                     (cartesian axes, spawn process pool)
                              v
          run manifests and tabular artifacts (parquet/csv/JSONL)

The standalone commands (ingest, ws3-run, principal-run, agent-run) exercise layers 1-4 individually against on-disk boundary artifacts; rh-run couples all layers in memory with the canonical ARE round-trip per step (or dispatches to single_pass by planning_mode); ensemble-run replicates that coupled run over a scenario grid.

Module Map

models

Pydantic v2 data models for inputs, configs, decisions, results, and manifests (ScenarioRunConfig, WS3RunConfig, PrincipalRunConfig, AgentRunConfig, RHRunConfig, EnsembleConfig, the *Manifest and *Result records, ArtifactLayout, Diagnostic). Config classes carry read()/write_json() helpers; validation fails at parse time.

data

Ingestion of the external stand layer at the pipeline boundary: severity ladder and coverage scaling (FS-VAL-01/02), species/grade volume splits, development-type derivation, and the calibrated economic constants every other layer defaults to.

ws3

Full-TSA WS3 input rebuild (raw ages snap to class midpoints, femic’s writer re-groups, sums, and writes the Woodstock files, and area conservation is checked to 1e-6 — see Model Semantics) and schedule solve (cc action at operable ages [60, 300], AAC ceiling via cgen_data, even flow, HiGHS). ws3 and femic are imported lazily so the pure helpers stay unit-testable without them.

principal

Principal-side continuous HiGHS LP for salvage-subsidy offers (offer fractions, expected burned-wood loss, green AAC ceiling, optional burned cap).

agent

Agent-side continuous HiGHS LP for harvest/salvage decisions; its rows implement the fire.py dynamics directly.

fire

The MFRI burn-rate table and the pure annual fire-dynamics primitives (simulate_cohort_years drives full-horizon replays and stops with an error on infeasible schedules). Single source of truth for the dynamics.

rh

Rolling-horizon coordination loop: cohort state table (ARE round-trip), in-memory period-0 inventory injection, decadal-to-annual ceiling split, principal/agent coupling, fire replay, area-conserving transitions. Also the multi-period schedule-to-cohort ceiling mapper (P8.1) and the run_planning dispatcher that selects an engine by planning_mode.

single_pass

Single-pass 100-year planning baseline: one WS3 solve at t=0, per-cohort per-year WS3 ceilings, one principal/agent LP pair over steps * period_length years with the decadal growth surface, grade clock, and burned-stock semantics, then one decade-block lineage replay (replay_lineage) that ages survivors, regenerates everything that left the live pool at the smashing midpoint, and writes the decade-boundary state snapshots. Emits the rh-run-comparable decade records.

ensemble

Scenario-grid driver: cartesian expansion over named RHRunConfig axes, spawn-based process pool, shared read-only bridge, per-scenario failure isolation, deterministic grid-order output.

io

Tabular and JSON artifact input/output helpers.

cli / __main__

Thin Typer wrappers over the module APIs (fresh-salvage entry point and python -m fresh_salvage); they own only argument parsing, the --json/Rich reporting, and the failure-diagnostic conversion.

rolling_horizon

Reserved Phase-0 scaffold stub (docstring only); the implemented engine is rh. Import nothing from it.

The detailed refactor contract for the predecessor-to-linear migration is documented in planning/phase0-refactor-contract.md; the as-built model equations are documented in Model Semantics.

Design Invariants

Hold these when extending the package; each exists because its violation already happened upstream once.

femic owns the Woodstock text. The WS3 input files are written by femic’s own stage-2 writer (femic.ws3_bridge.build_ws3_sections_from_femic_woodstock); fresh-salvage adjusts the staging table (snaps ages to class midpoints), hands it to that writer — which re-groups rows on the remaining key and sums areas — and then verifies the written bridge (theme count as expected, ages on the midpoint lattice, ARE area conserved to 1e-6 against staging — the writer silently drops area rows whose (tsa, ifm, au_id) key has no curve). Never hand-write bridge sections here.

fire.py is the single source of truth for dynamics. The agent LP rows are the same harvest -> fire -> salvage -> decay equations as simulate_cohort_years; the rolling-horizon replay calls the simulation directly. A semantics change lands in fire.py and propagates; it is never patched into one consumer.

Boundary parsing, then trust. External inputs are parsed once into typed Pydantic records at the module boundary with fail-fast structured errors; core logic contains no defensive re-validation and no silent defaults.

Continuous LPs only. No integer or binary variables, no thresholding or rounding of decision outputs; zero decisions are emitted explicitly so downstream panels are complete.

Structured fail-fast codes. Each layer raises one *Error(code, message) class; the CLI surfaces the code in its diagnostic. See Development for the convention.

Provenance on every run. Every command writes a manifest with input SHA-256 digests and the full effective config; outputs/ and other local working areas stay uncommitted (see AGENTS.md).

Glossary

AAC

Annual Allowable Cut — the regulator’s annual harvest ceiling, here 2,937,509 m3/yr, applied to offered green volume.

AU (analysis unit)

WS3/Woodstock stratification unit within a TSA; the validated femic TSA29 instance carries 54 AUs (18 strata x 3 site-index levels).

DT (development type)

The stand-level stratum key {leading_species_group}_{BEC} (for example SPF_SBPS) assigned at ingestion; also the WS3-side unit that carries the period-0 inventory age map.

IFM

Initial Forest Management (managed/unmanaged) dimension of the WS3 bridge key; the TSA29 bridge carries 2 IFMs.

MFRI

Mean Fire Return Interval (years) of a BEC zone; the annual burn probability is 1 / MFRI.

Stratum / stratum code

The WS3 bridge stratum {bec_zone}_{leading_species} (lowercase, for example sbps_pli); the fire-rate lookup parses the BEC zone prefix.

THLB

Timber Harvesting Land Base — the Crown forest land base available for harvest after netdowns; the AAC applies to it.

TSA

Timber Supply Area — the BC timber-supply management unit; TSA29 is Williams Lake (~4.93 Mha).

VRI

Vegetation Resources Inventory — the BC polygon forest inventory layer; WL_VFSL.csv is the TSA29 extract joined with burn-severity attributes.

VDYP / TIPSY

The BC yield models behind the femic curve tables: VDYP (Variable Density Yield Prediction, natural stands) and TIPSY (Table Interpolation Program for Stand Yields, managed stands). Curves enter this package as the femic stage-1 woodstock_yields.csv keyed by curve_id.

WS3

The open-source wood supply model (UBC FRESH) this package drives through its Python API; schedules are compiled from Woodstock-format bridge files (.lan/.are/.yld/.act/.trn).

femic

The FRESH-ecosystem package whose stage-1/stage-2 pipeline produces the validated TSA29 Woodstock CSVs and WS3 bridge this package consumes.

FESBC

Forest Enhancement Society of BC — the empirical salvage-support benchmark (~14-15 $/m3) the calibrated flip point is compared against.

BEC

Biogeoclimatic Ecosystem Classification — the zone system behind the MFRI table (SBPS, SBS, MS, IDF, ESSF, ICH, …).

LP

Linear program — an optimization problem with a linear objective and linear constraints. Every optimization layer in this package is a continuous LP solved by HiGHS.

NPV

Net present value — future cashflows discounted to today at the configured discount rate (3%/yr by default).

Stumpage

The per-m3 fee a BC licensee pays the Crown for standing timber; fire-damaged timber is charged at the tabular floor (0.25 $/m3 by default here).