PSA/ee/docs/plans/2026-03-21-system-managed-default-contract-cutover/ENGINEERING_NOTES.md

Engineering Notes — System-Managed Default Contract

Date: 2026-03-21

Domain Model

• Identity: a system-managed default contract is a non-template contract row in contracts where:
  • is_system_managed_default = true
  • owner_client_id = <target client>
  • tenant = <target tenant>
• Authority model: the system-managed default contract is an attribution shell only. It does not act as a recurring cadence authority, service-period authority, or user-authored pricing surface.
• Assignment: every default contract must have a corresponding client_contracts row for the same tenant/client/contract.
• Creation trigger: created on qualifying billing-settings ensure paths (shared and package wrappers), not at client create.

Invariants

1. At-most-one default contract per tenant+client.
2. Default contract is never template-backed (is_template = false).
3. Default contract is active lifecycle-safe baseline:
   • status = 'active'
   • is_active = true
4. Default contract has deterministic business naming:
   • contract_name = 'System-managed default contract'
   • contract_description = 'Created automatically for uncontracted work'
5. Default contract has deterministic owner:
   • owner_client_id = client_id
6. Default contract must have one reusable assignment relationship for that same client (client_contracts).
7. System-managed default contracts are non-authorable:
   • no contract-line authoring,
   • no pricing-schedule authoring,
   • no manual assignment/date lifecycle edits.
8. Runtime timing for unmatched default-contract work must come from client billing schedule windows (client cadence), never from default-contract recurrence metadata.

Historical Billing Bootstrap Model

• Optional input: billingHistoryStartDate on billing-schedule update flows.
• Normalization: user-entered bootstrap date is normalized to the containing cycle boundary using shared cycle-anchor math (resolveNormalizedBootstrapBoundary).
• Regeneration policy:
  • delete/rebuild uninvoiced cycles from normalized boundary forward,
  • keep invoiced boundaries immutable,
  • block requests earlier than earliest invoiced cycle boundary.
• Convergence:
  • schedule save with bootstrap and manual effective-date cycle bootstrap both normalize through shared boundary rules,
  • generated historical cycles remain contiguous through the current date.

Persistence Strategy

• Added marker column on contracts: is_system_managed_default boolean not null default false.
• Added uniqueness guard:
  • unique partial index on (tenant, owner_client_id) where is_system_managed_default = true and non-template.
• Resolution/ensure implementation catches uniqueness races and re-reads existing default contract.

Ensure Primitive Contract

• Shared primitive: ensureDefaultContractForClient(knexOrTrx, { tenant, clientId }).
• Behavior:
  • validates client exists,
  • reuses existing marked default contract when present,
  • inserts minimal contract header + assignment when absent,
  • idempotently ensures assignment exists,
  • safe under concurrent insert race via unique-violation retry-read.