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

Recurring Service-Period Regeneration

Purpose

F238 and F239 define the first regeneration algorithm for persisted future recurring service periods.

The v1 rule is intentionally conservative:

• untouched generated future rows may be refreshed when source recurrence rules change
• user-edited or repair-driven future rows must not be silently overwritten
• replaced untouched rows become superseded
• newly regenerated rows keep the logical slot identity by reusing the prior periodKey and incrementing revision

Authoritative Helper Surface

The shared v1 regeneration helper now lives in:

• shared/billingClients/regenerateRecurringServicePeriods.ts
  • regenerateRecurringServicePeriods(...)

Regeneration Rules

The helper applies the following slot-order policy to future active rows on one schedule:

1. Sort existing active rows and new candidate rows by service-period order.
2. Preserve override rows instead of overwriting them. Override rows are currently:
   • provenance.kind = user_edited
   • provenance.kind = repair
   • lifecycle states edited, locked, or billed
3. For untouched generated rows:
   • if the candidate row is equivalent, keep the existing row as-is
   • if the candidate row changed, write a new regenerated row that:
     • reuses scheduleKey
     • reuses periodKey
     • increments revision
     • points supersedesRecordId at the prior row
   • mark the prior row as superseded
4. If an untouched existing future row no longer has any candidate slot, supersede it.
5. If new candidate slots remain after existing future rows are exhausted, keep them as new generated rows.

Override-Preservation Rule

The first-cut override rule is explicit:

• regeneration must not silently replace user-edited future rows
• regeneration must not silently replace repair rows
• candidate rows that would have occupied those preserved slots are discarded until a later explicit conflict-handling flow exists

This keeps v1 safe before the later conflict-resolution work in F249.

Deliberate Non-Goals For F238/F239

This checkpoint does not yet define:

• operator-facing conflict queues when preserved overrides and new source rules diverge materially
• bulk conflict resolution
• per-field merge behavior between a user edit and a regenerated candidate

Those remain later follow-on work after the first preservation-safe regeneration path.