feat/one-api

Missing composite index on (org_id, contract_public_id) — full org-scan on a hot gate path

packages/database/src/schema/utility-contract-overview.ts

findOverviewByContractPublicId filters WHERE org_id = $1 AND contract_public_id = $2. The only available index is idx_utility_contract_overview_org (org_id only), so Postgres index-seeks on org_id then heap-scans every row for that org to evaluate contract_public_id. For large orgs (hundreds/thousands of contracts) this is O(contracts_per_org) on every contract detail open. contract_public_id is effectively unique per org (it mirrors utility_contracts.public_id, a ULID UNIQUE key). Add a composite unique index on (org_id, contract_public_id) — serves as both a constraint guarantee and an index-only lookup.

bill_count RPU union counts bills from all orgs sharing contract_number

packages/database/drizzle/0063_youthful_martin_li.sql

The bc LATERAL in the updated derive() counts bills across ALL utility_contracts sharing contract_number with no org-scoping: FROM utility_contracts sib JOIN bills b ON b.utility_contract_id = sib.id WHERE sib.contract_number = uc.contract_number AND sib.deleted_at IS NULL. Since the same RPU can be held by multiple orgs (ownership transfers, multiple integradores), Org A's displayed bill_count includes bills collected by Org B. The comment says it should match 'Historial filtered by RPU', but Historial IS org-scoped via RBAC — a user cannot reconcile the displayed count with what they can actually see.

uco_on_bills_delete trigger sibling-chapter fanout — soft-deleted bill edge case noted

packages/database/drizzle/0063_youthful_martin_li.sql

In uco_on_bills_delete, the chapters CTE unions affected contracts with sib.deleted_at IS NULL siblings. A bill on a soft-deleted/terminated chapter will correctly trigger refresh of the active chapter via uco_orgs_reaching (no deleted_at filter on initial old_rows select). No bug found — noted for completeness during the bill_count RPU union analysis.

runOverviewReconcile throws instead of returning Result<T,E>

domains/utility/src/utility-contract-overview/utility-contract-overview.queries.ts

FCIS (ADR-016) requires all fallible operations to return Result<T,E> from @batu/result — never throw. runOverviewReconcile throws a raw Error when the SQL function returns no row, and returns OverviewReconcileSummary bare on success. The comment justifies 'surface loudly', but callers (EventBridge Lambda, manual CLI) must now wrap in try/catch instead of pattern-matching on a discriminated error. Wrap in Result<OverviewReconcileSummary, InfraError> with a '_tag' so the FCIS contract is preserved and the error is attributable.

runOverviewReconcile belongs in shells.ts, not queries.ts

domains/utility/src/utility-contract-overview/utility-contract-overview.queries.ts

Canonical form (ADR-018): query functions take DbOrTx and return Entity|null; shells take Database when they own their transaction boundary (advisory locks + temp tables). runOverviewReconcile is typed Database precisely because it owns its transaction — that is the hallmark of a shell. It should live in utility-contract-overview.shells.ts, keeping queries.ts as pure thin DB wrappers.

OverviewReconcileSummary exported as loose identifier, not grouped with FCIS namespace

domains/utility/src/utility-contract-overview/index.ts

The canonical barrel exports an {Entity}FCIS namespace (UtilityContractOverviewFCIS). OverviewReconcileSummary is the return type of runOverviewReconcile — it should be grouped alongside or inside that namespace for discoverability. Currently exported as a standalone top-level re-export alongside the namespace, which is consistent with other summary types but diverges slightly from the 'sole import surface is the FCIS namespace' intent.

findOverviewByContractPublicId has zero test coverage

domains/utility/src/utility-contract-overview/utility-contract-overview.queries.ts

This function is an org-access gate for the contract detail drawer — a bug in either WHERE condition (orgId OR contractPublicId) is a direct IDOR. No test file exercises it. Three cases are missing: (1) matching row returned when both conditions hold; (2) null returned when contractPublicId belongs to a different orgId (the IDOR case); (3) null returned when contractPublicId does not exist. Should be integration-tested with two orgs and shared RPU.

No isolated mapper test for new tariffCode / utilityServiceCode fields

domains/utility/src/utility-contract-overview/utility-contract-overview.mapper.ts

The two new columns are structurally guarded by AssertEqual<DrizzleRow, DomainType> and exercised end-to-end in the rpu-history integration suite, but there is no targeted unit assertion that toUtilityContractOverview correctly passes tariffCode and utilityServiceCode through (including null values). Low priority given the compile-time guard, but a mapper round-trip test would catch a future copy-paste error without requiring a full DB setup.

utilityServiceCode filter has no supporting index

packages/database/src/schema/utility-contract-overview.ts

buildFilterCondition maps the 'utilityService' filter axis to inArray(t.utilityServiceCode, values), but there is no index on (org_id, utility_service_code). Every other filterable column with meaningful cardinality (lifecyclePhase, isMonitored, lastCheckedAt) has a dedicated (org_id, col) composite index. Without one, filtering by utility service code degrades to a post-orgIdx heap scan for large orgs. Add a composite index on (org_id, utility_service_code).

branch-provisioning rm list must be kept in sync manually

.claude/skills/branch-provisioning/SKILL.md

Replacing rm -rf .branch with rm -f .branch/scope.md .branch/intent.md .branch/stashes.log is the right fix, but the list is now a manual registry. If a future provisioning step writes a new tracked file under .branch/ (e.g. .branch/decisions.md), it won't be cleared and will silently carry stale content into the next branch. Add a comment: 'keep in sync with every file written by this skill's Initialize branch step'.

EventBridge-Lambda fallback documented but unwired

.claude/rules/contracts-read-model.md

contracts-read-model.md states 'EventBridge-Lambda remains the documented fallback if pg_cron is ever unavailable', and the queries.ts comment echoes this. The Lambda does not exist. If pg_cron fails silently (Supabase plan change, extension disabled), the CI watchdog is the only safety net — not a real fallback invocation path. Acceptable as a deferred work item but should be tracked in Linear rather than presented as an existing fallback.