From c8da0c72bce48628e94e7af96c1d995b897dadc4 Mon Sep 17 00:00:00 2001
From: Koen van Greevenbroek <koenvg@stanford.edu>
Date: Wed, 1 Jul 2026 13:40:27 -0700
Subject: [PATCH] feat: tie calibration artefact sets to configs via provenance
 stamps

Calibration artefacts now live in per-config sets under
data/curated/calibration/<source>/, selected by the new
calibration.source config key (a {calibration_source} placeholder in
artefact paths, resolved at config-load time). Each set carries a
provenance.yaml stamp of the structural config it was calibrated
against; every workflow run checks its config against the stamp of the
set it consumes and errors on structural mismatch.
calibration.accept_provenance_mismatch downgrades the error to a
warning for configs where calibration fidelity is irrelevant (test,
tutorials).

tools/calibrate gains --base <config> to calibrate a dedicated set for
a structurally divergent config: the base must declare its own
calibration.source, a fresh set is seeded from the default set, the
chain runs under name=calibration-<source> to keep processing trees
separate, and the set is (re)stamped after each successful run.
tools/calibrate --check also reports provenance drift.
---
 .claude/skills/model-calibration/SKILL.md     |  43 +-
 AGENTS.md                                     |  21 +-
 REUSE.toml                                    |   8 +
 config/default.yaml                           |  37 +-
 config/schemas/config.schema.yaml             |  15 +
 config/tutorial/01_ghg_prices.yaml            |   5 +
 config/tutorial/02_consumer_values.yaml       |   5 +
 .../calibration/{ => default}/animal_cost.csv |   0
 .../calibration/{ => default}/crop_cost.csv   |   0
 .../{ => default}/deviation_penalty.yaml      |   0
 .../{ => default}/exogenous_feed.csv          |   0
 .../{ => default}/exogenous_forage.csv        |   0
 .../{ => default}/fodder_conversion.csv       |   0
 .../calibration/{ => default}/food_demand.csv |   0
 .../calibration/{ => default}/food_waste.yaml |   0
 .../{ => default}/grassland_cost.csv          |   0
 .../{ => default}/grassland_yield.csv         |   0
 .../calibration/default/provenance.yaml       | 853 ++++++++++++++++++
 docs/calibration.rst                          |  58 +-
 docs/configuration.rst                        |  13 +-
 docs/costs.rst                                |   6 +-
 docs/livestock.rst                            |  20 +-
 tests/config/test.yaml                        |   6 +
 tests/test_calibration_provenance.py          | 184 ++++
 tests/test_production_stability.py            |   2 +-
 tools/calibrate                               | 169 +++-
 tools/export_model.py                         |   3 +-
 tools/smk                                     |   2 +-
 workflow/Snakefile                            |   5 +
 workflow/scripts/solve_namespace.py           |  27 +-
 .../scripts/write_calibration_provenance.py   | 118 +++
 workflow/validation/__init__.py               |   2 +
 workflow/validation/calibration_provenance.py | 173 ++++
 33 files changed, 1702 insertions(+), 73 deletions(-)
 rename data/curated/calibration/{ => default}/animal_cost.csv (100%)
 rename data/curated/calibration/{ => default}/crop_cost.csv (100%)
 rename data/curated/calibration/{ => default}/deviation_penalty.yaml (100%)
 rename data/curated/calibration/{ => default}/exogenous_feed.csv (100%)
 rename data/curated/calibration/{ => default}/exogenous_forage.csv (100%)
 rename data/curated/calibration/{ => default}/fodder_conversion.csv (100%)
 rename data/curated/calibration/{ => default}/food_demand.csv (100%)
 rename data/curated/calibration/{ => default}/food_waste.yaml (100%)
 rename data/curated/calibration/{ => default}/grassland_cost.csv (100%)
 rename data/curated/calibration/{ => default}/grassland_yield.csv (100%)
 create mode 100644 data/curated/calibration/default/provenance.yaml
 create mode 100644 tests/test_calibration_provenance.py
 create mode 100644 workflow/scripts/write_calibration_provenance.py
 create mode 100644 workflow/validation/calibration_provenance.py

diff --git a/.claude/skills/model-calibration/SKILL.md b/.claude/skills/model-calibration/SKILL.md
index 1744bd72..e56e5754 100644
--- a/.claude/skills/model-calibration/SKILL.md
+++ b/.claude/skills/model-calibration/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: model-calibration
-description: Run, refresh, or diagnose the model's calibration pipeline (feed -> food_waste -> food_demand -> cost -> stability) that produces the git-tracked artefacts under `data/curated/calibration/`. Covers the dependency order, the `tools/calibrate` wrapper, realistic runtime expectations, when each kind of upstream change forces a re-run, and how to diagnose the most common failure mode: a hidden supply/demand mismatch that inflates the production-stability L1 cost. Use whenever calibration is relevant -- the user touches inputs/build logic that feed the calibration solves, calibration artefacts look off, or a refresh of the artefacts is needed after a model/data change.
+description: Run, refresh, or diagnose the model's calibration pipeline (feed -> food_waste -> food_demand -> cost -> stability) that produces the per-config artefact sets under `data/curated/calibration/<source>/` (the default set is git-tracked). Covers the dependency order, the `tools/calibrate` wrapper, realistic runtime expectations, when each kind of upstream change forces a re-run, and how to diagnose the most common failure mode: a hidden supply/demand mismatch that inflates the production-stability L1 cost. Use whenever calibration is relevant -- the user touches inputs/build logic that feed the calibration solves, calibration artefacts look off, or a refresh of the artefacts is needed after a model/data change.
 ---
 
 <!--
@@ -11,12 +11,19 @@ SPDX-License-Identifier: CC-BY-4.0
 
 # Model Calibration
 
-The default workflow consumes five git-tracked calibration artefacts under
-`data/curated/calibration/`. Each is produced by a dedicated validation-mode
-solve and absorbs a specific class of residual mismatch so that ordinary
-solves don't have to. Without these files in place, production-stability,
+The default workflow consumes five calibration artefact groups organized
+in per-config *sets* under `data/curated/calibration/<source>/`, selected
+by the `calibration.source` config key (the `default` set is
+git-tracked). Each is produced by a dedicated validation-mode solve and
+absorbs a specific class of residual mismatch so that ordinary solves
+don't have to. Without these files in place, production-stability,
 costs, and food/feed accounting drift from observed 2020 reality.
 
+Every set carries a `provenance.yaml` stamp of the structural config it
+was fit against; workflow runs error at DAG time when their config
+differs structurally from the consumed set's stamp (see "Artefact sets
+and provenance" below).
+
 Authoritative reference: `docs/calibration.rst`. This skill is the operational
 companion: when to run, how to run, what to expect, what to watch out for.
 
@@ -58,12 +65,20 @@ tools/calibrate food_waste
 tools/calibrate food_demand
 tools/calibrate cost
 tools/calibrate stability
-tools/calibrate --check      # per-step staleness probe (dry-run, no execution)
+tools/calibrate --check      # per-step staleness + provenance probe (no execution)
+tools/calibrate --base config/<name>.yaml [all|<step>|--check]
+                             # calibrate a dedicated set for another config
 ```
 
 The wrapper defaults to `pixi -e gurobi` -- all calibration configs use
 Gurobi. HiGHS is too slow here. Override with `CALIBRATE_PIXI_ENV=<env>`.
 
+With `--base`, the base config must declare its own `calibration.source`
+(refusing to overwrite the shared `default` set); a fresh set is seeded
+from `default` and regenerated in order, and the `all` chain uses
+`name: calibration-<source>` so processing trees don't thrash. After any
+successful run the set is (re)stamped with `provenance.yaml`.
+
 Pass extra flags through positionally:
 
 ```bash
@@ -153,13 +168,21 @@ sequential (each Broyden iteration depends on the previous solve).
 
 ## Output landing zones
 
-- `data/curated/calibration/*` -- the five artefacts, **git-tracked**. Commit them together as a refresh; mixed-vintage artefacts are the most common cause of confusing downstream solves.
-- `processing/calibration/*` -- shared upstream prep, NOT committed.
+- `data/curated/calibration/<source>/*` -- one artefact set per base config, plus its `provenance.yaml` stamp; the `default` set is **git-tracked**. Commit a set together as a refresh; mixed-vintage artefacts are the most common cause of confusing downstream solves.
+- `processing/calibration/*` (or `processing/calibration-<source>/*` for non-default bases) -- shared upstream prep, NOT committed.
 - `results/calibration/*` -- per-iteration solve logs, NOT committed.
 - `results/calibration/calibration/deviation_penalty_trace.csv` -- per-iter Broyden trace (per-component lambda, achieved deviations, residual norm). Inspect when stability behaves oddly.
 
+## Artefact sets and provenance
+
+- A config selects its set with `calibration.source` (default: `default`); all artefact paths resolve through the `{calibration_source}` placeholder at config-load time.
+- Structurally divergent configs must either calibrate their own set (`calibration.source: <name>` + `tools/calibrate --base config/<name>.yaml`), point at a compatible set, or set `calibration.accept_provenance_mismatch: true` (test/tutorial-grade escape hatch: warning instead of error).
+- The provenance check covers config drift only; code/data staleness remains `tools/calibrate --check`'s job. Both run from `tools/calibrate --check`.
+- The stamp compares all non-solve-time leaves minus exempt machinery keys (see `PROVENANCE_EXEMPT_PREFIXES` in `workflow/validation/calibration_provenance.py`). Solve-time knobs (GHG price, value_per_yll, deviation_penalty, scenario overrides) never trip it.
+- `tests/test_calibration_provenance.py::TestDefaultStampConsistency` fails when `config/default.yaml` changes structurally without a recalibration/restamp -- that is the intended forcing function.
+
 The currently calibrated L1 centre lives in
-`data/curated/calibration/deviation_penalty.yaml` under
+`data/curated/calibration/default/deviation_penalty.yaml` under
 `l1_costs.<component>`. Solves that set
 `deviation_penalty.{land,feed,diet}.l1_cost: "calibrated"` resolve the
 sentinel from this file at solve time. Per-component
@@ -289,7 +312,7 @@ tools/smk --configfile config/validation.yaml -- \
     results/validation/solved/model_scen-default.nc
 
 # Current calibrated L1 centre
-cat data/curated/calibration/deviation_penalty.yaml
+cat data/curated/calibration/default/deviation_penalty.yaml
 
 # Per-iter Broyden trace (after a stability run)
 cat results/calibration/calibration/deviation_penalty_trace.csv
diff --git a/AGENTS.md b/AGENTS.md
index ca2756f5..1dba9424 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -325,14 +325,15 @@ pixi run -e dev pytest -v         # verbose output
 
 ## Calibration
 
-Five calibrations feed the default workflow. Their outputs live under
-`data/curated/calibration/` and are git-tracked; builds depend on them.
-When upstream data or build logic changes materially, regenerate in
-this order:
+Five calibrations feed the default workflow. Their outputs are organized
+in per-config artefact *sets* under `data/curated/calibration/<source>/`
+(selected by the `calibration.source` config key; the `default` set is
+git-tracked) and builds depend on them. When upstream data or build
+logic changes materially, regenerate in this order:
 
 1. **feed** — `config/calibration/feed.yaml` → `grassland_yield.csv`,
    `fodder_conversion.csv`, `exogenous_forage.csv`,
-   `exogenous_protein.csv`.
+   `exogenous_feed.csv`.
 2. **food_waste** — `config/calibration/food_waste.yaml` →
    `food_waste.yaml` (per-food-group consumer-side waste multipliers).
 3. **food_demand** — `config/calibration/food_demand.yaml` →
@@ -354,7 +355,15 @@ Single entrypoint: `tools/calibrate` (`all` by default; `feed`,
 `food_waste`, `food_demand`, `cost`, `stability`, or `--check` for
 staleness). `tools/smk` prints a one-line reminder when
 `data/curated/` inputs are newer than the oldest calibration artefact.
-See `docs/calibration.rst` for the full story.
+
+Each artefact set carries a `provenance.yaml` stamp of the structural
+config it was fit against (written by `tools/calibrate`); every workflow
+run checks its config against the stamp of the set it consumes and
+errors on structural mismatch. Configs with different structural
+assumptions must declare their own `calibration.source` and run
+`tools/calibrate --base config/<name>.yaml`, or set
+`calibration.accept_provenance_mismatch: true` (test/tutorial configs
+only). See `docs/calibration.rst` for the full story.
 
 ## Configuration Validation
 
