BucketWindows

The reader's zone, resolved into days and instants by the caller.

SPEC §7 makes a bucket a pure function of (due, lifecycle, priority, today, zone), and this store carries no timezone database - so a caller that wants buckets computes the edges and sends them, exactly as [TaskQuery::overdue] already does for the overdue split. Nothing here is guessed, defaulted or derived from a server clock: a store that decided what today meant would be wrong by morning and wrong in another country, which is the whole reason [ADR-287] refused to persist a bucket.

Six edges rather than the two a first sketch has, because the bucket function has two horizons and each of them has to be stated twice:

- a day edge, for dues stored as a calendar date or a floating wall clock - those carry a day that needs no zone to read; - an instant edge, for dues stored as a zoned instant, whose day is ZonedDateTime::date_in(zone) and therefore the caller's to compute.

The two are compared each in its own terms and never folded together ([ADR-183] rule 5). Calendar days here are inclusive last days - the day Next ends on, and the day Upcoming ends on - because that is how the domain function reads (within seven days, within thirty); the instants are the moments those days end, which is the same edge said the other way.

[ADR-183]: ../../../docs/decisions/ADR-201-225.md#adr-206-timemodel--koru-has-three-temporal-types-not-one-with-a-nullable-timezone [ADR-287]: ../../../docs/decisions/ADR-276-300.md#adr-287-taskread--the-tasks-query-is-a-second-question-asked-of-the-one-read-model

Type object

Shape

Field	Type	Description
todayrequired	string	Today in the reader's zone, strictly `YYYY-MM-DD`. A due on or before it is `Today` - overdue lands in Today, because an overdue task is the answer to what should I do next.
horizonrequired	string	The last day of `Next`, strictly `YYYY-MM-DD` - `today + 7` under the shipped rule, but the caller's arithmetic, not this store's.
upcoming_horizonrequired	string	The last day of `Upcoming`, strictly `YYYY-MM-DD` - `today + 30` under the shipped rule. Beyond it is `Later`, which is why one horizon is not enough to place a row.
today_ends_msrequired	integer (int64)	The instant [`today`](Self::today) ends at in the reader's zone, epoch-ms UTC: the edge a zoned due is compared against for `Today`.
horizon_ends_msrequired	integer (int64)	The instant [`horizon`](Self::horizon) ends at, epoch-ms UTC.
upcoming_ends_msrequired	integer (int64)	The instant [`upcoming_horizon`](Self::upcoming_horizon) ends at, epoch-ms UTC.
now_msrequired	integer (int64)	Now, epoch-ms UTC - what makes a zoned due overdue, beside [`today`](Self::today), which is what makes a dated one overdue. It splits the counts and never selects a row: an overdue task is in `Today` either way, and this is what tints it.
min_next_priorityrequired	string	The priority an undated task must reach to be `Next` rather than `Later` - a priority token, `high` under SPEC §7's rule that priority ≥ High replaces the original proposal's Important. On the wire rather than compiled in, for the reason every other window here is: it is a product rule the caller states, and a store that knew it would be a second place to change it.

Example

{
  "today": "string",
  "horizon": "string",
  "upcoming_horizon": "string",
  "today_ends_ms": 0,
  "horizon_ends_ms": 0,
  "upcoming_ends_ms": 0,
  "now_ms": 0,
  "min_next_priority": "string"
}

The contract has no example values, so example bodies are generated from each schema: every field is shown with a placeholder of its type.

Generated from contract version 1. Last updated November 12, 2026.