tera/BUILD_PLAN.md

# Tera / Spaces build plan

This is the execution order for the California world. It is intentionally a
dependency plan rather than a feature wish list: each milestone leaves behind a
tested substrate the next one can safely use.

## North star

One continuous California world at three nested scales:

1. **State / corridor** — Los Angeles to San Francisco, route traffic, flyover.
2. **City / exterior** — detailed Bay Area and Southern California boards,
   office buildings as real destinations.
3. **Office / metre scale** — walkable interiors, people, rooms, and screens.

Every scale supports **Observe**. Selected actors and vehicles additionally
support **Play**. Public geometry and ambient simulation work from a static
clone; identity, private presence, realtime state, webcam faces, and shared
screens are hosted capabilities layered on top.

## Work lanes

| Lane | Owns | Can run in parallel with |
| --- | --- | --- |
| World + simulation | transport packs, cells, origin rebasing, controllers | assets, UI, service contracts |
| Asset craft | vehicles, humanoids, dog, crow, buildings, animation | every milestone once interfaces are frozen |
| Product + camera | chapters, follow/chase/walk cameras, input, accessibility | simulation and assets |
| Realtime + media | session authority, interest zones, ACLs, WebRTC surfaces | solo play after state contracts exist |
| Quality | deterministic replays, browser captures, performance budgets, provenance | continuous; never a final cleanup phase |

The critical path is world coordinates → deterministic control → walkable actor
contract → authoritative sessions → private media. Art can stay one milestone
ahead; realtime/media must not jump ahead of the actor and access contracts.

## M0 — contracts and provenance

Status: **implemented**.

- Tera/Spaces is the renderer; `lumbridgecorp` is the control plane.
- Apache-2.0 remains the outbound code license.
- Every copied asset/data item gets a pinned source, license, hash, and intake
  note. Original procedural assets record their design lineage.
- `PROVENANCE.json` plus `npm run provenance` hash-gates every tracked
  distribution artifact, rejects undeclared copied items and remote/bundled
  fonts, and records original procedural/data lineage.
- `npm run licenses` enforces the reviewed dependency-license allowlist and
  registry integrity pins; `npm run sbom` emits SPDX 2.3 from the lockfile.

Exit gate: a clean clone builds and tests without private services or binary
runtime art; every shipped dependency, route, font, and asset has recorded
provenance. The only tracked raster art is the two generated social cards in
`public/`, both source-reproducible and SHA-256 pinned in the manifest.

## M1 — California roads and passive Model X traffic

Status: **implemented and rendered on desktop and mobile; repeatable California
and office browser performance-budget instrumentation is implemented**.

- Coarse California board plus detailed Bay Area and SoCal boards.
- Serializable US-101 and I-5/I-580/I-80 route graphs.
- Procedural black Model X with follow and corridor detail tiers.
- Fixed-step deterministic traffic, both carriageways, instanced background
  vehicles, and a chase/follow camera selected from route chapters.

Exit gate: one hero completes either route on the road; the same seed and frame
sequence reproduce the same poses; route switching leaks no GPU resources; the
declared desktop/mobile frame budgets pass in browser capture.

## M2 — solo playable driving

Status: **deterministic control core plus keyboard, standard gamepad, touch,
chase, and driver-height camera integration implemented and rendered on desktop
and mobile**. The vehicle owns a controller state separate from its render rig.

- Keyboard, gamepad, and touch input through one normalized action map.
- Chase and driver-height cameras.
- Assisted route following as a state machine; manual input takes over and can
  hand back cleanly.
- Route guardrails, recovery/reset, pause and background-tab recovery.
- Fixed input traces for deterministic replay tests.

Exit gate: finish both routes manually or assisted; no NaNs, ordinary-speed
tunneling, or tab-resume jumps; a recorded input trace replays identically.

## M3 — walkable offices and actors

Status: **implemented and integrated**. City actors and office walkers share the
same profile-derived appearance and journey identity; anonymous visitors change
from crow outdoors to dog indoors, while signed-in members remain humanoid.

- First-/third-person walker against the existing `Plan.blocked` wall segments.
- Door traversal and city ↔ office identity handoff.
- Customizable procedural humanoid for signed-in members.
- Anonymous office visitor is a dog; anonymous Tera visitor is a crow.
- Profiles begin as generated materials and parameters, not uploaded binaries.

Exit gate: every room reachable through doors but never through walls; identity
survives scene changes; anonymous clients receive no private presence; 30-minute
soak produces no stuck or out-of-bounds actor.

## M4 — authoritative multiplayer