diff --git a/REUSE.toml b/REUSE.toml
index 99df6266..5395f9cd 100644
--- a/REUSE.toml
+++ b/REUSE.toml
@@ -38,6 +38,14 @@ precedence = "aggregate"
 SPDX-FileCopyrightText = "2026 Koen van Greevenbroek"
 SPDX-License-Identifier = "PDDL-1.0"
 
+# Machine-generated calibration provenance stamps (written by
+# workflow/scripts/write_calibration_provenance.py via tools/calibrate).
+[[annotations]]
+path = "data/curated/calibration/**/provenance.yaml"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2026 Koen van Greevenbroek"
+SPDX-License-Identifier = "CC-BY-4.0"
+
 # Root LICENSE copy so GitHub detects the project license (it only scans the
 # repository root, not LICENSES/). The canonical text lives in LICENSES/.
 [[annotations]]
diff --git a/config/default.yaml b/config/default.yaml
index c6a67a8a..7d8d5fad 100644
--- a/config/default.yaml
+++ b/config/default.yaml
@@ -51,6 +51,23 @@ paths:
   logs_root: "logs"
   benchmarks_root: "benchmarks"
 
+# --- section: calibration ---
+# Which calibration artefact set to use. The five calibration artefact
+# groups (feed, food_waste, food_demand, cost, stability) live under
+# ``data/curated/calibration/<source>/``; every artefact path below that
+# contains the ``{calibration_source}`` placeholder resolves against this
+# key at config-load time. A config whose structural assumptions differ
+# from the set it consumes must either regenerate its own set
+# (``tools/calibrate --base <config>`` with its own ``source`` name) or
+# point ``source`` at a compatible existing set. Compatibility is checked
+# at workflow start against the set's ``provenance.yaml``.
+calibration:
+  source: "default"
+  # Downgrade a provenance mismatch from an error to a warning. Only for
+  # configs that knowingly reuse a set calibrated under different
+  # structural assumptions (e.g. coarse test/tutorial resolutions).
+  accept_provenance_mismatch: false
+
 # --- section: netcdf ---
 # NetCDF export settings for PyPSA network files (build and solve outputs)
 netcdf:
@@ -165,7 +182,7 @@ deviation_penalty:
     tolerance: 0.02
     max_iter: 8
     trust_region_log: 0.693  # log(2): caps |dx|_inf in log-coords per iteration
-    calibrated_yaml: "data/curated/calibration/deviation_penalty.yaml"
+    calibrated_yaml: "data/curated/calibration/{calibration_source}/deviation_penalty.yaml"
     trace_csv: "<results>/{name}/calibration/deviation_penalty_trace.csv"
     seeds:
       cropland: 1.0   # crop deviation reaches the 5% target near L1~1.1
@@ -656,9 +673,9 @@ grazing:
   grassland_forage_calibration:
     enabled: true
     generate: false
-    grassland_yield_correction: "data/curated/calibration/grassland_yield.csv"
-    fodder_conversion_correction: "data/curated/calibration/fodder_conversion.csv"
-    exogenous_forage: "data/curated/calibration/exogenous_forage.csv"
+    grassland_yield_correction: "data/curated/calibration/{calibration_source}/grassland_yield.csv"
+    fodder_conversion_correction: "data/curated/calibration/{calibration_source}/fodder_conversion.csv"
+    exogenous_forage: "data/curated/calibration/{calibration_source}/exogenous_forage.csv"
     scenario: "default"
 
 # Protein-feed calibration: per-country exogenous monogastric/ruminant
@@ -673,7 +690,7 @@ grazing:
 exogenous_feed_calibration:
   enabled: true
   generate: false
-  exogenous_feed: "data/curated/calibration/exogenous_feed.csv"
+  exogenous_feed: "data/curated/calibration/{calibration_source}/exogenous_feed.csv"
   scenario: "default"
 
 # Food waste calibration: a per-food-group multiplier on (1 - waste_fraction)
@@ -685,7 +702,7 @@ exogenous_feed_calibration:
 food_loss_waste_calibration:
   enabled: true
   generate: false
-  calibration_file: "data/curated/calibration/food_waste.yaml"
+  calibration_file: "data/curated/calibration/{calibration_source}/food_waste.yaml"
   food_groups:
   # Groups with documented FBS-vs-GDD gap that the SDG-based defaults
   # under- or over-state. The SDG global all-foods 10% waste rate fits
@@ -716,7 +733,7 @@ food_loss_waste_calibration:
 food_demand_calibration:
   enabled: true
   generate: false
-  calibration_file: "data/curated/calibration/food_demand.csv"
+  calibration_file: "data/curated/calibration/{calibration_source}/food_demand.csv"
   # Bounds on the per-food multiplier. Tight on purpose: anything that
   # would fall outside flags a structural data issue worth investigating
   # rather than being silently absorbed.
@@ -1687,9 +1704,9 @@ cost_calibration:
   enabled: true       # Apply calibration corrections to production costs
   generate: false     # Generate calibration from solved model (breaks DAG cycle when true)
   scenario: "calibration"  # Scenario name used for calibration solve
-  crop_correction_csv: "data/curated/calibration/crop_cost.csv"
-  grassland_correction_csv: "data/curated/calibration/grassland_cost.csv"
-  animal_correction_csv: "data/curated/calibration/animal_cost.csv"
+  crop_correction_csv: "data/curated/calibration/{calibration_source}/crop_cost.csv"
+  grassland_correction_csv: "data/curated/calibration/{calibration_source}/grassland_cost.csv"
+  animal_correction_csv: "data/curated/calibration/{calibration_source}/animal_cost.csv"
 
 # --- section: solving ---
 solving:
diff --git a/config/schemas/config.schema.yaml b/config/schemas/config.schema.yaml
index 6f9c1b30..4718542e 100644
--- a/config/schemas/config.schema.yaml
+++ b/config/schemas/config.schema.yaml
@@ -14,6 +14,7 @@ required:
   - currency_base_year
   - downloads
   - paths
+  - calibration
   - netcdf
   - validation
   - consumer_values
@@ -122,6 +123,20 @@ properties:
         minLength: 1
         description: "Root directory for Snakemake benchmark TSV files"
 
+  calibration:
+    type: object
+    required: [source, accept_provenance_mismatch]
+    additionalProperties: false
+    description: "Selection of the calibration artefact set under data/curated/calibration/<source>/"
+    properties:
+      source:
+        type: string
+        pattern: "^[a-zA-Z0-9_-]+$"
+        description: "Name of the calibration artefact set to read (and write, for generation runs)"
+      accept_provenance_mismatch:
+        type: boolean
+        description: "Downgrade a calibration provenance mismatch from an error to a warning"
+
   netcdf:
     type: object
     description: "NetCDF export settings for PyPSA network files"
diff --git a/config/tutorial/01_ghg_prices.yaml b/config/tutorial/01_ghg_prices.yaml
index 2ebf1938..77607c96 100644
--- a/config/tutorial/01_ghg_prices.yaml
+++ b/config/tutorial/01_ghg_prices.yaml
@@ -13,6 +13,11 @@
 
 name: "tutorial_01"
 
+# Tutorials knowingly reuse the default calibration artefacts at a coarser
+# regional resolution.
+calibration:
+  accept_provenance_mismatch: true
+
 # Reduced spatial resolution so the tutorial completes in a few minutes on a
 # laptop after the one-off data download. 200 is the smallest value the
 # default country list admits without enabling cross-border clustering.
diff --git a/config/tutorial/02_consumer_values.yaml b/config/tutorial/02_consumer_values.yaml
index 51144ebb..072ff4d3 100644
--- a/config/tutorial/02_consumer_values.yaml
+++ b/config/tutorial/02_consumer_values.yaml
@@ -24,6 +24,11 @@
 
 name: "tutorial_02"
 
+# Tutorials knowingly reuse the default calibration artefacts at a coarser
+# regional resolution.
+calibration:
+  accept_provenance_mismatch: true
+
 # See config/tutorial/01_ghg_prices.yaml for the rationale on target_count.
 aggregation:
   regions:
