CSPI asymptote covariate (#75 step 3) — draft, mechanism only

[holoros]

CSPI site-productivity asymptote covariate (#75 step 3) — DRAFT, mechanism only

Adds CSPI (climate site productivity index) as a covariate that scales the per-cell
yield-curve asymptote in the canonical FIADB engine, behind the YCX_CSPI_ASYM flag.
Default OFF; the live ycx_canonical_ci_fiadb.R is untouched. This PR adds the
mechanism and provenance only. It does not regenerate live data or change any published
number. See docs/decisions/0005-cspi-asymptote-covariate.md.

What this does

• Raster covariate, not a plot join. The intended CSPI ID → PLT_CN join (feat(economics): cost-of-carbon-floor card in the Faustmann tab #76) is
  blocked (CSPI build coordinates do not match the FIA true-coordinate convention, 0%
  match). Instead, sample the wall-to-wall 1 km CSPI surface at FIA plot coordinates on
  Cardinal and aggregate to the fit cell key (ft_group|prov_code). FIA true coordinates
  never leave the cluster; only the coordinate-free ycx_cell_cspi.csv (873 cells) is
  emitted.
• Scaling form: A_scaled = A * (1 + shrink*(clamp((CSPI/REF)^beta) - 1)),
  REF=56.36, beta=1.0, clamp [0.80,1.25], shrink=30/(30+n_plots).
  The free-fit exponent (2.77 within forest type, 3.13 pooled) was rejected as
  confound-amplified (productive ecoregions carry both high CSPI and high-biomass forest
  types; CSPI explains only ~9% of asymptote spread).
• t0-preserving: a second flagged block re-anchors area for non-FIA states so the
  scaled run reproduces baseline t0.

Verified (rcp45, full 48-state CONUS run)

	t0 (2025)	2125
CONUS reserve	+0.02%	−0.00%

Per-state 2125 delta: −0.39% (MA) to +0.72% (SD), median +0.00%. 360 of 873 cells (41%)
are sparse and get full CSPI weight (mean scalar 0.976). Redistributive at cell/state
scale, neutral at the CONUS aggregate.

Files

• scripts/yield_curve_engine/cspi/ — extraction, scaling module, flagged engine,
  reconcile script, diagnostic figure, README.
• scripts/yield_curve_engine/canonical_inputs/ycx_cell_cspi.csv — the covariate table.
• docs/decisions/0005-cspi-asymptote-covariate.md — the ADR.

Blocking before merge (team decision)

• Sign off on beta (default 1.0) and the clamp half-width (default ±25%) — same
  status as the senescence S_SEN knob.
• On sign-off: regenerate canonical CI with the flag on, validate t0 vs FIA, bump
  Zenodo to v1.2.

Draft until the two knobs are confirmed.

[holoros]

Stress-test update (2026-06-27). Knob sweep + spatial CV + Bakuzis site-ordering. Key finding: CSPI generalizes out-of-sample on the remeasurement asymptotes (leave-one-ecoregion-out held-out log-RMSE 0.783 to 0.716, +8.5%, within-ft partial r +0.37) but not on the hybrid production fits this flagged engine currently scales (+0.0%, r +0.08; hybrid A is noisier and a different peak-decline parameter). Knob sweep robust (~3% A-weighted change at beta=1.0/clamp 25%). Bakuzis site-ordering PASS (monotone, non-crossing). Re-scope: apply CSPI to the Block 1+3 remeas refit at promotion, not the hybrid engine. Keep draft. See scripts/yield_curve_engine/cspi/20260627_cspi_stress_bakuzis_assessment.md and ADR 0005.