PSA/ee/docs/plans/2026-03-21-service-catalog-billing-mode-decoupling/SCRATCHPAD.md

# Scratchpad — Service Catalog Billing Mode Decoupling

- Plan slug: `service-catalog-billing-mode-decoupling`
- Created: `2026-03-21`

## What This Is

Keep a lightweight, continuously-updated log of discoveries and decisions made while implementing this plan.

Prefer short bullets. Append new entries as you learn things, and also *update earlier notes* when a decision changes or an open question is resolved.

## Decisions

- (2026-03-21) Canonical billing vocabulary is `fixed|hourly|usage`; `per_unit` is compatibility-only. Rationale: current migrations already moved toward `usage`, while product APIs still emit `per_unit`; plan must converge on one canonical set.
- (2026-03-21) Service catalog defines identity and optional defaults; contract-line context defines billing behavior. Rationale: same service must be billable differently per agreement.
- (2026-03-21) Non-contract time/usage is explicit invoiceable scope, not implicit fallback absorption into contract lines. Rationale: deterministic allocation and user control over separate invoicing.
- (2026-03-21) Hard cutover selected: no dual-read/dual-write and no transitional alias retention after migration. Rationale: avoid long-term complexity debt and hidden fallback regressions.
- (2026-03-21) Wave 0 canonicalization starts by rejecting `per_unit` at server write-schema boundaries (`serviceSchemas`, `financialSchemas`, `contractLineSchemas`) and hardening migration post-conditions. Rationale: immediate write-path guardrails plus deterministic migration safety without waiting for downstream UI/type cleanup waves.
- (2026-03-21) Mode-specific catalog defaults are stored in a dedicated table (`service_catalog_mode_defaults`) rather than overloading existing `service_prices`. Rationale: keep contract-mode defaults explicit and avoid breaking multi-currency price reads while migration/backfill work lands.
- (2026-03-21) Backfill semantics for mode-defaults are one-way and service-scoped: seed from `service_prices` first, fallback to `service_catalog.default_rate` only when no per-currency rows exist, and fail on unresolved active-service mappings. Rationale: preserve the richest existing pricing data while preventing silent gaps.
- (2026-03-21) Wizard and template service pickers now apply only `itemKinds=['service']` gating for fixed/hourly/usage sections; billing-method filter arguments were removed from these step-level picker calls. Rationale: service identity is catalog-level and billing mode is contract-context.
- (2026-03-21) Contract/template wizard submit validators now enforce only `item_kind='service'` for fixed/hourly/usage service arrays; billing_method matching checks were removed from server-side submission validation.
- (2026-03-21) `addServiceToContractLine` now determines default configuration type from target `contract_line_type` (Fixed/Hourly/Usage) and validates explicit `configType` compatibility per line mode, instead of deriving from catalog/service-type billing method.

## Discoveries / Constraints

