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

Pass 0 Appendix — Inventory, Parity, and Compatibility Boundaries

This appendix turns the PRD's pass-0 goals into implementation-grade artifacts. It is intentionally source-backed: the file inventory below is paired with pass-0-source-inventory.json, and a docs contract test keeps the appendix aligned with live code references.

Architecture Flow

Recurring billing normalization in this plan follows one authoritative sequence:

1. cadence owner determines the boundary generator
2. the boundary generator emits canonical service periods
3. assignment activity windows intersect those service periods
4. due-position rules map service periods onto invoice windows
5. invoice selection chooses due recurring work for a billing run
6. persisted invoice detail rows carry the canonical service-period metadata downstream

Anything that still derives timing from invoice headers, billing_cycle_alignment, or charge-family-specific proration is inventory debt or cleanup work.

System-Surface Matrix

Surface	Key files / seams	Why it is in scope	Pass-0 requirement
Runtime billing	packages/billing/src/lib/billing/billingEngine.ts, shared/billingClients/createBillingCycles.ts, packages/billing/src/lib/billing/createBillingCycles.ts	Current runtime still mixes client cycles, assignment dates, billing_timing, enable_proration, and billing_cycle_alignment.	Inventory live timing controls and define the parity target before refactors begin.
Invoice generation and persistence	packages/billing/src/actions/invoiceGeneration.ts, packages/billing/src/services/invoiceService.ts	Recurring timing leaks into invoice detail persistence, duplicate prevention, and billed-through behavior.	Document the header-vs-detail timing split and the future cut line.
Credits / prepayment / negative invoices	packages/billing/src/actions/creditActions.ts, packages/billing/src/actions/invoiceModification.ts, server/src/test/infrastructure/billing/credits/*, server/src/test/infrastructure/billing/invoices/prepaymentInvoice.test.ts, server/src/test/infrastructure/billing/invoices/negativeInvoiceCredit.test.ts	These flows already depend on recurring timing metadata and are likely to regress if service periods move.	Capture the existing consumers before any timing model changes.
Pricing / discounts / PO / tax	server/src/test/infrastructure/billing/pricingSchedules/pricingScheduleRateOverrides.test.ts, packages/billing/src/services/purchaseOrderService.ts, packages/billing/src/services/accountingExportInvoiceSelector.ts	These features evaluate dates or grouping constraints that depend on recurring timing semantics.	Add them to the parity matrix instead of treating them as follow-on surprises.
Data model / API / repositories	server/src/lib/repositories/contractLineRepository.ts, server/src/lib/api/services/ContractLineService.ts, server/src/lib/api/schemas/contractLineSchemas.ts, packages/billing/src/repositories/contractLineRepository.ts	billing_cycle_alignment, billing_timing, and enable_proration are still propagated by write paths and read models.	Inventory live storage and propagation points before introducing cadence_owner.
UI authoring and settings	packages/billing/src/components/billing-dashboard/ContractLineDialog.tsx, packages/billing/src/components/billing-dashboard/contracts/ContractWizard.tsx, packages/billing/src/components/billing-dashboard/contracts/QuickStartGuide.tsx, packages/billing/src/actions/billingCycleAnchorActions.ts	Current UI teaches proration-centric workarounds and assumes client cadence is universal.	Capture every authoring surface that must be updated with explicit cadence language.
Portal / reporting / downstream readers	packages/client-portal/src/actions/account.ts, packages/client-portal/src/actions/client-portal-actions/client-billing.ts, packages/billing/src/actions/contractReportActions.ts	These readers mostly flatten contract or invoice-header timing today and will need an explicit post-cutover policy.	Document them now so parity is checked at the reader contract, not only in the engine.
Accounting exports	packages/billing/src/services/accountingExportInvoiceSelector.ts, packages/billing/src/repositories/accountingExportRepository.ts, packages/billing/src/adapters/accounting/xeroAdapter.ts, packages/billing/src/adapters/accounting/quickBooksOnlineAdapter.ts	Export adapters already persist or flatten service-period fields and are sensitive to shape drift.	Define their current data contract and include them in parity checks.
Migration / cleanup	server/migrations/20251025120000_add_billing_timing_metadata.cjs, server/migrations/20251028120000_consolidate_contract_line_rates.cjs	Historical timing fields and compatibility migrations already exist.	Treat migration state as part of the live system, not a background assumption.

Live Timing-Control Inventory

Source-backed file lists live in pass-0-source-inventory.json.

Current controls that materially affect recurring timing

Control	Current role	Evidence anchors
resolveServicePeriod	Billing-engine helper that still decides charge timing directly for recurring execution.	packages/billing/src/lib/billing/billingEngine.ts, server/src/test/unit/billing/billingEngine.timing.test.ts
billing_cycle_alignment	Legacy timing selector persisted across migrations, models, APIs, actions, and UI.	See billingCycleAlignmentRefs in pass-0-source-inventory.json.
billing_timing	Advance-vs-arrears switch that currently changes which period is billed and how detail metadata is written.	packages/billing/src/lib/billing/billingEngine.ts, packages/billing/src/services/invoiceService.ts, server/src/test/integration/billingInvoiceTiming.integration.test.ts, contract line schemas and UI actions.
enable_proration	Current user-facing workaround for partial-period coverage; still propagated through write paths and tests.	packages/billing/src/lib/billing/billingEngine.ts, server/src/lib/api/services/ContractLineService.ts, contract wizard/dialog components, infrastructure billing tests.
Client billing frequency and generated client cycles	Current recurring clock for existing tenants and the main parity baseline.	shared/billingClients/createBillingCycles.ts, packages/billing/src/lib/billing/createBillingCycles.ts, packages/billing/src/actions/invoiceGeneration.ts, packages/billing/src/actions/billingCycleActions.ts.
Client anchor settings	Monthly / quarterly / semi-annual / annual anchor behavior that must be preserved under client cadence.	shared/billingClients/billingCycleAnchors.ts, packages/billing/src/lib/billing/billingCycleAnchors.ts, packages/billing/src/actions/billingCycleAnchorActions.ts, server/src/test/infrastructure/billing/invoices/clientBillingCycleAnchors.test.ts.
Assignment start / end dates	Current overlay used to trim or skip recurring work and to explain portal contract periods.	shared/billingClients/contractLines.ts, packages/client-portal/src/actions/account.ts, packages/billing/src/lib/billing/billingEngine.ts.

Recurring product migration seam inventory

• BillingEngine.calculateBilling(...) no longer applies a late-stage product-only applyProrationToPlan(...) branch; product coverage settlement now happens inside calculateProductCharges(...) after canonical due-period selection.
• calculateProductCharges(...) now resolves due product periods through the shared recurring timing helper, so servicePeriodStart and servicePeriodEnd come from canonical service-period selection rather than the enclosing invoice window.
• Product selection now excludes license-tagged catalog rows so product and license recurring families do not double-bill the same catalog item once the dedicated license path is live.
• Product tax now evaluates against the canonical due service-period end date, which keeps service-date semantics attached to the recurring work being billed instead of the enclosing invoice window.

Recurring license migration seam inventory

• BillingEngine.calculateBilling(...) no longer defers license coverage settlement to the generic late-stage applyProrationToPlan(...) branch; license coverage settlement now happens inside the shared recurring quantity-charge helper after canonical due-period selection.
• calculateLicenseCharges(...) now resolves due license periods through the same shared recurring timing helper used by fixed and product recurring charges, so period_start, period_end, servicePeriodStart, and servicePeriodEnd follow the canonical due service period.
• License selection now uses explicit service_catalog.item_kind = product plus is_license = true selection so the placeholder license query is gone, without changing the catalog/storage surface used by contract-line authoring.
• License tax and period metadata now evaluate from the canonical due service period, which keeps tax-date semantics aligned with the billed license period rather than the enclosing invoice window.

Persisted Date and Period Fields

These are the persisted fields that currently participate in recurring timing or billed-through semantics.

Persisted field(s)	Current table / surface	Current purpose	Evidence
client_billing_cycles.start_date, client_billing_cycles.end_date, billing_cycle_id	Client billing cycle storage and generation actions	Primary recurring invoice window for current client-cadence execution.	shared/billingClients/createBillingCycles.ts, packages/billing/src/actions/invoiceGeneration.ts, packages/billing/src/actions/billingCycleActions.ts
invoices.billing_period_start, invoices.billing_period_end	Invoice headers	Current grouping metadata; some readers still derive recurring meaning from it.	packages/billing/src/actions/invoiceGeneration.ts, server/src/lib/api/services/InvoiceService.ts, packages/billing/src/services/accountingExportInvoiceSelector.ts
invoice_item_details.service_period_start, invoice_item_details.service_period_end, invoice_item_details.billing_timing	Invoice detail persistence	Current detail-level recurring timing record for advance/arrears and export consumers.	packages/billing/src/services/invoiceService.ts, server/migrations/20251025120000_add_billing_timing_metadata.cjs, server/src/test/integration/billingInvoiceTiming.integration.test.ts
client_contract_lines.start_date, client_contract_lines.end_date	Assignment / recurring obligation activity window	Current overlay for partial-period starts, terminations, and portal display.	shared/billingClients/contractLines.ts, packages/client-portal/src/actions/account.ts, packages/billing/src/lib/billing/billingEngine.ts
Accounting export batch line service_period_start, service_period_end	Export read model	Flattened downstream representation used by adapters and export history readers.	packages/billing/src/repositories/accountingExportRepository.ts, packages/billing/src/adapters/accounting/xeroAdapter.ts, packages/billing/src/adapters/accounting/quickBooksOnlineAdapter.ts

Service-Period Consumer Inventory

Detail-level consumers already reading canonical-like period fields

• Invoice detail persistence and hydration:
  • packages/billing/src/services/invoiceService.ts
  • server/src/interfaces/billing.interfaces.ts
• Accounting exports:
  • packages/billing/src/services/accountingExportInvoiceSelector.ts
  • packages/billing/src/repositories/accountingExportRepository.ts
  • packages/billing/src/adapters/accounting/xeroAdapter.ts
  • packages/billing/src/adapters/accounting/quickBooksOnlineAdapter.ts
• Accounting integration tests:
  • server/src/test/integration/accounting/invoiceSelection.integration.test.ts
  • server/src/test/integration/accounting/batchLifecycle.integration.test.ts
  • server/src/test/integration/accounting/xeroLiveExport.integration.test.ts

Dependent flows that already rely on recurring timing, even if they do not always read detail fields directly

• Credits and reconciliation:
  • packages/billing/src/actions/creditActions.ts
  • packages/billing/src/actions/creditReconciliationActions.ts
  • server/src/test/infrastructure/billing/credits/*
• Prepayment and negative invoices:
  • packages/billing/src/actions/invoiceModification.ts
  • packages/billing/src/actions/manualInvoiceActions.ts
  • server/src/test/infrastructure/billing/invoices/prepaymentInvoice.test.ts
  • server/src/test/infrastructure/billing/invoices/negativeInvoiceCredit.test.ts

Downstream readers that still flatten or infer timing

• Client portal:
  • packages/client-portal/src/actions/account.ts
  • packages/client-portal/src/actions/client-portal-actions/client-billing.ts
  • packages/client-portal/src/components/account/BillingSection.tsx
  • These currently derive cycle and contract periods from client billing cycles or assignment dates, not authoritative recurring detail rows.
• Reporting:
  • packages/billing/src/actions/contractReportActions.ts
  • These reports currently summarize invoice dates, contract dates, or assignment dates. They are downstream consumers because service-period-first billing can change which date basis is authoritative.

Compatibility Boundaries for Explicitly Out-of-Scope Flows

Flow	Scope status in this PRD	Compatibility boundary during v1 recurring work
Time entry billing	Out of first hard cut	May continue using event-driven usage dates and existing billed-through assumptions; recurring refactors must not silently change it.
Usage-record billing	Out of first hard cut	Usage event windows remain their own truth source until a separate follow-on plan explicitly unifies them.
Materials / non-recurring charges	Out of first hard cut	Manual or one-off financial artifacts stay intentionally outside the canonical recurring schedule.
Manual-only invoice flows	Out of first hard cut for canonical schedule generation	Manual invoices must coexist with recurring detail periods but must not begin generating service periods on their own during v1.
Bucket usage metrics outside recurring bucket contract lines	Explicit follow-on / partial scope only	Bucket readers that rely on usage period tables stay on current semantics unless the line is part of recurring contract-backed billing in scope for this plan.

Explicit v1 exclusions by behavior

• Time entry billing stays event-driven in v1:
  • selection continues to use time_entries.start_time / time_entries.end_time against the invoice window
  • no persisted recurring service-period ledger is generated for time entries during this cut
  • billed-through, duplicate prevention, and credit behavior for time entry billing must remain on the current invoice-window/date-query model until a separate follow-on plan says otherwise
• Usage-record billing stays event-driven in v1:
  • selection continues to use usage-event dates and current end-exclusive overlap rules
  • no canonical recurring service periods are generated for ad hoc usage records during this cut
  • recurring service-period-first work must not silently change how usage events are grouped, billed-through, or credited outside explicit recurring bucket overlays already in scope
• Bucket behavior is split explicitly:
  • in scope now: recurring bucket contract lines where allowance periods, rollover, overage charging, and tax-date evaluation already depend on recurring timing semantics
  • still out of scope: generic bucket reporting, remaining-unit readers, and other bucket metrics that are not tied to recurring contract-backed billing selection
  • bucket usage period tables remain the source of truth for those out-of-scope readers until a follow-on plan deliberately unifies them

Follow-On Boundary — Full Time And Usage Unification

Recurring v1 does not silently expand into a general time-and-usage service-period ledger.

The explicit follow-on trigger is:

• recurring materialized service periods must already exist as stable future billing objects
• regeneration, override preservation, locking, and invoice linkage must already be proven on recurring contract-backed charges
• operator and finance workflows must already be able to explain canonical recurring periods without relying on invoice headers as the real timing source

Until that trigger is met:

• time-entry billing keeps time_entries.start_time / time_entries.end_time and current invoice-window overlap semantics as its authoritative selection model
• usage-record billing keeps usage-event timestamps and current billed-through semantics as its authoritative selection model
• credits, exports, and reconciliation continue to treat time and usage as event-driven financial artifacts instead of inferred service-period-ledger rows

The future follow-on plan must define, not assume:

• whether time and usage adopt their own persisted period ledger, a projection onto the recurring ledger model, or a different canonical period abstraction entirely
• how event timestamps map onto any canonical period without losing source-event truth
• how mixed event-driven and period-driven invoice readers, exports, and analytics stay explainable during coexistence
• what migration and rollback posture applies once time or usage stop being purely event-driven

Follow-On Boundary — Advanced Service-Period Ledger Extensions

Recurring v1 must stop at the first authoritative persisted service-period ledger that supports:

• generation within the v1 horizon
• explicit future-period edits
• regeneration with override preservation
• invoice linkage and billed-period locking

The following are not implicit v1 requirements and must stay follow-on work unless the first-cut ledger proves insufficient:

• long-range materialization horizons intended for years of future schedule projection
• archival or cold-storage pipelines for billed, superseded, or otherwise inactive service-period records
• performance-oriented denormalization such as ledger summary tables, read-side caches, or bulk projection views
• mass-repair or bulk backfill tooling aimed at reshaping the ledger beyond the rollout-safe correction flows defined for v1

Trigger this follow-on only when there is source-backed evidence that v1 cannot stay operationally safe without it, for example:

• regeneration or due-selection cost that cannot be contained within the v1 horizon policy
• support, dashboard, or export reads that remain too slow when pointed at the canonical ledger shape
• storage or retention requirements that force archival semantics beyond the initial billed-history retention model

When that follow-on starts, it must define:

• which record remains the canonical source of truth versus which projections are derivative
• how archival, compaction, or denormalization preserves invoice linkage, provenance, and auditability
• replay and repair behavior when derived ledger structures drift from canonical persisted periods
• rollback posture if tenants temporarily carry both the canonical ledger and performance-oriented derivatives

Follow-On Boundary — Persisted Recurring Execution Records

Recurring v1 includes typed execution-window identity, selector inputs, and retry keys. It does not automatically include a durable recurring-run ledger or persisted due-selection snapshots.

Keep the following out of v1 unless there is concrete operational evidence they are needed:

• persisted recurring run records keyed by execution-window identity
• durable selection snapshots for every due-work batch
• operator-facing replay history beyond current job metadata, audit logs, and canonical invoice/detail persistence
• repair tooling that depends on replaying a stored execution ledger instead of recomputing due work from current source truth

Trigger this follow-on only when:

• support or finance workflows cannot explain failed or retried recurring runs from current scheduler metadata
• contract-cadence execution creates ambiguity that transient logs cannot resolve safely
• replay/debug requirements become strong enough that transient execution identity is no longer sufficient

When that follow-on starts, it must define:

• the authoritative relationship between persisted execution records and canonical recurring service-period truth
• retention, replay, and repair rules for execution records that outlive transient jobs
• rollback posture when some tenants have durable recurring execution records and others still rely on transient scheduler metadata

Follow-On Boundary — Invoice-Schema Versioning

Recurring v1 keeps old-shape and new-shape invoice support additive. It does not automatically introduce a formal invoice-schema version boundary.

Keep the following out of v1 unless dual-shape support becomes long-lived enough to justify versioning:

• explicit invoice payload version markers
• consumer-specific schema negotiation for portal, export, reporting, or workflow payloads
• version pinning whose only purpose is to replace documented additive compatibility fields
• forced backfill or re-projection work done only to collapse dual-shape support into one versioned contract

Trigger this follow-on only when:

• dual-shape compatibility remains in place long enough to create meaningful maintenance risk
• downstream consumers need an explicit version handshake instead of additive compatibility fields
• reader rollback and coexistence rules become too implicit to govern safely without a versioned boundary

When that follow-on starts, it must define:

• the authoritative boundary between historical flat invoice payloads and canonical detail-backed invoice payloads
• whether versioning applies only at API boundaries or also to stored export, workflow, and audit projections
• migration and rollback posture when tenants or consumers still need both shapes during the transition

Parity Matrix

The minimum comparison matrix for client-cadence parity must cover the cross-product below before contract cadence is enabled:

Dimension	Required values
Billing frequency	monthly, quarterly, semi-annual, annual, weekly, bi-weekly
Due position	advance, arrears
Coverage shape	full period, mid-period start, mid-period end, no-coverage
Charge family	fixed recurring, recurring product, recurring license, recurring bucket / allowance where timing matters
Commercial modifiers	pricing schedules, discounts, custom contract rates, catalog rates
Financial overlays	purchase-order required, credits, prepayment, negative invoice follow-on
Downstream projections	invoice detail persistence, invoice preview rows, accounting exports, portal / report readers

The initial fixture set must include at least:

• monthly client cadence anchored mid-month, both advance and arrears
• quarterly, semi-annual, and annual client cadence with anchored month/day behavior
• first partial period and final partial period coverage
• fixed, product, and license recurring families
• pricing schedule override and discount applicability overlays
• PO-required recurring lines
• credit / prepayment / negative invoice scenarios that consume recurring timing

Parity Harness Contract

Pass-0 parity work needs an executable harness contract before cutover work begins. The harness does not require the service-period-first engine to exist yet, but it must define the comparison surface now.

Inputs

• a fixture builder that emits one recurring scenario without requiring invoice persistence as a side effect
• a legacy adapter that can run today's recurring path:
  • BillingEngine.calculateBilling(...)
  • generateInvoice(...) when persistence comparison is required
• a candidate adapter contract that will run the canonical service-period-first path with the same fixture input

Outputs to compare

• charge identity and family
• service-period boundaries
• due invoice window
• subtotal / tax / total
• invoice detail timing metadata
• downstream export row timing fields where applicable

Blocking vs non-blocking drift

Blocking drift:

• changed charge count
• changed service-period boundaries
• changed due-window selection
• changed amounts, discount coverage, tax basis, or invoice grouping
• changed export- or portal-visible timing meaning

Non-blocking drift during staged rollout:

• additional explainability metadata
• new provenance fields
• additive trace metadata used only for parity comparison or future service-period-first rollout

Staged Rollout Plan

The rollout order must keep client-cadence parity ahead of any contract-cadence capability. The intent is to reduce risk in layers instead of enabling a second recurring clock before the first cutover is proven.

Stage 1 — Additive groundwork only

• Ship shared recurring timing primitives, canonical detail persistence, and client-cadence parity scaffolding with cadence_owner defaulting to client.
• Keep contract cadence blocked on all live write paths; API, service, and UI surfaces may describe the future option, but they must not let tenants persist cadence_owner = contract yet.
• Treat any contract-cadence runtime support in this stage as dark code only. It may exist for tests and isolated selection logic, but it is not tenant-enabled behavior.

Stage 2 — Client-cadence parity comparison

• Run comparison mode for client-cadence recurring lines only.
• Exit criteria for this stage:
  • parity harness reports no blocking drift for fixed, product, license, bucket-in-scope, pricing, discount, PO, credit, and export-reader scenarios
  • DB-backed client-cadence sanity coverage passes for the representative monthly and longer-frequency fixtures called out in the PRD
  • contract cadence remains write-blocked while parity comparison is still required

Stage 3 — Client-cadence cutover

• Make the canonical service-period-first path the live execution path for existing client-cadence tenants.
• Continue treating client billing cycles as the only schedulable recurring run identity in production during this stage.
• Keep contract cadence blocked until client-cadence parity validation is signed off and the post-cutover sanity checks pass.

Stage 4 — Contract-cadence enablement

• Enable contract cadence only after Stage 3 has been stable long enough to prove parity, duplicate prevention, reader hydration, and downstream export behavior on the live client-cadence cutover path.
• When contract cadence is enabled, mixed-cadence selection and grouping must already be deterministic, and unsupported combinations must fail fast rather than falling back to client-cycle behavior.
• Scheduler identity, due-work job payloads, and retry semantics for contract-owned windows remain a separate rollout gate; they must be complete before contract cadence is tenant-writable.

Stage 5 — Cleanup and deletion

• Remove billing_cycle_alignment from live execution only after both client-cadence parity and contract-cadence rollout are validated.
• Remove dead timing helpers and duplicated proration branches only after the validation suite proves no live recurring path still depends on them.
• Preserve rollback posture long enough for historical flat invoices and canonical detail-backed invoices to coexist safely during reader migration.

Fixture Builder Contract

Fixture builders for parity and shared-domain tests should be composable rather than charge-family-specific:

• base client cadence fixture:
  • frequency
  • anchor / reference date
  • invoice window
  • cadence owner
• assignment overlay:
  • start date
  • end date
• recurring obligation overlay:
  • charge family
  • billing timing
  • proration / partial-coverage expectations
• commercial overlay:
  • pricing schedule
  • discount
  • custom rate vs catalog rate
  • PO requirement
• financial overlay:
  • credit
  • prepayment
  • negative invoice follow-on

This keeps the future parity harness useful even after fixed recurring, product recurring, and license recurring all share the same canonical timing primitives.