Refactor: decouple electricity disagg from main cornerstone pipeline

[jvendries]

cc:
Closes:

What changed? Why?

Electricity imports in cornerstone_disagg_pipeline.py are now lazy — moved inside their respective flag-gated branches (electricity_reallocation_enabled(), electricity_disaggregation_enabled(), electricity_mixed_units_enabled()). Previously, electricity_disaggregation.py and electricity_end_use_mapping.py were loaded unconditionally at import time, meaning waste-only and canonical v0.3 configs pulled in electricity modules unnecessarily.

Module-level lazy facade functions (build_end_use_map, electricity_end_use_retail_prices_cents_kwh, classify_industry_end_use, build_end_use_map_resolved) and a __getattr__ hook for END_USE_MAPPING_REVIEW_STATUS are introduced in cornerstone_disagg_pipeline.py. These facades delegate to electricity_end_use_mapping on first call without loading it at import time, while preserving existing @patch targets.

In cornerstone_year_scaling.py, the correction imports are moved inside the if electricity_disaggregation_enabled(): block rather than before it.

In cache_reset.py, top-level imports of electricity helpers are removed. Electricity @cache clears are now handled by _clear_electricity_caches_if_loaded(), which uses sys.modules.get(...) to flush caches only when those modules are already loaded — ensuring multi-config processes (e.g. switching from a flag-on run to v0.3) still clear stale caches without ever importing electricity modules in a v0.3-only process.

The monetary_disagg_report.md is updated to reflect the renamed correction functions.

Several internal functions and symbols have been renamed to better reflect their purpose:

• table_2_4_prices_cents_kwh → electricity_end_use_retail_prices_cents_kwh across all call sites, imports, mock patches, and test assertions. The new name makes clear that the source is EIA Electric Power Annual Table 2.4 (average retail prices to ultimate customers) and that the result is used to build class-specific MWh/$ conversion factors.
• _table83_purchased_power_expenses → _iou_utility_gtd_operating_expenses
• _weights_from_table83_expenses → _normalize_gtd_expense_weights
• build_electricity_ugo305_scaling_ratios → build_electricity_detail_GO_growth_ratios
• utilities_summary_ratio_22 → utilities_summary_q_growth_ratio
• apply_electricity_d7_scaling_correction_to_A → rescale_electricity_children_to_detail_GO_growth_A
• apply_electricity_d7_scaling_correction_to_q → rescale_electricity_children_to_detail_GO_growth_q

Testing

• Verified that importing cornerstone_disagg_pipeline and cache_reset under a v0.3 config (all electricity flags false) does not load electricity_disaggregation or electricity_end_use_mapping into sys.modules.
• Confirmed clear_all_publish_caches() still flushes electricity caches in processes where those modules were previously loaded by a flag-on run.
• Existing tests for electricity disaggregation, reallocation, mixed units, and waste pipeline remain green.
• Patch targets on cornerstone_disagg_pipeline.electricity_end_use_retail_prices_cents_kwh continue to intercept calls correctly via the lazy facade.

[jvendries]

• Refactor: decouple electricity disagg from main cornerstone pipeline #558 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[jvendries]

The decoupling re-structuring happens in these files:

1. bedrock/transform/eeio/cornerstone_disagg_pipeline.py: main change: no top-level elec imports; lazy imports behind flags; lazy facade for electricity_end_use_retail_prices_cents_kwh / build_end_use_map
2. bedrock/publish/cache_reset.py: clears elec @cache via sys.modules.get only (must not import elec under v0.3)
3. bedrock/transform/eeio/cornerstone_year_scaling.py: detail-GO rescale imports nested inside if electricity_disaggregation_enabled()

The rest are renaming functions so that their use is more clearly indicated in the name.

[bl-young]

looks fine - thanks for the cleanup. I might recommend you clarify in the commit to main that this is a true refactor, e.g.

refactor: Decouple electricity disagg from main cornerstone pipeline

[jvendries]

looks fine - thanks for the cleanup. I might recommend you clarify in the commit to main that this is a true refactor, e.g.

refactor: Decouple electricity disagg from main cornerstone pipeline

Edited PR title to make it clear this is a true refactor