feat/tax-regime

Zod update schema missing taxRegime — silent strip if field is ever sent over wire

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

UpdateContractCommand now includes taxRegime. UpdateUtilityContractRequest = UpdateContractCommand & { version: number }, so taxRegime is now part of the accepted wire type. However, the UpdateUtilityContractSchema Zod object does not include taxRegime: z.enum(['iva','iva_frontera']).optional(). No satisfies failure occurs because the field is optional — ZodObject silently strips unknown keys on parse, so any caller that sends taxRegime in a future PATCH body will have it silently dropped. The Zod schema must be updated alongside the command type to close this gap before the endpoint goes live.

No DB-level CHECK constraint on tax_regime column

packages/database/src/schema/utility-contracts.ts

Drizzle's text('tax_regime', { enum: TAX_REGIMES }) does NOT emit a SQL CHECK constraint — enforcement is TypeScript-only. A direct SQL write, migration script, or ORM bug can insert an arbitrary string. The ?? 0.16 NaN guard mitigates the arithmetic consequence but silently applies 16% to frontera contracts with a corrupt value (over-billing by 2×). Add a $additionalConfig CHECK constraint: CHECK (tax_regime IN ('iva', 'iva_frontera')).

Silent 16% fallback for corrupt regime — no logging or error surfacing

domains/cross-domain/src/bill-compute.shells.ts:186

The ?? 0.16 fallback prevents NaN but silently over-taxes frontera contracts with a corrupt regime (applies 16% instead of the legal 8%). For a financial calculation this should at minimum emit a structured warning (tagged with contractId and the bad regime value). Silent fallbacks in billing code are a compliance risk.

taxRegime changes tracked in outbox events but no test pins the audit trail

domains/utility/src/utility-contract/utility-contract.decisions.ts:283

changes.taxRegime correctly captures old/new values in the decision output and will appear in outbox event data — good for audit. Consider adding an integration test that specifically asserts a taxRegime change produces an outbox event with the expected old/new pair, since this is a high-sensitivity financial configuration field.

CreateContractCommand declares taxRegime manually instead of picking from UtilityContract

domains/utility/src/utility-contract/utility-contract.decisions.ts:59

UpdateContractCommand correctly uses Partial<Pick<UtilityContract, ...'taxRegime'>>. CreateContractCommand re-declares taxRegime as a manual readonly field with a comment, instead of including 'taxRegime' in the Pick set. If the TaxRegime type changes, the manual declaration won't be caught by the AssertEqual type-check. Move taxRegime into the Pick.

NaN guard is a business rule — belongs in domain layer, not cross-domain shell

domains/cross-domain/src/bill-compute.shells.ts:186

Per FCIS/ADR-016, 'what rate applies when the regime is invalid?' is a decision, not shell orchestration. Extract a resolveTaxRate(regime: TaxRegime | undefined): number helper in the utility domain (bill-calculator or utility-contract decisions) that encapsulates both fallbacks. Minor layering concern — the guard is correct as-is.

No unit tests for decideUpdateContract with taxRegime

domains/utility/src/utility-contract/__tests__/utility-contract.decisions.test.ts

decideUpdateContract now handles taxRegime (line 281–284) but has no tests for: (1) taxRegime changes iva→iva_frontera → patch and changes populated, (2) taxRegime passed but equal to existing → no-op (idempotency), (3) taxRegime undefined → no patch. Three test cases needed, all follow the established pattern for the other fields.

No test for ?? 0.16 NaN guard in computeBillShell

domains/cross-domain/src/bill-compute.shells.ts:186

The ?? 0.16 fallback is the only defence against an unknown/corrupted taxRegime yielding NaN in the bill total. The comment in the diff explicitly calls this a safety guard — it should be pinned by a unit test that passes an unrecognised regime string and asserts the returned taxRate is 0.16, not NaN.

Integration test does not verify taxRegime is persisted by updateContractShell

domains/utility/src/utility-contract/__tests__/utility-contract.integration.test.ts

The integration test suite calls updateContractShell but has no case that passes taxRegime and asserts the persisted row reflects the new value. Without this, a dropped field in the Drizzle update or mapper layer would be invisible.

Wire response omission of taxRegime not covered by an API-level test

packages/api/src/types/utility-contract.api-types.ts:31

There is no test asserting that a GET /utility-contracts response body does not contain a taxRegime key. Type-level omission is correct but a handler-level test would guard against accidental re-inclusion if a mapper spreads the domain object instead of field-mapping.

UpdateContractCommand and UpdateContractPatch are parallel types maintained in two places

domains/utility/src/utility-contract/utility-contract.decisions.ts:124

Both types enumerate the same optional fields. The diff correctly adds taxRegime to both, but the parallel maintenance will bite again on the next field. UpdateContractPatch could be derived from UpdateContractCommand (e.g. as a mapped Required<UpdateContractCommand>) to make the single-source invariant structural.

taxRegime has no read surface — intentional but undocumented

packages/api/src/types/utility-contract.api-types.ts:31

taxRegime is billing-internal and excluded from the wire response. It's also not exposed by any read endpoint. This is a reasonable short-term stance but a future maintainer building a billing-settings UI may not know the domain layer is already wired. A brief comment on updateContractShell or UpdateContractCommand noting 'not exposed via HTTP yet' would prevent a parallel implementation.