diff --git a/data/curated/calibration/animal_cost.csv b/data/curated/calibration/default/animal_cost.csv
similarity index 100%
rename from data/curated/calibration/animal_cost.csv
rename to data/curated/calibration/default/animal_cost.csv
diff --git a/data/curated/calibration/crop_cost.csv b/data/curated/calibration/default/crop_cost.csv
similarity index 100%
rename from data/curated/calibration/crop_cost.csv
rename to data/curated/calibration/default/crop_cost.csv
diff --git a/data/curated/calibration/deviation_penalty.yaml b/data/curated/calibration/default/deviation_penalty.yaml
similarity index 100%
rename from data/curated/calibration/deviation_penalty.yaml
rename to data/curated/calibration/default/deviation_penalty.yaml
diff --git a/data/curated/calibration/exogenous_feed.csv b/data/curated/calibration/default/exogenous_feed.csv
similarity index 100%
rename from data/curated/calibration/exogenous_feed.csv
rename to data/curated/calibration/default/exogenous_feed.csv
diff --git a/data/curated/calibration/exogenous_forage.csv b/data/curated/calibration/default/exogenous_forage.csv
similarity index 100%
rename from data/curated/calibration/exogenous_forage.csv
rename to data/curated/calibration/default/exogenous_forage.csv
diff --git a/data/curated/calibration/fodder_conversion.csv b/data/curated/calibration/default/fodder_conversion.csv
similarity index 100%
rename from data/curated/calibration/fodder_conversion.csv
rename to data/curated/calibration/default/fodder_conversion.csv
diff --git a/data/curated/calibration/food_demand.csv b/data/curated/calibration/default/food_demand.csv
similarity index 100%
rename from data/curated/calibration/food_demand.csv
rename to data/curated/calibration/default/food_demand.csv
diff --git a/data/curated/calibration/food_waste.yaml b/data/curated/calibration/default/food_waste.yaml
similarity index 100%
rename from data/curated/calibration/food_waste.yaml
rename to data/curated/calibration/default/food_waste.yaml
diff --git a/data/curated/calibration/grassland_cost.csv b/data/curated/calibration/default/grassland_cost.csv
similarity index 100%
rename from data/curated/calibration/grassland_cost.csv
rename to data/curated/calibration/default/grassland_cost.csv
diff --git a/data/curated/calibration/grassland_yield.csv b/data/curated/calibration/default/grassland_yield.csv
similarity index 100%
rename from data/curated/calibration/grassland_yield.csv
rename to data/curated/calibration/default/grassland_yield.csv
diff --git a/data/curated/calibration/default/provenance.yaml b/data/curated/calibration/default/provenance.yaml
new file mode 100644
index 00000000..5d3673f9
--- /dev/null
+++ b/data/curated/calibration/default/provenance.yaml
@@ -0,0 +1,853 @@
+# Provenance stamp of this calibration artefact set: the
+# structural config it was fit against. Generated by
+# workflow/scripts/write_calibration_provenance.py via
+# tools/calibrate; do not edit by hand.
+# Licensing: see the annotation in REUSE.toml.
+base_config: config/default.yaml
+generated_at: '2026-07-01T20:40:06+00:00'
+git_commit: 66fc774742905270edac1d5d35dbdd4e4ab42626
+source: default
+structural_config:
+  aggregation.irrigated_area_source: current
+  aggregation.regions.allow_cross_border: false
+  aggregation.regions.method: kmeans
+  aggregation.regions.target_count: 750
+  aggregation.resource_class_quantiles:
+  - 0.25
+  - 0.5
+  - 0.75
+  aggregation.resource_class_score: regional_crop_mix_actual_yield
+  aggregation.simplify_min_area_km: 25
+  aggregation.simplify_tolerance_km: 5
+  animal_costs.fadn.exclude_costs.SE320: Feed for pigs & poultry
+  animal_costs.fadn.exclude_costs.SE325: Feed for pigs & poultry home-grown
+  animal_costs.fadn.exclude_costs.SE375: Rent paid
+  animal_costs.fadn.grazing_cost_items.SE310: Feed for grazing livestock
+  animal_costs.fadn.grazing_cost_items.SE315: Feed for grazing livestock home-grown
+  animal_costs.fadn.high_cost_threshold_usd_per_t: 50000
+  animal_costs.fadn.livestock_specific_costs.SE330: Other livestock specific costs
+  animal_costs.fadn.shared_farm_costs.SE340: Machinery & building current costs
+  animal_costs.fadn.shared_farm_costs.SE345: Energy
+  animal_costs.fadn.shared_farm_costs.SE350: Contract work
+  animal_costs.fadn.shared_farm_costs.SE356: Other direct inputs
+  animal_costs.fadn.shared_farm_costs.SE360: Depreciation
+  animal_costs.fadn.shared_farm_costs.SE370: Wages paid
+  animal_costs.fadn.shared_farm_costs.SE380: Interest paid
+  animal_costs.fadn.shared_farm_costs.SE390: Taxes
+  animal_costs.fallback_aliases.dairy-buffalo: dairy
+  animal_costs.fallback_values_usd_per_t.meat-chicken.grazing: 0
+  animal_costs.fallback_values_usd_per_t.meat-chicken.production: 1300
+  animal_costs.fallback_values_usd_per_t.meat-sheep.grazing: 2300
+  animal_costs.fallback_values_usd_per_t.meat-sheep.production: 1200
+  animal_costs.faostat.aggregate_area_code_limit: 5000
+  animal_costs.faostat.element_codes.producing_animals:
+  - '2313'
+  - '5318'
+  - '5313'
+  animal_costs.faostat.element_codes.production:
+  - '2510'
+  - '5510'
+  animal_costs.faostat.element_codes.stocks:
+  - '2111'
+  - '5111'
+  animal_costs.usda.dressed_weight_kg_per_head.meat-cattle: 350.0
+  animal_costs.usda.dressed_weight_kg_per_head.meat-pig: 90.0
+  animal_costs.usda.exclude_items:
+  - Homegrown harvested feed
+  - Purchased feed
+  - Total, feed costs
+  - Opportunity cost of land
+  - Total, operating costs
+  - Costs listed
+  animal_costs.usda.grazing_cost_items:
+  - Grazed feed
+  animal_costs.usda.include_items:
+  - Hired labor
+  - Opportunity cost of unpaid labor
+  - Bedding and litter
+  - Custom services
+  - Fuel, lube, and electricity
+  - Repairs
+  - Interest on operating capital
+  - Marketing
+  - Veterinary and medicine
+  - Capital recovery of machinery and equipment
+  - General farm overhead
+  - Taxes and insurance
+  animal_costs.usda.request_timeout_seconds: 120
+  animal_products.co_products.rendered-fat.yield_per_retail.meat-cattle: 0.09
+  animal_products.co_products.rendered-fat.yield_per_retail.meat-pig: 0.137
+  animal_products.faostat_items.dairy:
+  - Raw milk of cattle
+  - Raw milk of goats
+  - Raw milk of sheep
+  - Raw milk of camel
+  animal_products.faostat_items.dairy-buffalo:
+  - Raw milk of buffalo
+  animal_products.faostat_items.eggs:
+  - Hen eggs in shell, fresh
+  animal_products.faostat_items.meat-cattle:
+  - Meat of cattle with the bone, fresh or chilled
+  - Meat of buffalo, fresh or chilled
+  animal_products.faostat_items.meat-chicken:
+  - Meat of chickens, fresh or chilled
+  - Meat of ducks, fresh or chilled
+  - Meat of turkeys, fresh or chilled
+  - Meat of pigeons and other birds n.e.c., fresh, chilled or frozen
+  animal_products.faostat_items.meat-pig:
+  - Meat of pig with the bone, fresh or chilled
+  animal_products.faostat_items.meat-sheep:
+  - Meat of sheep, fresh or chilled
+  - Meat of goat, fresh or chilled
+  animal_products.gleam3_system_product_map.Buffalo.Grassland:
+  - dairy-buffalo
+  - meat-cattle
+  animal_products.gleam3_system_product_map.Buffalo.Mixed:
+  - dairy-buffalo
+  - meat-cattle
+  animal_products.gleam3_system_product_map.Cattle.Feedlots:
+  - meat-cattle
+  animal_products.gleam3_system_product_map.Cattle.Grassland:
+  - dairy
+  - meat-cattle
+  animal_products.gleam3_system_product_map.Cattle.Mixed:
+  - dairy
+  - meat-cattle
+  animal_products.gleam3_system_product_map.Chicken.Backyard:
+  - eggs
+  - meat-chicken
+  animal_products.gleam3_system_product_map.Chicken.Broiler:
+  - meat-chicken
+  animal_products.gleam3_system_product_map.Chicken.Layer:
+  - eggs
+  animal_products.gleam3_system_product_map.Goats.Grassland:
+  - dairy
+  - meat-sheep
+  animal_products.gleam3_system_product_map.Goats.Mixed:
+  - dairy
+  - meat-sheep
+  animal_products.gleam3_system_product_map.Pigs.Backyard:
+  - meat-pig
+  animal_products.gleam3_system_product_map.Pigs.Industrial:
+  - meat-pig
+  animal_products.gleam3_system_product_map.Pigs.Intermediate:
+  - meat-pig
+  animal_products.gleam3_system_product_map.Sheep.Grassland:
+  - dairy
+  - meat-sheep
+  animal_products.gleam3_system_product_map.Sheep.Mixed:
+  - dairy
+  - meat-sheep
+  animal_products.include:
+  - meat-cattle
+  - meat-pig
+  - meat-chicken
+  - dairy
+  - eggs
+  - dairy-buffalo
+  - meat-sheep
+  animal_products.me_scaling_clamp_factor: 2.0
+  animal_products.net_to_metabolizable_energy_conversion.k_g: 0.43
+  animal_products.net_to_metabolizable_energy_conversion.k_l: 0.64
+  animal_products.net_to_metabolizable_energy_conversion.k_m: 0.65
+  animal_products.residue_crops:
+  - banana
+  - barley
+  - cassava
+  - chickpea
+  - cowpea
+  - dry-pea
+  - dryland-rice
+  - foxtail-millet
+  - gram
+  - groundnut
+  - maize
+  - oat
+  - pearl-millet
+  - phaseolus-bean
+  - pigeonpea
+  - rapeseed
+  - rye
+  - sorghum
+  - soybean
+  - sugarbeet
+  - sugarcane
+  - sweet-potato
+  - wetland-rice
+  - wheat
+  baseline_year: 2020
+  biomass.biogas_crop_demand: data/curated/biogas_crop_demand.csv
+  biomass.crops:
+  - maize
+  - oil-palm
+  - sugarcane
+  - biomass-sorghum
+  biomass.disposal_foods:
+  - cottonseed-oil
+  - sesame-oil
+  - sesame-seed
+  - groundnut-oil
+  - groundnut
+  - coconut-oil
+  - coconut
+  - foxtail-millet
+  - soybean-oil
+  - rapeseed-oil
+  - sunflower-oil
+  - chickpea
+  - gram
+  - rendered-fat
+  biomass.enforce_baseline_demand: true
+  biomass.enforce_fiber_demand: true
+  byproducts:
+  - beet-pulp
+  - wheat-bran
+  - wheat-germ
+  - rice-bran
+  - barley-bran
+  - oat-bran
+  - buckwheat-hulls
+  - oilseed-meal
+  - palm-kernel-meal
+  - rapeseed-meal
+  - ddgs
+  - molasses
+  - maize-ethanol
+  - maize-gluten-feed
+  - maize-gluten-meal
+  - maize-starch
+  - sugarcane-ethanol
+  - cotton-lint
+  commodities.crops.classes.bulk_dry_goods.items:
+  - wheat
+  - dryland-rice
+  - wetland-rice
+  - maize
+  - barley
+  - oat
+  - rye
+  - sorghum
+  - buckwheat
+  - foxtail-millet
+  - pearl-millet
+  - soybean
+  - dry-pea
+  - chickpea
+  - cowpea
+  - gram
+  - phaseolus-bean
+  - pigeonpea
+  - cocoa
+  - coffee
+  - tea
+  - sunflower
+  - rapeseed
+  - groundnut
+  - sesame
+  - cotton
+  commodities.crops.classes.bulk_dry_goods.marketing_cost_per_t: 30
+  commodities.crops.classes.bulk_dry_goods.trade_cost_per_t_km: 0.006
+  commodities.crops.classes.bulky_fresh.items:
+  - white-potato
+  - sweet-potato
+  - cassava
+  - yam
+  - plantain
+  - sugarbeet
+  - sugarcane
+  - oil-palm
+  - alfalfa
+  - silage-maize
+  - biomass-sorghum
+  commodities.crops.classes.bulky_fresh.marketing_cost_per_t: 60
+  commodities.crops.classes.bulky_fresh.trade_cost_per_t_km: 0.014
+  commodities.crops.classes.perishable_high_value.items:
+  - tomato
+  - carrot
+  - onion
+  - cabbage
+  - banana
+  - watermelon
+  - mango
+  - citrus
+  - coconut
+  - apple
+  - olive
+  commodities.crops.classes.perishable_high_value.marketing_cost_per_t: 200
+  commodities.crops.classes.perishable_high_value.trade_cost_per_t_km: 0.022
+  commodities.crops.non_tradable:
+  - alfalfa
+  - biomass-sorghum
+  - silage-maize
+  commodities.feeds.classes.bulky_low_quality.items:
+  - ruminant_roughage
+  - monogastric_low_quality
+  commodities.feeds.classes.bulky_low_quality.marketing_cost_per_t: 35
+  commodities.feeds.classes.bulky_low_quality.trade_cost_per_t_km: 0.016
+  commodities.feeds.classes.forage.items:
+  - ruminant_forage
+  commodities.feeds.classes.forage.marketing_cost_per_t: 25
+  commodities.feeds.classes.forage.trade_cost_per_t_km: 0.012
+  commodities.feeds.classes.grain_protein.items:
+  - ruminant_grain
+  - ruminant_protein
+  - monogastric_grain
+  - monogastric_protein
+  commodities.feeds.classes.grain_protein.marketing_cost_per_t: 30
+  commodities.feeds.classes.grain_protein.trade_cost_per_t_km: 0.006
+  commodities.feeds.non_tradable:
+  - ruminant_forage
+  - ruminant_roughage
+  commodities.foods.classes.chilled_meat.items:
+  - meat-cattle
+  - meat-pig
+  - meat-chicken
+  - meat-sheep
+  commodities.foods.classes.chilled_meat.marketing_cost_per_t: 800
+  commodities.foods.classes.chilled_meat.trade_cost_per_t_km: 0.028
+  commodities.foods.classes.dairy_and_eggs.items:
+  - dairy
+  - dairy-buffalo
+  - eggs
+  commodities.foods.classes.dairy_and_eggs.marketing_cost_per_t: 300
+  commodities.foods.classes.dairy_and_eggs.trade_cost_per_t_km: 0.024
+  commodities.foods.classes.feed_byproduct.items:
+  - barley-bran
+  - beet-pulp
+  - buckwheat-hulls
+  - oat-bran
+  - rice-bran
+  - wheat-bran
+  - wheat-germ
+  - ddgs
+  - maize-gluten-feed
+  - maize-gluten-meal
+  - oilseed-meal
+  - palm-kernel-meal
+  - rapeseed-meal
+  - molasses
+  commodities.foods.classes.feed_byproduct.marketing_cost_per_t: 30
+  commodities.foods.classes.feed_byproduct.trade_cost_per_t_km: 0.008
+  commodities.foods.classes.fresh_produce.items:
+  - apple
+  - banana
+  - citrus
+  - coconut
+  - mango
+  - plantain
+  - watermelon
+  - cabbage
+  - carrot
+  - onion
+  - tomato
+  - cassava
+  - potato
+  - sweet-potato
+  - yam
+  commodities.foods.classes.fresh_produce.marketing_cost_per_t: 200
+  commodities.foods.classes.fresh_produce.trade_cost_per_t_km: 0.022
+  commodities.foods.classes.industrial_byproduct.items:
+  - cotton-lint
+  - maize-ethanol
+  - maize-starch
+  - sugarcane-ethanol
+  - rendered-fat
+  commodities.foods.classes.industrial_byproduct.marketing_cost_per_t: 40
+  commodities.foods.classes.industrial_byproduct.trade_cost_per_t_km: 0.008
+  commodities.foods.classes.processed_dry_goods.items:
+  - flour-white
+  - flour-wholemeal
+  - rice-brown
+  - rice-white
+  - barley-hulled
+  - buckwheat
+  - foxtail-millet
+  - maize
+  - oat
+  - pearl-millet
+  - rye
+  - sorghum
+  - chickpea
+  - cowpea
+  - dry-pea
+  - gram
+  - phaseolus-bean
+  - pigeon-pea
+  - soy
+  - groundnut
+  - sesame-seed
+  - sunflower-seed
+  - sugar
+  - cocoa-powder
+  - coffee-green
+  - tea-dried
+  commodities.foods.classes.processed_dry_goods.marketing_cost_per_t: 80
+  commodities.foods.classes.processed_dry_goods.trade_cost_per_t_km: 0.012
+  commodities.foods.classes.processed_oils.items:
+  - coconut-oil
+  - cottonseed-oil
+  - groundnut-oil
+  - olive-oil
+  - palm-oil
+  - rapeseed-oil
+  - sesame-oil
+  - soybean-oil
+  - sunflower-oil
+  commodities.foods.classes.processed_oils.marketing_cost_per_t: 120
+  commodities.foods.classes.processed_oils.trade_cost_per_t_km: 0.016
+  commodities.foods.non_tradable: []
+  commodities.hubs: 20
+  costs.averaging_period.end_year: 2024
+  costs.averaging_period.start_year: 2015
+  countries:
+  - AFG
+  - AGO
+  - ALB
+  - ARE
+  - ARG
+  - ARM
+  - ASM
+  - ATG
+  - AUS
+  - AUT
+  - AZE
+  - BDI
+  - BEL
+  - BEN
+  - BFA
+  - BGD
+  - BGR
+  - BHS
+  - BIH
+  - BLR
+  - BLZ
+  - BOL
+  - BRA
+  - BRB
+  - BRN
+  - BTN
+  - BWA
+  - CAF
+  - CAN
+  - CHE
+  - CHL
+  - CHN
+  - CIV
+  - CMR
+  - COD
+  - COG
+  - COL
+  - COM
+  - CPV
+  - CRI
+  - CUB
+  - CYP
+  - CZE
+  - DEU
+  - DJI
+  - DNK
+  - DOM
+  - DZA
+  - ECU
+  - EGY
+  - ERI
+  - ESP
+  - EST
+  - ETH
+  - FIN
+  - FJI
+  - FRA
+  - GAB
+  - GBR
+  - GEO
+  - GHA
+  - GIN
+  - GMB
+  - GNB
+  - GNQ
+  - GRC
+  - GRD
+  - GTM
+  - GUF
+  - GUY
+  - HND
+  - HRV
+  - HTI
+  - HUN
+  - IDN
+  - IND
+  - IRL
+  - IRN
+  - IRQ
+  - ISL
+  - ISR
+  - ITA
+  - JAM
+  - JOR
+  - JPN
+  - KAZ
+  - KEN
+  - KGZ
+  - KHM
+  - KOR
+  - LAO
+  - LBN
+  - LBR
+  - LBY
+  - LKA
+  - LSO
+  - LTU
+  - LUX
+  - LVA
+  - MAR
+  - MDA
+  - MDG
+  - MEX
+  - MKD
+  - MLI
+  - MLT
+  - MMR
+  - MNE
+  - MNG
+  - MOZ
+  - MRT
+  - MUS
+  - MWI
+  - MYS
+  - NAM
+  - NER
+  - NGA
+  - NIC
+  - NLD
+  - NOR
+  - NPL
+  - NZL
+  - OMN
+  - PAK
+  - PAN
+  - PER
+  - PHL
+  - PNG
+  - POL
+  - PRI
+  - PRT
+  - PRY
+  - PSE
+  - ROU
+  - RUS
+  - RWA
+  - SAU
+  - SDN
+  - SEN
+  - SLB
+  - SLE
+  - SLV
+  - SOM
+  - SRB
+  - SSD
+  - STP
+  - SUR
+  - SVK
+  - SVN
+  - SWE
+  - SWZ
+  - SYR
+  - TCD
+  - TGO
+  - THA
+  - TJK
+  - TKM
+  - TLS
+  - TTO
+  - TUN
+  - TUR
+  - TWN
+  - TZA
+  - UGA
+  - UKR
+  - URY
+  - USA
+  - UZB
+  - VEN
+  - VNM
+  - VUT
+  - YEM
+  - ZAF
+  - ZMB
+  - ZWE
+  crop_costs.faostat.price_element_code: 5532
+  crop_costs.faostat.yield_element_code: 5412
+  crop_costs.non_endogenous_cost_share: 0.7
+  crop_costs.outlier_cap_quantile: 0.9
+  cropgrids.suitable_area_expansion: 1.0
+  cropgrids_crops:
+  - apple
+  crops:
+  - wheat
+  - dryland-rice
+  - wetland-rice
+  - maize
+  - barley
+  - oat
+  - rye
+  - sorghum
+  - buckwheat
+  - foxtail-millet
+  - pearl-millet
+  - soybean
+  - dry-pea
+  - chickpea
+  - cowpea
+  - gram
+  - phaseolus-bean
+  - pigeonpea
+  - white-potato
+  - sweet-potato
+  - cassava
+  - yam
+  - plantain
+  - tomato
+  - carrot
+  - onion
+  - cabbage
+  - banana
+  - watermelon
+  - mango
+  - citrus
+  - coconut
+  - apple
+  - cocoa
+  - coffee
+  - tea
+  - sunflower
+  - rapeseed
+  - groundnut
+  - sesame
+  - oil-palm
+  - olive
+  - sugarcane
+  - sugarbeet
+  - cotton
+  - alfalfa
+  - silage-maize
+  - biomass-sorghum
+  currency_base_year: 2024
+  data.faostat.fbs_food_supply_element_code: 645
+  data.faostat.fbs_other_uses_element_code: 5154
+  data.faostat.fbs_production_element_code: 5511
+  data.faostat.qcl_production_element_code: 5510
+  data.gaez.climate_model: GFDL-ESM4
+  data.gaez.climate_model_ensemble: ENSEMBLE
+  data.gaez.climate_scenario: SSP126
+  data.gaez.input_level: H
+  data.gaez.period: FP2140
+  data.gaez.suitability_var: RES05-SX1
+  data.gaez.water_requirement_var: RES05-WDC
+  data.gaez.yield_var: RES05-YCX
+  data.land_cover.version: v2_1_1
+  data.land_cover.zenodo_record: '21085632'
+  data.soilgrids.target_resolution_m: 10000
+  data.usda.nutrients.cal: Energy
+  data.usda.nutrients.carb: Carbohydrate, by difference
+  data.usda.nutrients.fat: Total lipid (fat)
+  data.usda.nutrients.protein: Protein
+  data.usda.retrieve_nutrition: false
+  diet.baseline_age: All ages
+  diet.fbs_override_foods:
+  - yam
+  - cocoa-powder
+  - coffee-green
+  - tea-dried
+  - meat-cattle
+  - meat-pig
+  - meat-sheep
+  - meat-chicken
+  - eggs
+  diet.gdd_ia.cooked_to_raw.red_meat: 1.43
+  diet.nhanes.cycle: '1720'
+  diet.nhanes.reference_year: 2018
+  diet.nhanes.url: https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/fped/Table_1_FPED_MaleFemale_{cycle}.pdf
+  diet.source_basis.faostat_fbs_supply.meat-cattle: carcass
+  diet.source_basis.faostat_fbs_supply.meat-chicken: carcass
+  diet.source_basis.faostat_fbs_supply.meat-pig: carcass
+  diet.source_basis.faostat_fbs_supply.meat-sheep: carcass
+  diet.source_basis.faostat_fbs_supply.tea-dried: fresh
+  diet.source_basis.gbd.fruits: fresh
+  diet.source_basis.gbd.legumes: cooked
+  diet.source_basis.gbd.milk: fresh
+  diet.source_basis.gbd.nuts_seeds: dry
+  diet.source_basis.gbd.red_meat: cooked
+  diet.source_basis.gbd.vegetables: fresh
+  diet.source_basis.gbd.whole_grains: dry
+  emissions.ch4_to_co2_factor: 27.0
+  emissions.fertilizer.frac_gasf: 0.11
+  emissions.fertilizer.frac_gasm: 0.21
+  emissions.fertilizer.frac_leach: 0.24
+  emissions.fertilizer.indirect_ef4: 0.01
+  emissions.fertilizer.indirect_ef5: 0.011
+  emissions.fertilizer.organic_n2o_factor: 0.006
+  emissions.fertilizer.synthetic_n2o_factor: 0.01
+  emissions.n2o_to_co2_factor: 273.0
+  emissions.residues.incorporation_n2o_factor: 0.01
+  emissions.rice.methane_emission_factor_kg_per_ha: 134.47
+  emissions.rice.rainfed_wetland_rice_ch4_scaling_factor: 0.54
+  fertilizer.limit: 200000000
+  fertilizer.manure_n_to_fertilizer: 0.75
+  fertilizer.marginal_cost_usd_per_tonne: 500
+  fertilizer.n_percentile: 80
+  fertilizer.proxy_rates.plantain: banana
+  fertilizer.proxy_rates.silage-maize: maize
+  fodder_decomposition.eurostat.averaging_years: 5
+  fodder_decomposition.fdd_crops:
+  - alfalfa
+  - silage-maize
+  fodder_decomposition.suitability_blend_weight: 0.7
+  fodder_decomposition.yield_corrections.ceiling: 2.0
+  fodder_decomposition.yield_corrections.enabled: true
+  fodder_decomposition.yield_corrections.eurostat_moisture: 0.65
+  fodder_decomposition.yield_corrections.floor: 0.2
+  food_demand_calibration.max_multiplier: 2.0
+  food_demand_calibration.min_multiplier: 0.5
+  food_groups.included:
+  - whole_grains
+  - grain
+  - fruits
+  - vegetables
+  - legumes
+  - nuts_seeds
+  - starchy_vegetable
+  - oil
+  - red_meat
+  - poultry
+  - dairy
+  - eggs
+  - sugar
+  - stimulants
+  - animal_fat
+  food_loss_waste_calibration.food_groups:
+  - vegetables
+  - fruits
+  - starchy_vegetable
+  - oil
+  - stimulants
+  gleam3_feed_attribution.pathway_dispatch_shares.maize_ethanol: 0.12
+  gleam3_feed_attribution.pathway_dispatch_shares.maize_wetmill: 0.07
+  gleam3_feed_attribution.pathway_dispatch_shares.sugarcane_ethanol: 0.25
+  grazing.enabled: true
+  grazing.forage_overlap_crops:
+  - alfalfa
+  - silage-maize
+  - biomass-sorghum
+  grazing.isimip_utilization_rate: 0.6
+  health.alternative_rr.red_meat: data/curated/red_meat_rr_log_linear.csv
+  health.breakpoint_rel_tol: 0.05
+  health.causes:
+  - CHD
+  - Stroke
+  - T2DM
+  - CRC
+  health.clustering.weights.gdp: 0.5
+  health.clustering.weights.geography: 1.0
+  health.clustering.weights.population: 0.3
+  health.gbd_cause_id.CHD: 493
+  health.gbd_cause_id.CRC: 441
+  health.gbd_cause_id.Stroke: 495
+  health.gbd_cause_id.T2DM: 976
+  health.gbd_rei_id.fruits: 111
+  health.gbd_rei_id.legumes: 333
+  health.gbd_rei_id.nuts_seeds: 114
+  health.gbd_rei_id.red_meat: 116
+  health.gbd_rei_id.vegetables: 112
+  health.gbd_rei_id.whole_grains: 113
+  health.intake_age_min: 11
+  health.log_rr_points: 15
+  health.region_clusters: 30
+  health.risk_cause_map.fruits:
+  - CHD
+  - Stroke
+  - T2DM
+  health.risk_cause_map.legumes:
+  - CHD
+  health.risk_cause_map.nuts_seeds:
+  - CHD
+  health.risk_cause_map.red_meat:
+  - CHD
+  - Stroke
+  - T2DM
+  - CRC
+  health.risk_cause_map.vegetables:
+  - CHD
+  - Stroke
+  health.risk_cause_map.whole_grains:
+  - CHD
+  - Stroke
+  - T2DM
+  - CRC
+  health.risk_factors:
+  - fruits
+  - vegetables
+  - nuts_seeds
+  - legumes
+  - red_meat
+  - whole_grains
+  health.ssb_sugar_g_per_100g: 5.7
+  irrigation.irrigated_crops: all
+  land.conversion_cost_forest_usd_per_ha: 8000
+  land.conversion_cost_nonforest_usd_per_ha: 2000
+  land.discount_rate: 0.05
+  land.filtering.min_area_ha: 100
+  land.filtering.min_crop_yield_t_per_ha: 0.01
+  land.filtering.min_grassland_yield_t_per_ha: 0.05
+  land.investment_horizon: 30
+  land.land_use_cost_usd_per_ha: 0.0
+  luc.cropland_source: gaez
+  luc.forest_fraction_threshold: 0.2
+  luc.horizon_years: 30
+  luc.managed_flux_mode: zero
+  luc.savanna_pvc_threshold: 75
+  multiple_cropping.double_rice.crops:
+  - wetland-rice
+  - wetland-rice
+  multiple_cropping.double_rice.water_supplies:
+  - r
+  - i
+  multiple_cropping.maize_soybean.crops:
+  - maize
+  - soybean
+  multiple_cropping.maize_soybean.water_supplies:
+  - r
+  - i
+  multiple_cropping.rice_wheat.crops:
+  - wetland-rice
+  - wheat
+  multiple_cropping.rice_wheat.water_supplies:
+  - r
+  - i
+  non_food_crops:
+  - alfalfa
+  - silage-maize
+  - biomass-sorghum
+  optimal_taxes.enabled: false
+  residues.max_feed_fraction: 0.3
+  residues.max_feed_fraction_by_region.Asia: 0.7
+  residues.max_feed_fraction_by_region.Southern Asia: 0.85
+  residues.max_feed_fraction_by_region.Sub-Saharan Africa: 0.7
+  water.huang_reference_year: 2010
+  water.supply_scenario: current_use
+  weight_conversion.carcass_to_fresh.meat-cattle: 0.67
+  weight_conversion.carcass_to_fresh.meat-chicken: 0.6
+  weight_conversion.carcass_to_fresh.meat-pig: 0.73
+  weight_conversion.carcass_to_fresh.meat-sheep: 0.66
+  weight_conversion.cooked_to_dry.grain: 0.45
+  weight_conversion.cooked_to_dry.legumes: 0.4
+  weight_conversion.cooked_to_dry.whole_grains: 0.45
+  weight_conversion.cooked_to_fresh.poultry: 1.0
+  weight_conversion.cooked_to_fresh.red_meat: 1.43
+  weight_conversion.fresh_to_dry.tea-dried: 0.22
+  yield_calibration.crops:
+  - plantain
+  - coffee
+  - tea
+  yield_calibration.enabled: true
+  yield_calibration.multiplier_max: 3.0
+  yield_calibration.multiplier_min: 0.5
diff --git a/docs/calibration.rst b/docs/calibration.rst
index 4656379c..4eeaa8c5 100644
--- a/docs/calibration.rst
+++ b/docs/calibration.rst
@@ -13,9 +13,12 @@ by every subsequent solve. Running ``tools/calibrate`` regenerates them
 all in the right dependency order; individual steps can also be run
 directly.
 
