What
Today a quota resets on a calendar edge — midnight, the first of the month — at the same instant for everyone (ADR-138). Session quotas add the other shape: a window measured from when you first used it.
10,000 tokens, and your window resets 5 hours after you first used it.
Spelled Limit.reset_after, taking a datetime.timedelta, as an alternative to reset_schedule. Under ADR-137 a limit drips or resets, never both, so the two are mutually exclusive spellings of the reset half rather than two mechanisms that compose.
Settled semantics
- Idle-restarting, not tiling. The window is anchored by use, not by a repeating grid. A window ends at 14:00, the entity goes quiet, and a call at 20:00 starts a fresh window at 20:00 rather than landing inside one that has already elapsed. An entity can therefore restart its window by going idle.
- Rollover anchors; exhaustion does not. Crossing a boundary anchors the next window. Running out of tokens inside the current window leaves the anchor where it is, so an entity cannot restart its own window by spending it out.
- Parent and child anchor independently. A cascading child's window and its parent's window are separate state, consistent with how cascade already treats limits, shards and
disabled as per-entity state.
Prerequisite
Builds on the v0.14.0 quota machinery. A duration window is a quota under ADR-137 (refill_amount = 0), so it inherits that release's reset handling — in particular #587's reclaim-then-grant shard creation, which is what stops a shard split handing out net-new allowance mid-window.
Design and plan
Not restated here; the plan is the source of truth.
Sub-issues for the individual tasks can be cut when someone picks the work up — the plan carries them until then.
Refs #222
What
Today a quota resets on a calendar edge — midnight, the first of the month — at the same instant for everyone (ADR-138). Session quotas add the other shape: a window measured from when you first used it.
Spelled
Limit.reset_after, taking adatetime.timedelta, as an alternative toreset_schedule. Under ADR-137 a limit drips or resets, never both, so the two are mutually exclusive spellings of the reset half rather than two mechanisms that compose.Settled semantics
disabledas per-entity state.Prerequisite
Builds on the v0.14.0 quota machinery. A duration window is a quota under ADR-137 (
refill_amount = 0), so it inherits that release's reset handling — in particular #587's reclaim-then-grant shard creation, which is what stops a shard split handing out net-new allowance mid-window.Design and plan
Not restated here; the plan is the source of truth.
docs/plans/2026-09-15-session-quotas-plan.md(PR 📝 docs(limiter): plan session quotas as Limit.reset_after #596) — the implementation plan: task breakdown, decisions table, and the anchoring rule stated precisely.docs/plans/2026-09-15-rolling-session-windows-analysis.md— the design analysis the plan draws on.Sub-issues for the individual tasks can be cut when someone picks the work up — the plan carries them until then.
Refs #222