pub struct Regeneration {
pub mechanic: String,
pub rate: Option<RegenerationRate>,
}Expand description
A stated replenishment mechanic for a window.
Present only where an upstream describes how the quota returns. It exists
because the alternative — projecting a replenishment onto resets_at — makes
a continuously refilling pool indistinguishable from a hard cutoff, and the
projection is unrecoverable once published.
Fields§
§mechanic: StringWhich mechanic the upstream describes: cliff, drip, or unstated.
PACING DEPENDS ON THIS AND THE THREE ANSWERS DIFFER SHARPLY. A rate alone cannot separate them: “1,000,000 units per 720h” describes both a lump arriving on one instant and a steady accrual every hour, and the two give opposite answers about headroom on day 14.
cliff— the whole amount lands atresets_at, and accrual before that instant is exactly zero. A consumer treating this as gradual believes it has partial headroom when it has none.drip— the quota accrues continuously atrate, so headroom grows between reads and an exhausted pool becomes usable again without any reset event.unstated— the upstream states that quota replenishes but nothing establishes which mechanic. No pacing claim exists: display the rate, never derive headroom from it. Same contract asPoolFunding::UnknownandPoolBasis::Unstated, for the same reason — an honest arm keeps a producer from guessing to satisfy the type.
A plain String rather than an enum, and REQUIRED rather than optional.
String because this is an observability wire: a variant added later must
not make an old consumer drop the record that reports a state it has never
seen. Required because an optional discriminator invites exactly the
inference this field exists to prevent — with no value present, a consumer
picks one, and the picker has less evidence than the producer.
Treat an unrecognised value as unstated: render it, pace on nothing.
rate: Option<RegenerationRate>The stated replenishment rate, when the upstream gives one.
Absent means the mechanic is described without a quantity — a real and
common shape (“credits refresh monthly” with no amount). Absence here says
nothing about mechanic, which stays authoritative.