-The calibration artefacts live under ``data/curated/calibration/`` and
-are version-controlled so that ordinary builds don't need to re-solve
-anything.
+Calibration artefacts are organised in *sets*: one directory
+``data/curated/calibration/<source>/`` per base configuration they were
+calibrated against, selected by the ``calibration.source`` config key.
+The shipped ``default`` set is version-controlled so that ordinary
+builds don't need to re-solve anything. See
+:ref:`calibration-provenance` for how sets are tied to configs.
 
 .. _calibration-enabled-generate-pattern:
 
@@ -114,7 +117,9 @@ Everything is wrapped by ``tools/calibrate``:
    tools/calibrate food_demand
    tools/calibrate cost
    tools/calibrate stability
-   tools/calibrate --check      # per-step staleness, no execution
+   tools/calibrate --check      # per-step staleness + provenance, no execution
+   tools/calibrate --base config/<name>.yaml [all|<step>|--check]
+                                # calibrate a dedicated set for another config
 
 The wrapper invokes ``tools/smk`` with the matching config and the
 appropriate output targets. Any extra flags are passed through, e.g.
@@ -125,6 +130,41 @@ sequential (each Broyden step depends on the previous solve), so HPC
 offloading isn't worthwhile at this size. Each iteration is one paired
 solve (baseline + main), and 3–5 iterations are typically enough.
 
