PSA/ee/docs/plans/2026-03-16-contract-template-normalization/SCRATCHPAD.md

Scratchpad — Contract Template Normalization

• Plan slug: contract-template-normalization
• Created: 2026-03-16

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-16) Treat this as a new standalone ALGA plan rather than appending to 2026-03-16-client-owned-contracts-simplification. The earlier plan is implementation-specific and already largely shipped; this work is a broader normalization/cutover effort.
• (2026-03-16) Sequence the work as runtime cutover first, API/UI separation second, schema cleanup last. Deleting legacy columns/rows before removing runtime fallback is unsafe.
• (2026-03-16) Treat template instantiation as the only legal transfer boundary between authoring data and runtime data. Existing contracts must be self-contained after instantiation, with no reverse sync from templates.

Discoveries / Constraints

• (2026-03-16) packages/billing/src/lib/billing/billingEngine.ts still resolves live contract lines through coalesce(cc.template_contract_id, cc.contract_id) and discount joins still use template_contract_id OR contract_id. This is the primary runtime coupling to remove.
• (2026-03-16) shared/billingClients/templateClone.ts is already close to the target shape: it reads contract_template* tables and writes contract_* tables. The remaining question is whether template provenance should survive only as metadata.
• (2026-03-16) packages/billing/src/actions/contractActions.ts still maps template rows into IContract-shaped responses and falls back from contract lookup to template lookup.
• (2026-03-16) packages/billing/src/models/contractTemplate.ts template deletion still deletes from instantiated contract tables (contract_lines, contract_line_service_*, contract_line_services, contract_line_service_defaults). This is a hard coupling and a cleanup blocker.
• (2026-03-16) The strongest framing for this plan is not just “remove legacy template flags,” but “make templates authoring-only assets and instantiated contracts self-contained runtime facts.”
• (2026-03-16) server/scripts/verify-template-migration.ts currently validates parity between legacy template rows in contracts and canonical rows in contract_templates, which means the operational model still assumes duplicated storage exists.
• (2026-03-16) server/scripts/contract-template-decoupling.ts still preserves hybrid semantics by backfilling or relying on template_contract_id.
• (2026-03-16) Schema artifacts still present from the mixed model:
  • contracts.is_template
  • contract_lines.is_template
  • client_contracts.template_contract_id
• (2026-03-16) Citus / distributed-FK constraints are part of the sequencing risk. Some migrations intentionally avoided strict FKs, so application/runtime cleanup cannot assume the database enforces the final invariant today.

Commands / Runbooks

• (2026-03-16) Recon:
  • rg -n "is_template|template_contract_id|contract_templates|mapTemplateToContract|isTemplateContract\\(" packages/billing packages/clients server shared
  • sed -n '520,590p' packages/billing/src/lib/billing/billingEngine.ts
  • sed -n '1,220p' server/scripts/verify-template-migration.ts
  • sed -n '1,240p' packages/billing/src/actions/contractActions.ts
  • sed -n '120,210p' packages/billing/src/models/contractTemplate.ts
• (2026-03-16) Plan validation:
  • python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/validate_plan.py ee/docs/plans/2026-03-16-contract-template-normalization

Links / References

• Prior related plan:
  • ee/docs/plans/2026-03-16-client-owned-contracts-simplification/
• Key runtime files:
  • packages/billing/src/lib/billing/billingEngine.ts
  • shared/billingClients/templateClone.ts
  • packages/billing/src/actions/contractActions.ts
  • packages/billing/src/models/contract.ts
  • packages/billing/src/models/contractTemplate.ts
  • packages/billing/src/repositories/contractLineRepository.ts
• Key migration / ops files:
  • server/migrations/20251020090000_contract_templates_phase1.cjs
  • server/migrations/20251020164500_backfill_contract_template_tables.cjs
  • server/migrations/20251020180500_update_client_contract_template_foreign_keys.cjs
  • server/migrations/20251028090000_remove_contract_line_mappings.cjs
  • server/scripts/verify-template-migration.ts
  • server/scripts/contract-template-decoupling.ts

Open Questions

• Should client_contracts.template_contract_id remain as immutable provenance metadata, or should provenance move to a different field/table before full removal?
• Are there production-only support or ops workflows still depending on legacy template rows living in contracts?
• Is there any externally consumed contract API that currently depends on template rows being presented as IContract and needs a transition path?