PSA/ee/docs/plans/2026-03-16-service-period-first-billing-and-cadence-ownership/CUTOVER_SEQUENCE.md

Cutover Sequence

This artifact defines the operational cutover order after the core client-cadence parity work exists. The goal is to keep coexistence explicit instead of letting readers, writers, scheduler identity, and downstream consumers switch at unrelated times.

Reader-First Core Cutover

Stage A — Reader compatibility before writer cutover

• Keep invoice APIs, invoice models, preview rows, renderer adapters, portal readers, and export preview readers dual-shape aware before new writes depend on canonical recurring detail periods.
• Historical flat invoices must continue to hydrate through the same readers without synthesized canonical detail rows.
• Canonical-detail-aware readers must prefer invoice_charge_details when detail rows exist and fall back only when the invoice is genuinely historical or financial-only.
• Exit criteria:
  • reader hydration tests pass for both historical flat invoices and canonical detail-backed invoices
  • portal/export/reporting readers have an explicit flattening or omission policy

Stage B — Writer cutover after reader compatibility

• Persist canonical recurring detail periods on newly generated recurring invoices only after Stage A readers are already safe.
• Keep compatibility summary fields on parent charges and invoice headers during this stage; do not remove them while dual-shape readers are still active.
• Preserve billing_cycle_alignment as compatibility storage only; it must not re-enter live recurring execution.
• Exit criteria:
  • new recurring invoices persist canonical detail periods consistently
  • historical invoices remain queryable without migration or rewrite

Stage C — Scheduler identity cutover after reader and writer stability

• Introduce typed execution-window identity, selector-input payloads, and retry keys only after readers and writers already understand the canonical recurring detail model.
• Client cadence may continue using a billingCycleId bridge, but contract-cadence execution must be able to run from selectorInput plus execution-window identity without forcing a UUID billing-cycle lookup.
• Scheduler cutover is complete only when background jobs, comparison-mode traces, and retry identity all tolerate execution windows that do not map to client_billing_cycles.
• Exit criteria:
  • billingCycleId is no longer the only schedulable recurring identity
  • selector-input jobs and retries are deterministic for both client and contract cadence

Stage D — Grouping and invoice-candidate policy cutover

• Enable explicit grouping and split rules only after scheduler identity is stable enough to select the right due work.
• Group by invoice-window identity first, then apply contract scope, purchase-order scope, currency, tax-source, and export-shape splits.
• Do not let downstream consumers infer grouping from legacy billing-cycle assumptions once mixed cadence is live.
• Exit criteria:
  • candidate groups expose explainable split reasons
  • mixed cadence no longer relies on incidental client-cycle grouping

Stage E — Contract-cadence tenant enablement

• Make cadence_owner = contract tenant-writable only after Stages A through D are already stable on the client-cadence path.
• Unsupported combinations must fail fast instead of falling back to client cadence.
• Keep comparison-mode and rollout validation focused on the enabled path; do not treat dark code as evidence of cutover safety.

Downstream Consumer Cutover

Portal and dashboard readers

• Cut portal invoice detail and summary readers first because support workflows will notice header-versus-detail mismatches immediately.
• Keep explicit flattening or omission copy for historical/manual financial rows during coexistence.
• Do not promote portal coverage summaries to the basis for financial-state widgets such as pending-invoice counts.

Reporting families

• Apply the reporting date-basis policy after reader compatibility is in place, not before.
• Revenue and recurring coverage reporting may pivot to canonical detail periods once the read-model contract exists.
• Expiration, reconciliation, collections, and other financial-state readers stay on their documented invoice or transaction date basis unless a later report family explicitly changes that rule.

Accounting export readers and adapters

• Cut export repositories and preview selectors before adapter-specific payload transforms.
• Preserve per-line service_period_source so stored batches can contain both historical/header-fallback and canonical-detail-backed rows during coexistence.
• QuickBooks, Xero, and CSV flattening rules must be adapter-specific and additive; they must not mutate the stored source-of-truth export payload on replay or reread.

Ordering rule across downstream consumers

• Portal and reporting readers may cut over before all adapters do, but only after the shared invoice read-model contract is already stable.
• Export adapters are the last downstream step because they depend on both reader correctness and stored export payload provenance.

Rollback And Coexistence

Coexistence expectations

• Historical flat invoices and canonical detail-backed invoices will remain queryable together for an extended period.
• Reader rollback means halting forward cutover or re-enabling compatibility read paths, not rewriting persisted canonical detail rows into historical flat shapes.
• Stored export batches, audit logs, and workflow payloads may legitimately contain both legacy fallback semantics and canonical recurring provenance during the coexistence window.

Rollback posture by layer

• Reader rollback:
  • allowed if canonical-detail-aware readers regress
  • must preserve dual-shape support and must not delete canonical invoice_charge_details
• Writer rollback:
  • means stopping new canonical recurring writes or gating the affected path
  • must not backfill or erase already-persisted canonical detail periods
• Scheduler rollback:
  • means disabling the affected execution-window path or returning contract cadence to dark-code status
  • must not force contract-cadence identities back through fake billingCycleId bridges
• Downstream rollback:
  • may temporarily revert a portal/report/export consumer to its documented fallback projection
  • must preserve stored provenance fields so replay and reread remain explainable

Long-lived coexistence guardrails

• Keep dual-shape invoice schema support until product explicitly decides that historical flat readers can be removed.
• Keep canonical recurring detail rows authoritative whenever they exist, even if a temporary rollback makes a consumer flatten them differently.
• Treat historical/header-fallback invoices as compatibility data, not as proof that new invoices may skip canonical detail persistence.