# csi-v1.1.0 CANDIDATE — NOT a published methodology. NEVER consumed by the production engine.
#
# Status: candidate overlay on the csi-v1.1.0 certification track (ADR-009, upt-architecture).
# Owner green-lit the trade recalibration track on 2026-06-10 ("GREENLIGHT: csi-v1.1.0 trade
# recalibration track"). Activation still requires the full ADR-009 eleven-point gate with a
# named human review; until then the locked configs/csi.v1.yaml (csi-v1.0.0) remains the only
# published methodology and its bytes/methodologyHash are never edited.
#
# This file is an OVERLAY: it records only the candidate deltas against csi-v1.0.0. Every field
# not listed here is inherited from csi.v1.yaml unchanged — in particular the eight metric ids,
# the raw weights 25/20/15/10/10/10/7/4 over 101 (never renormalised), every direction factor,
# and the engine recurrence (smoothing -> per-epoch cap -> bounded deviation -> sub-index).
# If this overlay and csi.v1.yaml disagree on an inherited constant, publication fails closed.
#
# Empirical basis: scripts/evaluate_v110_trade_recalibration.py (deterministic; reproduces the
# deployed v1.0.0 trade trace to < 1E-12 before evaluating candidates) and the evaluation record
# docs/csi-v1-1-0-trade-recalibration-evaluation.md.

candidate_version: csi-v1.1.0-candidate.2
base_methodology: csi-v1.0.0
status: candidate_unactivated
activation_gate: >-
  ADR-009 eleven-point checklist, evaluated against the ADR-011 (Reading A) scope: this
  candidate carries the trade recalibration and the consumer redefinition only; the registry
  change (global_livestock_population, just_transition_integrity + W_JT, CSI_meas/CSI_ref)
  is the csi-v1.2.0 track. Owner scope decision and conditional activation pre-authorisation
  recorded 2026-06-11 in upt-architecture docs/csi-v1-1-0-activation-gate-status.md.

