# Map roadmap

Map is the geospatial cargo class of the Transaction Science substrate. The
standard is the deliverable; [maps.transaction.science](https://maps.transaction.science)
is the demonstrator pillar that rides on the reference.

## Done — v0.1.0 (the protocol spine)

- **Specification core.** `SPEC.md` (RFC 2119) + `spec/` sub-specs: the 4D cell
  key, the tileset container, the manifest + revision chain, the receipt.
- **`map-schema`** — the 4D cell key, deterministic content addressing, the
  tile cargo, the Hilbert-sorted tileset directory + range planner, and the
  signed manifest + revision chain.
- **`map-cascade`** — the F0–F4 fidelity resolver with a guaranteed F1 base-floor
  fallback.
- **`map-receipt`** — the per-resolve JCR-1 receipt (det-CBOR + COSE_Sign1/EdDSA),
  byte-compatible with the family verifiers, with the enforced provenance
  coupling.
- **`map-conformance`** — C1–C5 + C-neg, all checks real (no SKIPs), with
  published deterministic vectors in `conformance/v1/`.
- Workspace: `cargo test` green, `cargo clippy --all-targets` zero warnings.

## Done — the substrate port (from `joulesperbit`)

The reference scope's index, tiles, orbital, and routing crates have been ported
out of the existing engine (`joulesperbit/crates/joule-*`) into self-contained
`map-*` crates under `map-rs/`, retrofitted to the schema's cell key and content
addressing. All crates: `cargo test` green, `cargo clippy
--all-targets` zero warnings.

| Target crate | Ported from | Status | Provides |
|--------------|-------------|--------|----------|
| `map-index`  | `joule-s2` | **done (v0.1)** | Pure-Rust S2 geometry + a `bridge` that builds a `CellKey` from coordinates and covers any region (cap / rect / polygon) into the cell keys the directory range planner consumes. |
| `map-index` (4D) | `joule-spatial3d` | **done (v0.1)** | The recommended `volume` scheme — logarithmic altitude bands (bathymetry → cislunar) + logarithmic time tiers (1 s → 100 yr) + `SpatialKey` + the `Spatial3DIndex`/`PositionRingBuffer` runtime utilities — plus `bridge::{alt_band, time_bucket, cover_volume}` that maps the scheme into `CellKey`s and covers a horizontal region × altitude range × time range. tests green, zero warnings. |
| `map-tiles`  | `joule-tiles` | **done (v0.1)** | Tile codecs behind the `Tile` cargo: MVT vector (`F3`), raster PNG/WebP (`F2`), terrain quantized-mesh (`F1`), 3D Tiles b3dm (`F3`) + a generic photoreal/splat wrapper (`F4`), with a `tile` bridge that wraps each as a content-addressed `Tile` at its tier. tests green, zero warnings. |
| `map-orbital`| `joule-orbital` | **done (v0.1)** | TLE parsing + SGP4/SDP4 propagation + ECI/ECEF/geodetic transforms for the F3 live-satellite layer, with a `bridge` mapping a satellite sub-point to a `CellKey` (S2 cell + altitude band + time bucket). tests green, zero warnings. No correctness bug upstream — lint cleanups only. |
| `map-route`  | `joule-maps` | **done (v0.1)** | Local geocode / route (Dijkstra + A*) / geofence over a tileset (a capability, not a hosted service — SPEC §9), plus a feed-agnostic `Feed`/`Entity` adapter: any source (flights, vessels, satellites, CVEs, incidents, supply-chain nodes, enterprise signals) resolves to a `CellKey`. Energy metering dropped (that's `map-receipt`). tests green, zero warnings. |

Each remaining port adds: content-addressed, signed tiles (currently
content-addressed only); receipt emission per operation; and conformance vectors
for its payloads.

> **`AltSchedule` note.** `map-index`'s recommended altitude scheme is
> *logarithmic*, but `map_schema::AltSchedule` is currently *linear*
> (`{base_m, width_m}`). So a tileset using the log scheme can carry the right
> `AltBand(i16)` indices, but the manifest can't yet *describe* the non-linear
> band edges. Generalizing `AltSchedule` to an enum (linear | explicit edges) is
> a planned, contained pre-1.0 change.

> **`map-tiles` MVT note.** The upstream `encode_polygon` was broken — it
> clobbered the `CMD_MOVE_TO` command word with a coordinate and reset the
> geometry cursor per ring (wrong for multi-ring polygons / holes); there was no
> polygon test. The port fixes the command emission and uses a continuous
> per-feature cursor, with a regression test. Backported to `joule-tiles`.

> **`map-index` polygon note.** The upstream `polygon` module shipped broken (its
> containment and area routines fail their own tests in `joule-s2`) and never
> implemented `S2Region`, so a polygon could not be covered at all. The port
> **fixes** it: orientation-robust spherical winding-angle containment, van
> Oosterom–Strackee signed area, and `impl S2Region for S2Polygon`. The coverer
> now covers an arbitrary boundary / airspace footprint / geofence — not just
> caps and rectangles. A polygon's `may_intersect_cell` is conservative (its
> bounding cap); tightening it to per-edge intersection is a future contribution.

## In progress — the demonstrator on the standard

The demonstrator (the maps.transaction.science pillar) lives in its own repo,
`maps-transaction-science/`, and consumes `map-rs`. It is a *demonstration of the
standard*, not part of the Apache-2.0 reference.

- **Renderer to `wgpu` — phase 1 done.** `map-render` is a fresh `wgpu` renderer
  (replacing the original's hand-rolled JS-interop WebGPU, which was web-only). The
  globe renders **write-once**: `cargo check`/`clippy` clean on both native
  (`--all-targets`) and `wasm32-unknown-unknown` (`--lib`), zero warnings. Camera +
  icosphere ported; globe shader uses a procedural day/night fragment (the textured
  path is the `F2` raster tier, added with the tile pipeline). Native viewer
  (`examples/native.rs`, winit) + browser entry (`#[wasm_bindgen(start)]`).
- **Phase 2 — consume the standard in the renderer. Done.**
  - *Entity layer:* the renderer depends on `map-schema` + `map-index` and draws
    cell-addressed billboards — `globe_position(cell)` maps an S2 cell centre +
    altitude band to a world position; `set_entities(&[(CellKey, color)])` is the
    seam a feed drives. The native example wires the full `map-route::feed` chain
    (flight / vessel / ISS / CVE → `Entity::cell_key` → globe point).
  - *Tile path (2b):* the globe texture is produced **through the standard** — a
    raster is `map-tiles`-encoded, wrapped as a content-addressed `Tile`, resolved
    through `map-cascade` (closes at `F2:Field`), decoded, and uploaded. The native
    example prints the `map-receipt` JCR-1 wire for the resolve (tier + joules). A
    runtime test exercises the encode→resolve→decode path.
  - *Feature layer (vector):* `map-tiles` gained the missing **MVT decoder**
    (`decode_tile` / `decode_geometry`), and the renderer draws an `F3` vector
    layer through the full path — a graticule is MVT-encoded, content-addressed,
    resolved through the cascade (closes at `F3:Feature`), **MVT-decoded**,
    un-projected, and drawn as globe lines (new line pipeline).
  - *Multi-tile viewport coverage:* the renderer covers a viewport (a cap around
    the camera look-at) into cells via `map-index::cover_region`, resolves each
    through the cascade (finest cells → `F2:Field`, coarser → `F1:Base` fallback),
    and shows them coloured by tier. The native example sums the per-tile receipts
    — SPEC §6's "a viewport's cost is the sum of its tile receipts" (e.g. *127
    tiles: 17 Field + 110 Base → 3.51 mJ*).
  - *F0 cache:* a content-addressed `LocalStore` + `CachedSource` short-circuits
    the cascade — a cell already in the store closes at `F0:Cache` (picojoules)
    instead of re-resolving at `F2`+; a test shows the miss→`F2`→record→hit→`F0`
    transition and the ~1000× energy drop. Browser persistence is an OPFS backend
    (one content-addressed file; `opfs` feature, compiles against the
    unstable-gated File System Access bindings).
  - *Building extrusions (`F3`):* footprints are MVT-encoded as polygons with a
    `height` property, resolved through the cascade, **MVT-decoded** (reusing the
    decoder), and extruded to wireframe boxes on the globe (Mapbox fill-extrusion
    style) — a faithful round-trip for 3D features without a glTF decoder.
  - *`F4:Photoreal` — 3D Gaussian splatting (SOTA, the original thesis):* a real
    EWA-projected, depth-sorted 3DGS rasterizer. Each splat is stored the SOTA way
    — mean + per-axis **scale** + **rotation quaternion** + colour + opacity — and
    the 3×3 covariance `Σ = R S Sᵀ Rᵀ` is reconstructed **on the GPU**; the shader
    projects it to a 2D conic (Zwicker/Kerbl), expands an oriented billboard, and
    composites premultiplied back-to-front. The cloud round-trips through the
    standard at `F4` via the **`map-tiles` splat codec** (`encode_splats`/
    `decode_splats` — quantized fixed-point + log-scales + byte quat/colour, gzip;
    SPZ-style, the F4 codec the photoreal tier was missing). Demo cloud is a
    Gaussian shell of the planet; the data model, codec, covariance math, and
    rasterizer are real.
  - *Degree-3 spherical-harmonic colour + storage-buffer pipeline:* the codec
    encodes degree-`n` SH (`(n+1)²−1` quantized coefficients above DC); the
    renderer now holds splat data in a **read-only storage buffer** (flat layout,
    indexed by `instance_index`) with a **per-frame sorted-index buffer** as the
    only view-dependent upload — so it carries **full degree-3 SH** (the 3DGS
    default, beyond vertex-attribute limits) and scales toward millions of splats.
    The shader evaluates the 15-coefficient SH by view direction; `splat::sh_color`
    is its unit-tested CPU twin.
  - *GPU depth sort:* the per-frame back-to-front order is computed on the GPU by a
    **bitonic sorting network** (compute passes: a keygen pass encodes order-
    preserving depth keys, then one compare-exchange dispatch per network stage) —
    the last CPU cost removed from the splat path. A bitonic network is chosen
    because it is data-independent, so the WGSL kernel is a line-for-line port of
    `gpu_sort.rs`, whose CPU twin is **unit-tested against a reference sort**; GPU
    dispatch validates clean on a real device.
  - *Captured-scene ingest:* `map_tiles::splat::read_ply` ingests the de-facto
    **INRIA `.ply`** 3DGS interchange format (ASCII + binary-LE), inverting the
    trainer's storage conventions (log-scales, logit-opacity, `(w,x,y,z)` rotation,
    `0.5 + C₀·f_dc` DC, channel-major `f_rest` SH) into [`Splat`]s ready for
    `encode_splats` — so a real capture re-encodes into a conforming F4 tile. The
    demonstrator's `splat::load_ply` routes a capture through the codec into the
    renderer.
  - *glTF / b3dm decode:* `map_tiles::tiles3d::read_b3dm` / `read_glb` are the
    reader half of the 3D Tiles codec — they strip the b3dm header + feature/batch
    tables and decode the embedded binary glTF into a triangle mesh, general over
    accessors/bufferViews (f32 VEC3 positions; u8/u16/u32 indices; byte offsets +
    strides; multi-primitive merge). Round-trips `B3dmBuilder::encode`.
