Phoebe: reconcile exit-code (loud routine/quiet backfill) + window_start index + single-flight doc

[hhuuggoo]

Fix pass on the rater after PR #17 round 1 (Ben's reconcile-DELETE recommendations + mechanical findings). Money path — fail-closed, every behavioral change paired with an invariant-named test. Stacked on yaml-rater-fixes-3.

Contracts

Reconcile-delete exit-code (option (c): loud on routine, quiet on backfill). A run that DELETES a previously-billed rated_usage row (ReconciledDeletions > 0) is a revenue change. The exit code now depends on WHY the window was chosen:

• Routine (default trailing-hours window, no --since/--until): a prior bill vanishing on a routine cadence means data loss / an upstream regression → ERROR + exit 2 (the anomaly code; page someone).
• Backfill (--since/--until set): intended convergence (e.g. after a late price fix) → INFO + exit 0.

The gate is ReconciledDeletions > 0 && !windowExplicit. The decision lives in cmd/rater (the only place that knows the window was explicit) via a unit-testable exitCode helper; it is deliberately NOT folded into Result.HasAnomaly() (that would make explicit backfills exit nonzero too). resolveWindow now returns windowExplicit (true iff either flag was set). Semantics unchanged — store.go always reconciles ("what the latest run says is what bills"); this is purely the observability/exit contract.

New index for the reconcile DELETE. rated_usage_window_start_ix ON rated_usage (window_start) — the deleted CTE filters window_start alone, but every existing index leads with auth_id, so the reconcile seq-scanned and over-locked on every run. Added to both migrations/0002_rating.sql and the Atlas c2f1a3b4d5e6 revision. Also fixed the asymmetric downgrade: both drop_index calls now use if_exists=True for up/down/up idempotency. Verified against live PG: the reconcile DELETE plans as Index Only Scan using rated_usage_window_start_ix.

Single-flight requirement (Atlas concurrencyPolicy: Forbid hand-off). The reconcile DELETE + ordered upsert are deadlock-safe ONLY under single-flight (the ordered upsert prevents self-deadlock; cross-rater ABBA is unreachable only because no two raters run over overlapping windows). The ordered-upsert comment in store.go was overclaiming ("lock order across concurrent raters"); it now states the real contract. cmd/rater's package doc documents the single-flight assumption and that the deployment MUST enforce it. No delete-lock-ordering machinery added (per Ben/ledger — explicitly excluded). The actual concurrencyPolicy: Forbid lives in the Atlas manifest repo, outside phoebe — a hand-off item.

Tests (invariant-named)

• TestRater_RoutineRunReconcileDeleteExitsNonzero — RED-demonstrated against the old anomaly-only exit before wiring.
• TestRater_BackfillReconcileDeleteExitsZero — and a real anomaly during a backfill still exits nonzero.
• TestResolveWindow_SingleFlagIsExplicit + windowExplicit assertions on the existing window tests.
• TestIntegration_ReconcileDeleteUsesWindowStartIndex — live-PG EXPLAIN (seqscan off) proves the new index serves the reconcile predicate.

Gate

go build, go vet (+ -tags=integration), go test -race, golangci-lint v1.64.8 (default + integration tags), gofmt -l — all clean. Live-PG integration + e2e green; migration chain applies clean and the new index is used.

🤖 Generated with Claude Code

[hhuuggoo]

🔋 Re-battery — Round 1 (status: ESCALATE), WITH ledger

11 raw → 3 refuted → 8 confirmed + 3 persona. One real finding, narrow and good: the reconcile observability contract is HALF-implemented. The ledger suppressed all the settled decisions — this is a genuine implementation gap in the newest change.

The gap (contract-vs-implementation mismatch)

Option (c) says: routine reconcile-delete → loud (ERROR) + exit nonzero; backfill → quiet (INFO) + exit 0. The exit-code half is correct (exitCode() in cmd/rater gates on windowExplicit). But the log half is not: rater.go:134 emits the reconcile-delete line unconditionally at INFO — and rater.Run never receives windowExplicit, so it can't raise to ERROR for the routine case. Result: on the alarming path (a routine run rewriting a prior bill = data vanished / upstream regression), the process exits nonzero but the logs show only a reassuring INFO "what the latest run says is what bills" — the calmest message on the loudest event. Severity-keyed alerting sees an apparently-clean run.

Plus: TestRater_RoutineRunReconcileDeleteExitsNonzero (main_test.go:110) claims to pin "the loud half" but only asserts the exit code — the ERROR-log half is untested because it's unimplemented (the overclaim the cleanup angle flagged).

Why this is finish-the-ratified-decision, not a new door

The contract is decided (option c, in the ledger). The escalation was only about the package boundary (where routine-vs-backfill knowledge lives). That's a mechanical taste call, not a contract — resolution: thread windowExplicit into Rater.Run, mirroring the exit-code gate (keeps rating observability in the rating package), emit the routine reconcile-delete at ERROR with investigate-text, and add a test that asserts the ERROR line fires (closing the overclaim). I'm implementing this.

Also (mechanical, same pass)

The two ReconcileDeleteUsesWindowStartIndex integration tests EXPLAIN against an empty/standalone table (a freshly-created empty rated_usage → the planner may pick a seqscan regardless of the index) — tighten so the EXPLAIN actually proves index use on a populated table.

---

Battery wf_1e6324ec-606. Note: a trivial proxy-only commit (00833a2, iolog truncation-log carried from the now-closed #13) landed on the branch top after this battery started — it's outside the rating diff and was reviewed in #13's lineage; the final tip will re-battery clean. #18 needs the log-severity fix, then a dry round.

[hhuuggoo]

Landed on main via the squashed rating merge (3b22908). Closing the stack.