# Map sub-spec — The 4D cell key

Normative refinement of [SPEC §2](../SPEC.md). Reference: `map-schema::CellKey`.

A tile is addressed by four orthogonal axes. Equality is component-wise; the
field order below is the **canonical sort order** the tileset directory MUST
follow (SPEC §4).

```
CellKey = (s2: S2CellId, alt: AltBand, time: TimeBucket, lod: Lod)
```

## 1. Horizontal — `s2: u64`

An S2 cell identifier. S2 imposes a Hilbert ordering on the sphere: numerically
adjacent ids are spatially adjacent, so a viewport's cells occupy a
near-contiguous run of the integer key space. This is the property that makes
the directory range-requestable. The S2 *level* (0..=30) is the horizontal LOD;
a reader recovers it from the trailing-sentinel position of the id. The all-zero
id is invalid.

The reference treats the id as an opaque, orderable token; the full S2 geometry
(point↔cell, neighbours, covering a viewport) lives in `map-index` (ported from
`joule-s2`).

## 2. Vertical — `alt: i16`

A signed band index against the tileset's declared `AltSchedule { base_m,
width_m }`. Band 0 is the datum surface; band `n` spans
`[base_m + n·width_m, base_m + (n+1)·width_m)`. Negative bands are sub-surface
(bathymetry); positive bands carry atmosphere and orbit. A surface-only (2.5D)
tileset declares a single band of infinite width and uses only band 0.

## 3. Temporal — `time: (start_tai_ms: i64, width_ms: u64)`

A half-open `[start, start+width)` interval anchored to TAI. **Bucket 0**
(`start == 0 && width == 0`) is reserved for **atemporal** tiles — a coastline,
a border, bare terrain. Any other bucket is time-bound: a weather forecast hour,
a 28-day AIRAC cycle, an ADS-B snapshot. The temporal axis is first-class and
participates in the content id, so "this place on Tuesday 14:00Z" and "the same
place on Wednesday" are distinct, independently addressable, independently
signed tiles. This is what 3D Tiles lacks and what weather and flight navigation
require.

## 4. Detail — `lod: u8`

The within-tier detail level, independent of the S2 level (which is horizontal
*extent*). A single splat tile at S2 level 20 MAY carry LODs 0..N of
progressively denser Gaussians for streamed level-of-detail.

## 5. Canonicality

`CellKey` serializes through the family deterministic CBOR profile
(`map_schema::canonical_cbor`), so `ContentId::of(&key)` is a stable join key
across implementations. Conformance suite **C1** pins the canonical CBOR and
content id of the cell-key vectors in [`../conformance/v1/cell_key_vectors.json`](../conformance/v1/cell_key_vectors.json).