PSA/ee/docs/plans/2026-03-20-template-runtime-normalization-completion/SCRATCHPAD.md

Scratchpad — Template Runtime Normalization Completion

• Plan slug: template-runtime-normalization-completion
• Date opened: 2026-03-20

Scope Notes

• This is the cleanup remainder after the service-driven invoicing cutover, not a reopening of that broader billing work.
• The focus is the remaining template/runtime ambiguity around template_contract_id, contract application, line cloning/setup, service-layer helpers, and legacy decoupling scripts.
• Core billing fallback removal already landed elsewhere and should be treated as prerequisite context, not repeated scope.

Discoveries

• packages/clients/src/actions/clientContractActions.ts still resolves template source using clientContract.template_contract_id ?? clientContract.contract_id ?? null in applyContractToClient(...).
• packages/clients/src/actions/clientContractLineActions.ts still selects template_contract_id alongside contract_id and still resolves template source with clientContract.template_contract_id ?? clientContract.contract_id.
• server/src/lib/api/services/ContractLineService.ts still contains template-source fallback logic in client-owned mutation/setup paths.
• server/scripts/contract-template-decoupling.ts still backfills or depends on template_contract_id fallback semantics.
• packages/billing/src/models/contract.ts and related runtime readers still join template metadata for display/provenance. These joins need classification as allowed metadata reads versus behaviorally dangerous runtime widening.

Prior Plan Context

• The March 18 service-driven invoicing cutover already tracked and completed several adjacent cleanup items:
  • F083 remove template fallback joins from live billing computations
  • F084 split instantiated contract detail/assignment loading from template detail loading
  • F085 stop runtime backfill writes to client_contracts.template_contract_id
  • F086 extend static guards for post-drop table usage
• This new plan should pick up only what remains after those changes.

Working Decision

• Treat template_contract_id as suspicious by default:
  • allowed only when explicitly serving provenance metadata
  • forbidden when used as fallback runtime identity
• If a flow still needs authoring source data, make that dependency explicit and fail closed when the source cannot be determined.

Open Questions

• Keep client_contracts.template_contract_id as provenance-only metadata for renewals/draft resume/debugging, or drive toward making it removable in a later migration?
• Which remaining template joins in runtime loaders are genuinely operator-useful provenance reads versus accidental mixed-model leakage?

Candidate Commands

• rg -n "template_contract_id|coalesce\\(cc\\.template_contract_id|template_contract_id \\?\\?|contract_templates as template" packages/billing packages/clients server
• pnpm exec vitest run --coverage.enabled=false <targeted tests>
• jq empty ee/docs/plans/2026-03-20-template-runtime-normalization-completion/features.json
• jq empty ee/docs/plans/2026-03-20-template-runtime-normalization-completion/tests.json

2026-03-20 F001/T001 Inventory Classification

• Completed preflight runtime inventory with:
  • rg -n "template_contract_id|template_contract_id \\?\\?|coalesce\\([^\\n]*template_contract_id|contract_templates as template" packages/clients/src packages/billing/src server/src/lib/api/services server/scripts

Forbidden runtime fallback (must remove)

• packages/clients/src/actions/clientContractActions.ts
  • applyContractToClient(...) uses clientContract.template_contract_id ?? clientContract.contract_id ?? null before cloning services/config.
• packages/clients/src/actions/clientContractLineActions.ts
  • addClientContractLine(...) loads both template_contract_id and contract_id, then falls back with clientContract.template_contract_id ?? clientContract.contract_id.
• server/src/lib/api/services/ContractLineService.ts
  • assignPlanToClient(...) loads both IDs and falls back with clientContract.template_contract_id ?? clientContract.contract_id ?? null.
• server/scripts/contract-template-decoupling.ts
  • Backfills client_contracts.template_contract_id = contract_id when missing.
  • Uses clientContract?.template_contract_id ?? clientContract?.contract_id ?? null when cloning.

Legacy cleanup target

• server/scripts/contract-template-decoupling.ts
  • Script behavior is coupled to hybrid model (client_contract_lines + fallback backfill) and should be retired or rewritten to provenance-only semantics.

Allowed provenance-only references (not runtime fallback)

• packages/billing/src/models/contract.ts
  • getAllWithClients(...) left-joins contract_templates by cc.template_contract_id only to expose template name metadata for list views.
• packages/billing/src/actions/contractActions.ts
  • getDraftContracts(...) joins contract_templates and selects cc.template_contract_id as draft metadata.
• packages/billing/src/actions/renewalsQueueActions.ts
  • Optional-column guard + copy-through of template_contract_id into draft assignment metadata (no fallback derivation).
• packages/billing/src/actions/contractWizardActions.ts
  • Writes template_contract_id: submission.template_id ?? null and reads back template_id: clientContract.template_contract_id ?? undefined for draft resume UX.
• packages/billing/src/lib/billing/billingEngine.ts
  • Selects cc.template_contract_id as provenance field while live joins remain anchored on cc.contract_id -> contract_lines.
• packages/clients/src/actions/clientContractLineActions.ts
  • getClientContractLine(...) selects cc.template_contract_id in response payload.
  • Update/edit destructuring drops inbound template_contract_id from mutable update fields.
• packages/clients/src/models/clientContractLine.ts
  • Selects cc.template_contract_id in DTO shape and strips it from mutation payload updates.
