Recurring series

fixed_day_of_month: always around the same day. month_end: at month end, whatever the number of days; a direct debit on 31 January, 28 February and 31 March is a single pattern. last_business_day: the last business day, a common case for salaries. business_day_adjusted: a nominal day moved off the weekend (Saturday → Friday, Sunday → Monday). We do not model public holidays: neither French, nor target, nor banking holidays. A holiday shift is absorbed by the window's tolerance, not recognised; claiming to know a calendar we do not have would be worse than ignoring it. fixed_weekday: always the same day of the week. flexible_calendar_window: one occurrence per period, with no stable day. unknown: nothing identifiable.

A constant per anchor type, or a linear formula on the spread of days for fixed_day_of_month and flexible_calendar_window. 0 for unknown. A 0.33 fixed_day_of_month and a 0.3 flexible_calendar_window cannot be compared, and flexible_calendar_window changes its rule with the cadence (a constant 0.3 when weekly, 1 - etendue/10 when monthly).

Always non_calibree in this version, and that is a constraint, not a convention: the value is a vocabulary in the database, the columns that carry it reference it, and a guard rejects any literal outside the vocabulary at every producer. When a real calibration exists, it will enter through a declared migration, together with the corpus that supports it.

Stable. It derives from what does not change (workspace, family, counterparty, direction, currency), never from the latest occurrence or the current descriptor. One more occurrence does not create another series.

recurring_payment says "this payment comes back", and nothing more: rent and a loan instalment are this too. subscription is a stronger claim and requires its own signal; without it, the answer stays recurring_payment. Likewise, recurring_income covers a pension, a benefit and rent received; salary_series is a specialisation of it, not a synonym.

The more general type that this one specialises, if there is one.

Two occurrences make a series emerge, three can establish it, a single one never. broken is computed at read time: a series becomes late through the mere passage of time, with no write taking place.

Read on the calendar, not in bare days: 31 January and 28 February are one month apart, and a salary on the last business day shifts.

Exact equality is not required: an electricity bill varies, and so does a salary. Amounts in minor units, as a string, never a JSON number.

Optional, and that is the point. Absent as long as the series is not established or the cadence is irregular: returning a date on the basis of two weak observations would pass it off as a forecast. This is not a forecasting API.

This is not a probability: it is the share of corroborating signals present out of those this type can produce. And it is not the same number as relationships[].match_strength: same name, different denominator, different signals. Five heterogeneous criteria out of five: calendar cadence, fixed or narrow amount, at least three occurrences, known entity, specialised type. They only add up here.

Always non_calibree in this version, and that is a constraint, not a convention: the value is a vocabulary in the database, the columns that carry it reference it, and a guard rejects any literal outside the vocabulary at every producer. When a real calibration exists, it will enter through a declared migration, together with the corpus that supports it.

The signals the series rests on. value is a string or an integer depending on the code (occurrences carries an integer).

An axis different from status. status says how strongly we believe this is a series; lifecycle says what is happening to it now. A very well-established series may have stopped collecting, and a fresh series may be perfectly alive. And no state is concluded from an absence without coverage: if the source was not observed completely over the expected window, the state is unknown, not late. "I saw nothing" never becomes "nothing happened": that is the difference between a client that stopped sending and a subscription that stopped collecting.

active: the expected occurrence has arrived, or is not yet due. late: an occurrence is missing and the account was under observation. inactive: several consecutive occurrences are missing under complete observation; the series is no longer collecting, and we do not know why. ended: reserved for explicit terminal evidence. No accumulation of absences produces this state: a payment that stops may be a cancellation, a suspension, an expired card or a failed collection, and we do not guess which. unknown: we cannot conclude, and reason says why.

A window, not a date. A salary lands around the last business days, a SEPA direct debit around the 5th. Returning an exact instant would be a precision we do not have, and you would believe it.

The half-width of the window, in days. Larger = less precise. Comes from the anchor type, raised to the floor of the series family.

The anchor type that produced the window.

true if the tolerance was raised to the family floor (5 days for a subscription, 6 for a salary, 7 otherwise).

The counter only advances under complete coverage. Absent when nothing is expected, which is not the same ignorance as "we were not looking".

not_required: no due date has closed, nothing had to be observed. complete: every source of the series was covered over the expected window; a miss is a miss. incomplete: at least one source was not; the absence proves nothing, state is unknown. unknown: the sources are unknown or too numerous to be checked.

The same number as cadence_detail.strength, returned here so that the lifecycle can be read on its own. It is not a second score.

The same object as calendar_pattern (class anchor_stability), returned here for the same reason; { type: unknown } when no anchor was inferred. Absent when no occurrence is expected. duplicate_of: series[].calendar_pattern; it is not a second score.

Present for ended: the terminal evidence that produced it.

Present only when the identity of the series has been corrected, to say why state is unknown: this is not economic ignorance, it is that the verdict now belongs to the successors. The full identity state is read in identity, which is an axis in its own right; this field is only a pointer, and it never takes the value current.

Always non_calibree in this version, and that is a constraint, not a convention: the value is a vocabulary in the database, the columns that carry it reference it, and a guard rejects any literal outside the vocabulary at every producer. When a real calibration exists, it will enter through a declared migration, together with the corpus that supports it.

