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

PRD — Contract Template Normalization

• Slug: contract-template-normalization
• Date: 2026-03-16
• Status: Draft

Summary

Normalize the contracts domain so reusable templates exist only in contract_template* tables and instantiated client-owned contracts exist only in contracts / contract_lines / client_contracts. Remove the remaining runtime, API, UI, and migration compatibility layers that still treat templates as live contract fallbacks or contract-shaped resources.

Make template instantiation the only legal transfer boundary between authoring data and runtime data: templates can be copied into contracts, but live contracts must never read through templates again, and template edits/deletes must never mutate existing contract runtime state.

This is a follow-on to ee/docs/plans/2026-03-16-client-owned-contracts-simplification/. That plan established the client-owned contract invariant for non-template contracts. This plan finishes the decoupling by eliminating the mixed-model artifacts that still let runtime billing, contract APIs, and legacy scripts behave as if templates and contracts are interchangeable.

Problem

The repo currently supports two contradictory realities at once:

• The intended architecture says templates are reusable blueprints stored in dedicated contract_template* tables, and instantiated contracts are client-owned runtime objects.
• The implementation still carries multiple compatibility layers from the legacy mixed schema:
  • template rows can still exist in contracts and contract_lines behind is_template
  • client contracts still carry template_contract_id as an active runtime lookup key
  • billing still falls back from client_contracts.contract_id to client_contracts.template_contract_id
  • several actions and UI loaders still map templates into IContract-shaped responses
  • template deletion and line repository code still reaches into instantiated contract storage

This keeps the system harder to reason about than necessary and introduces real risks:

• Billing behavior can still depend on template-side data after a contract has supposedly been instantiated.
• The codebase still behaves as if a template and its instantiated contracts are linked by a live mutable relationship instead of a one-way copy boundary.
• Template and contract APIs remain ambiguous, which leaks complexity into every caller.
• Schema cleanup is blocked because runtime still relies on legacy fallback columns and flags.
• Operators still need verification scripts that compare “legacy template rows in contracts” to separated template tables, which means the cutover is not finished.

Goals

• Make template data authoring-only and one-way copied into instantiated contracts.
• Make template instantiation the only boundary where authoring data crosses into runtime contracts.
• Make runtime billing and discount resolution depend only on instantiated contract/client assignment state.
• Stop treating templates as IContract-shaped runtime resources in APIs and UI loaders.
• Remove the remaining behavioral dependence on contracts.is_template, contract_lines.is_template, and template-backed runtime fallbacks.
• Reduce client_contracts.template_contract_id to provenance-only metadata or remove it entirely if no longer needed.
• Retire legacy verification/backfill scripts that assume duplicated storage once cutover is complete.
• Leave the codebase with one clear model:
  • templates define reusable defaults
  • contracts and client contracts define live billing behavior

Non-goals

• Reversiting the client-owned contracts migration already delivered in the March 16 simplification plan.
• Redesigning the contract template product experience.
• Rewriting historical invoices or moving invoice history to template-aware tables.
• Changing the core contract billing semantics, tax calculation semantics, or renewal business rules beyond removing template fallback.
• General contract-domain redesign outside contract/template normalization.
• Adding observability, metrics, rollout toggles, or operational tooling beyond what is required to validate the cutover.

Users and Primary Flows

• Billing admin

  1. Creates or edits reusable templates in template-specific screens.
  2. Creates client-owned contracts from templates or from scratch.
  3. Bills clients from instantiated contract data without template-side fallback.

• Finance / operations

  1. Reviews live contracts and invoices without needing to understand template linkage.
  2. Runs billing/reporting flows that operate on instantiated contract facts only.

• Engineers / support

  1. Can trace a bug to either template authoring or contract runtime behavior without a mixed resource model.
  2. Can reason about template provenance separately from live billing state.

UX / UI Notes

• Templates and contracts should stop sharing a single implicit “contract detail” abstraction.
• Template screens should load template DTOs and template lines directly, not contract-shaped surrogates.
• Contract screens should load only client-owned contract headers and assignment/runtime data.
• getContractById-style flows should not silently return a template when a contract lookup misses.
• Any UI still showing is_template as a first-class branch on the same runtime type should be replaced with explicit route/view separation.
• Template edit/delete affordances should clearly operate on reusable authoring assets, not on already-instantiated contracts.

Requirements

Functional Requirements

• Single-write instantiation boundary

  • Template instantiation must be the only supported path for moving template-defined data into runtime contract tables.
  • After instantiation, runtime billing, reporting, and contract CRUD must treat instantiated rows as self-contained facts.
  • Template edits must not propagate into existing contracts unless an explicit reapply/reclone workflow is intentionally built later.
  • Template deletes must only affect authoring-side records and provenance references, never live contract behavior or runtime rows.

• Runtime/billing decoupling

  • Billing engine contract-line resolution must load only from instantiated contract IDs.
  • Billing discount resolution must not join through template_contract_id fallbacks.
  • Cloned contract data must remain billable even if the source template changes later.

• Template provenance

  • Decide and document whether client_contracts.template_contract_id remains as provenance metadata.
  • If retained, it must not be used as a live billing/configuration fallback.
  • If dropped, migration and API flows must preserve enough provenance elsewhere for audit/debug needs.

• Contract/template API separation

  • Contract list/detail APIs must only return instantiated contracts.
  • Template list/detail APIs must only return template resources.
  • Shared DTO adapters that map templates into IContract-shaped responses must be removed or isolated behind explicit compatibility endpoints slated for deletion.

