PSA/ee/docs/plans/2026-03-19-client-contract-line-post-drop-cutover/PRD.md

PRD — Client Contract Line Post-Drop Cutover

• Slug: client-contract-line-post-drop-cutover
• Date: 2026-03-19
• Status: Draft

Summary

Finish the post-client_contract_lines cutover so fully migrated environments run billing, recurring invoicing, contract authoring, and related read models entirely through the client-owned contract structure:

• contracts as the client-owned contract header
• contract_lines as the canonical line/runtime obligation
• client_contracts as the client assignment and lifecycle window

This plan covers both:

• restoring runtime correctness in environments where the legacy client_contract_* line tables have already been dropped
• cleaning up stale code, tests, and plan/runbook references that still encode client_contract_lines as a live dependency

The target end state is that no live billing or contract path requires the dropped client_contract_lines table, and recurring client-cadence obligations use a canonical post-drop identity consistent with the client-owned contract model.

Problem

The branch currently carries two contradictory models at once:

• the March 16 client-owned contracts work says non-template contracts are client-owned, contract_lines are the canonical line records, and client_contracts is the assignment/lifecycle layer
• a later migration drops client_contract_lines and related per-client line tables as redundant
• some newer runtime code already follows that post-drop model
• several recurring, invoicing, contract-authoring, credit, bucket, report, and API paths still query client_contract_lines directly or preserve client_contract_line as a first-class runtime identity
• server-side contract-line APIs, billing overview reporting, credit flows, and test/runbook fixtures still encode the dropped table as the live assignment model

In a fully migrated environment this causes real breakage, not just cleanup debt:

• AutomaticInvoices can 500 while loading recurring due work
• recurring preview/generate can fail when resolving selector-input windows
• service-period repair and regeneration paths can fail
• linkage, bucket, and contract authoring paths can drift between old and new structures
• tests can still pass because they mock or assert the removed table as expected live behavior

The current state is therefore unsafe:

• migrations say the old structure is gone
• runtime code still depends on it
• tests and docs partially protect the old behavior instead of the intended end state

Goals

• Make fully migrated environments work without client_contract_lines or related dropped client-contract line tables.
• Standardize live contract/billing runtime around:
  • contracts
  • contract_lines
  • client_contracts
• Define one canonical post-drop identity for recurring client-cadence obligations.
• Remove live recurring/invoicing dependence on client_contract_line_id and obligation_type = 'client_contract_line' where those concepts only preserve the removed table.
• Update contract authoring and mutation paths so they no longer write dropped client-contract line tables.
• Update dependent read models, reports, and linkage flows so they no longer query dropped tables.
• Update server-side contract-line service paths so deprecated client-line assumptions do not leak back into live runtime behavior.
• Remove or rewrite stale tests/static guards that preserve the removed structure as expected behavior.
• Update plan/runbook/docs language so future work does not regress back to the dropped structure.

Non-goals

• Reintroducing client_contract_lines or any other dropped client-contract line table.
• Reversing the client-owned contract model established in the March 16 simplification work.
• Redesigning contract templates, invoicing UI, or recurring cadence ownership beyond what is necessary to align them to the post-drop structure.
• Rewriting historical invoice financial data unless linkage/read-side migration is required for correctness.
• Broad billing-domain cleanup outside the specific dropped-table and recurring-obligation identity mismatch.

Users and Primary Flows

• Billing admin

  1. Creates a client-owned contract and contract lines.
  2. Generates recurring invoices from AutomaticInvoices.
  3. Previews, generates, reverses, or deletes recurring invoices without hidden dependence on removed tables.

• Finance / operations

  1. Reviews due recurring work in fully migrated environments.
  2. Uses service-period inspection and regeneration without schema mismatch failures.
  3. Trusts recurring history, linkage repair, and bucket-derived calculations after migration.

• Engineers / support

  1. Can reason about one contract-line runtime model.
  2. Do not have to special-case “post-drop environments” versus “legacy environments” in normal billing code.
  3. Can rely on tests to protect the intended client-owned post-drop structure.

UX / UI Notes

• This plan is primarily structural/runtime cleanup, but several user-facing surfaces must stop breaking or implying old lineage:
  • AutomaticInvoices
  • recurring preview / generate
  • recurring service-period management
  • contract authoring/wizard flows
  • contract line editing/configuration
  • recurring history / reverse / delete affordances
• No new major UI is required.
• Existing UI copy that refers to service periods or client-owned contracts should remain, but hidden legacy dependencies must be removed so the UI actually works in migrated tenants.
• Any operator-facing error about missing service periods should be a canonical repair action, not a missing-table or dropped-structure crash.

Requirements

Functional Requirements

• Canonical post-drop contract structure

  • Live billing and recurring paths must treat contract_lines as the canonical recurring/service obligation record.
  • Client ownership must resolve through contracts.owner_client_id.
  • Assignment lifecycle windows must resolve through client_contracts.

• Recurring obligation identity

  • The implementation must define one canonical post-drop identity for client-cadence recurring obligations.
  • Selector-input due work, materialization, regeneration, invoice linkage, reverse/delete repair, and duplicate prevention must all use that same identity.
  • Legacy client_contract_line recurring identity may remain only as passive historical compatibility metadata if required, not as a live table dependency.

