Rule
An on-demand raster exposes a period control only when its Channel declares a validated period_selection capability. annual-range-v1 defines the physical consecutive year range, whether the provider supports cumulative cutoffs, and a fallback default.
The Map Connection stores the bounded subset of years shown on its map timeline and exactly one mode: Annual or Cumulative. A connection never exposes both modes to viewers at once. New connections snapshot the Channel fallback into a versioned provider-neutral query, so later catalog changes do not alter existing maps. The current slider position remains viewer-local and keyed by Layer plus Channel; it does not mutate the connection query, Layer style, Channel metadata, or palettes.
Request boundary
The browser sends one semantic period_id: an exact declared year, through-YYYY for the declared start through a selected cutoff, or all for the full cumulative range. The UI presents one bounded year slider in the mode published by the Layer. It never sends provider query names or arbitrary start/end values. The tile proxy validates access to the bound Layer, Channel, and period, then translates that identifier into the provider-specific request. Cache identity includes the period automatically through the tile URL. When an encoded provider tile keeps all periods in one immutable image, Channel may additionally declare a validated value_filter. applied_by=browser lets the renderer mask the declared raw pixel channel. applied_by=proxy requires the authorized proxy to return an already masked numeric tile; the renderer then only applies Layer presentation. Changing period_id creates a new immutable raster frame and uses atomic source-loaded cutover. Zooming or panning never changes period identity and must not recreate the source.
The Map Connection may select cumulative mode only when the provider declares meaningful cumulative cutoffs. GeoLama does not merge or sum raster pixels in the browser. A local or proxy exact/through-year mask is allowed only when its pixel channel, year mapping, and execution boundary are provider-declared and validated; arbitrary client expressions are not accepted. The end-year cutoff uses canonical all, preserving the provider's full cumulative rendering. A cumulative-only dataset without exact periods does not receive a misleading year selector.
Map configuration
Channel settings display capability metadata but do not choose what a specific map shows. Add data and Layer settings → Data edit the Map Connection query; Display settings do not. The connection may narrow the timeline range inside the physical Channel bounds and choose one supported mode. The cumulative range always starts at the dataset's declared physical start; narrowing the timeline changes the available cutoff years, not the scientific accumulation baseline.
Checklist
cleanup, cache separation, and the fallback period.
document the pixel channel and execution boundary, and test both exact and cutoff masks visually across native pyramid levels.
- Declare physical provider bounds in Channel and the visible range in Map Connection.
- Validate the capability in the client render contract and the database.
- Validate
period_idagain in the authorized tile proxy. - Store one mode per Map Connection and keep Annual and Cumulative semantics distinct.
- Verify connection persistence, local cursor persistence, invalid preference
- For encoded time-series tiles, verify exact and cumulative upstream bytes,