- (2026-03-21) Wizard gates services by `billing_method` in picker and server submit validation. Key refs: `ServiceCatalogPicker`, `FixedFeeServicesStep`, `HourlyServicesStep`, `UsageBasedServicesStep`, `contractWizardActions`.
- (2026-03-21) `contractLineServiceActions` still enforces service/type billing-mode coupling in add/attach paths, so wizard-only changes are insufficient.
- (2026-03-21) Billing engine still includes `contract_line_id IS NULL` in time/usage queries per contract-line pass, which can multi-claim unresolved rows without service-aware guard.
- (2026-03-21) `time_entries` default to `contract_line_id = null` in save paths, so allocation correctness must be enforced centrally at billing execution.
- (2026-03-21) Many downstream APIs and schemas require/expose `billing_method` as identity truth (`serviceSchemas`, `productSchemas`, `financialSchemas`, shared interfaces, scheduling aliases); all are in-scope for one-shot cutover updates.
- (2026-03-21) E2E setup currently injects legacy billing-method constraints (`per_unit` etc.), which can mask decoupled behavior regressions.
- (2026-03-21) Existing migration `20251016120000_update_billing_method_to_text.cjs` normalized `per_unit` to `usage` but did not fail when residual legacy rows remained; added explicit residual-count guard + throw.
- (2026-03-21) Product flows still actively write `billing_method: 'per_unit'` (`ProductCatalogService`, `productSchemas`), so canonicalization for product writes remains follow-up in `F037/F039`.
- (2026-03-21) Added migration `20260321110000_create_service_catalog_mode_defaults.cjs` with tenant+service scoped FK, strict unique key `(tenant, service_id, billing_mode, currency_code)`, billing_mode check (`fixed|hourly|usage`), and non-negative rate check.
- (2026-03-21) Added migration `20260321113000_backfill_service_catalog_mode_defaults.cjs` that normalizes `per_unit -> usage`, inserts from `service_prices`, falls back to `service_catalog` defaults, and throws when active services with source defaults still have no mode-default rows.
- (2026-03-21) `ServiceCatalogPicker` still supports optional `billing_methods`, but wizard and template steps no longer pass billing-method filters in fixed/hourly/usage service flows; only products step still uses `itemKinds=['product']` as expected.
- (2026-03-21) Added integration coverage (`T013-T018`) in `server/src/test/integration/contractWizard.integration.test.ts` for decoupled acceptance (fixed/hourly/usage) and non-service rejections.
- (2026-03-21) Removed `service_types` join and `service_type_billing_method` dependency in `contractLineServiceActions` attach flow; compatibility now enforced via target line mode + `allowedConfigTypesByPlan`.

## Commands / Runbooks

- (2026-03-21) Locate all wizard and action gating points:
  - `rg -n "billingMethods=|must be a .*billing service|billing_method" packages/billing/src/components/billing-dashboard/contracts packages/billing/src/actions`
- (2026-03-21) Locate billing engine null-fallback clauses:
  - `rg -n "contract_line_id IS NULL|usage_tracking\\.contract_line_id.*IS NULL" packages/billing/src/lib/billing/billingEngine.ts`
- (2026-03-21) Locate downstream schema/interface coupling:
  - `rg -n "billing_method|service_type" server/src/lib/api/schemas server/src/interfaces packages/types/src/interfaces packages/scheduling/src/actions packages/client-portal/src/services`
- (2026-03-21) Validate plan artifacts:
  - `jq empty ee/docs/plans/2026-03-21-service-catalog-billing-mode-decoupling/features.json`
  - `jq empty ee/docs/plans/2026-03-21-service-catalog-billing-mode-decoupling/tests.json`
  - `python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/validate_plan.py ee/docs/plans/2026-03-21-service-catalog-billing-mode-decoupling`
- (2026-03-21) Validate canonicalization changes and migration guard:
  - `cd server && npx vitest run src/test/unit/migrations/billingMethodCanonicalizationMigration.test.ts src/test/unit/api/contractLineCadenceOwner.schema.test.ts src/test/unit/api/defaultBillingSettings.cadenceOwner.schema.test.ts`
- (2026-03-21) Validate API rejection + mode-default table migration tests:
  - `cd server && npx vitest run src/test/unit/api/serviceBillingMethodCutover.schema.test.ts src/test/unit/migrations/serviceCatalogModeDefaultsMigration.test.ts src/test/unit/migrations/billingMethodCanonicalizationMigration.test.ts`
- (2026-03-21) Validate mode-default backfill migration tests:
  - `cd server && npx vitest run src/test/unit/migrations/serviceCatalogModeDefaultsMigration.test.ts src/test/unit/migrations/serviceCatalogModeDefaultsBackfillMigration.test.ts`
- (2026-03-21) Validate wizard picker decoupling static guards:
  - `cd server && npx vitest run src/test/unit/fixedWizardPickerPolicy.static.test.ts`