• Due-work and invoicing

  • getAvailableRecurringDueWork() must work in environments where client_contract_lines does not exist.
  • Recurring due-work selection, preview, and generation must not join dropped tables.
  • AutomaticInvoices must load, preview, and generate recurring rows in a fully migrated environment.

• Service-period lifecycle

  • Recurring service-period inspection, regeneration, and repair actions must resolve obligation metadata without dropped tables.
  • Client-cadence regeneration must load obligations from the surviving structure and persist records keyed to the canonical post-drop identity.

• Contract authoring and mutation

  • Contract wizard and related create/update flows must stop inserting or updating dropped client-contract line tables.
  • Contract line mutation paths must use the surviving structures only.

• Linkage and dependent billing flows

  • Invoice/service-period linkage must resolve recurring obligation candidates without client_contract_lines.
  • Bucket period resolution and related recurring helpers must use the surviving structure.
  • Credit or other dependent billing flows that still look up client-contract line rows must be rewritten or removed.

• Reports / read models / API

  • Read models and report definitions must stop querying dropped client-contract line tables as live fact sources.
  • Server/package contract-line services that still use dropped client-line tables for unassign/deactivate, usage analytics, in-use checks, overlap validation, or overview counts must be rewritten or removed from live paths.
  • API/services that remain intentionally legacy must be clearly isolated and must not be called by live billing/runtime paths.

• Tests and docs cleanup

  • Static tests and integration tests that currently assert client_contract_lines usage as live expected behavior must be updated or removed.
  • Plans/runbooks/docs that still describe client_contract_lines as an expected live runtime table must be corrected or explicitly marked historical.
  • Cleanup-only references in teardowns, fixtures, tracked backup files, and stale runbooks should be removed so new work does not keep cargo-culting the dropped structure.

Non-functional Requirements

• No live runtime path should crash simply because a fully migrated database no longer contains client_contract_lines.
• The cutover should reduce structural ambiguity, not add more compatibility layers.
• Tests must fail if a live billing/runtime path reintroduces dropped-table dependence.
• The plan should prefer one clear canonical model over mixed old/new identity shims.

Data / API / Integrations

• Runtime data shape

  • contracts.owner_client_id remains the client ownership anchor.
  • client_contracts remains the assignment/lifecycle source.
  • contract_lines remains the canonical recurring/service obligation row.

• Recurring identity cleanup

  • The current use of obligation_type = 'client_contract_line' and client_contract_line_id in recurring service periods must be reviewed and either:
    • migrated to canonical contract_line identity, or
    • formally retained as a logical compatibility identity that no longer depends on a dropped table.
  • The chosen approach must be applied consistently across:
    • materialization
    • due-work selection
    • preview/generate
    • linkage
    • regeneration
    • reverse/delete repair

• API/services

  • Server and package services that still expose or derive live behavior from client_contract_lines must be rewritten or clearly deprecated away from runtime codepaths.
  • Report definitions and billing overview readers must use surviving contract/assignment structures.

Security / Permissions

• No new permissions are required.
• Existing billing, contract, invoice, and recurring-service-period permissions remain the guardrails.
• Cleanup must not bypass any existing authorization checks while rewriting dropped-table lookups.

Observability

• Errors that currently manifest as missing-relation failures should become explicit domain failures only where a real business precondition is missing.
• The plan does not require new observability infrastructure, but runtime failures should become diagnosable from the canonical structure instead of surfacing raw dropped-table errors.

Rollout / Migration

• This work assumes the migration dropping client_contract_lines and related tables has already run in target environments.
• Runtime code must therefore treat those tables as unavailable, not optional.
• The implementation sequence should be:
  1. unblock recurring due-work / AutomaticInvoices
  2. unblock recurring preview/generate/linkage/repair
  3. fix regeneration and service-period management
  4. remove dropped-table writes from contract authoring and mutation paths
  5. clean up dependent read models, contract-line services, credits, buckets, and reports
  6. rewrite stale tests/docs/runbooks that preserve the old structure
  7. remove tracked backup artifacts and low-value cleanup references that keep the removed table visible in active development flows
• If any historical data or compatibility read path still requires legacy recurring identity fields, keep them as passive metadata only and document the boundary clearly.

Open Questions

• Should recurring client-cadence obligations migrate fully to obligation_type = 'contract_line', or should the code retain a logical client_contract_line identity that is no longer backed by a physical table?
• If any historical invoices or recurring records still encode legacy line identity, what minimal read-side compatibility is required to keep them explainable without preserving old runtime joins?
• Which deprecated server/package services should be cleaned up in this plan versus explicitly deferred once live billing/runtime paths are fixed?
• Which stale historical plan/design docs should be left untouched but explicitly treated as historical, versus corrected because they are still used as operational guidance?

Acceptance Criteria (Definition of Done)

• AutomaticInvoices loads successfully in a fully migrated environment with no client_contract_lines table.
• Recurring due-work, preview, generate, reverse/delete repair, and service-period management no longer query dropped client-contract line tables.
• Contract wizard and related contract-authoring flows do not write dropped client-contract line tables.
• Invoice linkage, bucket timing, and dependent recurring/billing helpers work through the surviving contract-owned structure.
• Live report/read-model and contract-line service paths no longer depend on client_contract_lines.
• Tests and static guards no longer preserve dropped-table dependence as expected live behavior.
• Documentation and runbooks describe the post-drop client-owned structure accurately, and tracked backup artifacts or stale cleanup fixtures no longer point engineers back at the removed table.