Billing reconciliation aligns bill periods to calendar months, corrupting the delta #24

New issue

Open

opened 2026-07-17 03:06:31 +00:00 by claude-bot · 0 comments

claude-bot commented

2026-07-17 03:06:31 +00:00

Contributor

buildBillingReconciliation (src/lib/billing.js:39-40) maps each bill to periodEnd.slice(0,7) and compares its total against that calendar month's modeled bill. Ameren billing cycles run mid-month to mid-month, so the modeled and actual windows overlap by only ~50–60%, and at season boundaries (June, October) they straddle different rate seasons. The reconciliation delta — the feature's entire output — therefore contains a large alignment component unrelated to model accuracy.

Fix: compute the modeled cost over the exact bill window. The hourly simulation already produces per-hour costs (hourlyImpact behind the includeHourlyImpact option in src/lib/simulation.js); expose a per-day cost rollup from the monthly summary path and sum days in [periodStart, periodEnd]. If that is too heavy for the default calculation, fall back to blending adjacent calendar months by day overlap. Label any remaining approximation in the Billing tab.

Acceptance criteria

Modeled figure for each bill covers the bill's actual date window
Season-straddling periods (Jun/Oct) reconcile without systematic sign error
Test with a synthetic mid-month bill period against known hourly costs

Relations: relates to #14 (both concern billing-data fidelity)

(Audit finding F-03, 2026-07-16 — Severity: Medium, Confidence: High)

`buildBillingReconciliation` (`src/lib/billing.js:39-40`) maps each bill to `periodEnd.slice(0,7)` and compares its total against that calendar month's modeled bill. Ameren billing cycles run mid-month to mid-month, so the modeled and actual windows overlap by only ~50–60%, and at season boundaries (June, October) they straddle different rate seasons. The reconciliation delta — the feature's entire output — therefore contains a large alignment component unrelated to model accuracy. Fix: compute the modeled cost over the exact bill window. The hourly simulation already produces per-hour costs (`hourlyImpact` behind the `includeHourlyImpact` option in `src/lib/simulation.js`); expose a per-day cost rollup from the monthly summary path and sum days in [periodStart, periodEnd]. If that is too heavy for the default calculation, fall back to blending adjacent calendar months by day overlap. Label any remaining approximation in the Billing tab. **Acceptance criteria** - [ ] Modeled figure for each bill covers the bill's actual date window - [ ] Season-straddling periods (Jun/Oct) reconcile without systematic sign error - [ ] Test with a synthetic mid-month bill period against known hourly costs **Relations:** relates to #14 (both concern billing-data fidelity) *(Audit finding F-03, 2026-07-16 — Severity: Medium, Confidence: High)*

claude-bot referenced this issue

2026-07-17 03:09:20 +00:00

Version rate plans by effective date #46

claude-bot added this to the v1.1.1 - Calculation Correctness milestone

2026-07-17 03:10:38 +00:00

claude-bot added the

bug

label

2026-07-17 03:11:39 +00:00

claude-bot referenced this issue

2026-07-17 15:21:13 +00:00

Server-side calculations are computed in the container timezone, shifting all TOU windows #22