- (2026-03-21) Validate server submit decoupling integration tests:
  - `cd server && npx vitest run src/test/integration/contractWizard.integration.test.ts`
  - Note: blocked locally in this run due unavailable DB test harness (`ECONNREFUSED 127.0.0.1:5438`).
- (2026-03-21) Validate contract-line service attach mode-context guards:
  - `cd server && npx vitest run src/test/unit/api/contractLineService.decoupledAttach.static.test.ts`

## Links / References

- Plan folder: `ee/docs/plans/2026-03-21-service-catalog-billing-mode-decoupling/`
- Prior related plans:
  - `ee/docs/plans/2026-03-18-service-driven-invoicing-cutover/`
  - `ee/docs/plans/2026-03-20-grouped-automatic-invoices-selection/`
  - `ee/docs/plans/2026-03-20-multi-active-contracts-per-client/`
- Key files:
  - `packages/billing/src/actions/contractWizardActions.ts`
  - `packages/billing/src/actions/contractLineServiceActions.ts`
  - `packages/billing/src/lib/billing/billingEngine.ts`
  - `packages/billing/src/actions/serviceActions.ts`
  - `server/src/lib/api/services/ServiceCatalogService.ts`
  - `server/src/lib/api/services/ProductCatalogService.ts`
  - `packages/scheduling/src/actions/timeEntryCrudActions.ts`
  - `packages/client-portal/src/services/availabilityService.ts`
  - `server/src/lib/api/schemas/serviceSchemas.ts`
  - `server/src/test/e2e/utils/e2eTestSetup.ts`

## Open Questions

