What

Build a utils/post/validate/ sub-package that validates CAIRO runs 1–8 for any utility (NY first, generalizable to RI). The framework reads outputs from S3 (s3://data.sb/switchbox/cairo/outputs/hp_rates/{state}/{utility}/{timestamp}/), runs structured checks (revenue neutrality, BAT direction, tariff stability, output completeness), and generates plotnine plots + summary CSVs.

Why

CAIRO run validation is currently manual and ad-hoc—done in one-off Quarto notebooks with duplicated logic. A reusable validation framework will:

• Catch configuration errors and regressions early (before reports are built)
• Provide a consistent, auditable record of what passed/failed for each batch
• Reduce the time to validate a new batch from hours to minutes
• Make it easy to extend validation to new states (RI) and new run types

How

1. config.py: RunConfig and RunBlock dataclasses encoding run metadata (type, upgrade, cost scope, subclasses) and expected behaviors (revenue-neutral, BAT-relevant, tariff unchanged). Parse from existing scenario YAMLs.
2. discover.py: S3 batch discovery—find latest complete batch or resolve an explicit timestamp. Uses boto3.
3. load.py: Readers for CAIRO outputs (bills CSVs, BAT CSV, customer metadata, tariff JSON) via polars lazy scan + boto3 for JSON.
4. checks.py: Structured check functions returning CheckResult(name, passed, message, details)—revenue neutrality, subclass RR, BAT direction/near-zero, tariff stability, output completeness.
5. tables.py: Summary table builders (bills by subclass, BAT by subclass, revenue vs RR, tariff rates, non-HP composition).
6. plots.py: Plotnine plot functions organized by category (bills, cross-subsidy, revenue, tariffs, composition).
7. __main__.py: CLI entrypoint invoked via uv run python -m utils.post.validate --state ny --utility coned [--timestamp ...] [--runs ...].
8. Justfile recipe: validate-runs recipe in rate_design/hp_rates/Justfile.
9. Tests in tests/test_validate/.

Build order: config/IO → checks/tables → plots → CLI → Justfile + tests.

Deliverables

• PR that adds utils/post/validate/ package (config, discover, load, checks, tables, plots, CLI)
• Justfile recipe validate-runs in rate_design/hp_rates/Justfile
• Tests in tests/test_validate/
• Successful validation run on at least one NY utility batch (e.g. coned)