+.. _calibration-provenance:
+
+Artefact sets and provenance
+----------------------------
+
+Calibration artefacts are only valid for configurations sharing the
+structural assumptions they were fit under. Each set therefore carries
+a ``provenance.yaml`` stamp of the structural configuration it was
+calibrated against (all config leaves except solve-time keys and a
+small exempt list; see
+``workflow/validation/calibration_provenance.py``), written by
+``tools/calibrate`` after each successful run. At workflow start the
+active config is compared against the stamp of the set named by
+``calibration.source``; a structural mismatch is an error listing the
+differing keys.
+
+A config with different structural assumptions has three options:
+
+* **Calibrate its own set**: declare ``calibration.source: <name>`` in
+  the config and run ``tools/calibrate --base config/<file>.yaml``.
+  Artefacts land in ``data/curated/calibration/<name>/``. A fresh set
+  is first seeded from the ``default`` set (each calibration solve
+  consumes the other steps' artefacts) and then regenerated in
+  dependency order.
+* **Point at a compatible existing set** via ``calibration.source``.
+* **Accept the mismatch** with
+  ``calibration.accept_provenance_mismatch: true``, downgrading the
+  error to a warning. Only appropriate when calibration fidelity does
+  not matter (e.g. the coarse test and tutorial configs).
+
+Solve-time keys (GHG price, health valuation, the deviation-penalty
+block, scenario overrides, ...) never invalidate a set; the check fires
+only on structural changes. Code changes are not captured by the stamp:
+``tools/calibrate --check`` (Snakemake staleness) covers those.
+
 Consuming the calibrated values
 -------------------------------
 
@@ -139,7 +179,7 @@ workflow when their configuration blocks are enabled (the default):
   the monogastric/ruminant protein and ruminant-roughage feed buses (see
   :ref:`exogenous-protein-feed`).
 * ``food_demand_calibration.enabled: true`` loads
-  ``data/curated/calibration/food_demand.csv`` at solve time and applies
+  ``data/curated/calibration/<source>/food_demand.csv`` at solve time and applies
   each per-food multiplier uniformly to the baseline-diet ``target_mt``
   in ``_match_baseline_to_consume_links`` (see
   :ref:`food-demand-calibration`).
@@ -148,7 +188,7 @@ workflow when their configuration blocks are enabled (the default):
 * ``deviation_penalty.calibration.enabled: true`` resolves the sentinel
   ``"calibrated"`` on any of
   ``deviation_penalty.{land.crops,land.grassland,feed,diet}.l1_cost`` from
-  ``data/curated/calibration/deviation_penalty.yaml`` at solve time
+  ``data/curated/calibration/<source>/deviation_penalty.yaml`` at solve time
   (see :ref:`production-stability-bounds` for the config reference).
   Scenarios that want an explicit numeric value simply override the
   sentinel with a number; scenarios that want to scan around the
@@ -167,13 +207,13 @@ validation solve:
   ``feed:ruminant_forage:*``). Surplus countries get a per-country
   multiplier on grassland yield and fodder-conversion efficiency;
   deficit countries get an exogenous-forage supply written to
-  ``data/curated/calibration/exogenous_forage.csv``. See
+  ``data/curated/calibration/<source>/exogenous_forage.csv``. See
   :ref:`grassland-forage-calibration` in the livestock chapter for the
   algorithm.
 * **Protein corrections** (deficit side only, on
   ``feed:monogastric_protein:*`` and ``feed:ruminant_protein:*``). The
   positive slack on each protein feed bus is written to
-  ``data/curated/calibration/exogenous_feed.csv``. See
+  ``data/curated/calibration/<source>/exogenous_feed.csv``. See
   :ref:`exogenous-protein-feed` for what real-world sources it stands
   in for.
 
@@ -382,7 +422,7 @@ log-log slope for a relationship of the form
 Convergence target: :math:`\lvert \log(\text{dev}/t) \rvert_\infty
 < 0.02`, i.e. all calibrated deviations within +/-2 % of the target.
 The calibrated coefficients are written to
