Module plan 

Pure window/unit planning for faucet backfill — boundary parsing, range chunking (timezone/DST-correct), ${backfill.*} token substitution, and the stable range hash the progress marker is keyed by. No I/O.

Structs

BackfillUnit

One independent, resumable slice of the backfill range.

Constants

MAX_UNITS

Hard ceiling on planned units — a tiny --window over a huge range is a config error, not a workload.

WARN_UNITS

Above this many units a loud warning is emitted (but planning proceeds).

Functions

parse_boundary

Parse a --from / --to boundary: RFC3339 (2026-06-01T00:00:00Z) or a bare date (2026-06-01, interpreted as midnight in tz). A date that falls in a DST gap resolves to the earliest valid instant.

parse_window

Parse a --window duration: 45s, 30m, 6h, 1d, 1w (or a bare integer = seconds). Must be positive.

plan_windows

Chunk [from, to) into contiguous half-open windows of window (the last window truncated at to). window: None = the whole range as one unit. Window arithmetic is absolute (instants), so units never gap or overlap — including across DST transitions; boundaries are re-rendered in tz so ${now.*} tokens see local wall-clock time.

range_hash

Deterministic 64-bit FNV-1a hash of the range descriptor, hex-encoded. Keys the progress marker so --resume finds the same backfill across process restarts (std’s DefaultHasher is randomly seeded — unusable).

substitute_unit_tokens

Substitute ${backfill.*} tokens in every string leaf of value: start / end (RFC3339), start_date / end_date (YYYY-MM-DD, local), start_unix / end_unix (epoch seconds), unit (the unit id). An unrecognized ${backfill.*} token is a typo — typed error.