feat/rpu-history

OCC race on display refresh defers silently — by design, documented in PR

domains/utility/src/utility-contract/utility-contract.shells.ts

When updateWithVersion returns null (lost OCC race), the shell returns the pre-refresh contract with action='found' and logs 'deferred'. The refresh only re-fires when the next bill has a strictly-newer periodEnd. The log says 'deferred' but nothing actively re-queues — it is naturally re-triggered on the next ingest cycle. Documented as intentional best-effort behaviour; no action required.

conceptName literals 'tariff'/'regulatedTariff' confirmed valid — correctness finding retracted

domains/utility/src/bill/bill.decisions.ts

The review panel initially flagged extractBillOwnTariff's use of camelCase conceptName literals. Verified: EnrichedLineItem carries a conceptName field populated from the bill_concepts_catalog, and 'tariff'/'regulatedTariff' are confirmed catalog conceptName values. The function is correct.

Trigger fan-out is atomic — TOCTOU concern retracted

packages/database/drizzle/0063_youthful_martin_li.sql

The uco_on_bills_* triggers call utility_contract_overview_refresh() per affected (org, contract), which internally calls derive() — a full atomic re-derive + upsert. bill_count is recomputed as a LATERAL COUNT(*) subquery, not a read-then-increment. No race possible.

chapters query uses bare database after org-gate — no org-id predicate on chapter rows

apps/platform/src/api/handlers/utility-contracts.handler.ts

After the RLS-enforced overview lookup establishes org ownership, the subsequent utility_contracts query runs against plain `database` filtering only on contract_number + deleted_at. A contract_number collision between two orgs (data-entry error, multi-tenant edge case) would return the other org's chapters. Adding `.where(eq(utilityContracts.orgId, orgId))` (or scoping through the rlsDb transaction) eliminates the risk structurally.

listContractChaptersHandler throws instead of returning discriminated error

apps/platform/src/api/handlers/utility-contracts.handler.ts

throw new Error('Request object is required') deviates from the FCIS convention of never throwing; it would surface as an unhandled 500 if the request object is ever absent in a test harness or future call site. This is the established file-wide pattern for all handlers here, so it is consistent within the file — but the file-level pattern is itself a deviation.

ContractChapterItem.status typed as string rather than CONTRACT_STATUSES enum

packages/api/src/schemas/utility-contract.schemas.ts

ContractChapterItemSchema uses z.string() for status, consistent with UtilityContractResponse.status elsewhere in this file (widened at API boundary). A z.enum(CONTRACT_STATUSES) would give callers type-safe discrimination. Low risk since isCurrent is pre-computed by the handler.

chapters endpoint (GET /utility-contracts/:publicId/chapters) has zero test coverage

apps/platform/src/api/handlers/utility-contracts.handler.ts

listContractChaptersHandler has no handler-level or integration test. The UCO integration suite covers the underlying DB query but never exercises this HTTP route or its response shape. New billing-visible endpoints warrant at least a happy-path smoke test.

getBillPeriodRangesByContracts has no tests

domains/utility/src/bill/bill.queries.ts

New query function with COUNT/MIN/MAX aggregation across the chapter union — zero test coverage (confirmed by grep). Warrants an integration test covering the union semantics (bills on sibling chapters counted together).

RateTagChip and ContractDetailDrawer have no component tests

apps/platform/src/app/[locale]/(dashboard)/bills/_components/RateTagChip.tsx

Two new user-facing components (RateTagChip, ContractDetailDrawer) have no render or snapshot tests. At minimum, a test covering the null/empty tariff code path and a basic render of the drawer with one active chapter would guard against regressions.

LEGACY_TARIFF_DISPLAY_MAP duplicated from xml-parser — silent drift risk

domains/utility/src/bill/bill.decisions.ts

The comment explicitly says 'Mirror of the xml-parser's LEGACY_TARIFF_MAP — keep in sync'. Two hand-maintained copies will diverge silently when a new legacy code is added. Extracting to a shared package (e.g. @batu/api or a utility-bill-concepts constants file) or importing from the xml-parser's constants would eliminate this.

window.history.replaceState less idiomatic than useRouter().replace() in App Router

apps/platform/src/app/[locale]/(dashboard)/bills/contratos/_components/ContractDetailDrawer.tsx

Direct replaceState bypasses Next.js App Router's internal state (prefetch cache, scroll restoration, transition state). useRouter().replace(url, { scroll: false }) achieves the same shallow URL update while keeping the router in sync. Low impact today but may cause subtle issues if searchParams-keyed data fetching is added later.