-``data/curated/calibration/deviation_penalty.yaml`` under
+``data/curated/calibration/<source>/deviation_penalty.yaml`` under
 ``l1_costs.<component>`` and resolved at solve time wherever the
 sentinel ``"calibrated"`` appears in
 ``deviation_penalty.{land.crops,land.grassland,feed,diet}.l1_cost`` (see
diff --git a/docs/configuration.rst b/docs/configuration.rst
index 4aadbd6d..2aac7661 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -300,8 +300,19 @@ Path Options
 .. literalinclude:: ../config/default.yaml
    :language: yaml
    :start-after: # --- section: paths ---
+   :end-before: # --- section: calibration ---
+
+Calibration Artefact Set
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../config/default.yaml
+   :language: yaml
+   :start-after: # --- section: calibration ---
    :end-before: # --- section: netcdf ---
 
+See :ref:`calibration-provenance` for the semantics of ``source`` and
+``accept_provenance_mismatch``.
+
 NetCDF Options
 ~~~~~~~~~~~~~~
 
@@ -441,7 +452,7 @@ across components.
 
 The default calibration (cropland + grassland + feed) is regenerated
 with ``tools/calibrate stability`` and lands at
-``data/curated/calibration/deviation_penalty.yaml`` (see
+``data/curated/calibration/<source>/deviation_penalty.yaml`` (see
 :doc:`calibration`).
 
 .. _growth-caps:
diff --git a/docs/costs.rst b/docs/costs.rst
index 8d7caf4f..02f4edbe 100644
--- a/docs/costs.rst
+++ b/docs/costs.rst
@@ -782,9 +782,9 @@ Cost-related configuration parameters are specified in ``config/default.yaml``:
      enabled: false       # Apply calibration corrections
      generate: false      # Generate calibration from solved model
      scenario: "calibration"
-     crop_correction_csv: "data/curated/calibration/crop_cost.csv"
-     grassland_correction_csv: "data/curated/calibration/grassland_cost.csv"
-     animal_correction_csv: "data/curated/calibration/animal_cost.csv"
+     crop_correction_csv: "data/curated/calibration/{calibration_source}/crop_cost.csv"
+     grassland_correction_csv: "data/curated/calibration/{calibration_source}/grassland_cost.csv"
+     animal_correction_csv: "data/curated/calibration/{calibration_source}/animal_cost.csv"
 
 **Animal cost fallbacks** (see :ref:`animal_cost_fallbacks`):
 
diff --git a/docs/livestock.rst b/docs/livestock.rst
index f49ae148..0e044301 100644
--- a/docs/livestock.rst
+++ b/docs/livestock.rst
@@ -675,9 +675,9 @@ FAOSTAT area cap.
      grassland_forage_calibration:
        enabled: true
        generate: false
-       grassland_yield_correction: "data/curated/calibration/grassland_yield.csv"
-       fodder_conversion_correction: "data/curated/calibration/fodder_conversion.csv"
-       exogenous_forage: "data/curated/calibration/exogenous_forage.csv"
+       grassland_yield_correction: "data/curated/calibration/{calibration_source}/grassland_yield.csv"
+       fodder_conversion_correction: "data/curated/calibration/{calibration_source}/fodder_conversion.csv"
+       exogenous_forage: "data/curated/calibration/{calibration_source}/exogenous_forage.csv"
        scenario: "default"
 
 The figure below shows the grassland calibration results.
@@ -715,10 +715,12 @@ forage calibration:
 2. **Phase 2 — Calibrated model**: All other scenarios (including
    ``default``) apply all three calibration files.
 
-Pre-computed calibration files are stored under ``data/curated/calibration/``
-so they can be reused across configurations without re-running the validation
-solve.  Set ``generate: true`` in the relevant configuration block to
-re-generate them (requires a full validation solve).
+Pre-computed calibration files are stored under
+``data/curated/calibration/<source>/`` (see :ref:`calibration-provenance`
+for how a config selects a compatible set) so structurally equivalent
+configurations reuse them without re-running the validation solve.  Set
+``generate: true`` in the relevant configuration block to re-generate
+them (requires a full validation solve).
 
 .. _exogenous-protein-feed:
 
@@ -803,7 +805,7 @@ supply that mirrors the existing
    ``feed:ruminant_roughage:{country}`` buses reveal the
    per-country gap.
 2. ``compute_exogenous_feed_calibration`` writes those positive slacks
-   to ``data/curated/calibration/exogenous_feed.csv``.
+   to ``data/curated/calibration/<source>/exogenous_feed.csv``.
 3. At solve time, ``_apply_exogenous_feed_calibration`` reads the CSV
    and adds free per-country generators on the matching protein and
    roughage feed buses. In validation / ``enforce_baseline_feed: true`` mode the
@@ -840,7 +842,7 @@ generators are named ``supply:exogenous_{category}:{country}``.
    exogenous_feed_calibration:
      enabled: true
      generate: false
-     exogenous_feed: "data/curated/calibration/exogenous_feed.csv"
+     exogenous_feed: "data/curated/calibration/{calibration_source}/exogenous_feed.csv"
      scenario: "default"
 
 When upstream feed or crop data changes, re-run
diff --git a/tests/config/test.yaml b/tests/config/test.yaml
index c1d7391c..79ef399f 100644
--- a/tests/config/test.yaml
+++ b/tests/config/test.yaml
@@ -7,6 +7,12 @@
 
 name: "test"
 
+# The test config knowingly reuses the default calibration artefacts at a
+# much coarser structural resolution; calibration fidelity is irrelevant
+# for the integration tests.
+calibration:
+  accept_provenance_mismatch: true
+
 scenarios:
   # Toy scenarios for pytest integration tests.
   # Subset of production scenarios to exercise key code paths.
diff --git a/tests/test_calibration_provenance.py b/tests/test_calibration_provenance.py
new file mode 100644
index 00000000..9f5a0e3c
--- /dev/null
+++ b/tests/test_calibration_provenance.py
@@ -0,0 +1,184 @@
+# SPDX-FileCopyrightText: 2026 Koen van Greevenbroek
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Unit tests for calibration artefact provenance tracking."""
+
+import copy
+
+import pytest
+import yaml
+
+from workflow.scripts.solve_namespace import (
+    load_merged_config,
+    resolve_calibration_source_paths,
+)
+from workflow.validation.calibration_provenance import (
+    diff_snapshots,
+    is_generation_run,
+    structural_snapshot,
+    validate_calibration_provenance,
+)
+
+# Minimal config carrying every key the provenance machinery touches.
+MINIMAL_CONFIG = {
+    "name": "unit",
+    "calibration": {"source": "unit", "accept_provenance_mismatch": False},
+    "crops": ["wheat", "maize"],
+    "planning_horizon": 2030,
+    "baseline_year": 2020,
+    "emissions": {"ghg_price": 100},
+    "validation": {"use_actual_yields": True},
+    "grazing": {
+        "grassland_forage_calibration": {"generate": False, "scenario": "default"}
+    },
+    "exogenous_feed_calibration": {"generate": False},
+    "food_loss_waste_calibration": {"generate": False, "food_groups": ["fruits"]},
+    "food_demand_calibration": {"generate": False, "min_multiplier": 0.5},
+    "cost_calibration": {"generate": False},
+    "deviation_penalty": {"calibration": {"generate": False}},
+}
+
+
+class TestStructuralSnapshot:
+    def test_keeps_structural_leaves(self):
+        snap = structural_snapshot(MINIMAL_CONFIG)
+        assert snap["crops"] == ["wheat", "maize"]
+        assert snap["baseline_year"] == 2020
+        assert snap["food_loss_waste_calibration.food_groups"] == ["fruits"]
+        assert snap["food_demand_calibration.min_multiplier"] == 0.5
+
+    def test_drops_solve_time_and_exempt_keys(self):
+        snap = structural_snapshot(MINIMAL_CONFIG)
+        for key in snap:
+            assert not key.startswith(
+                ("emissions.ghg_price", "deviation_penalty", "validation")
+            )
+        assert "name" not in snap
+        assert "planning_horizon" not in snap
+        assert "calibration.source" not in snap
+        assert not any(
+            k.startswith("grazing.grassland_forage_calibration") for k in snap
+        )
+        assert "cost_calibration.generate" not in snap
+        assert "food_loss_waste_calibration.generate" not in snap
+
+
+class TestDiffSnapshots:
+    def test_identical(self):
+        snap = structural_snapshot(MINIMAL_CONFIG)
+        assert diff_snapshots(snap, dict(snap)) == []
+
+    def test_changed_added_removed(self):
+        stamped = {"a": 1, "b": [1, 2]}
+        active = {"b": [1, 3], "c": "x"}
+        diffs = diff_snapshots(stamped, active)
+        assert len(diffs) == 3
+        assert any(d.startswith("a:") and "not in config" in d for d in diffs)
+        assert any(d.startswith("b:") and "!=" in d for d in diffs)
+        assert any(d.startswith("c:") and "not in stamp" in d for d in diffs)
+
+
+class TestGenerationRunDetection:
+    def test_not_generation_run(self):
+        assert not is_generation_run(MINIMAL_CONFIG)
+
+    @pytest.mark.parametrize(
+        "path",
+        [
+            ("grazing", "grassland_forage_calibration", "generate"),
+            ("food_loss_waste_calibration", "generate"),
+            ("deviation_penalty", "calibration", "generate"),
+        ],
+    )
+    def test_generation_run(self, path):
+        cfg = copy.deepcopy(MINIMAL_CONFIG)
+        node = cfg
+        for key in path[:-1]:
+            node = node[key]
+        node[path[-1]] = True
+        assert is_generation_run(cfg)
+
+
+class TestValidateCalibrationProvenance:
+    def _write_stamp(self, root, config):
+        path = root / "data/curated/calibration/unit/provenance.yaml"
+        path.parent.mkdir(parents=True)
+        stamp = {
+            "source": "unit",
+            "structural_config": structural_snapshot(config),
+        }
+        with open(path, "w") as f:
+            yaml.safe_dump(stamp, f)
+
+    def test_match_passes(self, tmp_path):
+        self._write_stamp(tmp_path, MINIMAL_CONFIG)
+        validate_calibration_provenance(MINIMAL_CONFIG, tmp_path)
+
+    def test_solve_time_change_passes(self, tmp_path):
+        self._write_stamp(tmp_path, MINIMAL_CONFIG)
+        cfg = copy.deepcopy(MINIMAL_CONFIG)
+        cfg["emissions"]["ghg_price"] = 500
+        validate_calibration_provenance(cfg, tmp_path)
+
+    def test_structural_change_raises(self, tmp_path):
+        self._write_stamp(tmp_path, MINIMAL_CONFIG)
+        cfg = copy.deepcopy(MINIMAL_CONFIG)
+        cfg["crops"] = ["wheat"]
+        with pytest.raises(ValueError, match="crops"):
+            validate_calibration_provenance(cfg, tmp_path)
+
+    def test_accept_flag_downgrades_to_warning(self, tmp_path):
+        self._write_stamp(tmp_path, MINIMAL_CONFIG)
+        cfg = copy.deepcopy(MINIMAL_CONFIG)
+        cfg["crops"] = ["wheat"]
+        cfg["calibration"]["accept_provenance_mismatch"] = True
+        validate_calibration_provenance(cfg, tmp_path)
+
+    def test_missing_stamp_raises(self, tmp_path):
+        with pytest.raises(ValueError, match="no provenance stamp"):
+            validate_calibration_provenance(MINIMAL_CONFIG, tmp_path)
+
+    def test_generation_run_skipped(self, tmp_path):
+        cfg = copy.deepcopy(MINIMAL_CONFIG)
+        cfg["cost_calibration"]["generate"] = True
+        # No stamp written: generation runs must not require one.
+        validate_calibration_provenance(cfg, tmp_path)
+
+
+class TestResolveCalibrationSourcePaths:
+    def test_substitutes_placeholder(self):
+        cfg = {
+            "calibration": {"source": "foo"},
+            "cost_calibration": {
+                "crop_correction_csv": (
+                    "data/curated/calibration/{calibration_source}/crop_cost.csv"
+                )
+            },
+            "nested": {"list": ["{calibration_source}/x", 3]},
+            "untouched": "results/{name}/foo.csv",
+        }
+        resolved = resolve_calibration_source_paths(cfg)
+        assert (
+            resolved["cost_calibration"]["crop_correction_csv"]
+            == "data/curated/calibration/foo/crop_cost.csv"
+        )
+        assert resolved["nested"]["list"] == ["foo/x", 3]
+        assert resolved["untouched"] == "results/{name}/foo.csv"
+
+
+class TestDefaultStampConsistency:
+    def test_default_stamp_matches_default_config(self):
+        """The committed default stamp must match config/default.yaml.
+
+        This is the enforcement point for structural default-config
+        changes: editing config/default.yaml structurally without
+        recalibrating (or at least restamping via
+        workflow/scripts/write_calibration_provenance.py) fails here and
+        in every workflow invocation.
+        """
+        config = load_merged_config("config/default.yaml")
+        with open("data/curated/calibration/default/provenance.yaml") as f:
+            stamp = yaml.safe_load(f)
+        diffs = diff_snapshots(stamp["structural_config"], structural_snapshot(config))
+        assert diffs == [], "\n".join(diffs)
diff --git a/tests/test_production_stability.py b/tests/test_production_stability.py
index f11f81a2..f1b61722 100644
--- a/tests/test_production_stability.py
+++ b/tests/test_production_stability.py
@@ -385,7 +385,7 @@ def dp_cfg(self):
         with open("config/default.yaml") as f:
             return yaml.safe_load(f)["deviation_penalty"]
 
-    ARTEFACT = "data/curated/calibration/deviation_penalty.yaml"
+    ARTEFACT = "data/curated/calibration/default/deviation_penalty.yaml"
 
     def test_resolves_shipped_artefact(self, dp_cfg):
         """Default config sentinels must resolve against the shipped artefact.
diff --git a/tools/calibrate b/tools/calibrate
index 7cdbf3fb..d1f4cbc2 100755
--- a/tools/calibrate
+++ b/tools/calibrate
@@ -5,21 +5,32 @@
 
 # Orchestrator for the calibrations that feed the default workflow.
 #
+# Artefacts land in data/curated/calibration/<source>/ where <source> is
+# the calibration.source of the base config (default: "default").
+#
 # Dependency order (upstream data changed → rerun in this order):
-#   1. feed        → data/curated/calibration/{grassland_yield,fodder_conversion,exogenous_forage,exogenous_feed}.csv
-#   2. food_waste  → data/curated/calibration/food_waste.yaml
-#   3. food_demand → data/curated/calibration/food_demand.csv
-#   4. cost        → data/curated/calibration/{crop_cost,grassland_cost,animal_cost}.csv
-#   5. stability   → data/curated/calibration/deviation_penalty.yaml
+#   1. feed        → {grassland_yield,fodder_conversion,exogenous_forage,exogenous_feed}.csv
+#   2. food_waste  → food_waste.yaml
+#   3. food_demand → food_demand.csv
+#   4. cost        → {crop_cost,grassland_cost,animal_cost}.csv
+#   5. stability   → deviation_penalty.yaml
+#
+# After a successful run the artefact set is stamped with a provenance
+# record (provenance.yaml) of the structural config it was fit against;
+# workflow runs check their config against the stamp of the set they
+# consume.
 #
 # Usage:
-#   tools/calibrate                # run all in order
+#   tools/calibrate                # run all in order (default artefact set)
 #   tools/calibrate feed           # one step (forage + protein feed slack)
 #   tools/calibrate food_waste
 #   tools/calibrate food_demand
 #   tools/calibrate cost
 #   tools/calibrate stability
 #   tools/calibrate --check        # report which calibrations are stale (no execution)
+#   tools/calibrate --base config/<name>.yaml [all|<step>|--check]
+#                                  # calibrate against a different base config;
+#                                  # the base must declare its own calibration.source
 #
 # All steps invoke ``tools/smk`` under the hood; any extra flags after the
 # subcommand are passed through.
@@ -34,25 +45,84 @@ SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
 cd "$PROJECT_ROOT"
 
+PROVENANCE_SCRIPT=workflow/scripts/write_calibration_provenance.py
+
+# Extract a global --base <config> option (anywhere in argv).
+BASE_CONFIG=""
+_args=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --base)
+      BASE_CONFIG="$2"
+      shift 2
+      ;;
+    --base=*)
+      BASE_CONFIG="${1#--base=}"
+      shift
+      ;;
+    *)
+      _args+=("$1")
+      shift
+      ;;
+  esac
+done
+set -- "${_args[@]}"
+
+BASE_ARGS=()
+if [[ -n "$BASE_CONFIG" ]]; then
+  [[ -f "$BASE_CONFIG" ]] || { echo "[calibrate] Base config not found: $BASE_CONFIG" >&2; exit 2; }
+  BASE_ARGS=(--base "$BASE_CONFIG")
+fi
+
+SOURCE=$(pixi run python "$PROVENANCE_SCRIPT" "${BASE_ARGS[@]}" --print-source | tail -n1)
+if [[ -n "$BASE_CONFIG" && "$SOURCE" == "default" ]]; then
+  echo "[calibrate] $BASE_CONFIG does not declare its own calibration.source;" >&2
+  echo "            it would overwrite the shared 'default' artefact set." >&2
+  echo "            Set calibration.source: <name> in $BASE_CONFIG first." >&2
+  exit 2
+fi
+CAL_DIR="data/curated/calibration/${SOURCE}"
+echo "[calibrate] artefact set: ${SOURCE} (${CAL_DIR})"
+
+# Non-default sources get their own processing/results tree so repeated
+# calibrations against different bases don't thrash each other's builds.
+NAME_OVERRIDE=()
+if [[ "$SOURCE" != "default" ]]; then
+  NAME_OVERRIDE=(--config "name=calibration-${SOURCE}")
+fi
+
+ARTEFACT_FILES=(
+  grassland_yield.csv
+  fodder_conversion.csv
+  exogenous_forage.csv
+  exogenous_feed.csv
+  food_waste.yaml
+  food_demand.csv
+  crop_cost.csv
+  grassland_cost.csv
+  animal_cost.csv
+  deviation_penalty.yaml
+)
+
 FEED_TARGETS=(
-  data/curated/calibration/grassland_yield.csv
-  data/curated/calibration/fodder_conversion.csv
-  data/curated/calibration/exogenous_forage.csv
-  data/curated/calibration/exogenous_feed.csv
+  "$CAL_DIR"/grassland_yield.csv
+  "$CAL_DIR"/fodder_conversion.csv
+  "$CAL_DIR"/exogenous_forage.csv
+  "$CAL_DIR"/exogenous_feed.csv
 )
 FOOD_WASTE_TARGETS=(
-  data/curated/calibration/food_waste.yaml
+  "$CAL_DIR"/food_waste.yaml
 )
 FOOD_DEMAND_TARGETS=(
-  data/curated/calibration/food_demand.csv
+  "$CAL_DIR"/food_demand.csv
 )
 COST_TARGETS=(
-  data/curated/calibration/crop_cost.csv
-  data/curated/calibration/grassland_cost.csv
-  data/curated/calibration/animal_cost.csv
+  "$CAL_DIR"/crop_cost.csv
+  "$CAL_DIR"/grassland_cost.csv
+  "$CAL_DIR"/animal_cost.csv
 )
 STABILITY_TARGETS=(
-  data/curated/calibration/deviation_penalty.yaml
+  "$CAL_DIR"/deviation_penalty.yaml
 )
 
 # All three calibration configs use gurobi; default the pixi env accordingly.