- None blocking. Hard cutover policy is set; remaining implementation work is execution order only.
- (2026-03-21) Completed F012-F014 by resolving fixed/hourly/usage wizard prefill from `service_catalog_mode_defaults` keyed by line mode + currency, with fallback to catalog `default_rate` and explicit submission overrides taking precedence. Key ref: `packages/billing/src/actions/contractWizardActions.ts`.
- (2026-03-21) Hardened wizard currency validation to treat mode-default/catalog-default resolved rates as priced inputs so contracts do not fail when no `service_prices` row exists but valid defaults do. Rationale: preserve prefill semantics under decoupled model.
- (2026-03-21) Replaced temporary static checks with DB-backed integration tests `T021-T024` in `server/src/test/integration/contractWizard.integration.test.ts` covering mode-default prefill and override precedence for fixed/hourly/usage.
- (2026-03-21) Test run: `cd server && npx vitest run src/test/integration/contractWizard.integration.test.ts` currently blocked locally by Postgres not listening on `127.0.0.1:5438`/`::1:5438`; suite collected and skipped tests due beforeAll connection failure.
- (2026-03-21) Completed F015 by adding contract-line form metadata labels (`Effective mode`, `Default source`) and switching mode derivation to contract-line context instead of `service_catalog.billing_method`. Key refs: `ContractLineServiceForm.tsx`, `ServiceConfigurationPanel.tsx`, `BaseServiceConfigPanel.tsx`.
- (2026-03-21) Added `T025` UI test coverage in `packages/billing/tests/contractLineServiceForm.metadata.test.tsx` validating catalog-default, contract-override, and none source labels plus contract-line effective mode mapping.
- (2026-03-21) Test run: `cd server && npx vitest run ../packages/billing/tests/contractLineServiceForm.metadata.test.tsx` (pass).
- (2026-03-21) Completed F016/F017 by updating draft/template resume readers to preload `service_catalog_mode_defaults` (hourly/usage) and prefer mode-default rates before catalog fallback when reconstructing wizard snapshots. Key ref: `getDraftContractForResume`, `getContractTemplateSnapshotForClientWizard` in `contractWizardActions.ts`.
- (2026-03-21) Added/updated `T026/T027` in `packages/billing/tests/draftContractForResumeActions.test.ts` to assert resume/template round-trip uses decoupled selections and mode-default prefills when stored rates are empty.
- (2026-03-21) Test run: `cd server && npx vitest run ../packages/billing/tests/draftContractForResumeActions.test.ts` (pass).
- (2026-03-21) Completed F018-F022 in billing engine by removing unconditional null-line allocation and introducing service-constrained allocation: explicit `contract_line_id` first, otherwise unassigned rows only when service-to-line match is unique for active client assignments in the service window. Added contract-line service membership filters for both time and usage.
- (2026-03-21) Completed F023-F025 guard rails by preserving existing hourly minimum/round/overtime logic, usage minimum/custom-rate/tier logic, and bucket overage path; added static assertions to lock these behaviors.
- (2026-03-21) Added/updated tests: `server/src/test/unit/billingEngine.test.ts` (T030-T035 behavior coverage) and `server/src/test/unit/billing/billingEngine.contractLineAllocation.static.test.ts` (T028-T029, T036-T040 static guards).
- (2026-03-21) Test run: `cd server && npx vitest run src/test/unit/billingEngine.test.ts src/test/unit/billing/billingEngine.contractLineAllocation.static.test.ts` (pass).
- (2026-03-21) Completed F026/F027 by extending due-work materialization to append unresolved non-contract rows (time + usage) using deterministic `schedule:...:non_contract:<type>:<recordId>` selectors and client-level currency/tax metadata in `getAvailableRecurringDueWork`. Key refs: `packages/billing/src/actions/billingAndTax.ts`, `packages/billing/src/lib/billing/billingEngine.ts`.
- (2026-03-21) Completed F028/F029/F030 by rendering non-contract child labels in grouped Automatic Invoices UI and preserving child-level generation targeting so contract-only and non-contract-only selection paths generate independently. Key ref: `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`.
- (2026-03-21) Added non-contract selection handling in invoice generation scoping: non-contract selector keys bypass recurring obligation scoping and flow through dedicated `nonContractSelection` options. Key ref: `packages/billing/src/actions/invoiceGeneration.ts`.
- (2026-03-21) Added tests for T041-T045:
  - `server/src/test/unit/billing/nonContractDueWork.integration.test.ts`
  - `server/src/test/unit/billing/automaticInvoices.nonContractSelection.ui.test.tsx`
