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

System-Managed Default Contract Cutover Sequencing Runbook

This runbook defines the required execution order for the cutover and the explicit gates that must pass before moving to the next stage.

Stage 1: Data Model + Ensure Primitive

Required state:

• Default-contract identity marker and uniqueness guarantees are live.
• ensureDefaultContractForClient is idempotent and concurrency-safe.

Gate checks:

• npx vitest run --config shared/vitest.config.ts shared/__tests__/billingSettings.defaultContract.ensure.test.ts
• Ensure no duplicate contracts.is_system_managed_default=true rows per (tenant, owner_client_id).

Stage 2: Ensure Hooks on Billing Configuration Touchpoints

Required state:

• Shared/package billing settings/schedule/cycle-anchor paths call ensure hooks.
• Null-setting override/deletion flows do not eagerly recreate default contracts.

Gate checks:

• Billing settings/schedule update integration tests for create/update/delete paths.
• Manual smoke: update billing settings with and without active config and verify ensure behavior.

Stage 3: Effective-Date Resolver Alignment

Required state:

• Scheduling and billing disambiguation resolve by effective date.
• Save paths + UI eligible-lines path use the same effective-date semantics.

Gate checks:

• cd packages/scheduling && npx vitest run tests/timeEntryCrud.changeRequests.test.ts
• cd server && npx vitest run ../packages/billing/tests/usageActions.effectiveDate.test.ts

Stage 4: Reconciliation + Due-Work Semantics

Required state:

• Deterministic single-match unresolved rows are written back to source records.
• Ambiguous/no-match rows remain unresolved.
• Due-work output excludes deterministic rows after write-back.

Gate checks:

• cd server && npx vitest run src/test/unit/billing/billingEngine.unresolvedReconciliation.test.ts
• cd server && npx vitest run src/test/unit/billing/nonContractDueWork.integration.test.ts

Stage 5: Invoice Selection + Grouped Attribution Safety

Required state:

• Recurring selection keys no longer depend on primary-path legacy non-contract fallback semantics.
• Grouped rows include attribution metadata and hard-block generation on missing attribution.

Gate checks:

• cd server && npx vitest run src/test/unit/billing/invoiceGeneration.unresolvedSelectionKeys.test.ts
• cd server && npx vitest run src/test/unit/billing/automaticInvoices.nonContractSelection.ui.test.tsx

Stage 6: UI Semantics + Guardrails

Required state:

• Contract list/detail and time/usage messaging use system-managed default terminology.
• System-managed contract destructive/lifecycle controls are constrained.

Gate checks:

• cd server && npx vitest run src/test/unit/billing/systemManagedDefaultContracts.ui.static.test.ts
• cd server && npx vitest run src/test/unit/billing/defaultContractTerminology.ui.static.test.ts

Stage 7: Lifecycle Cleanup + API Path Parity

Required state:

• Package and API delete paths both remove default-contract assignment artifacts.
• No dangling references remain after client/billing-config cleanup.

Gate checks:

• Lifecycle integration tests for package delete and API/controller delete paths.
• Post-delete DB verification query for orphaned default-contract references.

Stage 8: Observability + Operational Markers

Required state:

• Ensure/reconcile/route paths emit structured logs.
• Operational markers for created/reused/deterministic-resolved/ambiguous are present.

Gate checks:

• cd server && npx vitest run src/test/unit/billing/defaultContractObservability.wiring.test.ts
• Validate log payloads in lower env traces for expected event names.

Stage 9: Attribution-Shell + Historical Bootstrap Finalization

Required state:

• System-managed default contracts are attribution-only and excluded from recurring/service-period authority flows.
• Optional historical bootstrap can backfill/regenerate uninvoiced client billing cycles from normalized boundaries.
• Invoiced-history boundary guardrails block unsafe backwards bootstrap moves.

Gate checks:

• npx vitest run --config shared/vitest.config.ts shared/__tests__/billingSchedule.historyBootstrap.test.ts
• cd server && npx vitest run src/test/unit/billing/systemManagedDefaultAttributionOnly.ui.wiring.test.ts src/test/unit/billing/defaultContractHistoricalBootstrapAndBillingRoute.wiring.test.ts src/test/unit/billing/systemManagedDefaultRecurringExclusion.wiring.test.ts

Rollback / Safety Rules

• Do not remove compatibility parsing until Stage 5 gates pass in CI and staging.
• If Stage 4 reconciliation introduces ambiguous-growth regressions, disable grouped generation for affected candidates and re-run Stage 4 diagnostics.
• Keep default-contract ensure lazy (billing-config touchpoint only) during rollout; do not introduce eager global backfill.