spec: the temporal and located companion declarations (issue #410)

docs/hive_layout.md

@@ -906,7 +906,8 @@ Raster (pull-NN) pipelines write the same tree with **windowed `(time, cells)`
 leaves**: one vanilla zarr v3 leaf per **(shard, window)** unit at
 `shard_leaf_path(root, shard, window=label)`, each carrying leaf-local `time`
 (int64 microseconds with CF attrs by default, or `uint64` mortie toc words
-carrying the spec §8 `temporal` declaration and no CF attrs under
+carrying the spec §8.1 `temporal` declaration at `shape: "coordinate"`
+and no CF attrs under
 `output.time_encoding: toc` — which the shipped Sentinel-2 config sets, issue
 #443) and `morton` (packed u64 words) as the sole cell
 coordinate — `cell_ids` (NESTED) rides only the `emit_cell_ids` transition hatch

docs/ragged_layout.md

@@ -25,7 +25,7 @@ migration is metadata-only.
 
 ## Why the attrs are the contract
 
-The element interpretation (dtype, inner shape, the located sibling's name)
+The element interpretation (dtype, inner shape, the companion siblings' names)
 is self-describing in the array's attrs — the
 [spec §1.2 block](specification.md#12-the-ragged-attrs-block) — so a reader
 decodes exactly what the writer declared rather than hardcoding a dtype or
@@ -37,6 +37,38 @@ layout. A vlen array without a well-formed `element` declaration is **not** a
 zagg ragged array — pre-issue-209 CSR stores are a hard break, and the readers
 raise a pointed error rather than decode under a guessed layout.
 
+## Why the companion words are declared, not implied
+
+A companion sibling holds **packed words**, not self-describing scalars — a
+morton cell in `{field}_locations`, a toc time in `{field}_times` — so
+nothing in a uint64 array says which grammar produced it. The spec's
+word-typed declaration
+([§8](specification.md#8-zagg-toc1), instantiated for space in
+[§9](specification.md#9-zagg-located1)) closes that: a `{spec, shape,
+grammar}` block, stamped by the writer on the array that *holds* the words,
+with the payload array carrying only the *binding* to it. One rule follows
+from that split and is worth stating plainly here: **read the declaration off
+the sibling you bound, never off the payload.**
+
+Two properties the family is designed around:
+
+- **Absence is never a refusal.** Every located store written before §9
+  carries no `located` key, and reads exactly as
+  [§2.2](specification.md#22-the-location-channel) always said it did. The
+  declaration adds self-description and the shape vocabulary; it never
+  reinterprets a byte.
+- **Composition gates on `{shape, grammar}`** — the same discipline the
+  [§2.0 `weights`](specification.md#20-the-weights-declaration) declaration
+  established, and for the same reason: merging two arrays whose words mean
+  different things yields an array that means neither.
+
+The binding for the temporal sibling is a **sibling attrs key** (`times`),
+not a key inside the versioned `ragged` block, matching `weights` and for the
+same reason — the block is retired wholesale under
+[`zagg-ragged/2`](specification.md#6-zagg-ragged2), and a key outside it
+survives that metadata-only migration untouched. `locations` predates that
+ruling and stays where it is; the asymmetry is history, not design.
+
 ## Why the wire framing is golden-pinned
 
 Round-trip tests pass under *any* self-consistent encoding, so only a fixed
@@ -85,7 +117,9 @@ store). The sharded 2-GET count is pinned by
 A [hive](hive_layout.md) leaf zarr is exactly this layout scoped to one shard.
 Under the leaf's `{group}` path a reader finds the ragged vlen array with its
 versioned `ragged` attrs, the sibling `morton` coordinate array (chunk
-identity), and, for a located field, the `{field}_locations` sibling — all
+identity), and the field's companion siblings — `{field}_locations` for a
+located field, `{field}_times` for one carrying the per-centroid temporal
+companion ([spec §8.3](specification.md#83-shape-per-centroid)) — all
 sharded as one whole-leaf `ShardingCodec` object (one stored span). So a hive
 product is **read one leaf at a time**: open the leaf store
 (`hive.shard_leaf_path`) and pass the same `field` path to the readers. The
@@ -114,7 +148,8 @@ and hive-leaf writers are pinned to store byte-identical per-cell payloads
   then the one inner chunk holding the cell), never the whole shard object. An
   out-of-range index raises `IndexError` naming the valid range (no negative-index
   wrap); an absent cell returns the zero-length `(0, *inner_shape)` array. Works
-  on the `{field}_locations` sibling too.
+  on the `{field}_locations` and `{field}_times` siblings too — both are
+  themselves `zagg-ragged/1` uint64 arrays.
 - **Sub-leaf subtree read** (`subtree=` on the sweep readers —
   [issue #351](https://github.com/englacial/zagg/issues/351)) — the nested
   cells axis makes the subtree below any ancestor one **contiguous cell span**

docs/signal_strata.md

@@ -31,8 +31,11 @@ is **committed at ingest** and carried through the store in three pieces:
 
 The shipped template is `zagg/configs/atl03_tdigest_strata_healpix.yaml` —
 **located strata is the default**: both digest fields carry `location:
-leaf_id`, so each centroid stores its order-29 morton word (an exact photon
-position at weight 1) in the `{field}_locations` sibling arrays. The
+leaf_id`, so each centroid stores a morton word in the `{field}_locations`
+sibling arrays — an order-29 **point** word (the photon's reported position,
+no area claim) for an unmerged centroid, the deepest common ancestor of its
+members' words once centroids merge; a reader decodes kind and order from
+each word, never from the centroid's weight (spec §2.2/§9.1). The
 five confidence columns are read from the single 2-D `signal_conf_ph` dataset
 via the per-variable `column` selector (`{path: ..., column: k}` — the
 variable analogue of the structured-filter `column`); the shared path is