[bl-young]

cc:
Related: #1144, #1146, https://github.com/cornerstone-data/ceda/issues/547

What changed? Why?

Adds A_margin to SNAPSHOT_NAMES and writes it from derive_cornerstone_A_margin in generate_snapshots, so the next canonical snapshot cut emits the Cornerstone commodity x commodity margin allocation matrix next to Phi. Documents the interim GCS sidecar pattern (same as Phi #649) and the CEDA handoff contract N_margin = N @ A_margin (multiply by the consumer's N after mapping codes). Does not bump .SNAPSHOT_KEY.

Impact

No change to published USA A/B/q/N or SEF outputs; consumers that load snapshots gain A_margin.parquet on the next full cut. Until then, CEDA loads the commodity-split interim from #1144 (not the early buyer-split object under the v0.6 snapshot key).

Testing

Local derive under 2025_usa_cornerstone_v0_6: 405 x 405, 24 nonzero margin-provider rows inside the Transportation/Wholesale/Retail map, no NaN/Inf; spot-checked goods columns and confirmed col-sum > 1 cases match the filtered margins table ratios.

uv run python -c "from bedrock.utils.config.usa_config import set_global_usa_config; from bedrock.transform.eeio.derived_cornerstone import derive_cornerstone_A_margin; set_global_usa_config('2025_usa_cornerstone_v0_6'); print(derive_cornerstone_A_margin().shape)"

Heads-up

CEDA interim handoff (commodity-split; #1144):

gs://cornerstone-default/snapshots/a_margin/v0.6.0_5d40d42/A_margin.parquet

This PR only registers the snapshot name for future full cuts. Time-series MUT rebuild + v1.0 retarget: #1146.

Evidence

• Shape 405 x 405; index/columns named sector (buyer-split derive under canonical v0.6 used for wiring smoke-check)
• Nonzero rows: 24 margin providers; zero rows among map codes: 485000, 492000, 48A000, 493000, 4200ID
• Margin-on-margin block all zero; electricity 221100 column all zero

[bl-young]

@WesIngwersen - until we generate a new snapshot here, the A_margins file to use is in the temporary location shown above. Please confirm this matches the margins file you expect for the 2024 model.

[WesIngwersen]

A_margin[i, j] is the margin dollars commodity j's purchasers pay to margin sector i, divided by j's total producer value.

Confirm the product is a 405x405 matrix with these contents for the 2024 margins. No price adjustment occurs since nominal value is the same as the given values, because usa_base_io_data_year == model_base_year

[bl-young]

@WesIngwersen could you approve this when you have a moment?

Still needed for future generate_snapshots / .SNAPSHOT_KEY cuts (A_margin in SNAPSHOT_NAMES), even though the interim object under …/a_margin/e10c75f…/ is not what CEDA should use — that handoff is the #1144 sidecar at gs://cornerstone-default/snapshots/a_margin/v0.6.0_5d40d42/A_margin.parquet (see ceda#555).

Happy to land this alongside #1144; follow-on for time-series MUT rebuild + v1.0 retarget is #1146.