- **Tile-serving core** (`map-serve`) — the transport-agnostic protocol logic of a
  tile server, with **no HTTP-framework dependency**: parse a tile request →
  resolve through the F0–F4 cascade → build a content-addressed response (strong
  `ETag`, `Cache-Control: immutable`, `If-None-Match` → `304`, `X-Map-Tier` /
  fell-back, and a **JCR-1 energy-receipt** header). Ships a `MemoryStore`
  reference store and a filesystem `DirStore` (content-addressed blobs on disk +
  a JSON index, reloaded on `open` so a restart keeps serving — `std`-only);
  binding to a socket (axum/hyper/worker) is a thin caller-side wrapper. Pure +
  unit-tested (incl. a runnable doctest).
- **Routing engine** (`map-route`) — Dijkstra + A* path-finding now joined by
  **turn-by-turn directions** (`directions::turn_by_turn`: maneuvers from segment
  bearing deltas, straight-run merging, cardinal-heading departure, arrival) and
  **isochrones** (`isochrone::isochrone`: budget-bounded Dijkstra reachability by
  travel time or distance, ready to cover into cells), and **multi-modal +
  traffic-aware costs** (`cost::find_route_with` over a `CostModel`: per-mode
  access matrices + free-flow speeds for car/bike/foot, a congestion multiplier,
  and an admissible time-based A* heuristic), and **public-transit routing**
  (`transit`: the Connection Scan Algorithm over a GTFS-like `Timetable` —
  earliest arrival with timetabled connections, walking-footpath transfers, and
  auto-generated transfers within a radius; reconstructs ride/walk legs).
- **HTTP binding** (`map-serve-axum`) — an axum/tokio wrapper: `router(store,
  steward)` routes every request through `serve`, and `run(addr, …)` is a one-call
  server. The async stack is confined to this crate, keeping `map-serve` framework-
  free. Verified by `oneshot` integration tests *and* a live-socket demo
  (`examples/serve_demo`) exercised over real HTTP (200 + receipt / 304 / 400 / 404).
- **Phase 3 — remaining layers** (atmosphere, borders/coastlines, satellites/
  aircraft/vessels, labels, routes) onto the same `Renderer`.
- **OPFS tile cache.** The F0 cache tier backed by an OPFS-resident slice of the
  tileset: check the local store, fall back to HTTP range, write back. Offline
  maps and instant revisits as the purest extension of "it's just a file" to the
  client.
- **Capture → tileset pipeline.** Reference tooling to publish a signed tileset
  (terrain, fields, features, splats) so a third party can light up a layer.

## Later

- WASM build of `map-schema` + `map-cascade` for an in-browser coordinate
  playground at maps.transaction.science.
- Cross-language conformance certifications (Python/Go) against `conformance/v1/`.
- A `map-time` binding for forecast/AIRAC revision streams as first-class dated
  archives.