# v2 roadmap (briefs a to m)

One page over the `agents/v2-*.md` briefs. Spec: `agents/world-format-v2.md` (index; area docs in
`agents/v2/`); contract:
`agents/v2-formats.md`. Status read from `origin` branches on 2026-09-27: **merged** = in
`world-format-v2`; **done** = pushed, not merged; **not started** = no branch. "Running"
can't be seen from git; mark it by hand when an agent is on a brief.

## Briefs, in order

| # | Brief | Branch | Depends on | Status |
|---|---|---|---|---|
| a | Entity + scene snapshot, traffic off the camera | `v2-snapshot` | none | done (not merged; v2 copy of the format is in `v2-sim-core`) |
| b | Refetch and archive raw inputs | `v2-raw-inputs` | none | merged |
| c | Benchmark harness | `v2-bench` | a | built on its own branch (hooks v1's runtime; owner runs it on the M3) |
| d | Rapier determinism spike | `v2-determinism` | none | merged (ARM unproven) |
| e | WebGPU/TSL renderer (the plan) | `v2-webgpu` | a, c | not started (draft; g is its stage 1) |
| f | Splat capture pilot | none (owner) | none | not started |
| g | Renderer spikes | `v2-renderer-spike` | e, a, sim-core; c for results | not started |
| h | Forge MVP | `v2-forge-mvp` | sim-core, formats v1.1, catalogue pilot | not started |
| i | Characters, first milestone | `v2-characters` | sim-core, d; research pass in spec | not started |
| j | Audio engine v0 | `v2-audio` | sim-core, clock | not started |
| k | Multiplayer referee v0 | `v2-referee` | sim-core, d | not started |
| l | Vehicle handling + Metro rails | `v2-vehicles` | sim-core, d, clock (dmath) | not started |
| m | Rust/WASM core port | `v2-rust-core` | sim-core, d; k's codec vectors | not started |

Unlettered work already on `origin`: formats v1.1 (`v2-formats-1-1`), registry aliases
(`v2-registry-alias`), catalogue pilot (`v2-catalogue-pilot`), world clock
(`v2-world-clock`), systems sandbox (`v2-systems-sandbox`): all merged. Simulation kernel
(`v2-sim-core`): done, **not merged**, and every brief from g on starts after it lands.

## Suggested order
1. **Merge `v2-sim-core`** (and decide whether `v2-snapshot` merges into v1 or stays a branch
   v2 copied from).
2. **c** bench, so g has a result format and the M3 has something to run.
3. In parallel, no shared files: **g** renderer spikes, **h** forge, **l** vehicles,
   **k** referee. h and k both touch entity ids and events only through the kernel.
4. **i** characters and **j** audio once g has a render path worth dressing and hearing.
5. **m** Rust core after k's codec vectors exist and l's module is stable, so both port once.
6. **e** stages 2-5 after g's verdicts.

## What the owner must do himself
- **M3 bench run:** brief c's routes and brief g's spike pages in Chrome and Safari on the
  M3; commit the JSON. Nothing about speed is decided on this box (SwiftShader).
- **ARM determinism check:** `node tools/determinism/serve.mjs`, then `/?build=det` on Apple
  Silicon Safari and an iPhone (and Android if handy); compare the final hash with
  `tools/determinism/results/results.json`. Gates lockstep bubbles and brief m's native check.
- **Splat capture:** brief f, one Sunday morning (bin, shelter, frontage) plus a GPU day.
- **RTT measurement** from Newcastle ISPs to Nuremberg/Helsinki and between two home lines:
  tunes brief k's K and tier rates.
- **Legal reads:** CMU mocap inside a free mod SDK; contracts with under-18 contributors
  (solicitor); Open-Meteo licence (CC BY vs CC BY-SA); which Esri terms govern the imagery
  endpoint; publishing extracted map data (ODbL); the OSA illegal-content and children's
  access assessments before public upload opens.
- **Decisions asked for in briefs:** relay-only forced for under-18 accounts in 12-rated
  worlds (k); which v1 handling numbers are the target, pre- or post-2026-09-24 braking pass
  (l); hecs vs sparse sets and the phase list (m, stage 0).

## Loose ends found while writing these
- (Resolved in formats v1.2: canonical is `rules18`, PEGI 18.)
- (Resolved in formats v1.2 K1: phases are the kernel's `input environment systems physics post`.)

## Decisions taken by the orchestrator (owner delegated, 2026-09-27)
- Tick phases: the kernel's `input, environment, systems, physics, post` win; the formats
  doc changes to match (formats v1.2).
- State hash in entity-id order (layout-independent) so the Rust/hecs port can match; the JS
  kernel changes first with a format bump.
- Car handling targets (l): re-measure today's v1 (after the 2026-09-24 braking pass) and use
  those numbers.
- P2P for under-18 accounts in 12-rated worlds (k): relay-only is forced; their IPs are never
  exposed to peers.
- Welding (h): brief h proposes the overlay entry in the formats doc before code.

Status updates since this file was written: sim core, dialogue engine and weather merged;
running at time of writing: missions, formats v1.2, weather snow fix, voice recorder, bench,
navmesh, chunk converter, registry reserved ids, browser compatibility matrix.

Goal 1 closed 2026-09-27: missions, weather snow fix, recorder and chunks merged into
`world-format-v2`; `bash v2/test.sh` green. `v2-bench` and `v2-snapshot` stay as their own
branches by design (they modify v1's live runtime); the owner runs `v2-bench` on the M3.