@@ -97,8 +167,11 @@ run_step() {
   shift 2
   split_args "$@"
   inject_env
-  echo "[calibrate] $label -- tools/smk --configfile $configfile ${PASSTHROUGH_ARR[*]} -- ${TARGETS_ARR[*]}"
-  tools/smk --configfile "$configfile" "${PASSTHROUGH_ARR[@]}" -- "${TARGETS_ARR[@]}"
+  local cfgfiles=()
+  [[ -n "$BASE_CONFIG" ]] && cfgfiles+=("$BASE_CONFIG")
+  cfgfiles+=("$configfile")
+  echo "[calibrate] $label -- tools/smk --configfile ${cfgfiles[*]} ${NAME_OVERRIDE[*]} ${PASSTHROUGH_ARR[*]} -- ${TARGETS_ARR[*]}"
+  tools/smk --configfile "${cfgfiles[@]}" "${NAME_OVERRIDE[@]}" "${PASSTHROUGH_ARR[@]}" -- "${TARGETS_ARR[@]}"
 }
 
 check_step() {
@@ -106,8 +179,11 @@ check_step() {
   shift 2
   split_args "$@"
   inject_env
+  local cfgfiles=()
+  [[ -n "$BASE_CONFIG" ]] && cfgfiles+=("$BASE_CONFIG")
+  cfgfiles+=("$configfile")
   local out
-  if ! out=$(tools/smk --configfile "$configfile" "${PASSTHROUGH_ARR[@]}" --dry-run --quiet -- "${TARGETS_ARR[@]}" 2>&1); then
+  if ! out=$(tools/smk --configfile "${cfgfiles[@]}" "${NAME_OVERRIDE[@]}" "${PASSTHROUGH_ARR[@]}" --dry-run --quiet -- "${TARGETS_ARR[@]}" 2>&1); then
     printf '  [error]      %-10s (dry-run failed; see output below)\n' "$label"
     printf '%s\n' "$out" | sed 's/^/    /'
     return 2
@@ -120,12 +196,56 @@ check_step() {
   fi
 }
 
+# Stamp the artefact set with the structural config it was fit against.
+stamp_provenance() {
+  pixi run python "$PROVENANCE_SCRIPT" "${BASE_ARGS[@]}"
+}
+
+# A fresh (non-default) artefact set must be seeded before the chain can
+# run: each step's solve consumes the other steps' artefacts, so missing
+# files are copied from the default set as a starting vintage and then
+# regenerated in order by the full chain.
+seed_source_set() {
+  local missing=()
+  local f
+  for f in "${ARTEFACT_FILES[@]}"; do
+    [[ -f "$CAL_DIR/$f" ]] || missing+=("$f")
+  done
+  [[ ${#missing[@]} -eq 0 ]] && return 0
+  if [[ "$cmd" != all ]]; then
+    echo "[calibrate] Artefact set '${SOURCE}' is incomplete (missing: ${missing[*]})." >&2
+    echo "            Run the full chain first: tools/calibrate --base $BASE_CONFIG all" >&2
+    exit 2
+  fi
+  mkdir -p "$CAL_DIR"
+  for f in "${missing[@]}"; do
+    cp "data/curated/calibration/default/$f" "$CAL_DIR/$f"
+  done
+  echo "[calibrate] Seeded ${#missing[@]} artefact(s) in $CAL_DIR from the default set;"
+  echo "            the full chain will regenerate them in order."
+}
+
 cmd="${1:-all}"
 shift || true
 
+if [[ "$SOURCE" != "default" ]]; then
+  case "$cmd" in
+    all|feed|food_waste|food_demand|cost|stability) seed_source_set ;;
+    --check|check)
+      for f in "${ARTEFACT_FILES[@]}"; do
+        if [[ ! -f "$CAL_DIR/$f" ]]; then
+          echo "[calibrate] Artefact set '${SOURCE}' is incomplete (missing e.g. $f)." >&2
+          echo "            Generate it first: tools/calibrate --base $BASE_CONFIG all" >&2
+          exit 2
+        fi
+      done
+      ;;
+  esac
+fi
+
 case "$cmd" in
   -h|--help|help)
-    sed -n '7,22p' "$0"
+    sed -n '7,40p' "$0"
     exit 0
     ;;
   --check|check)
@@ -136,6 +256,7 @@ case "$cmd" in
     check_step food_demand config/calibration/food_demand.yaml "${FOOD_DEMAND_TARGETS[@]}" -- "$@" || rc=$?
     check_step cost        config/calibration/cost.yaml        "${COST_TARGETS[@]}"        -- "$@" || rc=$?
     check_step stability   config/calibration/stability.yaml   "${STABILITY_TARGETS[@]}"   -- "$@" || rc=$?
+    pixi run python "$PROVENANCE_SCRIPT" "${BASE_ARGS[@]}" --check | sed 's/^/  /' || rc=$?
     exit "$rc"
     ;;
   all)
@@ -144,25 +265,31 @@ case "$cmd" in
     run_step food_demand config/calibration/food_demand.yaml "${FOOD_DEMAND_TARGETS[@]}" -- "$@"
     run_step cost        config/calibration/cost.yaml        "${COST_TARGETS[@]}"        -- "$@"
     run_step stability   config/calibration/stability.yaml   "${STABILITY_TARGETS[@]}"   -- "$@"
+    stamp_provenance
     ;;
   feed)
     run_step feed config/calibration/feed.yaml "${FEED_TARGETS[@]}" -- "$@"
+    stamp_provenance
     ;;
   food_waste)
     run_step food_waste config/calibration/food_waste.yaml "${FOOD_WASTE_TARGETS[@]}" -- "$@"
+    stamp_provenance
     ;;
   food_demand)
     run_step food_demand config/calibration/food_demand.yaml "${FOOD_DEMAND_TARGETS[@]}" -- "$@"
+    stamp_provenance
     ;;
   cost)
     run_step cost config/calibration/cost.yaml "${COST_TARGETS[@]}" -- "$@"
+    stamp_provenance
     ;;
   stability)
     run_step stability config/calibration/stability.yaml "${STABILITY_TARGETS[@]}" -- "$@"
+    stamp_provenance
     ;;
   *)
     echo "[calibrate] Unknown subcommand: $cmd" >&2
-    echo "Usage: tools/calibrate [all|feed|food_waste|food_demand|cost|stability|--check]" >&2
+    echo "Usage: tools/calibrate [--base <config>] [all|feed|food_waste|food_demand|cost|stability|--check]" >&2
     exit 2
     ;;
 esac
diff --git a/tools/export_model.py b/tools/export_model.py
index e36f2e4a..3637f268 100755
--- a/tools/export_model.py
+++ b/tools/export_model.py
@@ -37,6 +37,7 @@
     build_residue_feed_fraction_by_country,
 )
 from workflow.scripts.solve_model.health import add_health_objective
+from workflow.scripts.solve_namespace import resolve_calibration_source_paths
 
 # Enable new PyPSA components API
 pypsa.options.api.new_components_api = True
@@ -70,7 +71,7 @@ def load_config(config_path: str) -> dict:
         user_config = yaml.safe_load(f)
 
     _recursive_update(config, user_config)
