Recurring Periods
How bounded recurring payment streams are proposed, posted, and protected from duplicates.
Recurring periods
A recurring payment stream is bounded: it is defined by a total amount, a period count, and a period type, and it ends once the period count is reached. O2A draws a sharp line between a recurring period that is merely due and one that has been made financially real: a due period is a proposal, and it only becomes fact when a Ledger Event is posted for it.
How It Works
A stream carries a total amount, a period count, and a period type — MONTH, QUARTER, SEMI_ANNUAL, or YEAR. The per-period amount is the total divided across the period count, and the stream ends once the period count is reached: 100,000 over 4 QUARTER periods pays out in four quarterly installments; 100,000 over 12 MONTH periods pays out in twelve monthly ones. This bounded model is shared by recurring Purchase and recurring Investment streams. The standard fixes the total, the count, and the period type; how any rounding remainder is distributed across the periods is the implementation's concern.
Each period carries a stable label — YYYY-MM for months, YYYY-Qq for quarters, YYYY-Hh for half-years, YYYY for years — anchored to the calendar period start, not to the exact activation timestamp. When a period comes due it surfaces as a recurring period proposal, which is not yet a Ledger Event. Posting that period materializes exactly one Ledger Event for it: a recurring period is financially real only when its Ledger Event exists. The optional lastPostedPeriod cursor records the most recent period label already proposed or posted, so duplicate protection keyed to the period label ensures the same period is never posted twice.
An Investment contract may also carry a disbursement schedule: several disbursements, each either a lump sum or a bounded recurring stream, and each released either at a fixed date or by milestone acceptance.
Statements
These statements fix the recurring-period contract:
- A recurring payment stream is bounded.
- A recurring payment stream has a total amount, a period count, and a period type.
- Recurring period types include MONTH, QUARTER, SEMI_ANNUAL, and YEAR.
- The per-period amount is the total amount divided across the period count.
- A recurring payment stream ends once its period count is reached.
- The bounded recurring model is shared by recurring Purchase and recurring Investment.
- Rounding-remainder distribution across periods is an implementation concern.
- A recurring period label is anchored to the calendar period start.
- A recurring period proposal represents a due period before financial materialization.
- Recurring period posting creates one Ledger Event per due period.
- A recurring period is financially real only when its Ledger Event exists.
- The lastPostedPeriod cursor records the most recent proposed or posted period label.
- An Investment disbursement is a lump sum or a bounded recurring stream, released at a fixed date or by milestone acceptance.
Why It Matters
This separation keeps the source-truth rule intact for repeating payments. Because every stream is bounded, its total commitment is known up front and it can never run past the agreed amount. Future or matured-but-unposted periods stay proposals, so they never inflate a balance or P&L before money has actually moved. Per-period duplicate protection means re-running the stream cannot double-post the same period — financial history stays append-only and correct.