- (2026-03-21) Updated preview summary copy to explicitly differentiate one combined invoice vs multiple separate invoices in grouped preview dialog (`AutomaticInvoices.tsx`).
- (2026-03-21) Completed F031 by extending grouped UI combinability checks to include invoice-window scope alongside client/currency/tax/export/PO and by validating mixed selection behavior end-to-end in UI tests. Key ref: `AutomaticInvoices.tsx`.
- (2026-03-21) Marked F032 complete after verifying grouped preview summary explicitly states one combined invoice vs N separate invoices (`preview-invoice-count-summary`), with test coverage in `automaticInvoices.nonContractSelection.ui.test.tsx`.
- (2026-03-21) Added/updated `T011` in `server/src/test/unit/billing/automaticInvoices.nonContractSelection.ui.test.tsx` to assert compatible mixed selections combine as a parent-group target while incompatible scope selections (currency mismatch) split into child-level targets.
- (2026-03-21) Marked `T001` complete by validating migration canonicalization + mode-default schema/backfill suites (`billingMethodCanonicalizationMigration`, `serviceCatalogModeDefaultsMigration`, `serviceCatalogModeDefaultsBackfillMigration`).
- (2026-03-21) Completed F033 by decoupling service-catalog API filter/sort semantics from billing metadata for non-service contexts: `billing_method` filtering and sort precedence now apply only when `item_kind='service'`, with safe service-name fallback elsewhere.
- (2026-03-21) Completed F034 by mirroring the same service-only billing-metadata filter/sort semantics in shared helper `shared/billingClients/services.ts` to keep caller behavior consistent across API and shared query paths.
- (2026-03-21) Added static guard coverage `T014` in `server/src/test/unit/billing/serviceQueryDecoupling.static.test.ts` to lock decoupled filter/sort behavior in both `ServiceCatalogService` and shared billing-client helpers.
- (2026-03-21) Marked `T002` complete via backfill migration guard assertions in `serviceCatalogModeDefaultsBackfillMigration.test.ts` (unmappable mode + missing required default mappings fail fast with actionable messages).
- (2026-03-21) Completed F035 by removing scheduling lookup proxying (`sc.billing_method as service_type`) in `timeEntryCrudActions`; service identity now resolves from `service_types.name`, while billing metadata is returned separately as `billing_mode` + `item_kind`.
- (2026-03-21) Completed F036 by updating client-portal availability service queries to join `service_types` and expose `service_type` from taxonomy instead of aliasing `billing_method`; `billing_mode` and `item_kind` are returned as metadata fields.
- (2026-03-21) Added static guard coverage `T015` in `server/src/test/unit/billing/schedulingAvailabilityDecoupling.static.test.ts` to prevent regression to `billing_method as service_type` proxying in scheduling and client-portal availability reads.
- (2026-03-21) Completed F037 by canonicalizing product catalog writes in `ProductCatalogService` create/update paths from legacy `per_unit` to `usage` so active product writes no longer emit legacy billing vocabulary.
- (2026-03-21) Added static write guard `server/src/test/unit/api/productCatalogCanonicalWrites.static.test.ts` to enforce canonical product billing writes and prevent reintroduction of `billing_method: 'per_unit'` in product service APIs.
- (2026-03-21) Completed F038/F039 by hard-cutting service/product schema contracts to canonical vocabulary: product schema now accepts/defaults `usage` (not `per_unit`), and schema tests explicitly reject legacy values. Key refs: `server/src/lib/api/schemas/productSchemas.ts`, `server/src/test/unit/api/productBillingMethodCutover.schema.test.ts`.
- (2026-03-21) Completed F040 by removing `per_unit` from server/shared billing interface unions and adding static guards that financial + contract-line schemas remain canonical `fixed|hourly|usage`. Key refs: `server/src/interfaces/billing.interfaces.ts`, `packages/types/src/interfaces/billing.interfaces.ts`, `server/src/test/unit/api/billingInterfacesCutover.static.test.ts`.
- (2026-03-21) Marked T012/T013 complete based on schema + interface guard suite run (service/product cutover schemas and financial/contract-line canonical enums).
- (2026-03-21) Completed F041 by decoupling onboarding service creation from service-type billing metadata: onboarding now captures an explicit `serviceBillingMode` and `setupBilling` writes `service_catalog.billing_method` from onboarding input (fallback `usage`) instead of `service_types.billing_method`. Key refs: `packages/onboarding/src/actions/onboarding-actions/onboardingActions.ts`, `packages/onboarding/src/components/steps/BillingSetupStep.tsx`, `packages/onboarding/src/components/OnboardingWizard.tsx`, `packages/types/src/lib/onboardingWizard.ts`.
- (2026-03-21) Completed F042 by removing service-type-driven billing auto-overwrite in service settings forms (`ServiceForm`, `QuickAddService`); changing service type now updates taxonomy only and preserves user-selected billing mode.
- (2026-03-21) Added `T016` guard coverage in `server/src/test/unit/billing/onboardingServiceTypeDecoupling.static.test.ts` to enforce onboarding/service-settings decoupling and prevent regressions to identity-level billing coupling.
- (2026-03-21) Completed F043 by removing usage-tracking picker gating on `service_catalog.billing_method='usage'`; usage tracking now sources picker options from service identity (`item_kind !== 'product'`) via a shared memoized options set used in both filter + create/edit dialog.
- (2026-03-21) Added `T017` guard coverage in `server/src/test/unit/billing/usageTrackingPickerDecoupling.static.test.ts` to prevent reintroduction of billing-method-only filtering in usage tracking service pickers.
- (2026-03-21) Completed F044 debt purge by removing remaining catalog-method eligibility gates in contract-line authoring dialogs (`ContractLineDialog`, `CreateCustomContractLineDialog`), deleting template-attach fixed-method coupling in `contractLineServiceActions`, and eliminating active `per_unit` compatibility references from billing UI/models/action types plus e2e constraint normalization.
- (2026-03-21) Added hard-cutover guard suite `server/src/test/unit/billing/hardCutoverDebtGuard.static.test.ts` (T018) to assert no `per_unit` compatibility in active billing paths, no picker `billingMethods` gates in contract authoring, no unconditional `contract_line_id IS NULL` fallback SQL in billing engine, and no `billing_method as service_type` alias proxying.
- (2026-03-21) Added `server/src/test/unit/billing/contractAuthoringDecouplingChecklist.static.test.ts` to lock T003-T006 checklist behaviors (service-identity validation in wizard flows, template/draft resume decoupled mode-default hooks, contract-line attach mode validation, and override/default precedence hooks).
- (2026-03-21) Marked T007-T010 complete from passing billing engine + automatic invoice suites:
  - `billingEngine.contractLineAllocation.static.test.ts`
  - `billingEngine.test.ts`
  - `automaticInvoices.nonContractSelection.ui.test.tsx`