metric_overlays:
  - id: animal_product_trade
    # THE SATURATION FIX — re-anchor (option D/E of the evaluation; options B and C rejected
    # because widening bounds or rescaling the deviation keeps the cap-bound constant grind,
    # which is rate-insensitive and therefore still uninformative).
    #
    # 1. Historical measurement baseline window moves 2000-2004 -> 2018-2022 for THIS metric
    #    only. World animal-product export volume is ~2.9x the 2000-2004 median, so the locked
    #    anchor forces y_bar onto the +1 rail (sub-index 9.17 at 2023, pinned at 0 by 2025) and
    #    the 5%-of-baseline per-epoch cap binds permanently (a constant -5/yr grind regardless
    #    of the real rate). Against the 2018-2022 median the 2023 level is a meaningful 99.12
    #    and the rail sits far away.
    baseline_window: { from: 2018, to: 2022 }
    # 2. Per-epoch cap retuned 0.050 -> 0.100 of the (new) baseline. The cap exists to damp
    #    one-epoch shocks, not to hide sustained moves; recent real episodes run ~11%/yr, so at
    #    0.050 the cap would still bind through fast episodes (option D shows a cap-shaped
    #    -5/-5/-5 tail), while at 0.100 the path tracks the smoothed real deviation (option E:
    #    -5.4/-7.9/-4.7, rate-sensitive). Tunable on this track; 0.100 is the recommendation.
    per_epoch_cap_fraction_of_baseline: "0.100"
    # 3. Bounds stay at the inherited [-1, 1]: with a modern anchor the deviation lives well
    #    inside the rails, so no axis rescaling or negative sub-index values are introduced.
    #
    # Restatement contract: activating this overlay RESTATES the 2000-2026 trade sub-index
    # series against the new anchor (the v1.1.0 series starts at 106.57 in 2018, 99.12 in 2023).
    # The restated series is published as a NEW labelled series on the candidate proof chain;
    # the locked csi-v1.0.0 series is preserved untouched as the historical record. Direct
    # raw-to-CSI parity at E8 must pass on the candidate track before any publication switch.

  - id: consumer_transition_score
    # THE CONSUMER REDEFINITION (owner blueprint 2026-06-10; decision log: evidence collector
    # green-lit UNWIRED, wired replacement HELD until ADR-009). This block is the explicit
    # transformation from price-basket evidence into a positive transition score that the
    # decision log requires before any wiring.
    #
    # Candidate construction (evidence artefact: upt-web public/data/csi/g20-consumer-cpi/):
    #   relative_price_signal[m] = ln(plant_basket_index[m] / animal_basket_index[m])
    #   expenditure_scaler       = plant_weight / max(animal_weight, 0.0001)
    #   score_raw[m]             = -1 * relative_price_signal[m] * expenditure_scaler
    #   score_3m[m]              = trailing 3-month mean of score_raw (the headline nowcast)
    # Baskets at official 4-digit classifications: animal = meat + fish/seafood + dairy/eggs;
    # plant = cereals + fruit + vegetables. EU economies use HICP ECOICOP v2 (coicop18, I25)
    # with prc_hicp_iw item weights; the US uses BLS CPI aggregates with the OFFICIAL Consumer
    # Expenditure scaler (CE 2024: plant 1732 USD / animal 2045 USD = 0.8469). Commercial retail
    # reports are validation-only, never production inputs.
    #
    # TRANSFORMATION into the engine's positive transition sub-index (direction +1 inherited):
    #   metric_annual[t]    = calendar-year mean of score_3m
    #   aggregated_index[t] = 100 * (1 + (metric_annual[t] - metric_annual[2023]))
    # so the candidate metric sits at exactly 100 at the 2023 anchor, rises as the plant basket
    # becomes relatively cheaper and/or structurally more important, and composes through the
    # unchanged engine recurrence. Anchor/baseline window for THIS metric moves to 2023 (the
    # CPI-evidence era); weight 4/101 and direction +1 are inherited unchanged.
    baseline_window: { from: 2023, to: 2023 }
    canonical_unit: normalised_index
    candidate_construction: cpi_relative_price_basket_v1
    # Gate parameters PINNED 2026-06-11 (owner delegation per ADR-011; previously open):
    #   smoothing_lambda: inherited "0.50" unchanged — the CPI construction already carries a
    #     trailing 3-month mean, and stacking a tighter annual smoother would double-damp.
    #   per_epoch_cap: inherited "0.030" unchanged — relative food-price drifts are slow;
    #     the 2023-2026 evidence (simulatedImpact in the CPI artefact) moves well inside it.
    #   economy coverage at activation: DE, FR, IT, TR, EU aggregate, US — the six economies
    #     with official ECOICOP-v2/BLS series live today (>= half of G20 consumer spending);
    #     additions ride later releases as data work, not methodology change.
    #   CP01144 (non-animal milks): STAYS in the animal dairy basket for v1.1.0 — the
    #     reassignment needs 5-digit ECOICOP detail not yet collected at evidence grade;
    #     moving it later is a recorded one-line basket change on the next candidate rev.
    smoothing_lambda: "0.50"
    per_epoch_cap_fraction_of_baseline: "0.030"
    activation_economy_coverage: [DEU, FRA, ITA, TUR, EU, USA]
    cp01144_assignment: animal_basket
    # Pooling rule (pinned 2026-06-11): the composed metric pools score_raw as the equal-weight
    # mean over the NON-OVERLAPPING blocs [EU27_2020, TUR, USA] — the EU aggregate already
    # contains DE/FR/IT, which stay published as per-economy validation lenses and are never
    # pooled (no double counting, mirroring the sub-index-vs-lens rule). Months where a bloc's
    # series has not started yet (EU27_2020 begins 2000-12) pool over the available blocs, with
    # the per-epoch panel composition recorded in the replay artefact. Basket aggregation and
    # the expenditure scaler use each year's own published weights (HICP item weights per year;
    # US CE expenditures per year), falling back to the nearest earlier published year.
    pooling_rule: equal_weight_non_overlapping_blocs
    pooled_blocs: [EU27_2020, TUR, USA]
    validation_lenses: [DEU, FRA, ITA]
    weights_vintage: per_year_published
    # History bridge (restatement contract for this metric): the redefined score is computed
    # from official CPI/HICP series, which exist back past 2000 (ECOICOP v1 frozen dataset to
    # 2025-12, ECOICOP v2/coicop18 from 2026-01, spliced at the cutover; BLS CPI + annual CE
    # weights for the US). The candidate series is therefore REPLAYED from the actual price
    # history, not bridged from the v1.0.0 FBS series; the locked v1.0.0 consumer series is
    # preserved untouched as the historical record of the old definition.
    #
    # Until ADR-009 activates this block, the v1.0.0 consumer metric (FBS plant-protein share)
    # remains the only composed definition — and it is separately ARMED with a same-meaning
    # source splice (upt-web scripts/collect-consumer-protein-share.py) that moves it on the
    # next FAOSTAT FBS release without any methodology change.

bridge_inputs:
  # Evidence and bridge sources for the recalibrated metric (data inputs, not methodology).
  # SUPERSEDED 2026-06-11: the operational bridge is now the QUANTITY-CONSISTENT bridge
  # (upt-web scripts/collect-g20-trade-quantity.py — registered Comtrade tier, HS6 leaf net
  # weight, 18 of 19 G20 reporters, activationUse: true; kg matched-panel factors 1.0457 /
  # 1.0673 for 2024 / 2025-26), resolving the value-vs-quantity caveat that parked the old
  # value bridge. Five national customs comparison rows are live (BRA and FRA also
  # quantity-consistent; USA matches the value bridge to -0.05 percent in 2024); the
  # remaining national collectors stay a hardening track, not an activation blocker.
  operational_bridge: un_comtrade_quantity
  superseded_value_proxy: un_comtrade_export_value
  target_primary: national_customs_collectors_15
  comparison_required_before_activation: true
  comparison_recorded: upt-architecture docs/csi-v1-1-0-activation-gate-status.md
