small fixes 2026-08-05: refuse a sub-second windowing epoch (issue #390)

docs/hive_layout.md

@@ -167,7 +167,9 @@ output:
   need `bounds.temporal` to enumerate generative windows.
 - **Stamps carry the truth, the manifest the schema** (D15): each windowed
   leaf's commit stamp records its `window` label and the ACTUAL written
-  `time_range` as ISO-8601 UTC strings; the root `coverage.moc` summary
+  `time_range` as ISO-8601 UTC strings (both ends at whole-second
+  granularity, which narrows the tail by up to 1 s — see
+  [The commit stamp](#the-commit-stamp)); the root `coverage.moc` summary
   carries the run's time-range union (cache, regenerable); temporal *extent*
   never lives in the manifest, which stays write-once. Appending a new year
   to a `yearly` store adds leaves the schedule already describes — no
@@ -194,7 +196,13 @@ same second (say `12:00:01.0Z` → `12:00:01.4Z`) the window dispatches as an
 empty `ge x`/`lt x` pair, so it is rejected — the point form is the spelling
 for one-second intent. A sub-second range that *straddles* a second boundary
 (`12:00:01.9Z` → `12:00:02.1Z`) is still valid; it renders to the one-second
-window its truncated bounds describe. On the raster path
+window its truncated bounds describe. The `epoch` is the one time value held
+to a stricter rule ([issue #390](https://github.com/englacial/zagg/issues/390)):
+it too renders at whole-second granularity, but it defines *every* window
+conversion rather than one edge of one window, so a sub-second `epoch` is
+**refused** rather than truncated — `2018-01-01T00:00:00.5Z` would shift every
+boundary by half a second, invisibly. Declare it at second precision. On the
+raster path
 ([issue #247](https://github.com/englacial/zagg/issues/247)) membership is
 the acquisition's STAC `datetime`: `time_field` is optional (fixed to
 `datetime`) and the `epoch`/`scale`/`units` conversion knobs are rejected.
@@ -613,6 +621,26 @@ A windowed leaf's stamp ([Time windows](#time-windows-morton-hive2)) declares
 `spec: "morton-hive/2"` and adds `window` (the label) plus `time_range` — the
 actual `[t_min, t_max]` written, as ISO-8601 UTC strings.
 
+**Reader caveat — `t_max` floors, so the recorded range can end up to 1 s
+early.** Both ends render through `windows.iso_utc`'s whole-second
+granularity (`isoformat(timespec="seconds")`), so each truncates to the second
+*containing* it. On `t_min` that is harmless: the recorded start is at or
+before the true first observation. On `t_max` it is not — a last observation
+at `12:00:00.7` is recorded as `12:00:00`, so the closed `[t_min, t_max]` is
+a slight **under**-estimate of the extent written, not an envelope around it.
+**A consumer that prunes leaves on the stamp must treat `t_max` as inclusive
+with 1 s of slack** (test the query against `t_max + 1 s`); pruning on the
+recorded value alone can skip a leaf that genuinely holds data in the queried
+interval. Sub-second inputs reach the rendering on both pipelines — a float
+`delta_time` column on the point path (`windows.iso_time_range`), a
+millisecond-bearing STAC `datetime` on the raster path
+(`processing/raster._us_iso`). The narrowing is recorded rather than fixed
+(ruled on [PR #398](https://github.com/englacial/zagg/pull/398)): no in-tree
+consumer prunes on `time_range` — every use is a union into the regenerable
+root `coverage.moc` summary or the overview rollup — and rendering the range
+outward instead would change the bytes of a stamp field external readers
+decode.
+
 ## Coverage
 
 Where the data is, declared hierarchically

src/zagg/config.py

@@ -7,7 +7,7 @@
 import re
 from collections.abc import Callable
 from dataclasses import asdict, dataclass, field
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from importlib import resources
 from typing import Any, NotRequired, TypedDict
 
@@ -1436,9 +1436,30 @@ def _validate_windowing(config: PipelineConfig) -> None:
             "delta_time)"
         )
     try:
-        _windows.parse_utc(epoch)
+        parsed_epoch = _windows.parse_utc(epoch)
     except ValueError as e:
         raise ValueError(f"output.windowing.epoch: {e}") from e
+    # Validate the RENDERED epoch, not the parsed one (issue #390). get_windowing
+    # canonicalizes through windows.iso_utc (timespec="seconds"), so a sub-second
+    # epoch parses clean here and is then silently truncated at the one place it
+    # is consumed — shifting EVERY window conversion by the dropped fraction. The
+    # predicate calls the renderer and round-trips it rather than repeating the
+    # truncation rule, so the two cannot drift (the PR #367 pattern).
+    # The message renders parsed_epoch rather than repr-ing the declared value:
+    # yaml.safe_load types an ISO timestamp scalar as a datetime, which parse_utc
+    # passes through, so repr would hand the author a stdlib constructor call
+    # instead of the value they wrote. The drop is reported in microseconds
+    # because that is exactly what iso_utc discards and nothing else: an integer,
+    # so no scientific notation for the 1 µs case, and never negative.
+    rendered_epoch = _windows.iso_utc(parsed_epoch)
+    if _windows.parse_utc(rendered_epoch) != parsed_epoch:
+        raise ValueError(
+            f"output.windowing.epoch {parsed_epoch.isoformat()!r} carries sub-second "
+            f"precision that the canonical whole-second rendering drops: it is "
+            f"recorded as {rendered_epoch!r}, which would shift every window "
+            f"conversion by {parsed_epoch.microsecond} µs — declare the epoch at "
+            f"second precision"
+        )
     scale = block.get("scale") or "utc"
     if scale not in _windows.EPOCH_SCALES:
         raise ValueError(
@@ -3510,6 +3531,16 @@ def _is_nan_fill(meta: dict) -> bool:
     return isinstance(fill, float) and np.isnan(fill)
 
 
+#: The raster branch's fixed windowing epoch (issue #247, ratified): raster
+#: window membership is the acquisition's STAC ``datetime``, already an ISO-8601
+#: UTC instant, so the encoding is the identity one and is never author-declared.
+#: Held as an *instant*, not a spelling — ``get_windowing`` renders it through
+#: ``windows.iso_utc``, the same renderer its point branch canonicalizes the
+#: declared epoch with, so the two branches cannot write different spellings of
+#: the same instant if that rendering ever changes (issue #390).
+_UNIX_EPOCH = datetime(1970, 1, 1, tzinfo=timezone.utc)
+
+
 def get_windowing(config: PipelineConfig) -> dict | None:
     """The normalized temporal windowing declaration, or ``None`` (issue #246).
 
@@ -3520,17 +3551,25 @@ def get_windowing(config: PipelineConfig) -> dict | None:
         {"schedule", "time_field", "epoch", "scale", "units", "windows"}
 
     ``epoch`` and explicit-window boundaries are canonicalized to ISO-8601
-    UTC strings; ``windows`` is ``None`` except for ``schedule: explicit``,
-    where a ``{label, timestamp}`` point entry is desugared to its second-wide
-    range (issue #355) so the normalized list is uniformly ``{label, start,
-    end}``.
+    UTC strings. The ``epoch`` canonicalization is lossless on any config that
+    passed ``validate_config`` — ``timespec="seconds"`` would otherwise truncate
+    a sub-second epoch and shift every window conversion, so
+    :func:`_validate_windowing` refuses one outright (issue #390). A config
+    built without that check (``load_config_from_dict``, a hand-rolled worker
+    payload) still truncates here; explicit bounds truncate either way,
+    documented on :func:`_explicit_window_bounds`. ``windows`` is ``None``
+    except for ``schedule: explicit``, where a ``{label, timestamp}`` point
+    entry is desugared to its second-wide range (issue #355) so the normalized
+    list is uniformly ``{label, start, end}``.
     On the raster branch (``reader: raster``) ``time_field`` is the fixed STAC
-    ``datetime`` and ``epoch``/``scale``/``units`` are hardcoded to the
-    Unix-epoch UTC-seconds encoding any ISO instant normalizes to, rather than
+    ``datetime`` and ``epoch``/``scale``/``units`` are fixed to the Unix-epoch
+    UTC-seconds encoding any ISO instant normalizes to, rather than
     canonicalizing a declared ``epoch`` off the block (``_validate_windowing``
-    rejects those conversion knobs there). The same dict feeds the manifest
-    temporal block (:func:`zagg.hive.build_manifest`) and the dispatch fan-out,
-    so the two can never disagree.
+    rejects those conversion knobs there); the fixed epoch is still rendered
+    through the same ``windows.iso_utc`` as the declared one, so the branches
+    cannot spell one instant two ways (issue #390). The same dict feeds the
+    manifest temporal block (:func:`zagg.hive.build_manifest`) and the dispatch
+    fan-out, so the two can never disagree.
     """
     from zagg import windows as _windows
 
@@ -3554,11 +3593,16 @@ def get_windowing(config: PipelineConfig) -> dict | None:
         # #247, ratified): the manifest records the resolved field plus the
         # fixed encoding any ISO-8601 UTC instant normalizes to (UTC seconds
         # since the Unix epoch). _validate_windowing rejects the conversion
-        # knobs on raster configs, so nothing here can disagree with it.
+        # knobs on raster configs, so nothing here can disagree with it. The
+        # epoch is *rendered* through iso_utc rather than spelled out, for the
+        # reason _validate_windowing's #390 guard calls the renderer instead of
+        # restating its truncation rule: a literal here would be a copy of
+        # iso_utc's output format, free to drift from the spelling the point
+        # branch below gives the very same instant (see _UNIX_EPOCH).
         return {
             "schedule": block["schedule"],
             "time_field": "datetime",
-            "epoch": "1970-01-01T00:00:00+00:00",
+            "epoch": _windows.iso_utc(_UNIX_EPOCH),
             "scale": "utc",
             "units": "seconds",
             "windows": declared,

tests/test_hive_windows.py

@@ -7,6 +7,9 @@
 on the mortie spec page (mortie#62).
 """
 
+import re
+from datetime import datetime, timezone
+
 import pytest
 
 from zagg import hive
@@ -41,6 +44,21 @@ def _windowed(cfg, schedule="yearly", **over):
     return cfg
 
 
+def _raster_windowed(schedule="yearly"):
+    """A minimal raster + hive + windowing config (issue #247)."""
+    c = default_config("atl06")
+    c.data_source = {
+        "reader": "raster",
+        "bands": {"red": {"asset": "red", "dtype": "uint16"}},
+    }
+    c.aggregation = {}
+    c.output["grid"] = {"type": "healpix", "parent_order": 6, "child_order": 12}
+    c.output["store_layout"] = "hive"
+    c.output["windowing"] = {"schedule": schedule}
+    validate_config(c)
+    return c
+
+
 # ── config block (phase 2) ───────────────────────────────────────────────────
 
 
@@ -234,6 +252,96 @@ def test_bad_epoch_rejected(self, cfg):
         with pytest.raises(ValueError, match="ISO-8601"):
             validate_config(cfg)
 
+    @pytest.mark.parametrize(
+        "epoch, declared, rendered, shift",
+        [
+            (
+                "2018-01-01T00:00:00.5Z",
+                "2018-01-01T00:00:00.500000+00:00",
+                "2018-01-01T00:00:00+00:00",
+                "500000",
+            ),
+            # The fraction survives a non-UTC declaration: the guard compares
+            # INSTANTS, not spellings, so it is the dropped fraction that
+            # refuses this — never the offset (Python accepts sub-minute
+            # offsets, and a whole-second one of those round-trips clean).
+            (
+                "2018-01-01T05:30:00.001+05:30",
+                "2018-01-01T00:00:00.001000+00:00",
+                "2018-01-01T00:00:00+00:00",
+                "1000",
+            ),
+            # The smallest representable violation — a microsecond-precision
+            # timestamp pasted in from a data file — reads as an integer count,
+            # not as 1e-06.
+            (
+                "2018-01-01T00:00:00.000001Z",
+                "2018-01-01T00:00:00.000001+00:00",
+                "2018-01-01T00:00:00+00:00",
+                "1",
+            ),
+            # The production path is datetime-typed, not str: yaml.safe_load
+            # resolves an ISO timestamp scalar to an aware datetime and
+            # windows.parse_utc passes it through, so the message must render
+            # the author's value rather than repr a stdlib constructor call.
+            (
+                datetime(2018, 1, 1, 0, 0, 0, 500000, tzinfo=timezone.utc),
+                "2018-01-01T00:00:00.500000+00:00",
+                "2018-01-01T00:00:00+00:00",
+                "500000",
+            ),
+        ],
+    )
+    def test_subsecond_epoch_rejected(self, cfg, epoch, declared, rendered, shift):
+        # The epoch parses at full precision but is CONSUMED through
+        # windows.iso_utc (timespec="seconds"), so a sub-second epoch used to
+        # validate clean and then shift every window conversion by the dropped
+        # fraction (issue #390 — the PR #367 validate-vs-render mismatch class).
+        # The message quotes the declared instant, the rendered value and the
+        # shift, so the refusal is tied to what get_windowing would actually emit.
+        _windowed(cfg, epoch=epoch)
+        with pytest.raises(
+            ValueError,
+            match=rf"epoch {re.escape(repr(declared))} carries sub-second precision.*"
+            rf"recorded as {re.escape(repr(rendered))}.*shift every window "
+            rf"conversion by {shift} µs",
+        ):
+            validate_config(cfg)
+
+    @pytest.mark.parametrize(
+        "epoch",
+        [
+            "2018-01-01T00:00:00Z",
+            "2018-01-01T00:00:00+00:00",
+            # Naive input is taken AS UTC (windows.parse_utc), and a whole-second
+            # offset-bearing epoch still round-trips — only the fraction is lost.
+            "2018-01-01T00:00:00",
+            "2018-01-01T05:30:00+05:30",
+        ],
+    )
+    def test_whole_second_epoch_accepted(self, cfg, epoch):
+        # The guard is exactly "the rendering is lossless", not "the declaration
+        # is spelled canonically": every whole-second spelling stays legal and
+        # canonicalizes to the same instant.
+        _windowed(cfg, epoch=epoch)
+        validate_config(cfg)
+        assert get_windowing(cfg)["epoch"] == "2018-01-01T00:00:00+00:00"
+
+    def test_schedule_none_keeps_subsecond_epoch(self, cfg):
+        # The guard sits AFTER the ``schedule: none`` early return, and must:
+        # an inert block is equivalent to an absent one (test_absent_is_none),
+        # get_windowing returns None, and the epoch is never rendered — so
+        # there is no conversion to shift and nothing to refuse.
+        cfg.output["store_layout"] = "hive"
+        cfg.output["windowing"] = {
+            "schedule": "none",
+            "time_field": "delta_time",
+            "epoch": "2018-01-01T00:00:00.5Z",
+            "scale": "gps",
+        }
+        validate_config(cfg)
+        assert get_windowing(cfg) is None
+
     def test_bad_scale_and_units(self, cfg):
         _windowed(cfg, scale="tt")
         with pytest.raises(ValueError, match="scale"):
@@ -590,6 +698,20 @@ def test_raster_windowing_validates_on_hive(self):
         validate_config(c)
         assert get_windowing(c)["time_field"] == "datetime"
 
+    def test_raster_epoch_renders_through_iso_utc(self):
+        # Issue #390: the raster epoch is FIXED (issue #247) but not SPELLED —
+        # get_windowing renders it with windows.iso_utc like every other
+        # instant it emits. Asserting against the renderer's own output rather
+        # than a literal is the point: this stays true through a change to
+        # iso_utc's precision or offset form, and only a re-introduced literal
+        # in config.py can break it.
+        from zagg import windows as _windows
+
+        c = _raster_windowed()
+        assert get_windowing(c)["epoch"] == _windows.iso_utc(
+            _windows.parse_utc(datetime(1970, 1, 1, tzinfo=timezone.utc))
+        )
+
 
 # ── manifest temporal block + spec bump (phase 2) ────────────────────────────
 
@@ -630,6 +752,21 @@ def test_yearly_manifest_declares_v2_temporal(self, cfg):
             "append_policy": "new-window",
         }
 
+    def test_raster_and_point_epochs_spell_one_instant_alike(self, cfg):
+        # The drift the rendered raster epoch prevents (issue #390): both
+        # branches of get_windowing feed the SAME manifest field, so a given
+        # instant has to reach it spelled one way. A point config declaring
+        # the Unix epoch and a raster config (whose epoch is fixed to it)
+        # therefore must produce byte-identical temporal epochs — this is the
+        # assertion a re-introduced literal on either branch breaks, since a
+        # literal is free to disagree with whatever iso_utc emits.
+        _windowed(cfg, epoch="1970-01-01T00:00:00Z", scale="utc")
+        validate_config(cfg)
+        point = hive.build_manifest(self._grid(cfg), windowing=get_windowing(cfg))
+        rcfg = _raster_windowed()
+        raster = hive.build_manifest(self._grid(rcfg), windowing=get_windowing(rcfg))
+        assert raster["temporal"]["epoch"] == point["temporal"]["epoch"]
+
     def test_explicit_manifest_carries_windows_and_retemplate_policy(self, cfg):
         _windowed(cfg, schedule="explicit")
         m = hive.build_manifest(self._grid(cfg), windowing=get_windowing(cfg))