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

Recurring Service-Period Provenance

Purpose

F234 defines the authoritative provenance model for persisted recurring service-period records.

The goal is not just to label a row as "generated" or "edited". The persisted provenance payload must also explain:

• whether the current row still matches generated cadence rules or now diverges from them
• why the row exists in its current shape
• whether it replaced an earlier persisted record version
• whether a background materialization/regeneration run produced it or whether the change came from an explicit operator action

This keeps later edit, regeneration, repair, and support tooling work on one shared provenance vocabulary instead of ad hoc strings.

Authoritative Type Surface

The shared provenance contract now lives in:

• packages/types/src/interfaces/recurringTiming.interfaces.ts
  • RECURRING_SERVICE_PERIOD_PROVENANCE_REASON_CODES
  • GeneratedRecurringServicePeriodReasonCode
  • UserEditedRecurringServicePeriodReasonCode
  • RegeneratedRecurringServicePeriodReasonCode
  • RepairRecurringServicePeriodReasonCode
  • IRecurringServicePeriodRecordProvenance
• shared/billingClients/recurringServicePeriodProvenance.ts
  • isRecurringServicePeriodProvenanceReasonCode(...)
  • isRecurringServicePeriodProvenanceDivergent(...)
  • validateRecurringServicePeriodProvenance(...)

The type is intentionally discriminated by kind so field requirements cannot drift silently.

Provenance Kinds

Kind	Meaning	Diverges from source cadence rules?
generated	First materialized version produced directly from current source rules.	No
user_edited	Operator changed a future period explicitly and the new row supersedes the generated or previously edited row.	Yes
regenerated	System replaced a prior future row because source recurrence rules or cadence inputs changed.	Yes
repair	Administrative or integrity repair row used to correct a broken ledger state explicitly.	Usually yes; treat as exceptional.

isRecurringServicePeriodProvenanceDivergent(...) is the v1 helper for this policy: every kind except generated represents a row that no longer reflects untouched rule-derived cadence output.

Field Requirements By Kind

Kind	reasonCode	sourceRunKey	supersedesRecordId
generated	Required. Must be one of the generated reason codes.	Required. Materialization should remain traceable to the generating run.	Must be null/absent. The first generated row does not supersede anything.
user_edited	Required. Must explain the operator-visible divergence.	Optional. A user edit may happen outside the background generation run path.	Required. An edit must point at the row it replaced.
regenerated	Required. Must explain which rule/input change forced replacement.	Required. Regeneration must stay traceable to the background run or explicit rebuild action.	Required. Regeneration replaces an earlier future row.
repair	Required. Must explain the repair class.	Optional. A repair may or may not be tied to a formal run.	Optional. Some repairs replace a prior row; others only correct metadata in place through a new revision.

The shared validator enforces the same baseline literally:

• Generated provenance requires sourceRunKey
• Generated provenance must not supersede an earlier record
• User-edited provenance requires supersedesRecordId
• Regenerated provenance requires sourceRunKey
• Regenerated provenance requires supersedesRecordId

Reason-Code Catalog

generated

• initial_materialization
• backfill_materialization

user_edited

• boundary_adjustment
• invoice_window_adjustment
• activity_window_adjustment
• skip
• defer

regenerated

• source_rule_changed
• billing_schedule_changed
• cadence_owner_changed
• activity_window_changed
• backfill_realignment

repair

• integrity_repair
• invoice_linkage_repair
• admin_correction

These reason codes are deliberately narrow. They explain why a persisted row differs without yet committing v1 to richer audit payloads or UI verb taxonomies that belong in later edit and permissions work.

Operational Meaning

The persisted provenance contract now answers the first support-grade questions directly:

• Did the row come from untouched rule output or from a later override?
• If it changed, was the change user-authored, regeneration-driven, or repair-driven?
• What class of change happened?
• Which prior row did this one supersede?
• Which run key generated or regenerated it when a background process was involved?

This is the minimum v1 provenance needed before:

• F238-F239 regeneration behavior
• F245-F249 edit and conflict semantics
• F253 permissions/audit requirements
• F268 operator runbook work

Deliberate Non-Goals For F234

This checkpoint does not yet define:

• actor identity, approval metadata, or full audit payloads for user edits
• the UI verbs or form contracts for editing future periods
• repair authorization policy
• whether repairs are always new revisions versus metadata corrections on existing rows

Those remain sequenced behind the later edit, permission, and runbook passes.