Status: **core hosted actor, vehicle, and aircraft presence is implemented**.
The service uses short-lived rotating grants, exact interest cells, bounded
10 Hz publishing, strict motion validation, reconnect snapshots, and aggregate-
only presence UI. Deterministic two-client and bounded-service acceptance tests
cover convergence, late join, cell isolation, ownership, revocation, cleanup,
and speed-hack rejection.

- Dedicated realtime session service; do not merge it into the control plane.
- Server-authoritative actor/vehicle poses, input validation, interpolation,
  reconnect, and interest zones keyed by Tera cell / Office / Floor / Room.
- `lumbridgecorp` issues short-lived launch grants and revalidates membership.
- Delta snapshots around 10–15 Hz for nearby dynamic actors; media never rides
  on this socket.

Exit gate: two browsers converge within the declared latency; reconnect restores
the right cell; revocation ejects promptly; malformed and speed-hack state is
rejected; selected cell concurrency passes a repeatable load test.

## M5 — profile and webcam faces

- Generated profile face is the default.
- Webcam face is opt-in and ephemeral: explicit contextual permission, active
  indicator, one-click stop, no recording/storage by default.
- Server-enforced visibility capabilities; unauthorized clients never receive
  the private object or track.

Exit gate: revocation and tab close stop every track; anonymous/unapproved peers
cannot subscribe; the full product works without a camera.

## M6 — office media surfaces

- `MediaSurface` records identify office/room/screen, ACL, source, and state.
- WebRTC SFU track after authorization and explicit viewer opt-in; Three.js gets
  a video texture only while subscribed.
- Share tab/window by default, muted viewer autoplay, visible broadcast state,
  presenter kill switch, late join and reconnect.

Exit gate: no unauthorized subscription; revoke ends tracks and disposes GPU
textures; bandwidth adaptation and safe public placeholders work.

## M7 — playable aircraft

Status: **solo and hosted multiplayer play are implemented**. The original
procedural electric V-tail has deterministic assisted/manual control, chase
camera, California bounds, and an authoritative geographic wire adapter; remote
clients render its bank, control surfaces, and fan phase from validated state.

Keep today's aircraft ambient until vehicle, actor, camera, and network
abstractions are proven. A later `PlayableAircraft` reuses flight-source data for
the world but owns a separate controller and authority model.

Exit gate: route/altitude bounds, camera and control handoff, multiplayer
validation, and no regression to ambient live ADS-B rendering.

## Performance gates

Run `npm run build && npm run performance`. The harness serves the production
bundle locally, uses system Chrome (real GPU when available, SwiftShader as the
headless fallback), warms each scene, and writes `/tmp/tera-performance-budget.json`.
Budgets live in `scripts/performance-budgets.json`; a threshold, console error,
insufficient sample, or anonymous private endpoint request makes the command
non-zero. Use `--output`, `--budgets`, `--warmup-ms`, `--sample-ms`, or
`--software` for explicit CI/diagnostic runs. The named matrix is California and
Office at 1440×900 desktop and 390×844 mobile viewports. Frame comparisons allow
only 0.1 ms for Chrome's rAF timestamp quantization; the declared and reported
budgets are not raised.

- Named benchmark scenes: p95 frame at or below 16.7 ms desktop and 33.3 ms on
  the selected supported mobile tier.
- Hard budgets per scale for resident cells, triangles, draw calls, dynamic
  actors, GPU memory, and media textures.
- Fixed simulation tick separated from rendering; instancing, LOD, pooling,
  frustum/distance culling, and explicit resource disposal.
- Degrade shadows, traffic density, and far detail before input, access control,
  identity, or privacy enforcement.

## Immediate parallel build

The California driving vertical slice now proves the transport, vehicle,
controller, input, camera, and responsive UI contracts. Continue in these lanes:

1. **World:** corridor cell streaming, origin rebasing, city/office destination
   transitions, and deterministic route-completion scenarios.
2. **Office:** integrate the walker with first-/third-person cameras, doors,
   actor possession, and identity-preserving city ↔ office transitions.
3. **Assets:** add driver-view interior hints and animation/state adapters for
   the existing humanoid, dog, and crow rigs; keep the code-only asset pipeline.
4. **Platform:** define versioned launch-grant, session, interest-zone, actor,
   vehicle, and media-capability schemas plus their threat model—without coupling
   the renderer to a hosted service.
5. **Quality:** add repeatable frame-time/draw-call budgets, screenshot baselines,
   long-route and office soak tests, asset-manifest CI, and cross-browser input
   coverage.