- (2026-03-21) Validation runbooks:
  - `cd server && npx vitest run src/test/unit/billing/nonContractDueWork.integration.test.ts src/test/unit/billing/automaticInvoices.nonContractSelection.ui.test.tsx`
  - `cd server && npx vitest run src/test/unit/billing/recurringDueWorkReader.integration.test.ts`
  - `npx tsc -p packages/billing/tsconfig.json --noEmit` (fails on pre-existing unrelated package type errors; no new errors from the F026-F030 patch set).
  - `cd server && npx vitest run src/test/unit/billing/automaticInvoices.nonContractSelection.ui.test.tsx` (pass, includes T011 and T049 assertions)
  - `cd server && npx vitest run src/test/unit/migrations/billingMethodCanonicalizationMigration.test.ts src/test/unit/migrations/serviceCatalogModeDefaultsMigration.test.ts src/test/unit/migrations/serviceCatalogModeDefaultsBackfillMigration.test.ts` (pass)
  - `cd server && npx vitest run src/test/unit/billing/serviceQueryDecoupling.static.test.ts` (pass, T014 guards)
  - `cd server && npx vitest run src/test/unit/billing/schedulingAvailabilityDecoupling.static.test.ts` (pass, T015 guards)
  - `cd server && npx vitest run src/test/unit/api/productCatalogCanonicalWrites.static.test.ts` (pass)
  - `cd server && npx vitest run src/test/unit/api/serviceBillingMethodCutover.schema.test.ts src/test/unit/api/productBillingMethodCutover.schema.test.ts src/test/unit/api/billingInterfacesCutover.static.test.ts` (pass, T012/T013)
  - `cd server && npx vitest run src/test/unit/billing/onboardingServiceTypeDecoupling.static.test.ts` (pass, T016)
  - `cd server && npx vitest run src/test/unit/billing/usageTrackingPickerDecoupling.static.test.ts` (pass, T017)
  - `cd server && npx vitest run src/test/unit/billingEngine.test.ts src/test/unit/billing/billingEngine.contractLineAllocation.static.test.ts src/test/unit/billing/automaticInvoices.nonContractSelection.ui.test.tsx` (pass, T007-T010)
  - `cd server && npx vitest run src/test/unit/billing/contractAuthoringDecouplingChecklist.static.test.ts src/test/unit/billing/hardCutoverDebtGuard.static.test.ts` (pass, T003-T006 and T018)