-    return config
+    return resolve_calibration_source_paths(config)
 
 
 def build_and_export_model(
diff --git a/tools/smk b/tools/smk
index 3b470a1a..fbd30e04 100755
--- a/tools/smk
+++ b/tools/smk
@@ -68,7 +68,7 @@ trap restore_cursor EXIT
 # reminder. Intentionally non-blocking and non-authoritative; run
 # ``tools/calibrate --check`` for the real answer.
 if [[ -z "${SMK_SKIP_CALIBRATION_HINT:-}" && -d data/curated/calibration ]]; then
-  cal_oldest=$(find data/curated/calibration -maxdepth 1 -type f -printf '%T@\n' 2>/dev/null | sort -n | head -n1 || true)
+  cal_oldest=$(find data/curated/calibration -type f -printf '%T@\n' 2>/dev/null | sort -n | head -n1 || true)
   if [[ -n "${cal_oldest}" ]]; then
     upstream_newest=$(find data/curated -type f -not -path 'data/curated/calibration/*' -printf '%T@\n' 2>/dev/null | sort -n | tail -n1 || true)
     if [[ -n "${upstream_newest}" ]] && awk -v u="$upstream_newest" -v c="$cal_oldest" 'BEGIN { exit (u > c) ? 0 : 1 }'; then
diff --git a/workflow/Snakefile b/workflow/Snakefile
index 48789da0..8b4e08cd 100644
--- a/workflow/Snakefile
+++ b/workflow/Snakefile
@@ -9,6 +9,8 @@ from snakemake.utils import min_version
 
 from validation import load_secrets_with_env_fallback, validate
 
+from workflow.scripts.solve_namespace import resolve_calibration_source_paths
+
 min_version("9.0")
 
 os.makedirs("data/downloads", exist_ok=True)
@@ -21,6 +23,9 @@ configfile: "config/default.yaml"
 secrets = load_secrets_with_env_fallback(Path.cwd())
 config.setdefault("credentials", {}).update(secrets)
 
+# Resolve {calibration_source} placeholders in artefact paths against
+# config["calibration"]["source"] before any rule or validator reads them.
+resolve_calibration_source_paths(config)
 
 validate(config, project_root=Path.cwd())
 
diff --git a/workflow/scripts/solve_namespace.py b/workflow/scripts/solve_namespace.py
index 9bd82c19..7b82a3e0 100644
--- a/workflow/scripts/solve_namespace.py
+++ b/workflow/scripts/solve_namespace.py
@@ -205,6 +205,31 @@ def validate_scenario_config_schemas(
 )
 
 
+def resolve_calibration_source_paths(config: dict) -> dict:
+    """Substitute ``{calibration_source}`` in all string config values.
+
+    Calibration artefact paths in config/default.yaml carry the
+    ``{calibration_source}`` placeholder so that a single key,
+    ``calibration.source``, selects which artefact set under
+    ``data/curated/calibration/<source>/`` a config reads (and, for
+    generation runs, writes). Mutates ``config`` in place and returns it.
+    """
+    source = config["calibration"]["source"]
+
+    def _substitute(node):
+        if isinstance(node, dict):
+            return {k: _substitute(v) for k, v in node.items()}
+        if isinstance(node, list):
+            return [_substitute(v) for v in node]
+        if isinstance(node, str):
+            return node.replace("{calibration_source}", source)
+        return node
+
+    for key in list(config.keys()):
+        config[key] = _substitute(config[key])
+    return config
+
+
 def load_merged_config(*configfiles) -> dict:
     """Load and merge YAML config files (later files override earlier ones)."""
     merged: dict = {}
@@ -212,7 +237,7 @@ def load_merged_config(*configfiles) -> dict:
         with open(path) as f:
             data = yaml.safe_load(f) or {}
         _recursive_update(merged, data)
-    return merged
+    return resolve_calibration_source_paths(merged)
 
 
 def get_effective_config(
diff --git a/workflow/scripts/write_calibration_provenance.py b/workflow/scripts/write_calibration_provenance.py
new file mode 100644
index 00000000..2cc5aebb
--- /dev/null
+++ b/workflow/scripts/write_calibration_provenance.py
@@ -0,0 +1,118 @@
+# SPDX-FileCopyrightText: 2026 Koen van Greevenbroek
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Write (or check) the provenance stamp of a calibration artefact set.
+
+The stamp records the structural configuration a calibration artefact set
+was fit against; see workflow/validation/calibration_provenance.py for
+the snapshot semantics. Invoked by ``tools/calibrate`` after a successful
+run (and with ``--check`` as part of ``tools/calibrate --check``).
+
+Usage:
+    pixi run python workflow/scripts/write_calibration_provenance.py \
+        [--base config/<name>.yaml] [--check]
+"""
+
+import argparse
+from datetime import datetime, timezone
+from pathlib import Path
+import subprocess
+import sys
+
+import yaml
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(PROJECT_ROOT))
+
+from workflow.scripts.solve_namespace import load_merged_config  # noqa: E402
+from workflow.validation.calibration_provenance import (  # noqa: E402
+    diff_snapshots,
+    load_provenance,
+    provenance_path,
+    structural_snapshot,
+)
+
+
+def _git_commit() -> str | None:
+    try:
+        return subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=PROJECT_ROOT,
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+    except (OSError, subprocess.CalledProcessError):
+        return None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--base",
+        help="Base config layered on config/default.yaml (default: none)",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Compare the existing stamp against the current config instead of writing",
+    )
+    parser.add_argument(
+        "--print-source",
+        action="store_true",
+        help="Print the resolved calibration.source and exit (used by tools/calibrate)",
+    )
+    args = parser.parse_args()
+
+    configfiles = [PROJECT_ROOT / "config" / "default.yaml"]
+    if args.base:
+        configfiles.append(Path(args.base))
+    config = load_merged_config(*configfiles)
+    source = config["calibration"]["source"]
+
+    if args.print_source:
+        print(source)
+        return 0
+
+    snapshot = structural_snapshot(config)
+
+    if args.check:
+        try:
+            stamp = load_provenance(source, PROJECT_ROOT)
+        except ValueError as exc:
+            print(exc)
+            return 1
+        diffs = diff_snapshots(stamp["structural_config"], snapshot)
+        if diffs:
+            print(f"Provenance MISMATCH for artefact set '{source}':")
+            for d in diffs:
+                print(f"  {d}")
+            return 1
+        print(f"Provenance of artefact set '{source}' matches the current config.")
+        return 0
+
+    path = provenance_path(source, PROJECT_ROOT)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    stamp = {
+        "source": source,
+        "base_config": str(Path(args.base)) if args.base else "config/default.yaml",
+        "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "git_commit": _git_commit(),
+        "structural_config": snapshot,
+    }
+    with open(path, "w") as f:
+        f.write(
+            "# Provenance stamp of this calibration artefact set: the\n"
+            "# structural config it was fit against. Generated by\n"
+            "# workflow/scripts/write_calibration_provenance.py via\n"
+            "# tools/calibrate; do not edit by hand.\n"
+            "# Licensing: see the annotation in REUSE.toml.\n"
+        )
+        yaml.safe_dump(stamp, f, sort_keys=True, default_flow_style=False)
+    print(f"Wrote {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/workflow/validation/__init__.py b/workflow/validation/__init__.py
index 9c5f98ba..80bd8fcf 100644
--- a/workflow/validation/__init__.py
+++ b/workflow/validation/__init__.py
@@ -11,6 +11,7 @@
 from snakemake.logging import logger
 
 from .calibration import validate_calibration
+from .calibration_provenance import validate_calibration_provenance
 from .commodities import validate_commodities
 from .config_schema import validate_config_schema
 from .consumer_values import validate_consumer_values
@@ -40,6 +41,7 @@
 _CHECKS: dict[str, Validator] = {
     "config_schema": validate_config_schema,
     "calibration": validate_calibration,
+    "calibration_provenance": validate_calibration_provenance,
     "commodities": validate_commodities,
     "restricted_data": validate_restricted_data,
     "consumer_values": validate_consumer_values,
diff --git a/workflow/validation/calibration_provenance.py b/workflow/validation/calibration_provenance.py
new file mode 100644
index 00000000..241937ad
--- /dev/null
+++ b/workflow/validation/calibration_provenance.py
@@ -0,0 +1,173 @@
+# SPDX-FileCopyrightText: 2026 Koen van Greevenbroek
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Provenance tracking for calibration artefact sets.
+
+Each artefact set under ``data/curated/calibration/<source>/`` carries a
+``provenance.yaml`` recording the structural configuration it was
+calibrated against (written by ``tools/calibrate`` via
+``workflow/scripts/write_calibration_provenance.py``). At workflow start
+the active config is compared against the stamp of the set it consumes
+(``calibration.source``); a mismatch means the artefacts were fit under
+different structural assumptions and are not valid for this config.
+
+The comparison covers all *structural* config leaves: solve-time keys
+(SOLVE_TIME_CONFIG_PREFIXES) never invalidate calibration, and a small
+set of additional prefixes is exempted below because it describes run
+identity or calibration machinery rather than what the artefacts were
+fit to.
+"""
+
+from pathlib import Path
+
+from snakemake.logging import logger
+import yaml
+
+from workflow.scripts.solve_namespace import _is_solve_time_key
+
+CALIBRATION_DIR = Path("data/curated/calibration")
+PROVENANCE_FILENAME = "provenance.yaml"
+
+# Exempt from the structural snapshot, on top of the solve-time prefixes.
+PROVENANCE_EXEMPT_PREFIXES = {
+    # Run identity and workflow machinery.
+    "name",
+    "scenarios",
+    "paths",
+    "downloads",
+    "credentials",
+    "calibration",
+    # Validation-mode switches: the artefacts are consumed by regular and
+    # validation-mode solves alike (the calibration chain itself runs in
+    # validation mode).
+    "validation",
+    # Artefacts are fit at baseline_year and applied at any planning
+    # horizon by design.
+    "planning_horizon",
+    # Post-solve analysis only.
+    "sensitivity_analysis",
+    # Calibration application/generation machinery. Fit-relevant knobs in
+    # these sections (e.g. food_loss_waste_calibration.food_groups,
+    # food_demand_calibration.min_multiplier) stay in the snapshot.
+    "grazing.grassland_forage_calibration",
+    "exogenous_feed_calibration",
+    "cost_calibration",
+    "food_loss_waste_calibration.enabled",
+    "food_loss_waste_calibration.generate",
+    "food_loss_waste_calibration.scenario",
+    "food_loss_waste_calibration.calibration_file",
+    "food_demand_calibration.enabled",
+    "food_demand_calibration.generate",
+    "food_demand_calibration.scenario",
+    "food_demand_calibration.calibration_file",
+}
+
+# Dotted paths of the generate flags of all calibration sections; any of
+# them being true marks a generation run (the calibration chain itself),
+# for which the provenance check is skipped.
+_GENERATE_FLAG_PATHS = [
+    ("grazing", "grassland_forage_calibration", "generate"),
+    ("exogenous_feed_calibration", "generate"),
+    ("food_loss_waste_calibration", "generate"),
+    ("food_demand_calibration", "generate"),
+    ("cost_calibration", "generate"),
+    ("deviation_penalty", "calibration", "generate"),
+]
+
+
+def _is_exempt(key: str) -> bool:
+    return any(key == p or key.startswith(p + ".") for p in PROVENANCE_EXEMPT_PREFIXES)
+
+
+def structural_snapshot(config: dict) -> dict:
+    """Flat dotted-key map of the fit-relevant structural config leaves."""
+    snapshot: dict = {}
+
+    def walk(node: dict, prefix: str) -> None:
+        for k, v in node.items():
+            full = f"{prefix}.{k}" if prefix else str(k)
+            if _is_solve_time_key(full) or _is_exempt(full):
+                continue
+            if isinstance(v, dict):
+                walk(v, full)
+            else:
+                snapshot[full] = v
+
+    walk(config, "")
+    return snapshot
+
+
+def diff_snapshots(stamped: dict, active: dict) -> list[str]:
+    """Human-readable differences between a stamp and the active snapshot."""
+    diffs = []
+    for key in sorted(stamped.keys() | active.keys()):
+        if key not in active:
+            diffs.append(f"{key}: in stamp ({stamped[key]!r}) but not in config")
+        elif key not in stamped:
+            diffs.append(f"{key}: in config ({active[key]!r}) but not in stamp")
+        elif stamped[key] != active[key]:
+            diffs.append(f"{key}: stamp {stamped[key]!r} != config {active[key]!r}")
+    return diffs
+
+
+def provenance_path(source: str, project_root: Path) -> Path:
+    return project_root / CALIBRATION_DIR / source / PROVENANCE_FILENAME
+
+
+def load_provenance(source: str, project_root: Path) -> dict:
+    path = provenance_path(source, project_root)
+    if not path.exists():
+        raise ValueError(
+            f"Calibration artefact set '{source}' has no provenance stamp "
+            f"({path}). Regenerate the set with tools/calibrate (which "
+            "stamps it), or point calibration.source at a stamped set."
+        )
+    with open(path) as f:
+        return yaml.safe_load(f)
+
+
+def is_generation_run(config: dict) -> bool:
+    """True if any calibration section has generate=true (calibration chain)."""
+    for path in _GENERATE_FLAG_PATHS:
+        node = config
+        for key in path:
+            node = node[key]
+        if node:
+            return True
+    return False
+
+
+def validate_calibration_provenance(
+    config: dict, project_root: Path | None = None
+) -> None:
+    """Check the active config against the consumed artefact set's stamp."""
+    if is_generation_run(config):
+        return
+
+    root = Path(project_root) if project_root else Path.cwd()
+    source = config["calibration"]["source"]
+    stamp = load_provenance(source, root)
+    diffs = diff_snapshots(stamp["structural_config"], structural_snapshot(config))
+    if not diffs:
+        return
+
+    bullet_list = "\n".join(f"   {d}" for d in diffs)
+    message = (
+        f"The active config differs structurally from what calibration "
+        f"artefact set '{source}' was calibrated against "
+        f"({provenance_path(source, root)}):\n{bullet_list}\n"
+        "The artefacts are not valid for this config. Either recalibrate "
+        "(set a dedicated calibration.source in this config and run "
+        "tools/calibrate --base <configfile>), point calibration.source at "
+        "a compatible set, or set calibration.accept_provenance_mismatch: "
+        "true to knowingly proceed."
+    )
+    if config["calibration"]["accept_provenance_mismatch"]:
+        logger.warning(
+            f"Accepted calibration provenance mismatch ({len(diffs)} "
+            f"differing keys) between the active config and artefact set "
+            f"'{source}'."
+        )
+        return
+    raise ValueError(message)