Raster time axis encodes as toc words (spec §8, S2 first)

deployment/aws/lambda_handler.py

@@ -838,10 +838,13 @@ def _handle_setup(event: Dict[str, Any]) -> Dict[str, Any]:
             import numpy as np
 
             from zagg.processing.raster import emit_raster_template
+            from zagg.time_axis import time_axis_dtype, time_encoding
 
             store = open_store(event["store_path"], **_output_store_kwargs(event))
             grid = from_config(config)
-            times_us = np.asarray(event["times_us"], dtype=np.int64)
+            # The wire carries plain ints; the cast is the config's declared
+            # time encoding (spec §8) — a toc word does not fit int64.
+            times_us = np.asarray(event["times_us"], dtype=time_axis_dtype(time_encoding(config)))
             if times_us.size == 0:
                 # A zero-timestep template is degenerate: the arrays get a
                 # 0-length time axis no worker can slab-write into.

docs/specification.md

@@ -2,8 +2,8 @@
 
 This page is the **normative record** of zagg's byte-level store conventions:
 the ragged vlen-bytes layout, the t-digest payload bytes, the packed
-composition word, the pyramid/overview declarations, and the O11 content-hash
-recipe. It exists so an independent reader
+composition word, the pyramid/overview declarations, the O11 content-hash
+recipe, and the temporal declaration on a time coordinate. It exists so an independent reader
 ([moczarr](https://github.com/espg/moczarr)) can decode a zagg store from this
 page and the committed conformance fixtures alone — no zagg import, no
 reverse-engineering of `grids/base.py`
@@ -55,7 +55,7 @@ text marked *informative* explains or motivates and binds nothing.
   explicit succession clause; readers add revisions, they never drop them.
 - The committed conformance fixtures (§7) are part of the contract: a reader
   implementation that reproduces the fixtures' expected decoded values and
-  content hashes conforms to §1–§3 and §5. zagg's own test suite asserts the
+  content hashes conforms to §1–§3, §5 and §8. zagg's own test suite asserts the
   same expectations (`tests/test_spec_conformance.py`), so the spec, the
   fixtures, and the shipping reader cannot drift apart silently.
 
@@ -68,6 +68,7 @@ Contents:
 5. [O11 content hashes](#5-o11-content-hashes)
 6. [`zagg-ragged/2` — the typed `vlen-ndarray` revision](#6-zagg-ragged2)
 7. [Conformance fixtures](#7-conformance-fixtures)
+8. [`zagg-toc/1` — the temporal declaration](#8-zagg-toc1)
 
 ---
 
@@ -1397,19 +1398,20 @@ stores may deliberately stay `/1` for vanilla-zarr openability).
 **Status: contract.** The committed stores under
 [`tests/data/spec/`](https://github.com/englacial/zagg/tree/main/tests/data/spec)
 are part of this specification: a reader implementation that reproduces
-their expected decoded values and content hashes conforms to §1–§3 and §5.
-They are generated by
+their expected decoded values and content hashes conforms to §1–§3, §5 and
+§8. They are generated by
 [`tools/generate_spec_fixtures.py`](https://github.com/englacial/zagg/blob/main/tools/generate_spec_fixtures.py)
 through zagg's **production write path** (manifest, sharded leaf template,
 dense + ragged writes, coverage sidecar, commit stamp), so writer↔spec
 drift fails zagg's own suite (`tests/test_spec_conformance.py`) on
 whichever side moved. moczarr vendors the same fixtures for its parity
 gates (espg/moczarr#19/#20).
 
-Four tiny single-shard hive stores plus one manifest-only declaration, all
+Five tiny single-shard hive stores plus one manifest-only declaration, all
 on the same deliberately small geometry — shard order 4, inner-chunk order
 5, cell order 6 (16 cells, K = 4 inner chunks of 4 cells), sharded (the
-hive default):
+hive default; `raster_toc/` is the one exception — a `(time, cells)`
+product is never sharded, §8/#247):
 
 - **`minimal/`** — one *unlocated* digest field (`h_tdigest`) plus `count`.
   The smallest thing that is a conforming store.
@@ -1461,6 +1463,20 @@ hive default):
   arrives with the sweep-side fixtures of
   [#384](https://github.com/englacial/zagg/issues/384).
 
+- **`raster_toc/`** — the §8 temporal declaration surface: one raster
+  `(time, cells)` hive leaf whose `time` coordinate is `uint64` toc words
+  carrying `temporal: {"spec": "zagg-toc/1", "shape": "axis", …}` and no CF
+  `units`/`calendar` attrs, beside `morton` and two band arrays. Its axis
+  mixes both word variants deliberately — one single-item timestep encoded
+  as an exact **timestamp** word and two multi-item acquisition groups
+  encoded as **range** words — so a reader that implements only one variant
+  fails a §7 fixture. `raster_toc.expected.json` records the words as
+  decimal strings (JSON numbers cannot carry `uint64` faithfully) together
+  with the `(start, end)` nanoseconds a conforming decode yields and the
+  real acquisition spans they must contain, which is the §8 conservative
+  containment claim pinned on committed bytes. The other four fixtures,
+  which carry no `temporal` key anywhere, are the absent-key ⇒ legacy pin.
+
 `minimal/` and `kitchen_sink/` pin the layout edge cases a reader must
 handle (`column/`'s leaf is `minimal/`'s, so it pins them again): inner chunk
 ordinal 2 is **empty** (absent from the shard index — the §1.5 sentinel, and
@@ -1506,9 +1522,9 @@ itself on both sides, which is also the only mechanism that catches a future
 zagg↔moczarr divergence (neither side's fixture can: espg/moczarr#23).
 
 **Conformance criteria for an external reader**: decode every ragged array
-per §1–§2 and the composition array per §3, reproducing the expected
-decoded values exactly (byte-exact float32/uint64 — no tolerance), and
-reproduce `content_hashes` per §5. zagg's own suite additionally decodes
+per §1–§2, the composition array per §3, and the declared time coordinate
+per §8, reproducing the expected decoded values exactly (byte-exact
+float32/uint64 — no tolerance), and reproduce `content_hashes` per §5. zagg's own suite additionally decodes
 the shard objects with **spec-text-only** decoders (struct + zstd, no zagg
 read path) to prove the byte recipes in §1.4/§1.5 are sufficient on their
 own.
@@ -1521,3 +1537,106 @@ principle as §5). In the committed D20 sidecar
 `cells_with_data` are pinned: `timestamp`, `zagg_version`, `run_id` and the
 run counters are **informative provenance**, they churn on every
 regeneration, and conformance never asserts them.
+
+---
+
+## 8. `zagg-toc/1`
+
+**Status: contract** ([issue #443](https://github.com/englacial/zagg/issues/443)
+— the first shape of the temporal series,
+[#410](https://github.com/englacial/zagg/issues/410)).
+
+An array that carries **time values** declares how to read them under the
+**`temporal`** attrs key on that array. The key is spec-owned: the writer
+stamps it from the config's declared encoding, never author-transcribed
+(§1.2's reserved-key discipline, extended to the time coordinate).
+
+**An absent `temporal` key MUST be read as the legacy encoding** — signed
+`int64` microseconds since `1970-01-01T00:00:00` UTC, self-described by the
+CF `units`/`calendar` attrs the writer stamps beside it. Every store written
+before this revision is conformant verbatim, no byte rewritten, and a reader
+MUST NOT refuse a store for lacking the declaration.
+
+```json
+"temporal": {
+  "spec": "zagg-toc/1",
+  "shape": "axis",
+  "epoch": "1850-01-01T00:00:00",
+  "timescale": "gps-continuous",
+  "quantum_start_ns": 2147483648,
+  "quantum_end_ns": 4294967296
+}
+```
+
+- **`spec`** — the convention revision. Readers MUST strict-check it: an
+  unknown or future revision raises, never half-parses under a guessed
+  layout.
+- **`shape`** — where the words sit relative to the store's cells.
+  **`"axis"`** is the only value this revision defines: the declaring array
+  **is** the time coordinate of a `(time, cells)` product — one word per
+  timestep, row-aligned with the leading axis of every `(time, cells)` array
+  in the same group. The discriminator exists so a later per-cell or
+  per-centroid temporal companion declares itself in *this* grammar rather
+  than a parallel one; a reader MUST refuse a `shape` it does not implement.
+- **`epoch`** / **`timescale`** — the word grammar's fixed time origin and
+  time scale. They are properties of the grammar, not writer choices; a
+  reader MUST refuse a declaration whose values differ from the grammar it
+  implements (a differing epoch is a future revision, not a re-basing hint).
+- **`quantum_start_ns`** / **`quantum_end_ns`** — the range variant's
+  outward-rounding grids in nanoseconds, echoed so a reader can state its
+  own decode tolerance without hard-coding the grammar's constants.
+
+### The word grammar is mortie's
+
+A `zagg-toc/1` value is a mortie **toc word** (temporal order coverage): one
+`uint64` that is a tagged union of an exact nanosecond **timestamp** and an
+outward-rounded, conservative **range**, on a continuous, leap-free,
+GPS-aligned timescale with a fixed `1850-01-01T00:00:00` epoch. The bit
+layout, the flag position, the unsigned sort order, and the semilattice
+merge law are normative in mortie's
+[`mortie.toc` reference](https://espg.github.io/mortie/api/toc/) and its
+decision ledger ([espg/mortie#175](https://github.com/espg/mortie/issues/175)),
+and are **not restated here** — exactly as §2.2 defers the morton word's
+layout to mortie's specification §1/§4. What follows is zagg's half of the
+contract.
+
+### 8.1 `shape: "axis"`
+
+**Contract.**
+
+- The declaring array's element type is `uint64`, one word per timestep.
+- A timestep whose real acquisition is a single instant MUST be encoded as a
+  **timestamp** word, exact to the nanosecond; a timestep covering a real
+  interval MUST be encoded as a **range** word whose envelope conservatively
+  contains that interval. A conforming writer therefore never widens an
+  instant into a range, and never narrows a real interval into an instant.
+- Words are stored in **ascending acquisition order** — the order the time
+  axis has always had, and the order the `(time, cells)` slabs were indexed
+  by. Unsigned word order is order by conservative encoded *start*, so a
+  plain ascending sort of the stored words reproduces the stored order
+  except where two timesteps fall in one start quantum, where the grammar's
+  own tiebreak decides. A reader MUST NOT assume the stored words are
+  strictly increasing.
+- Decoding to wall time yields **`(start, end)`** per timestep: for a
+  timestamp both bounds are its exact instant; for a range `end` is the
+  envelope's **exclusive** upper bound. A reader that must present one
+  instant per timestep SHOULD present `start`, and MUST NOT present a
+  midpoint as if it were the observation time — the midpoint of a
+  conservative envelope is not an observation.
+- Temporal window selection is the grammar's overlap predicate applied to
+  the stored words directly: it over-reports by at most one quantum at a
+  window edge and **never under-reports**, so a selection is a conservative
+  superset of the timesteps whose real acquisition intersects the window.
+
+**Composition.** Time axes compose only between **matching declarations** —
+`zagg-toc/1` with `zagg-toc/1`, legacy with legacy (an absent key is legacy
+for this rule too). A concatenation across encodings would produce an axis
+whose values mean two different things, so a reader or writer joining two
+stores' time axes MUST refuse a mismatch. This is a *join* rule only:
+reading either store on its own is always legal.
+
+**What this revision does not cover** (informative). Per-cell and
+per-centroid temporal companions — the other shapes of #410 — are not
+defined here; they will arrive as further `shape` values under this same
+`spec` marker and this same word grammar. Nothing in §8 constrains the
+`(time, cells)` band arrays themselves, which are unchanged.

src/zagg/config.py

@@ -263,6 +263,13 @@ def validate_config(config: PipelineConfig) -> None:
     # validated before the kind branch, like credentials_provider above.
     _validate_worker(config)
 
+    # The time coordinate's encoding (spec §8, issue #443) is checked on every
+    # pipeline kind, like the two blocks above: the value is only meaningful
+    # where a time coordinate exists, so declaring it elsewhere is a typo
+    # worth catching at submission rather than a knob that silently does
+    # nothing.
+    _validate_time_encoding(config)
+
     ptype = get_pipeline_type(config)
     if ptype != "spatial":
         _validate_temporal_config(config)
@@ -757,6 +764,24 @@ def _validate_temporal_config(config: PipelineConfig) -> None:
     _validate_collection_options(config)
 
 
+def _validate_time_encoding(config: PipelineConfig) -> None:
+    """Validate ``output.time_encoding`` (spec §8, issue #443).
+
+    The knob declares how the ``(time, cells)`` time coordinate is encoded —
+    legacy int64 microseconds (absent/default) or mortie toc words. It is
+    raster-only: the spatial and temporal pipelines write no time coordinate,
+    so a declaration there would be inert.
+    """
+    from zagg.time_axis import DEFAULT_TIME_ENCODING, time_encoding
+
+    encoding = time_encoding(config)
+    if encoding != DEFAULT_TIME_ENCODING and (config.data_source or {}).get("reader") != "raster":
+        raise ValueError(
+            f"output.time_encoding: {encoding!r} applies to raster (time, cells) "
+            f"products only — this pipeline writes no time coordinate (spec §8)"
+        )
+
+
 def _validate_raster_config(config: PipelineConfig) -> None:
     """Validate a raster (pull-NN) pipeline config (issue #218).
 

src/zagg/configs/sentinel2_l2a.yaml

@@ -5,7 +5,7 @@
 # cell-ID joins are direct) takes the source pixel nearest its center --
 # dense by construction, exact uint16 DNs. Reflectance = DN * 1e-4 - 0.1,
 # recorded as CF scale_factor/add_offset attrs and never applied to the
-# stored data. Timesteps are datatakes (time_key), not item datetimes:
+# stored data. Timesteps are datatakes (time_key, toc-encoded), not item datetimes:
 # adjacent MGRS tiles of one datatake are a single (time, cells) slab, with
 # the 9,840 m tile overlap resolved by nearest-tile-center ownership.
 #
@@ -32,6 +32,12 @@ data_source:
   anonymous: true
 
 output:
+  # Time axis as mortie toc words (spec §8, issue #443): a datatake is a
+  # ~seconds-long acquisition whose adjacent MGRS tiles are sensed seconds
+  # apart, so the honest coordinate value is a conservative RANGE -- which
+  # int64 microseconds cannot state and a toc word can. Output-defining: a
+  # store born on toc is a different product from a legacy-axis one.
+  time_encoding: toc
   grid:
     type: healpix
     parent_order: 11