• packages/clients/src/actions/clientContractActions.ts and packages/clients/src/models/clientContract.ts
  • New client contract inserts set template_contract_id: null explicitly (no fallback behavior).

Notes / gotchas

• There are additional template_contract_id mentions in tests; they are fixture/static assertions and not part of runtime inventory for F001.
• Immediate implementation focus after F001: remove the four forbidden fallback sites and convert missing-provenance cases to explicit fail-closed errors.

2026-03-20 F002 Semantics Decision (authoritative)

• client_contracts.template_contract_id remains in the schema for now as provenance-only metadata.
• It is not a valid runtime identifier and must never be used as fallback identity for live contract operations.
• Runtime ownership and live reads remain anchored on client_contracts.contract_id and cloned contract_lines.
• Current retained provenance uses:
  • draft/resume and renewal flows (contractWizardActions, renewalsQueueActions)
  • operator-facing metadata surfaces (getAllWithClients, draft list views, selected DTO fields)
• Removal readiness: not ready for immediate drop migration in this plan because retained draft/renewal metadata reads still exist; this plan’s objective is to remove behavioral dependence and leave only explicit provenance reads.

2026-03-20 Implementation Log (F003-F014)

Runtime behavior changes

• Removed forbidden fallback resolution in client contract apply flow:
  • packages/clients/src/actions/clientContractActions.ts
  • replaced template_contract_id ?? contract_id with explicit provenance read and fail-closed error when missing.
• Removed forbidden fallback resolution in client contract line add flow:
  • packages/clients/src/actions/clientContractLineActions.ts
  • replaced fallback with explicit provenance read and fail-closed error when missing.
• Removed forbidden fallback resolution in API service contract-line assignment:
  • server/src/lib/api/services/ContractLineService.ts
  • assignment now requires template_contract_id provenance explicitly and errors when absent.
• Retired hybrid decoupling script semantics:
  • server/scripts/contract-template-decoupling.ts
  • rewritten to audit-only reporting; no template_contract_id backfill writes; no template clone fallback behavior.

Runtime model/type provenance alignment

• Clarified provenance-only semantics in shared interfaces:
  • packages/types/src/interfaces/billing.interfaces.ts
  • packages/types/src/interfaces/contract.interfaces.ts
• Added explicit provenance metadata handling/comments in runtime client contract-line surfaces:
  • packages/clients/src/models/clientContractLine.ts
  • packages/clients/src/actions/clientContractLineActions.ts

Legacy tests/fixtures normalization updates

• Updated tests that previously encoded fallback behavior:
  • server/src/test/unit/api/contractLineService.clientOwnedMutation.test.ts now asserts fail-closed on missing provenance and success when provenance exists.
  • server/src/test/unit/billing/clientContractLineReplacementIdentity.test.ts now asserts fail-closed add behavior when provenance is missing.
  • packages/clients/src/actions/clientContractLineActions.recurringCompatibility.test.ts now asserts template_contract_id is nullable provenance metadata.

New tests added

• Apply flow provenance/fail-closed unit coverage:
  • server/src/test/unit/billing/clientContractApplyProvenance.test.ts
• Runtime fallback static guard extensions:
  • server/src/test/unit/billing/clientContractLineRuntimeSourceGuards.static.test.ts
  • now guards template_contract_id ?? contract_id, SQL coalesce(template_contract_id, contract_id), and mixed-ID join patterns in targeted runtime files/scripts.
• Script contract test for decoupling script retirement:
  • server/src/test/unit/scripts/contractTemplateDecoupling.script.test.ts
• Shared type/schema provenance contract test:
  • server/src/test/unit/billing/templateContractIdProvenance.types.test.ts
• Runtime contract loader provenance static test:
  • server/src/test/unit/billing/contractRuntimeLoaderTemplateProvenance.static.test.ts
• DB-backed integration coverage for apply + line-add happy/failure:
  • server/src/test/integration/templateRuntimeNormalization.clientActions.integration.test.ts

Commands / runbook

• Inventory command:
  • rg -n "template_contract_id|template_contract_id \\?\\?|coalesce\\([^\\n]*template_contract_id|contract_templates as template" packages/clients/src packages/billing/src server/src/lib/api/services server/scripts
• Unit/static test command (passing):
  • pnpm exec vitest run src/test/unit/api/contractLineService.clientOwnedMutation.test.ts src/test/unit/billing/contractRuntimeLoaderTemplateProvenance.static.test.ts src/test/unit/billing/clientContractLineRuntimeSourceGuards.static.test.ts src/test/unit/scripts/contractTemplateDecoupling.script.test.ts src/test/unit/billing/templateContractIdProvenance.types.test.ts src/test/unit/billing/clientContractApplyProvenance.test.ts src/test/unit/billing/clientContractLineReplacementIdentity.test.ts ../packages/clients/src/actions/clientContractLineActions.recurringCompatibility.test.ts --coverage.enabled=false
• Integration command (test authored; local environment blocked):
  • pnpm exec vitest run src/test/integration/templateRuntimeNormalization.clientActions.integration.test.ts --coverage.enabled=false

Gotchas / blockers

• Local DB integration execution is blocked in this environment by:
  • ECONNREFUSED ::1:5438 and ECONNREFUSED 127.0.0.1:5438
• Integration tests are implemented and ready, but could not be executed locally until Postgres test DB is reachable on configured port.