A third axis, and it mixes with neither status nor lifecycle. status says how strongly we believe this is a series; lifecycle says what is happening to it economically; identity says whether its name is still the right one. A series can debit every month and still have changed identity because we worked out that it was in fact two flows, or two halves of one. And a series_id is never rewritten or silently reused. When we correct, the old name remains, marked superseded, and it carries its successors.

current: this name is the current name of this flow. superseded: this name has been replaced by an identity correction. It stays valid as a historical reference (it will not disappear), but future occurrences will carry the name of its successors.

After a split there is no single redirect, and that is why this field returns a list. If we discover that a series was mixing two flows, neither successor is "the continuation" of the old one: half of the old one's occurrences are missing from each of them. Electing a canonical one would be comfortable and wrong.

split: this identity was covering several, and each now has its own. merge: this identity and another were the same flow; both are replaced by a new identity.

The evidence codes that authorised the correction. Never an internal score, never a row identifier.

One after a merge, several after a split. Never empty when status is superseded.

The way back, and it matters as much as the other one. The identities this one replaces. Without it, the old series_id you had stored would no longer correspond to anything you receive, and you would have no way to make the link. Empty for a series that was not born of any correction.

Where this occurrence came from, and where it is now. When an identity is corrected, the occurrence changes series: without this block, you would have no way to relate the series_id you had stored to the one you receive. You never have to rebuild the graph yourself.

The series this occurrence was attached to the first time. Equal to current_series_id for as long as no correction has taken place.

The successive moves, from oldest to most recent. Empty for an occurrence that has never moved.

The first day WE Observed this series, not the day it started. A series may have been running for five years while we have only been observing it for three months. There is deliberately NO started_at field: we do not know it.

true: our observation begins with the first known occurrence, so the series may have started before us and nothing will show it. false: the first known occurrence predates the start of our observation, so its beginning is observed, not assumed.

How often the event repeats, and nothing else. The cadence is deduced from the progression of calendar periods, not from gaps in days: three consecutive months are three consecutive months, whether the gaps are 28, 30 or 31 days. And a 28-day recurrence is not monthly: it falls once a month for eleven months, then twice, and its day moves back with every cycle. We do not call it monthly: this version has no cadence for it, and irregular_recurring is better than a false monthly. strength is the share of expected cycles that carry an occurrence. It is not a probability.

0 = no calendar hypothesis retained, not "weak".

Always non_calibree in this version, and that is a constraint, not a convention: the value is a vocabulary in the database, the columns that carry it reference it, and a guard rejects any literal outside the vocabulary at every producer. When a real calibration exists, it will enter through a declared migration, together with the corpus that supports it.

Where, within each period, the series tends to fall: a different question from cadence. A series can be squarely monthly while floating between the 1st and the 6th: without this field, "monthly" would read as "the same day every month", which is false for most real series. It is also what gives expected_next_window its width: a direct debit always on the 5th justifies three days, a rent that floats justifies eight. Applying the same window to both would declare a perfectly normal series "late".

fixed_day_of_month: always around the same day. month_end: at month end, whatever the number of days; a direct debit on 31 January, 28 February and 31 March is a single pattern. last_business_day: the last business day, a common case for salaries. business_day_adjusted: a nominal day moved off the weekend (Saturday → Friday, Sunday → Monday). We do not model public holidays: neither French, nor target, nor banking holidays. A holiday shift is absorbed by the window's tolerance, not recognised; claiming to know a calendar we do not have would be worse than ignoring it. fixed_weekday: always the same day of the week. flexible_calendar_window: one occurrence per period, with no stable day. unknown: nothing identifiable.

A constant per anchor type, or a linear formula on the spread of days for fixed_day_of_month and flexible_calendar_window. 0 for unknown. A 0.33 fixed_day_of_month and a 0.3 flexible_calendar_window cannot be compared, and flexible_calendar_window changes its rule with the cadence (a constant 0.3 when weekly, 1 - etendue/10 when monthly).

Always non_calibree in this version, and that is a constraint, not a convention: the value is a vocabulary in the database, the columns that carry it reference it, and a guard rejects any literal outside the vocabulary at every producer. When a real calibration exists, it will enter through a declared migration, together with the corpus that supports it.

What we can see, and what we cannot. insufficient means "our memory is too short to judge", never "there is no older occurrence". And there are two memories, which must not be confused. raw_days (30) says how long the transaction remains readable; derived_days (400) says how long what we have learnt about a series outlives it. A purged transaction stays purged (this API never brings it back), but the series remembers that it happened. That is what makes a monthly cadence confirmable when January's transaction no longer exists. observed_days is what we actually saw: a client reading "monthly / sufficient" can check that the conclusion does not come from thirty days.

Lifetime of the raw transaction. Past this delay it is physically deleted and nothing brings it back.

Lifetime of the series memory, counted from the latest occurrence. Without a new occurrence, the derived state is physically deleted when it expires, and a later occurrence opens a new series.

The span actually observed, from the first to the last known occurrence.

Kept for compatibility: identical to raw_days.

Answers one question only: can the cadence be believed? Not "do we know when it started", which is the next field.

Says why first_occurrence_bounded has the value it has.

A different question from sufficiency, and one that used to be confused with it. true: our observation of this series begins with the first occurrence we know of, so it may have started before us, and nothing will ever show it. false: the first known occurrence predates the start of our observation, so the beginning is observed, not assumed. A history import returns false; a series discovered as transactions arrive returns true.