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

Recurring Service-Period Backfill

F244 defines the parity-safe initialization rule for tenants that already have recurring invoice history before the persisted service-period ledger exists.

This checkpoint is still additive:

• it initializes future persisted rows for existing recurring obligations
• it does not rewrite historical invoices or synthesize historical persisted rows just to mirror already-billed coverage
• it does define how billed-history boundaries fence off future backfill so the later runtime cutover can start from a clean future ledger

Historical Boundary

Backfill now resolves one explicit historical cutoff:

• legacyBilledThroughEnd
• or, if persisted billed rows already exist, the latest servicePeriod.end among billed / linked records

shared/billingClients/backfillRecurringServicePeriods.ts treats that date as the billed-history boundary.

The rules are:

• candidate periods ending on or before the boundary are skipped
• candidate periods starting on or after the boundary remain eligible for insertion
• a candidate that overlaps the boundary is rejected instead of being silently clipped or split

That overlap rejection is deliberate. Backfill must not invent partial historical rewrites just to make a future ledger fit.

Initialization Policy

Future candidates are normalized onto explicit backfill provenance:

• provenance.kind = generated
• provenance.reasonCode = backfill_materialization
• sourceRuleVersion and sourceRunKey reflect the backfill run, not the earlier materializer placeholder

This keeps initialized rows distinguishable from first-day greenfield materialization while still saying they are untouched generated schedule rows.

Existing Future Rows

Backfill must also be safe when a tenant already has some persisted future rows from an earlier partial rollout or retry.

The v1 rule is:

• billed historical rows are retained unchanged
• equivalent future rows are retained unchanged
• untouched generated future rows that disagree with the current candidate schedule are regenerated with reasonCode = backfill_realignment
• user-edited, repair, locked, and billed rows still follow the existing preservation rules from RECURRING_SERVICE_PERIOD_REGENERATION.md

This means backfill can reconcile future schedule drift without mutating billed history or trampling explicit overrides.

Deliberate Boundary

This checkpoint still does not define:

• invoice-time due selection from persisted rows
• historical persisted-row backfill for already-billed invoices
• UI or API listing/editing surfaces for future persisted periods
• bulk repair tooling for overlap conflicts discovered during backfill

Those remain sequenced behind F245-F267.