• Repository/action separation

  • Contract line repositories/actions must stop accepting a single “maybe template, maybe contract” ID space.
  • Template line CRUD and contract line CRUD must be separated at the repository/action boundary.
  • Template delete/update flows must not mutate instantiated contract tables.

• Schema cleanup

  • Remove live reliance on contracts.is_template.
  • Remove live reliance on contract_lines.is_template.
  • Remove or re-scope legacy verification scripts that compare duplicated legacy template rows with dedicated template tables.
  • After runtime cutover and validation, add cleanup migration(s) that drop obsolete columns / legacy rows / compatibility references.

• Data validation and migration safety

  • Before destructive cleanup, validate that all legacy template rows in contracts and contract_lines have equivalent canonical records in contract_template*.
  • Fail closed if any tenant still relies on legacy-only template data or missing canonical template records.
  • Provide a deterministic operator runbook for preflight, cutover, and post-cutover verification.

Non-functional Requirements

• Cutover must be staged so runtime behavior changes land before schema deletion.
• Validation must rely on real database reads against migrated schema, not only source-string tests.
• The resulting architecture must be simpler than the current one: no hidden runtime fallback from live contracts to templates.
• The resulting architecture must have a single, obvious data-flow direction: template authoring data can be copied into runtime contracts, but runtime contracts do not read back through template state.
• The cleanup must remain compatible with the current multi-tenant / Citus environment constraints.

Data / API / Integrations

• Template source of truth

  • contract_templates
  • contract_template_lines
  • contract_template_line_*

• Runtime source of truth

  • contracts
  • contract_lines
  • client_contracts
  • contract_pricing_schedules
  • contract-line child/config tables

• Required cleanup targets

  • contracts.is_template
  • contract_lines.is_template
  • any runtime coalesce(template_contract_id, contract_id) joins
  • any OR joins on template_contract_id vs contract_id
  • contract/template action adapters that flatten templates into contract DTOs

• Scripts and verification

  • server/scripts/verify-template-migration.ts currently assumes duplicated storage and will need to become either:
    • a strict pre-cutover verifier only, or
    • a cleanup verifier that proves legacy rows are gone and canonical template rows remain
  • server/scripts/contract-template-decoupling.ts currently preserves hybrid semantics and should be retired or rewritten to match the normalized model

• External/accounting integrations

  • No intentional behavior change to invoice export payloads, but invoice generation must continue to derive from instantiated invoices/contracts only.
  • If any downstream export uses template provenance today, document and preserve that explicitly rather than via hidden fallback joins.

Security / Permissions

• No new roles or permissions are required.
• Existing billing/contract/template permissions remain in force.
• API separation must not accidentally broaden template visibility through contract endpoints or vice versa.

Observability

• Out of scope as a product feature.
• Migration/cutover scripts must log sufficient validation output to identify blocking tenants and mismatched legacy/template records.

Rollout / Migration

• Phase 0: inventory and invariants

  • inventory all runtime uses of template_contract_id, contracts.is_template, and contract_lines.is_template
  • inventory all API/UI contract-template compatibility adapters
  • verify canonical template data exists for every legacy template row

• Phase 1: runtime cutover

  • codify template instantiation as the sole transfer boundary from authoring data to runtime data
  • remove billing-engine and discount fallback to template-backed contract IDs
  • ensure all template-to-contract instantiation paths fully clone required data into runtime tables
  • validate invoice generation and discount application on instantiated contracts only

• Phase 2: API/UI and repository separation

  • split template DTOs/routes/actions from contract DTOs/routes/actions
  • split template-line CRUD from contract-line CRUD
  • remove “contract lookup falls back to template lookup” behavior

• Phase 3: schema and script cleanup

  • stop relying on duplicated legacy template rows
  • retire or rewrite legacy backfill/verification scripts
  • drop obsolete legacy columns / rows once preconditions are satisfied

• Phase 4: post-cutover validation

  • verify no runtime code path joins templates as a live billing source
  • verify no contract endpoint returns template-backed data
  • verify deleting/updating a template cannot mutate live contract rows

Open Questions

• Should client_contracts.template_contract_id remain as immutable provenance metadata, or should provenance move to a different field/table before removal?
• Do any production tenants still depend on template rows remaining present in contracts for operational tooling outside the app?
• Should the final cleanup physically delete legacy template rows from contracts/contract_lines, or mark them unreachable first and purge later?
• Do we want a temporary compatibility API for callers currently expecting templates in contract-shaped payloads, or should we cut those consumers over directly?

Acceptance Criteria (Definition of Done)

• Billing and discount resolution no longer fall back from client_contracts.contract_id to template-backed IDs.
• Template instantiation is the only supported authoring-to-runtime transfer path, with no reverse sync or live template reads after assignment.
• Templates are no longer returned from contract endpoints or contract lookups.
• Template CRUD no longer mutates instantiated contract tables.
• Editing or deleting a template after contract instantiation does not change live contract runtime behavior.
• Contract line CRUD and template line CRUD are separated in repositories/actions and no longer share a mixed “contract or template” code path.
• Canonical template records fully replace legacy template rows as the reusable source of truth.
• Legacy compatibility scripts/paths are either removed or rewritten to validate the normalized model.
• The system can safely drop obsolete legacy template markers/columns without changing runtime behavior.