NEMOCITY v0 — mock backend, gradio 6.16.0 (pre-SSR)

ARCHITECTURE.md

@@ -0,0 +1,583 @@
+# NEMOCITY — Architecture Contract (v1, June 12 2026, ~7pm)
+
+> **This file is the single source of truth for the parallel build.** Every builder agent reads
+> this FIRST and writes ONLY the files it owns (see File Ownership). When in doubt, follow the
+> schemas here exactly — the integrator fixes drift, but don't create it.
+
+## One-liner
+
+Ask the city for a building — a 9B Nemotron city hall reads your petition, the deterministic
+engine zones it, and you (and every other visitor on Earth) watch it rise, floor by floor, in ONE
+shared persistent miniature city. Cars commute, rush hour jams the bridge, and the AI City
+Engineer reads real traffic telemetry and fixes it while you watch.
+
+- **Name:** NEMOCITY — "the tiny city the internet builds." (nano = Nemotron Nano + the
+  hackathon's small-model thesis; -polis = city.)
+- **Tagline:** "Ask for a building and watch it rise — one tiny persistent city the whole
+  internet builds, with a 9B Nemotron running city hall."
+- Track: 🍄 Thousand Token Wood. Hackathon: Build Small (Gradio + HF). Deadline June 15 morning.
+- Awards targeted: NVIDIA team-judged RTX 5080 (Nemotron load-bearing — the model's raw JSON
+  plan is shown in the UI on every action), TTW podium, Community Choice (shared persistent
+  city), Best Demo (timelapse + FPV walk footage), Judges' Wildcard, badges: offbrand, sharing,
+  fieldnotes (+ offgrid/llama stretch).
+
+## Non-negotiable design rules
+
+1. **The "her" pattern** (org-celebrated judge taste): the deterministic engine owns ALL city
+   state, placement, geometry, and traffic facts. The LLM only interprets petitions into a tiny
+   JSON (no coordinates, EVER) and narrates. The engine clamps/repairs everything; a visitor
+   action ALWAYS yields visible construction.
+2. **One petition at a time** — single serialized queue, visitors see their position.
+3. **The landing page must be gorgeous with ZERO GPU.** The whole city renders client-side from
+   the event JSON; cars/citizens/day-night simulate deterministically in the browser. Judges
+   evaluate while GPUs sleep.
+4. **Determinism end-to-end.** All motion is a pure function of (event list, simTime). NO
+   `Math.random()`, NO `Date.now()` inside sim/render logic (the shared clock anchor in main.js
+   is the single allowed wall-clock read). NO `position += v*dt` accumulation — always evaluate
+   `position(t)` absolutely (the godseed life.js idiom). This makes replay, timelapse, shared
+   sync, and headless screenshots free.
+5. **ONE `@spaces.GPU` call per user action** (one-shot JSON generation, model resident on cuda,
+   duration=240). The multi-call loop crashes ZeroGPU — June 12 lesson, never relitigate.
+6. **Moderation before execution** (charset/length + folded wordlist; LLM judge OFF by default).
+   LLM-proposed building NAMES also pass the wordlist. One slur on a storefront during judging
+   week ends every award.
+7. **≤32B params total, ONE model:** `nvidia/NVIDIA-Nemotron-Nano-9B-v2`.
+8. **Copy/naming:** never use "wish", "god", "remember/remembers", "Book of ___" in USER-FACING
+   copy (rival differentiation + GODSEED separation). The user-facing words: **petition**,
+   **city hall**, **City Engineer**, **ledger**. (Wire format & Python internals KEEP godseed's
+   `wish_id`/`wish_*` names verbatim — zero-risk code reuse; UI copy is the only rename layer.)
+9. Frame: a FLAT city grid (true SimCity feel). NOT a planet, NOT an island. Plus a first-person
+   walk mode ("Walk the streets") — verified unclaimed across all 385 rival submissions.
+
+## Repo layout & FILE OWNERSHIP (do not touch files you don't own)
+
+```
+nemocity/
+  ARCHITECTURE.md          (this file — read-only for everyone)
+  app.py                   ← AGENT-SERVER   (adapt from godseed; already copied here)
+  requirements.txt         ← AGENT-SERVER
+  README.md                ← AGENT-SERVER   (HF Space card w/ full YAML tags — see Deploy)
+  server/                  ← AGENT-SERVER   (sse.py, persistence.py, schemas.py, ratelimit.py — copied, adapt envs/fields)
+  engine/                  ← AGENT-ENGINE
+    constants.py             (canonical: grid, river, building table, road classes, traffic constants, palette-relevant hues)
+    genesis.py               (the exact genesis event list — see Genesis)
+    world.py                 (copied from godseed — keep the Feature/load/apply/state_dict machinery; adapt _observation + validation hook)
+    tools.py                 (NEW: kind-synonym map, clamp tables, event validation — engine-side "tool" specs for the 4 event types)
+    city.py                  (derived state from events: occupancy grid, road graph + street names, population, growth_radius)
+    placement.py             (the never-fails placement scorer + connector BFS)
+    traffic.py               (static assignment: trip gen, A*, demand map, Traffic Index, fix candidates + predicted index)
+    summary.py               (≤600-char city summary for the LLM prompt)
+    moderation.py            (copied — adapt env names GODSEED_→CITY_)
+    queue_worker.py          (copied — adapt: one-shot planner drive, fix-kind jobs, plan SSE event)
+  mind/                    ← AGENT-MIND
+    prompts.py               (build + fix one-shot prompts; persona; tool docs from engine tables)
+    backends.py              (copied — adapt: env names, ONESHOT only, model id, /no_think + <think> strip stays)
+    validate.py              (lenient parse for the BUILD and FIX JSON schemas; balanced-brace extraction + salvage)
+    planner.py               (one-shot grant(): prompt → generate → parse → clamp → engine acts; fix(): stats → generate → choice)
+    mock_scripts.py          (keyword→BUILD-JSON scripts exercising every kind; fix script; drives local dev + demos)
+    moderation_judge.py      (copied; off by default via CITY_JUDGE)
+  web/
+    index.html, style.css  ← AGENT-UI       (HUD per Visual Bible; element ids are the contract)
+    main.js                ← AGENT-UI       (copied — adapt SSE applier, petition form, HUD, mode buttons, mock boot, window.__app harness)
+    mock/world.json        ← generated by tools/gen_web.py (AGENT-ENGINE writes the generator; integrator runs it)
+    mock/feed.js           ← AGENT-UI       (scripted petition feed for ?mock=1 demos)
+    lib/                   (vendored three r160 + addons + PointerLockControls — already in place; read-only)
+    city/
+      constants.js         ← generated by tools/gen_web.py from engine/constants.py (AGENT-RFOUND hand-seeds it from THIS contract; gen overwrites later — values must match this doc)
+      rng.js               (copied verbatim — mulberry32; read-only)
+      util.js              ← AGENT-RFOUND   (cellToWorld/worldToCell/key/clamp/lerp/eases/cityCenter)
+      scene.js             ← AGENT-RFOUND   (copied — adapt: fog, camera start, tilt-shift+grade passes, MSAA target, rig-swap hook, daylight wiring)
+      ground.js            ← AGENT-RFOUND   (ground chunks, river water, vertex-color lawn, contact-shadow quads API, occupancy mirror + isWalkable)
+      world.js             ← AGENT-RFOUND skeleton; INTEGRATOR owns final wiring (event dispatch → subsystems)
+      replay.js            (copied verbatim; read-only until integrate)
+      buildings.js         ← AGENT-RKIT     (the 19-kind procedural kit, global window InstancedMesh, hue/variant jitter)
+      construction.js      ← AGENT-RKIT     (dirt lot → scaffold → crane → floor-by-floor rise → finish; progress = f(ev.t, simTime))
+      roads.js             ← AGENT-RTRAFFIC (road/bridge/sidewalk/crosswalk meshes from road cells; canvas atlas; lamp posts)
+      traffic.js           ← AGENT-RTRAFFIC (road graph, A* + path cache, trip gen, 10Hz car CA, congestion EMA, Traffic Index, heatmap overlay)
+      vehicles.js          ← AGENT-RTRAFFIC (instanced car kit rendering of traffic.js car states; head/taillights; blob shadows)
+      citizens.js          ← AGENT-RTRAFFIC (instanced pedestrians on sidewalk loops)
+      sky.js               ← AGENT-RCAM     (sun arc, hemisphere, fog colors, gradient sky dome, stars; exported pure daylight(simTime))
+      camera.js            ← AGENT-RCAM     (orbit/pan/zoom rig, gaze(point,{hold}), landing choreography, bounds)
+      fpv.js               ← AGENT-RCAM     (pointer-lock walk: WASD+shift, occupancy collision w/ axis slide, enter/exit)
+  tools/
+    shot.mjs               (copied — AGENT-UI adapts selectors/harness; the screenshot-and-LOOK loop is mandatory)
+    gen_web.py             ← AGENT-ENGINE   (emits web/city/constants.js + web/mock/world.json from engine constants/genesis)
+  tests/                   ← test_engine.py + test_traffic.py (ENGINE), test_mind.py (MIND), test_api.py (SERVER)
+  traces/                  (runtime output — wishes.jsonl; gitkeep only)
+```
+
+Build waves: **Wave 1 (parallel):** ENGINE, MIND, SERVER, RFOUND, UI. **Wave 2 (parallel):**
+RKIT, RTRAFFIC, RCAM. **Wave 3:** INTEGRATOR. **Wave 4:** verify (pytest + headless screenshots).
+
+## The grid
+
+- 64×64 cells; cell coords `(cx, cz)` each in `[-32, 31]`. `CELL = 4` world units (= 4 m;
+  1 unit = 1 m — human scale, FPV-ready). City plane = 256×256 u at y=0.
+- World position of cell center: `x = cx*4 + 2`, `z = cz*4 + 2`. +X = east, +Z = south.
+- A cell holds at most ONE of: road | water | building-footprint | park | empty.
+- Buildings occupy `w×d` rectangular footprints, anchor = top-left (min cx, min cz) cell.
+- **The river** (load-bearing: guarantees the traffic bottleneck + a beauty anchor). Water cell
+  columns per row, formula (identical in `engine/constants.py` and `web/city/constants.js`):
+
+  ```
+  riverCols(cz) = cz <= -5 ? [7, 8] : cz <= 3 ? [8, 9] : [9, 10]
+  ```
+
+  Water cells are unbuildable and uncrossable except on bridge cells (road cells over water).
+- `growth_radius` = max Chebyshev distance of any developed (non-water) cell from (0,0), min 6.
+  Placement penalizes beyond `growth_radius + 2` → the city accretes outward, ring by ring.
+
+## Shared sim clock (every visitor sees the same city at the same moment)
+
+- `CITY_EPOCH_S = 1781222400` (June 12 2026 00:00 UTC; constant in engine + web constants).
+- `simTime = serverNow - CITY_EPOCH_S` (seconds). main.js estimates `serverNow` once from
+  `server_now` in `/api/state` (and SSE hello), then free-runs on the fixed-step clock, slewing
+  ±2% toward the server clock when a heartbeat shows >1.5 s drift. Never snap.
+- ONE in-game day = `DAY_S = 240` seconds. `dayHours = (simTime % 240) / 240 * 24`.
+- Rush hours: bell curves at dayHours 8 and 18 (σ≈1.2h) — judges see a rush within ~2 min.
+- Day/night: `daylight(simTime)` ∈ [0,1], pure function in sky.js — smooth sunrise centered
+  dayHours 5.5, sunset centered 19.5 (transitions ~1.5h wide). Night is short and gorgeous.
+- Construction progress (any client, incl. late joiners):
+  `progress = clamp((CITY_EPOCH_S + simTime - ev.t) / DURATION(kind), 0, 1)`.
+- `tick(dt)`/`seek(t)` fixed-step core (already in scene.js) MUST keep working: timelapse,
+  replay, and shot.mjs depend on it.
+
+## Building table (CANONICAL — engine/constants.py is the source; gen_web.py mirrors to JS)
+
+`kind: {w×d, floors min–max, residents, jobs, attract, duration_s}`
+
+| kind | w×d | floors | residents | jobs | attract | duration |
+|---|---|---|---|---|---|---|
+| house | 1×1 | 1–2 | 4 | 0 | 0 | 20 |
+| townhouse | 1×1 | 2–3 | 6 | 0 | 0 | 20 |
+| apartments | 2×2 | 4–7 | 16 | 0 | 0 | 45 |
+| cafe | 1×1 | 1 | 0 | 3 | 5 | 20 |
+| shop | 1×1 | 1–2 | 0 | 4 | 4 | 20 |
+| market | 1×2 | 1 | 0 | 8 | 6 | 30 |
+| bank | 2×1 | 2–4 | 0 | 12 | 2 | 30 |
+| office | 1×1 | 3–8 | 0 | 40 | 1 | 30 |
+| tower | 2×2 | 8–16 | 0 | 60 | 2 | 45 |
+| school | 2×2 | 1–2 | 0 | 10 | 3 | 30 |
+| hospital | 3×3 | 3–6 | 0 | 25 | 2 | 45 |
+| fire_station | 2×1 | 2 | 0 | 8 | 1 | 30 |
+| warehouse | 2×2 | 1 | 0 | 10 | 0 | 30 |
+| factory | 3×2 | 1–2 | 0 | 18 | 0 | 45 |
+| park | 2×2 | 0 | 0 | 0 | 8 | 20 |
+| plaza | 1×1 | 0 | 0 | 0 | 6 | 20 |
+| stadium | 4×4 | 1 | 0 | 15 | 9 | 45 |
+| church | 2×1 | 1 | 0 | 2 | 3 | 30 |
+| town_hall | 2×2 | 2 | 0 | 6 | 4 | 45 |
+
+- Mixed-use feel comes from variety + placement affinities, not more kinds.
+- **Synonym map** (engine/tools.py — the model can never pick a kind we lack): skyscraper/
+  highrise→tower, apartment/apartment building/condo→apartments, coffee shop/diner/restaurant/
+  bakery→cafe, store/boutique/pharmacy→shop, mall/grocery/supermarket→market, police station/
+  police→fire_station, library/museum/city hall→town_hall, temple/mosque/chapel→church,
+  garden/playground→park, fountain/square→plaza, arena/stadium→stadium, clinic→hospital,
+  gym→shop, hotel→apartments, factory/plant→factory, anything unknown→**house**.
+- `population = Σ residents × build_progress` (a finishing tower visibly ticks the HUD up).
+- Citizens (pedestrians): `clamp(ceil(population/5), 6, 80)`.
+- Demand-driven infill: after a granted petition, if `jobs > housing_capacity*1.15`, engine
+  appends ONE bonus house/apartments event (same wish_id, normal scorer, near the new jobs),
+  note blurb "New families are moving in." Max 1 infill per petition.
+
+## Roads & the road graph
+
+- Roads are CELLS. Classes: `street` {capacity 2, speed 1.0 cells/s, 1 dash lane marking},
+  `avenue` {capacity 6, speed 1.6, wider look, double yellow center}. Road cells over water
+  render as BRIDGES (raised deck + railings; same graph semantics).
+- Graph (derived IDENTICALLY in Python `engine/city.py` and JS `traffic.js`): node = road cell;
+  edge between 4-adjacent road cells. Intersection = road cell with ≥3 road neighbors.
+- **Street names:** each maximal straight run of road cells laid in one event gets a name from a
+  curated list indexed by `crc32(event_id) % len(list)` ("Main St" and "1st Ave" and "Old Bridge"
+  fixed in genesis). Names power LLM stats ("Old Bridge carries 3.1× its capacity") + HUD.
+- **Engine-routed roads only — the LLM never outputs geometry:**
+  1. Placing a building with no road frontage auto-routes a CONNECTOR: BFS over empty cells from
+     footprint perimeter to nearest road cell (max length 8), Manhattan path, emitted as its own
+     `lay_road` event in the same wish.
+  2. Traffic fixes lay engine-routed bypass roads (BFS avoiding jammed cells; water crossable at
+     4× cost — fixes may deliberately build a second bridge).
+- `road_version` = count of road-mutating events; all path caches key on it.
+
+## Traffic model (client-side presentation; Python mirror for facts)
+
+- Fixed **10 Hz logic tick** (accumulator inside the existing 60 Hz fixed-step; render
+  interpolates). RNG = mulberry32 from event seeds only.
+- **Trip generation** (static OD, gravity; recompute only when buildings change): each completed
+  residential building emits `residents` commuters; commuter `i` picks a destination via seeded
+  roulette over job/attract buildings, `weight = (jobs + 2*attract) / (1 + manhattanDist^1.5)`,
+  `seed = building.seed ^ i`.
+- **Cars:** visible cars `N = clamp(round(population * 0.8 * rushFactor(simTime)), 8, 120)`,
+  `rushFactor = 0.35 + 0.65 * (bell(dayH,8,1.2) + bell(dayH,18,1.2))` (bell = gaussian, capped
+  at 1). Each car = one commuter loop home→work (dwell 10–20 s seeded)→home, phase-offset seeded.
+- **Pathfinding:** A* over road cells, `cost(cell) = (1/speed(class)) * (1 + 2*demandRatio(cell))`
+  — congestion-aware so fixes visibly reroute. Cache per (origin, dest, road_version); on bump,
+  re-solve incrementally ≤20 paths/frame.
+- **Movement — queueing cellular automaton** (no physics): car = scalar progress along its path;
+  per tick `speed = base * clamp(capacity / max(occ(nextCell), 1), 0.25, 1)`; if
+  `occ(nextCell) ≥ 2*capacity` the car HOLDS. occ = integer car count per road cell. Cars
+  visibly slow, bunch, queue back from the bridge. Intersection yield = deterministic priority
+  (lower car index). U-turn at dead ends.
+- **Congestion:** per road cell `cong = EMA(occ/capacity, τ=5 s)`. **Traffic Index** =
+  `round(100 * mean(top-15 cong cells))`, color-coded on the HUD live.
+- **Heatmap overlay** (toggle): one InstancedMesh of road quads, green < 0.5 / yellow < 1.0 /
+  red ≥ 1.0, instanceColor updated at 2 Hz. Jammed segments ALSO get an in-world additive red
+  underglow strip (#E84F3D) — utility visible from orbit, not just HUD.
+- **Python mirror** (`engine/traffic.py`): same trip gen + A* + demand map from the same event
+  list/constants (static assignment, no CA). This feeds the LLM stats + fix candidates, so the
+  ENGINE owns the facts; live car queueing is presentation and may drift a car or two, harmless.
+- **ACCEPTANCE (engine agent must verify, tune capacities/CAR rate until true):** genesis city
+  + ~3 extra houses west jams the Old Bridge (cong ≥ 1.0 red) at rush hour in mock mode.
+
+## The traffic-fix mechanic (V0-CRITICAL — the prize-winning beat; never let it slip)
+
+1. Client shows live Traffic Index; when any cell holds cong ≥ 1.0 for 10 s → pulsing chip
+   "Traffic alert: Old Bridge" + button **[Ask the City Engineer]**.
+2. `POST /api/fix` → engine gate: if Python static assignment max demandRatio < 0.8 → 409
+   "Traffic is flowing smoothly." Else enqueue a fix job (global cooldown 120 s, 2/hr/client).
+3. Engine computes stats snapshot: top-5 cells by demand/capacity WITH street names, worst
+   intersection, traffic_index, and 2–4 pre-validated CANDIDATE FIXES, e.g.
+   `{id:"F1", action:"new_road", desc:"second bridge at Oak St, 7 cells", predicted_index:41}`
+   (predicted by re-running static assignment with the candidate applied). Actions v0:
+   `new_road` (bypass/bridge) and `upgrade_avenue` (repaint a named street's cells to avenue).
+4. **ONE** @spaces.GPU Nemotron call: input {stats, candidates} → output
+   `{"diagnosis":"≤160 chars citing the real numbers","choice":"F1","blurb":"≤120"}`.
+   Invalid choice/parse failure → engine applies best predicted candidate + canned diagnosis.
+5. Engine appends ONE `apply_fix` event (exact cells + diagnosis + metrics_before/predicted);
+   SSE `world_delta`. Every client: road_version bumps, paths re-solve, the new road paints in
+   over 4 s, queued cars peel onto it, red drains green over ~20 s, HUD animates "78 → 41".
+
+## Placement algorithm (engine/placement.py — deterministic, NEVER fails, Python-only)
+
+Input: kind (post-synonym), w×d, floors (clamped), anchor from the "near" hint, resolved fuzzily:
+named building → its centroid; street name → midpoint; "center"/"downtown" → (0,0); "river" →
+nearest water-adjacent developed cell; null/unresolvable → centroid of all buildings.
+
+1. Candidates = empty cells within Chebyshev radius R of anchor; R starts 6, +4 until ≥1 valid.
+2. VALID = footprint fits on empty non-water cells AND (perimeter touches a road OR connector
+   BFS ≤8 exists).
+3. SCORE: `+30*(1 - dist_to_anchor/R)` `+20*roadFrontage` `+3/developed-8-neighbor (cap +18)`
+   + affinities: cafe/shop +12 if house/apartments ≤3 cells; office/bank/tower
+   `+10*(1 - dist_to_center/12)` (downtown skyline emerges); house/townhouse/apartments +8 if
+   cafe/shop/park ≤4, −6 if factory/warehouse ≤3; factory/warehouse −10 if residential ≤3, +8
+   if industrial ≤4 (an industrial quarter self-organizes); park −25 if another park ≤6;
+   `−8*max(0, chebyshev_from_center − (growth_radius+2))` (ring growth).
+4. floors: office/tower `clamp(base + round(4*(1 − dist_to_center/10)), range)` — taller downtown.
+5. Tie-break: seeded jitter `U(0,1)` from `crc32(wish_id:candidate_index)`.
+6. Emit `place_building` (exact cells FINAL) + optional connector `lay_road`. Re-derive occupancy
+   after EACH building within a multi-building petition (siblings cluster, never overlap).
+
+## Event schema (append-only; byte-compatible with godseed Feature: id, wish_id, tool, args, seed, t)
+
+`seed = crc32(f"{wish_id}:{call_index}") & 0x7fffffff`. City-at-T = pure fn of (events t≤T, T).
+
+```json
+{"id":"e_000017","wish_id":"w_000005","tool":"place_building",
+ "args":{"kind":"cafe","name":"Cafe Luna","cx":3,"cz":-2,"w":1,"d":1,"floors":1,"hue":35,"variant":2},
+ "seed":1830293847,"t":1781230000.0}
+
+{"id":"e_000018","wish_id":"w_000005","tool":"lay_road",
+ "args":{"cells":[[3,-1],[4,-1],[5,-1]],"klass":"street","name":"Olive St"},"seed":482919,"t":1781230000.5}
+
+{"id":"e_000031","wish_id":"w_000009","tool":"apply_fix",
+ "args":{"action":"new_road","cells":[[5,-6],[6,-6],[7,-6],[8,-6],[9,-6]],"klass":"avenue",
+  "name":"Oak St Bridge","diagnosis":"Old Bridge carries 3.1x capacity at rush — a second crossing cuts the index 78→41.",
+  "metrics_before":{"traffic_index":78,"worst":"Old Bridge"},"metrics_predicted":{"traffic_index":41}},
+ "seed":99182,"t":1781231100.0}
+
+{"id":"e_000032","wish_id":"w_000009","tool":"note","args":{"text":"New families are moving in.","kind":"infill"},"seed":7,"t":1781231101.0}
+```
+
+Derived, never stored: occupancy, road graph + names, road_version, population, demand map,
+growth_radius. WishTrace persists per petition exactly like godseed (text, moderation, RAW LLM
+JSON, event ids, ms_total) → `traces/wishes.jsonl` → HF dataset (Sharing badge + NVIDIA evidence).
+
+## Genesis (epoch 0 — engine/genesis.py is canonical; web/mock/world.json is GENERATED from it)
+
+wish_id "genesis", t = CITY_EPOCH_S. Order: roads, then buildings, then a note.
+
+Roads:
+- **Main St** — avenue, cx=0, cz −12..12.
+- **1st Ave** — avenue, cz=0, cx −12..16, EXCEPT the two river cells.
+- **Old Bridge** — **street** class (the bottleneck by design), cells (8,0),(9,0) over water.
+- **River Rd** — street, cx=13, cz −6..6.
+- **Elm St** — street, cz=−5, cx −8..0.
+- **2nd St** — street, cx=−5, cz −5..3.
+
+Buildings (anchor top-left; every footprint touches a road; engine must assert validity):
+- town_hall 2×2 @ (−2,−3) — faces Main St.
+- office 1×1, 5 floors @ (1,−2); cafe 1×1 @ (1,1); market 1×2 @ (−1,1).
+- park 2×2 @ (−4,1) — beside 2nd St + 1st Ave.
+- houses 1×1 @ (−1,−6), (−4,−6), (−6,−4) — Elm/2nd St cluster.
+- EAST of the river (jobs/homes that force bridge commutes from day one):
+  factory 3×2 @ (14,−3); warehouse 2×2 @ (14,1); houses @ (14,3), (14,−5) — all on River Rd.
+- note: {"text":"Nemocity is listening. Ask for a building.","kind":"milestone"}
+
+Genesis population ≈ 20, jobs ≈ 95, one street-class bridge carrying every river crossing.
+
+## LLM one-shot schemas (mind/ — small, flat, enum-heavy; a 9B nails these)
+
+**BUILD** — input: petition text (≤160 chars) + engine summary (≤600 chars: city name, pop,
+counts by kind, named landmarks/streets, traffic index). Output:
+
+```json
+{"intent":"build","blurb":"≤140 chars, warm city-planner voice",
+ "buildings":[{"kind":"cafe","name":"Cafe Luna","near":"the park","floors":4,"hue":35}],
+ "decline_reason":null}
+```
+
+- buildings 1..3; kind = table enum (synonyms repaired by engine); name ≤24 chars (wordlist-
+  checked, default derived from petition words); near = free text the ENGINE resolves; floors/
+  hue optional. intent "decline" (+reason) only for nonsense — moderation already gated abuse.
+- Parse failure after 1 retry → deterministic fallback: one house, name from petition words,
+  blurb "The city granted a home." Something ALWAYS builds.
+
+**FIX** — input: {stats, candidates} as in the fix mechanic. Output:
+`{"diagnosis":"≤160","choice":"F1","blurb":"≤120"}`. Invalid choice → best predicted candidate.
+
+**Prompting** (mind/prompts.py): persona = terse municipal planner AI ("You are city hall of one
+shared miniature city. The engine owns all facts; you only translate petitions into permits.
+Build generously — a district request deserves 2–3 buildings. Never refuse a buildable thing.").
+Tool/kind docs rendered from engine tables (single source). NO multi-example few-shot (GODSEED
+leakage bug) — ONE inline example-shape JSON + "your own values, JSON only". Backend: copied
+ZeroGPUBackend (resident cuda at load, @spaces.GPU(duration=240), /no_think system slot,
+<think> strip, temperature 0.4 for JSON, max_new_tokens 700, lenient parse + 1 retry).
+
+## HTTP API + SSE (server — keep godseed wire names; adapt fields)
+
+```
+GET  /api/state          → {world:{version,epoch,features:[...]}, queue, wishes_recent, server_now}
+POST /api/wish {text}    → {wish_id, position}     (petition; 400 poetic reason on moderation reject)
+POST /api/fix            → {wish_id, position}     (409 if traffic is smooth; cooldowns)
+GET  /api/stream         → SSE (X-Accel-Buffering: no)
+GET  /api/wishes[, /{id}]→ ledger index / full trace (replay)
+GET  /api/turn?wish_id=  → {token} (cookie-bound; ZeroGPU browser-invoke dance — copied)
+@app.api("grant")        → gradio endpoint the petitioner's browser calls (their GPU quota)
+GET  /                   → web/ static (mounted AFTER launch — the route-eviction trick, copied)
+```
+
+SSE events (godseed names + ONE new event):
+```
+{type:"hello", world_version, epoch, server_now}
+{type:"queue", length, current}
+{type:"wish_started", wish_id, text}
+{type:"plan", wish_id, plan:{...raw validated LLM JSON...}}   ← NEW: City Hall paperwork (NVIDIA evidence, shown in UI)
+{type:"tool_call", wish_id, call_index, tool, args}
+{type:"world_delta", feature:{...}}
+{type:"wish_granted", wish_id, epitaph, epoch}    (epitaph = the blurb)
+{type:"wish_rejected", wish_id, reason}
+{type:"heartbeat", server_now}
+```
+
+Env vars: `CITY_BACKEND` (mock|zerogpu; llamacpp stretch), `CITY_DATASET`, `CITY_JUDGE`,
+`CITY_INVOKE`, `CITY_MOCK_DELAY`, `CITY_SECRET`, `CITY_HF_MODEL`, `HF_TOKEN`, `PORT`.
+Rate limits: 3 petitions/hr/client (cookie+IP), 1 pending/client, queue cap 50, fix cooldowns.
+
+## Visual Bible — "Golden Hour Toybox" (miniature diorama / tilt-shift)
+
+**Thesis: the city should feel like a hand-built miniature model village on a sunlit table —
+small enough to love, alive enough to watch grow.** ("Build Small" made literal.)
+
+Palette (hex — `web/city/palette.js` carries these; AGENT-RFOUND owns it. constants.js holds
+only engine-mirrored values since gen_web.py overwrites it):
+- Ground: lawn `#8FC474` (±3% per-cell lightness jitter, vertex colors), park `#6FB257`,
+  dirt lot `#CFB78F`. Water `#58AFC7` (darken 12% center). Sidewalk `#D6D2C4` w/ 0.06 u curb lip.
+- Roads: asphalt `#565B66` (warm dark gray, never black), markings warm-white `#F5F1E6`,
+  center-line yellow `#EFC75E`.
+- Facades (8, seeded ±6° hue ±5% lightness jitter): cream `#F4E9D0`, terracotta `#E07856`,
+  butter `#F2CC8F`, coral `#EC9AA2`, powder blue `#8FB8D8`, dusty teal `#7FB69E`, sage
+  `#A9B98A`, brick `#BD6B6E`. Civic white `#F8F4EA` (bank/town_hall/hospital/church).
+- Roofs: clay `#C06B4F` (houses/church), slate `#5C6470` (apartments/school), charcoal
+  `#3F454F` (offices/towers), gravel `#D9D5CB` (flat commercial — HVAC boxes read).
+- Sky: day zenith `#7BC1E8` / horizon `#FFE9C2`; night zenith `#141C36` / horizon `#2C3760`
+  (indigo, never black). Fog = horizon color (day near 140 far 420; night near 100 far 360).
+- Emissives (night money colors): window glow `#FFC97A`, streetlamp `#FFD9A0`, headlight
+  `#FFF6DC`, taillight/signal red `#FF5340`, signal amber `#FFB13D`, signal green `#43D17C`,
+  neon teal `#45E0C0`, neon pink `#FF6FA6`, construction orange `#FF8A3D`, congestion red
+  underglow `#E84F3D`.
+
+Lighting: ONE shadow-casting DirectionalLight (the sun), golden-hour default `#FFCE96` @ 2.4,
+elev 28°, az 235°; arcs with the day cycle (noon `#FFE3BB` @2.8 elev 62°; dusk `#FF9E62` @1.2;
+night = moon `#8FA8D8` @0.15). PCFSoftShadowMap, map 2048 (1024 small), ortho frustum fit to
+city bounds +10%, texel-snapped, re-fit only on growth; bias −0.00035, normalBias 0.5. Casters:
+building InstancedMeshes + trees ONLY. Cars/citizens/trees use instanced radial-gradient blob
+quads (sells the miniature). Hemisphere fill sky `#BCD7EA`/ground `#C7B18E` @0.6 day →
+`#2B3450`/`#161B28` @0.3 night. NO AmbientLight. RoomEnvironment PMREM, envMapIntensity 0.25
+per-material. Max 4 PointLights citywide (active construction, newest build). Window emissives
+stagger on over ~8 s at dusk (in-shader hash threshold — zero CPU).
+
+Postprocessing (in order): RenderPass → UnrealBloomPass (DAY 0.32/0.35/0.85 — pastel facades
+must NOT glow in daylight; NIGHT 0.70/0.45/0.62; lerp by daylight) → tilt-shift H pass →
+tilt-shift V pass (+ grade folded in: saturation +8%, warm shadow lift +0.02, vignette
+0.25/0.75) → OutputPass. Tilt-shift = classic separable 9-tap Gaussian, weights
+[.051 .0918 .12 .1531 .1633 .1531 .12 .0918 .051], per-fragment radius
+`maxBlur * smoothstep(bandHalf, bandHalf+falloff, abs(vUv.y - focusY))`, focusY tracks the
+orbit target's screen y, bandHalf 0.13, falloff 0.22, maxBlur 2.2 px × pixelRatio. Amount: 1.0
+god view → lerp to 0 between camera heights 60→25 m → **0.0 in FPV (hard requirement — DoF in
+first person is nauseating)**. MSAA: composer target `samples: 4` (2 on small). NO BokehPass,
+NO SSAO — fake AO: baked dark edges in the road atlas + instanced contact-shadow quads under
+every building (footprint ×1.25, opacity 0.22) + tree blobs ×0.5.
+
+Roads/ground: ground = one plane per 16×16-cell chunk, vertex-colored per cell. Roads = flat
+quads y=0.02, ONE InstancedMesh, per-instance UV offset into a procedurally-drawn 512² canvas
+atlas (8 tiles: street straight, avenue straight, intersection, crosswalk approach, T-junction,
+parking edge, dirt, plaza paving) — dashes/stop lines/crosswalks PAINTED in the atlas, zero
+extra geometry, 6 px soft dark edge baked. Sidewalk curb strips instanced on road cells adjacent
+to zoned cells. Street furniture: instanced lamp posts every 3rd road cell (emissive head +
+fake light-pool quad at night), hydrants/mailbox dots at corners, 10% density.
+
+Buildings (19 kinds): assembled from a shared low-poly part kit (wall box, gabled/flat roof,
+awning, AC boxes, water tower, chimney, steeple, smokestack, drive-thru-style signage on shop/
+cafe, fire-escape strip on apartments) — ONE InstancedMesh per part archetype with
+instanceColor; whole city ≈ 10–14 draw calls. Windows: ONE GLOBAL InstancedMesh citywide,
+emissive atlas, in-shader night flicker. Signature silhouettes matter more than detail: water
+towers on apartments, AC clusters, awnings + sidewalk tables on cafes (neon at night), sawtooth
+factory roof + smokestack, hospital cross, church steeple, stadium light masts, town_hall dome.
+
+Motion: cars = two-box kit (body + cabin, dark skirt fakes wheels), 7 seeded paint colors,
+right-lane offset, ease at intersections, ±2° pitch bobble on accel/brake; night headlight
+emissive dots + 2 short additive cone quads + taillights. Citizens = instanced capsule + head,
+2-tone seeded clothes, 1.5 Hz walk bob; spawn near homes dawn / shops midday / drain home at
+dusk. Construction (the "watch it being built" payoff): [0,.12] dirt + dust ring → (.12,.30]
+orange scaffold wireframe pops to height (+ barrier cubes + blinking amber) + kit crane (mast,
+counterweighted jib rotating 0.15 rad/s) on ≥4-floor builds → (.30,.90] floors rise in
+quantized easeOutBack steps → (.90,1] scaffold drops, windows light bottom-to-top, sparkle +
+floating name label ("Cafe Luna — built for visitor #12"). Roads: a roller prop sweeps the path
+painting asphalt over 4 s; bridges add a deck-drop. Idle cranes over a skyline = a city mid-boom.
+
+Landing choreography (first paint <1 s, ZERO model calls, no spinner ever): T+0 frame one IS
+the screenshot — golden hour, long shadows, camera LOW (~10 m) behind a moving car on Main St,
+tilt-shift full. T0–3.5 s slow dolly forward along the avenue. T3.5–7 s single eased crane up +
+pull back to god view (38° pitch, downtown rule-of-thirds left, skyline against warm horizon).
+T7–10 s gentle 0.5°/s drift; a guaranteed construction event plays in view (if the live queue
+is empty the client keeps one scripted "welcome build" so a crane is ALWAYS rising when a judge
+arrives); ticker types its first headline; petition input pulses once. Any input cancels →
+orbit camera. Walk button drops to FPV (tilt-shift fades 0.4 s).
+
+HUD ("museum placards around a diorama" — labels NEXT TO the model, never chrome OVER it):
+fonts = Bricolage Grotesque 600/800 (display), Schibsted Grotesk 400/500 (UI), Spline Sans Mono
+(ticker/queue). Panels: warm frosted glass — `rgba(252,249,242,0.78)`, blur(14px), 1px
+`rgba(60,50,40,0.12)` border, radius 14px, text `#2A2620`; panels stay light at night (lit
+placards in a dark gallery). Layout: top-left city name + stat chips (population odometer,
+buildings, Traffic Index color-coded, day clock, "Built by N visitors"); bottom-center ONE
+rounded petition field + Build button (placeholder cycles: "a ramen shop near the park…", "a
+fire station downtown…"), lifecycle chips above it (queued → city hall is reading (animated
+ellipsis) → under construction → built, each with jump-camera link); bottom edge 28 px
+news-ticker (mono, LLM blurbs as headlines: "MAYOR CUTS RIBBON ON CAFE LUNA — TRAFFIC ON OLD
+BRIDGE UP 12%"); top-right: Walk toggle, sound toggle, PHOTO button (fades ALL UI for clean
+screenshots). Accents: terracotta #E07856 primary, congestion red only for traffic warnings.
+A "City Hall paperwork" drawer shows the raw Nemotron JSON per petition (NVIDIA evidence).
+Chrome <15% of screen; every panel fades 250 ms.
+
+Sound (stretch, OFF until toggled): WebAudio-synthesized only — filtered-noise traffic hum,
+bird blips day / cricket ticks night, soft thunk per construction floor, marimba chime on
+grant, single honk when a jam forms.
+
+## FPV walk mode (web/city/fpv.js)
+
+- Vendored `lib/addons/controls/PointerLockControls.js` (r160) for look; fpv.js adds WASD
+  (target 5 m/s, Shift 9 m/s, exponential accel/decel) integrated in the FIXED-STEP tick.
+- Eye height 1.65 m; camera near 0.1 far 1500 (fog covers the horizon).
+- Collision: occupancy-grid only — player circle r=0.35 m; test X and Z displacement
+  independently against building cells, cancel only the blocked axis (axis-slide). Roads,
+  sidewalks, parks, plazas walkable; water blocks (except bridge cells); clamp to city plot
+  −2-cell margin with soft vignette hint.
+- Enter: "Walk" button / F key → requestPointerLock, 300 ms fade, spawn at nearest road cell to
+  camera look-point. Exit: pointerlockchange (NOT keydown ESC) → restore orbit rig over player.
+- ONE camera, one scene — FPV is a controller swap via scene.js's rig-swap hook. Tilt-shift
+  amount = 0 in FPV. Mobile: hide the Walk button on touch (v0); dual-zone joystick is stretch.
+
+## Perf budgets (enforced, not hoped)
+
+Targets: 60 fps mid laptop, <300 draw calls, <1.2 M tris, pixelRatio ≤2 (1.7 small).
+Caps: buildings ≤400, cars ≤120, pedestrians ≤80, trees/props ≤1500, road cells ≤600.
+InstancedMesh per part-archetype (NEVER one Group per building — godseed's per-structure
+PointLight habit dies at city scale). Static meshes matrixAutoUpdate=false. Roads/river/ground
+rebuilt only on road events. A* cached per road_version, incremental re-solve ≤20 paths/frame.
+Degrade ladder (fps<45 for 3 s or hardwareConcurrency≤4): halve cars+peds → bloom off ��
+shadows off → pixelRatio 1. LOD: beyond 180 m swap buildings to untextured-box instance set,
+hide pedestrians. All canvas atlases generated once at boot. dispose() discipline on
+construction particles.
+
+## Local dev + verification
+
+- Python 3.12 venv via uv: `uv venv -p 3.12 .venv && uv pip install -r requirements.txt`
+  (mock backend needs NO ML deps — fastapi/uvicorn/gradio/pydantic/hub only).
+- `CITY_BACKEND=mock PORT=7900 .venv/bin/python app.py` → http://localhost:7900
+- Renderer standalone: `python3 -m http.server 8123 --directory web` + `?mock=1`
+  (web/mock/world.json + feed.js; zero backend).
+- **The screenshot-and-LOOK loop is mandatory** (don't ship the first thing that renders):
+  `node tools/shot.mjs` variants — god view day, god view night, street FPV, construction
+  close-up, heatmap on. window.__app harness (seek/tick/stats) must keep working.
+- pytest: engine (placement determinism, clamps, genesis validity, traffic acceptance), mind
+  (parse/salvage/fallback), api (SSE flow, rate limits, fix gate, injected fakes).
+
+## Blueprint Update (v1.1 contract — June 12 PM. ⚠️ NOT part of the v0 build wave: v0 agents
+## and the v0 integrator IGNORE this section entirely. It ships as its own wave after v0 verifies.)
+
+User-requested: petitions like "a Korean BBQ restaurant" must produce a building that looks
+UNIQUE — not just the generic cafe model. Mechanism: **bones + LLM-designed decoration**. The
+kit archetype is the bones (walls/floors/windows/roof — unchanged, instanced, fast); Nemotron
+additionally emits a compact STYLE BLUEPRINT the deterministic renderer interprets. No 3D-gen
+model (slow, ugly, non-deterministic, breaks zero-GPU replay); the LLM becomes the *architect*
+— a stronger Nemotron-load-bearing story, and the blueprint JSON shows in the paperwork drawer.
+
+Backwards compatible: `place_building.args.style` is OPTIONAL. Absent/partial style → engine
+fills a seeded per-kind default pack, so old events and fallback builds render unchanged-or-richer.
+
+### style schema (LLM-emitted inside each buildings[] entry; engine clamps EVERYTHING)
+
+```json
+"style": {
+  "facade_hue": 12, "trim_hue": 350,
+  "roof": "flat|gabled|hipped|sawtooth|dome|pagoda",
+  "roof_color": "clay|slate|charcoal|gravel|copper",
+  "windows": "grid|tall|arched|round|shoji",
+  "awning": {"hues": [350, 40], "shape": "flat|scalloped"},
+  "sign": {"style": "hanging|vertical|rooftop|window", "neon_hue": 0,
+            "icon": "bowl|flame|cup|leaf|star|fish|bread|music|cross|book|gear|heart|moon|paw|cart|none"},
+  "props": ["lanterns", "smoke_vent"],
+  "vibe": "charcoal smoke and red neon"
+}
+```
+
+- Enum-heavy on purpose (9B-reliable). Engine: unknown enum → dropped/default; hues → 0..360;
+  `props` ≤4 from: lanterns, string_lights, plants, umbrellas, barrels, crates, smoke_vent,
+  chimney_smoke, banner, menu_board, bike_rack, flag, grill_smoke. `vibe` ≤40 chars is
+  TOOLTIP/ticker text only — NEVER rendered as world geometry.
+- The sign renders the building **name** (already wordlist-moderated — the only world text) +
+  icon glyph + neon hue. Sign textures live in ONE shared canvas atlas (256×128/slot, grown in
+  chunks); sign quads instanced with per-instance UV offset. Icons = ~16 pre-drawn glyphs.
+- Props are instanced prop archetypes (a lantern string = sagging line + emissive spheres;
+  smoke = ONE shared particle system with per-emitter offsets). All bounded: ≤4/building.
+- Seeded default packs per kind (engine table): e.g. cafe → menu_board+awning+window sign;
+  factory → smoke stack already in kit. Defaults keyed by `seed` so two unstyle'd houses differ.
+- Prompt addition (mind): "Design the building too: pick a roof, windows, awning, a sign icon
+  and neon color, and up to 3 props that match the petition's culture/cuisine/mood. A Korean
+  BBQ wants flame icon, smoke_vent, grill_smoke, red neon; a ramen shop wants bowl icon,
+  lanterns, banner." max_new_tokens 700 → 900.
+- File ownership for this wave: ENGINE (tools.py style clamp tables + default packs +
+  constants), MIND (prompts/validate/mock_scripts style), RKIT (buildings.js decor layer:
+  sign atlas, prop archetypes, roof/window variants), UI (paperwork drawer shows style;
+  tooltip vibe). gen_web.py mirrors the style enums.
+
+## Deploy (June 12 night / 13 morning — see hf-spaces-deploy-pins memory for war stories)
+
+1. README YAML: `sdk: gradio`, `app_file: app.py`, **NO sdk_version** (transformers≥5.4 has
+   nemotron_h IN-TREE, pairs with default gradio 6.18/hub≥1.5 — godseed's final shipped recipe).
+   `models: [nvidia/NVIDIA-Nemotron-Nano-9B-v2]`, `datasets: [AndresCarreon/nemocity-world]`,
+   tags: `build-small-hackathon, track:wood, sponsor:nvidia, achievement:offbrand,
+   achievement:sharing, achievement:fieldnotes, thousand-token-wood, nemotron, nvidia,
+   simulation, city-builder, world-building, three-js, multiplayer` (+offgrid/llama if the
+   llamacpp path ships). README must LINK demo video + social post (placeholders until June 13/14).
+2. requirements.txt: fastapi>=0.115, uvicorn>=0.30, pydantic>=2.7, huggingface_hub>=0.30,
+   transformers>=5.4, accelerate, einops, sentencepiece. **NEVER pin gradio/spaces/torch**
+   (image force-installs them). NO mamba-ssm/causal-conv1d. dtype= (not torch_dtype=).
+3. app.py invariants (already copied): `import spaces` before torch when CITY_BACKEND=zerogpu;
+   gr.Server (no gr.Blocks); launch(prevent_thread_lock=True) THEN mount_static() route
+   eviction; ensure_worker lazy start; SSE X-Accel-Buffering: no; SameSite=None+Secure cookies.
+4. Space: `build-small-hackathon/nemocity` + dataset `AndresCarreon/nemocity-world`. Secrets:
+   HF_TOKEN; vars: CITY_DATASET, CITY_BACKEND=mock first. `request_space_hardware('zero-a10g')`.
+   Never set_space_sleep_time on ZeroGPU. Deploy mock → verify landing/SSE/persistence → flip
+   CITY_BACKEND=zerogpu → one real signed-in petition → tail logs.
+5. If the 9B fails to load: fall back to mock granting, KEEP SERVING the city (copied posture).

README.md

@@ -1,13 +1,147 @@
 ---
-title: Nemocity
-emoji: 📚
-colorFrom: gray
+title: NEMOCITY
+emoji: 🏙️
+colorFrom: red
 colorTo: yellow
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: 6.16.0
 app_file: app.py
 pinned: false
+license: mit
+short_description: Ask for a building, watch one tiny shared city rise
+models:
+  - nvidia/NVIDIA-Nemotron-Nano-9B-v2
+datasets:
+  - AndresCarreon/nemocity-world
+tags:
+  - build-small-hackathon
+  - track:wood
+  - sponsor:nvidia
+  - achievement:offbrand
+  - achievement:sharing
+  - achievement:fieldnotes
+  - thousand-token-wood
+  - nemotron
+  - nvidia
+  - simulation
+  - city-builder
+  - world-building
+  - three-js
+  - multiplayer
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<!-- ^ Space card config. app.py runs as a Gradio Server (gr.Server): it serves
+     the WebGL city at /, the JSON/SSE API under /api, and the gradio endpoint
+     that runs the granting call under /gradio_api. sdk_version 6.16.0 is the
+     pre-SSR gradio proven live on the org ZeroGPU (pareidolia) with this exact
+     launch pattern; pairs with transformers <5 (nemotron_h in-tree from 4.55.4). -->
+
+# NEMOCITY
+
+**Ask for a building and watch it rise — one tiny persistent city the whole
+internet builds, with a 9B Nemotron running city hall.**
+
+Type a petition — *"a ramen shop near the park"* — and a small NVIDIA Nemotron
+reads it at city hall, the deterministic engine zones a lot, and you (and every
+other visitor on Earth) watch it rise floor by floor in ONE shared miniature
+city. There is no level select and no reset button: your cafe stands next to a
+stranger's fire station, forever, on the same 64x64 grid.
+
+The city is alive between petitions. Cars commute on a shared deterministic
+clock, rush hour jams the Old Bridge twice a day, windows light at dusk, and a
+news ticker reads the model's blurbs as headlines. Press Walk and you are on the
+sidewalk in first person, at street level, under the buildings the internet
+asked for.
+
+The whole city renders client-side from an append-only event log — judges see a
+gorgeous living diorama with zero GPU spend. The GPU wakes exactly once per
+action, for one one-shot JSON generation.
+
+## How city hall works (the "her" pattern)
+
+The deterministic engine owns ALL facts: city state, placement, geometry, road
+routing, traffic telemetry. [NVIDIA-Nemotron-Nano-9B-v2](https://huggingface.co/nvidia/NVIDIA-Nemotron-Nano-9B-v2)
+never outputs a coordinate — it translates your petition into one tiny JSON
+permit (kinds, names, a fuzzy "near" hint) and narrates. The engine resolves,
+clamps, and repairs everything, so a visitor action ALWAYS yields visible
+construction. The model's raw JSON is shown in the UI on every action (the
+"City Hall paperwork" drawer).
+
+```
+        your petition ("a ramen shop near the park")
+            |
+            v
+   +- CITY HALL - Nemotron-Nano-9B-v2 (ONE one-shot call) -----+
+   |  {"intent":"build","blurb":"...",                         |
+   |   "buildings":[{"kind":"cafe","name":"Ramen Ichi",        |
+   |                 "near":"the park"}]}                      |
+   |  no coordinates, ever - kinds + names + fuzzy hints only  |
+   +------------------------------+----------------------------+
+                                  | permit JSON
+                                  v
+   +- THE ENGINE - deterministic Python -----------------------+
+   |  synonym-repairs kinds -> scores placement -> clamps      |
+   |  floors -> routes connector roads -> seeds + appends      |
+   |  events; owns ALL state, the model owns none of it        |
+   +------------------------------+----------------------------+
+                                  | world_delta (SSE broadcast)
+                                  v
+   +- THE CITY - Three.js, client-side, zero GPU ---------------+
+   |  pure function of (event list, shared simTime):           |
+   |  buildings rise floor by floor, cars commute, jams form   |
+   +------------------------------------------------------------+
+```
+
+## The traffic fix (ask the City Engineer)
+
+Rush hour is real, simulated telemetry — not theater. When a road segment stays
+jammed, a traffic alert appears with one button: **Ask the City Engineer**. The
+engine snapshots the facts (worst cells by demand/capacity with street names,
+the Traffic Index) and pre-validates candidate fixes with predicted outcomes by
+re-running its static traffic assignment. Nemotron gets `{stats, candidates}`
+and answers with a diagnosis citing the real numbers plus a choice — *"Old
+Bridge carries 3.1x capacity at rush — a second crossing cuts the index
+78 to 41."* The engine lays the new road, every client's cars re-route live, and
+the red drains green while you watch. Facts from the engine, judgment from the
+model — small models doing what small models are great at.
+
+## Built for Build Small — Thousand Token Wood
+
+- One model, 9B params, in-process on ZeroGPU — comfortably under the 32B cap.
+- **Off-Brand** — fully custom WebGL frontend on `gr.Server`; gradio powers the
+  API endpoints, not the visible UI.
+- **Sharing is Caring** — every petition's full trace (text, moderation verdict,
+  raw model JSON, resulting events) appends live to a public dataset:
+  [AndresCarreon/nemocity-world](https://huggingface.co/datasets/AndresCarreon/nemocity-world).
+  The dataset also makes the city persistent across Space restarts.
+- **Field Notes** — build log shipping with the submission.
+
+## Submission links
+
+<!-- TODO(fill-at-deploy): replace both placeholders before the deadline. -->
+
+- **Demo video:** *coming before the deadline — link will land here.*
+- **Social post:** *coming before the deadline — link will land here.*
+- **Trace dataset:** [AndresCarreon/nemocity-world](https://huggingface.co/datasets/AndresCarreon/nemocity-world)
+
+## Run it locally
+
+```bash
+uv venv -p 3.12 .venv && uv pip install -r requirements.txt
+CITY_BACKEND=mock PORT=7900 .venv/bin/python app.py   # open http://localhost:7900
+```
+
+Renderer alone (no backend): `python3 -m http.server 8123 --directory web` and
+open `http://localhost:8123/?mock=1`.
+
+Env: `CITY_BACKEND` (`mock | zerogpu`), `CITY_DATASET` + `HF_TOKEN` (trace
+publishing and persistence across restarts), `CITY_SECRET` (stable visitor
+identity), `CITY_JUDGE` (optional LLM moderation layer), `CITY_INVOKE`
+(`browser | server` GPU invocation), `CITY_MOCK_DELAY`, `CITY_HF_MODEL`, `PORT`.
+
+## Credits
+
+- **LLM:** NVIDIA Nemotron Nano 9B v2 (open weights), via transformers on ZeroGPU.
+- **Rendering:** [three.js](https://threejs.org) (MIT), vendored.
+
+*Ask, and the city builds.*

app.py

@@ -0,0 +1,649 @@
+"""NEMOCITY — Space entrypoint. gr.Server (FastAPI) + SSE + the WebGL city.
+
+One tiny persistent city the whole internet builds, with a 9B Nemotron at city hall.
+
+Wiring (ARCHITECTURE.md is the contract; wire names keep godseed's wish_*):
+
+  web/ (Three.js city)    <--  GET /            static (mounted after launch)
+  city snapshot           <--  GET /api/state   (includes server_now: shared sim clock)
+  file a petition         <--  POST /api/wish   (rate-limited, moderation fast-path)
+  ask the City Engineer   <--  POST /api/fix    (409 when traffic flows; cooldowns)
+  live event stream       <--  GET /api/stream  SSE broadcast (X-Accel-Buffering: no)
+  the grant token         <--  GET /api/turn    (cookie-authenticated; owner only)
+  grant the petition (GPU)<--  gradio @app.api "grant"  (runs in the visitor's quota)
+  ledger index            <--  GET /api/wishes
+  single trace (replay)   <--  GET /api/wishes/{id}
+
+Run:        python app.py                       (gr.Server launch on $PORT, default 7860)
+Backends:   CITY_BACKEND = mock | llamacpp | zerogpu   (default mock; live = zerogpu)
+Sync:       HF_TOKEN + CITY_DATASET enable trace persistence to an HF dataset.
+
+The deterministic engine owns all city state; the mind only interprets and narrates;
+this file only moves bytes. Engine/mind constructor assumptions are concentrated in
+``_default_wiring`` below — the single integration point.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import os
+import time
+
+# ZeroGPU runtime: the `spaces` lib must be imported before torch anywhere in
+# the process (it patches torch to virtualize the GPU). No-op everywhere else.
+if os.environ.get("CITY_BACKEND", "").strip().lower() == "zerogpu":
+    try:
+        import spaces  # noqa: F401
+    except ImportError:
+        pass
+    # No GPU exists at startup, so torch never loads its bundled CUDA runtime —
+    # best-effort preload of libcudart so any compiled kernel import resolves.
+    # (Harmless no-op on the in-tree nemotron_h path; kept from godseed.)
+    try:
+        import ctypes
+        import glob
+
+        for _lib in glob.glob(
+            "/usr/local/lib/python3*/site-packages/nvidia/cuda_runtime/lib/libcudart.so.12*"
+        ):
+            try:
+                ctypes.CDLL(_lib, mode=ctypes.RTLD_GLOBAL)
+                break
+            except OSError:
+                continue
+    except Exception:  # noqa: BLE001 — best-effort; worst case the slow path runs
+        pass
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, Callable, Optional, Protocol
+
+from fastapi import FastAPI, HTTPException, Query, Request, Response
+from fastapi.responses import JSONResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+
+from server.persistence import PersistenceService
+from server.ratelimit import (
+    COOKIE_NAME,
+    DEFAULT_IP_LIMIT,
+    ClientIdentity,
+    RateLimiter,
+    client_ip,
+)
+from server.schemas import (
+    QueueInfo,
+    StateResponse,
+    WishAccepted,
+    WishRequest,
+    WishSummary,
+    WorldState,
+)
+from server.sse import SSEHub
+
+log = logging.getLogger("nemocity")
+
+ROOT = Path(__file__).resolve().parent
+WEB_DIR = ROOT / "web"
+TRACES_DIR = ROOT / "traces"
+
+VALID_BACKENDS = ("mock", "llamacpp", "zerogpu")
+
+# City-hall voice for the unhappy paths — never a stack trace.
+RATE_LIMIT_REASON = (
+    "City hall hears three petitions an hour from one voice. "
+    "Walk the streets a while; come back when the lights change."
+)
+QUEUE_FULL_REASON = "City hall is swamped with paperwork; come back shortly."
+NOT_FOUND_REASON = "No such petition is on record."
+FIX_RATE_REASON = (
+    "The City Engineer takes two requests an hour from one visitor. "
+    "Watch the traffic a while; the jam isn't going anywhere."
+)
+FIX_COOLDOWN_REASON = (
+    "The City Engineer is already out on a call. Give the road crews two minutes."
+)
+TRAFFIC_SMOOTH_REASON = "Traffic is flowing smoothly."
+FIX_GLOBAL_KEY = "fix:global"
+
+# Fix pacing per the contract: 2 requests/hr/client + ONE engineer citywide (120 s
+# global cooldown). Both expressed as sliding-window limiters so tests can inject
+# clocks.
+FIX_CLIENT_LIMIT = 2
+FIX_CLIENT_WINDOW_S = 3600.0
+FIX_GLOBAL_COOLDOWN_S = 120.0
+
+
+# --------------------------------------------------------------------------- protocols
+class WorldLike(Protocol):
+    """What the server reads from the engine's world (engine owns all writes)."""
+
+    version: int
+    epoch: int
+    features: list[dict[str, Any]]
+
+
+class QueueLike(Protocol):
+    """What the server needs from engine.queue_worker. submit_fix is optional
+    (hasattr-guarded): it enqueues a City Engineer job and raises TrafficSmooth
+    (matched by type name, never imported) when the static assignment gate says
+    there is nothing to fix."""
+
+    async def submit(self, text: str, client_id: str) -> tuple[str, int]: ...
+
+    def snapshot(self) -> dict[str, Any]: ...  # {"length": int, "current": {...}|None}
+
+
+FastCheck = Callable[[str], Optional[str]]  # returns a readable rejection reason or None
+
+
+# ----------------------------------------------------------------- default (real) wiring
+def _default_wiring(traces_dir: Path) -> dict[str, Any]:
+    """Build the real engine + mind stack. ALL cross-component wiring lives here so
+    integration fixes touch exactly one function."""
+    backend_name = os.environ.get("CITY_BACKEND", "mock").strip().lower() or "mock"
+    if backend_name not in VALID_BACKENDS:
+        log.warning("unknown CITY_BACKEND=%r; falling back to mock", backend_name)
+        backend_name = "mock"
+
+    from engine.genesis import genesis_features
+    from engine.moderation import Moderator
+    from engine.queue_worker import QueueWorker
+    from engine.world import World
+    from mind.backends import make_backend
+    from mind.moderation_judge import judge as judge_fn
+    from mind.planner import Planner
+
+    # Boot: restore wishes.jsonl from the dataset if configured, rebuild the ordered
+    # feature list (genesis + every trace's features), load the world verbatim.
+    persistence = PersistenceService(traces_dir)
+    features = persistence.boot(genesis_features())
+    epitaphs = [t.get("epitaph") for t in persistence.traces() if t.get("epitaph")]
+    world = World.load(features, epitaphs)
+
+    # The zerogpu backend eager-loads the 9B at construction (ZeroGPU needs the
+    # weights resident before the first request). If that fails — OOM, a model
+    # download hiccup — DON'T crash-loop the whole Space: the city, the ledger
+    # and every zero-GPU view must still serve. Fall back to mock so visitors
+    # see the city; granting degrades to scripted until the Space is healthy.
+    try:
+        backend = make_backend(backend_name)
+    except Exception:
+        log.exception("backend %r failed to load; serving with mock granting", backend_name)
+        backend = make_backend("mock")
+        backend_name = "mock"
+    planner = Planner(backend)
+    # Moderation layers 1-2 (charset/length + a thorough wordlist with
+    # confusable/leetspeak/skeleton folding) are the reliable gate and run on
+    # EVERY petition. Layer 3 (an LLM yes/no judge through the same model) is
+    # opt-in: its constrained verdict can fail to parse and then DEFAULT-DENY
+    # every clean petition (godseed, June 12). Off by default; CITY_JUDGE=on
+    # re-enables it.
+    use_judge = os.environ.get("CITY_JUDGE", "").strip().lower() in ("1", "on", "true")
+    judge = (lambda text: judge_fn(text, backend)) if use_judge else None
+    moderator = Moderator(judge=judge)
+
+    def fast_check(text: str) -> Optional[str]:
+        verdict = moderator.precheck(text)
+        if verdict.allowed:
+            return None
+        return verdict.poetic_reason or "City hall declines this petition."
+
+    hub = SSEHub()
+
+    async def persist(trace: Any) -> None:
+        """Worker hands over the WishTrace; embed the wish's engine-built features
+        (filtered from the world by wish_id) so boot rebuild is exact."""
+        if not isinstance(trace, dict):
+            trace = dict(getattr(trace, "__dict__", None) or {})
+        wish_id = trace.get("wish_id")
+        wish_features = [
+            f.to_dict() for f in world.features if f.wish_id == wish_id
+        ]
+        trace.setdefault("feature_ids", [f["id"] for f in wish_features])
+        await persistence.record(trace, wish_features)
+
+    # ZeroGPU: GPU work must run inside the petitioner's gradio request (their HF
+    # auth headers carry the quota), so the worker hands the grant to the browser
+    # via your_turn/invoke. Override with CITY_INVOKE=server|browser.
+    invoke_mode = os.environ.get("CITY_INVOKE", "").strip().lower()
+    browser_invoked = (
+        invoke_mode == "browser"
+        if invoke_mode in ("browser", "server")
+        else backend_name == "zerogpu"
+    )
+    # Wish numbering must survive zero-feature petitions across restarts: the
+    # worker derives its counter from WORLD features, but a petition whose calls
+    # all failed leaves no feature — after a restart the same id was reissued
+    # (godseed June 12: two w_000004 in the log). Traces are the complete record.
+    import re as _re
+
+    trace_max = 0
+    for t in persistence.traces():
+        m = _re.match(r"w_(\d{6})$", str(t.get("wish_id") or ""))
+        if m:
+            trace_max = max(trace_max, int(m.group(1)))
+    queue = QueueWorker(
+        world=world,
+        moderator=moderator,
+        planner=planner,
+        emit=hub.emit,
+        persist=persist,
+        browser_invoked=browser_invoked,
+        next_wish_index=max(QueueWorker._derive_wish_counter(world), trace_max + 1),
+    )
+    log.info(
+        "nemocity wired: backend=%s features=%d traces=%d dataset=%s",
+        backend_name,
+        world.version,
+        len(persistence.traces()),
+        persistence.sync.dataset if persistence.sync.enabled else "off",
+    )
+    return {
+        "world": world,
+        "queue": queue,
+        "hub": hub,
+        "persistence": persistence,
+        "fast_check": fast_check,
+    }
+
+
+# --------------------------------------------------------------------------- helpers
+async def _maybe_await(result: Any) -> Any:
+    if inspect.isawaitable(result):
+        return await result
+    return result
+
+
+def _set_identity_cookie(response: Response, request: Request, value: str) -> None:
+    """Spaces serve over https inside an iframe (cross-site -> SameSite=None+Secure);
+    local dev is plain http (Lax, not Secure)."""
+    scheme = request.headers.get("x-forwarded-proto", request.url.scheme)
+    secure = scheme == "https"
+    response.set_cookie(
+        COOKIE_NAME,
+        value,
+        max_age=365 * 24 * 3600,
+        path="/",
+        httponly=True,
+        secure=secure,
+        samesite="none" if secure else "lax",
+    )
+
+
+def _world_state(world: WorldLike) -> WorldState:
+    # engine.world.World exposes state_dict() (features as plain dicts); the model
+    # ignores its extra derived keys. Attribute fallback covers simpler worlds.
+    if hasattr(world, "state_dict"):
+        return WorldState.model_validate(world.state_dict())
+    return WorldState(
+        version=int(world.version),
+        epoch=int(world.epoch),
+        features=list(world.features),
+    )
+
+
+def _queue_info(queue: QueueLike) -> QueueInfo:
+    try:
+        snapshot = queue.snapshot() or {}
+    except Exception:  # noqa: BLE001 — a queue hiccup must not kill /api/state
+        log.exception("queue snapshot failed")
+        snapshot = {}
+    return QueueInfo.model_validate(
+        {"length": snapshot.get("length", 0), "current": snapshot.get("current")}
+    )
+
+
+def _wish_summary(trace: dict[str, Any], epoch: int) -> WishSummary:
+    return WishSummary(
+        wish_id=str(trace.get("wish_id", "")),
+        text=str(trace.get("text", "")),
+        epitaph=str(trace.get("epitaph") or ""),
+        epoch=epoch,
+        ts=float(trace.get("submitted_at") or 0.0),
+    )
+
+
+# --------------------------------------------------------------------------- the app
+def create_app(
+    *,
+    world: Optional[WorldLike] = None,
+    queue: Optional[QueueLike] = None,
+    hub: Optional[SSEHub] = None,
+    persistence: Optional[PersistenceService] = None,
+    fast_check: Optional[FastCheck] = None,
+    rate_limiter: Optional[RateLimiter] = None,
+    ip_rate_limiter: Optional[RateLimiter] = None,
+    fix_rate_limiter: Optional[RateLimiter] = None,
+    fix_cooldown: Optional[RateLimiter] = None,
+    identity: Optional[ClientIdentity] = None,
+    traces_dir: Optional[Path | str] = None,
+    mount_web: bool = True,
+    mount_panel: bool = True,
+) -> FastAPI:
+    """Build the ASGI app. With no arguments this wires the real engine + mind from
+    env config; tests inject fakes for everything engine/mind-shaped."""
+    traces_path = Path(traces_dir) if traces_dir is not None else TRACES_DIR
+
+    if queue is None:
+        wired = _default_wiring(traces_path)
+        world = wired["world"]
+        queue = wired["queue"]
+        # The default queue emits into the hub _default_wiring built; an injected hub
+        # is only honored together with an injected queue.
+        hub = wired["hub"]
+        persistence = wired["persistence"]
+        fast_check = wired["fast_check"]
+    if world is None or hub is None or persistence is None:
+        raise ValueError(
+            "create_app: when injecting `queue`, also inject `world`, `hub`, and "
+            "`persistence`"
+        )
+
+    rate_limiter = rate_limiter or RateLimiter()
+    ip_rate_limiter = ip_rate_limiter or RateLimiter(limit=DEFAULT_IP_LIMIT)
+    fix_rate_limiter = fix_rate_limiter or RateLimiter(
+        limit=FIX_CLIENT_LIMIT, window=FIX_CLIENT_WINDOW_S
+    )
+    fix_cooldown = fix_cooldown or RateLimiter(limit=1, window=FIX_GLOBAL_COOLDOWN_S)
+    identity = identity or ClientIdentity()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        queue_task: Optional[asyncio.Task[Any]] = None
+        if hasattr(queue, "start"):
+            await _maybe_await(queue.start())
+        elif hasattr(queue, "run"):
+            queue_task = asyncio.create_task(queue.run())
+        yield
+        if hasattr(queue, "stop"):
+            await _maybe_await(queue.stop())
+        elif queue_task is not None:
+            queue_task.cancel()
+            await asyncio.gather(queue_task, return_exceptions=True)
+        await persistence.drain()
+
+    # Gradio Server mode (the "her" idiom): gr.Server IS a FastAPI app with
+    # gradio's API engine attached — the sdk:gradio runtime serves it natively,
+    # and @app.api endpoints are gradio endpoints the browser calls via
+    # @gradio/client, which forwards the HF auth headers ZeroGPU quota needs.
+    try:
+        import gradio as gr
+
+        app: FastAPI = gr.Server(title="NEMOCITY")
+        app.router.lifespan_context = lifespan
+    except Exception:  # pragma: no cover — gradio always present in prod
+        app = FastAPI(title="NEMOCITY", docs_url=None, redoc_url=None, lifespan=lifespan)
+    app.state.world = world
+    app.state.queue = queue
+    app.state.hub = hub
+    app.state.persistence = persistence
+
+    async def ensure_worker() -> None:
+        """Start the queue worker on the SERVING event loop, lazily. gradio's
+        launch() runs uvicorn without honoring an injected lifespan (verified
+        June 12: the worker never started under Server mode), so the first
+        request opens city hall instead. Idempotent and loop-correct everywhere."""
+        if (
+            hasattr(queue, "start")
+            and hasattr(queue, "is_running")
+            and not queue.is_running
+        ):
+            await _maybe_await(queue.start())
+
+    # GPU grant endpoint: when the queue announces your_turn over SSE, the
+    # petitioner's browser calls this named gradio endpoint with the one-time token.
+    if hasattr(app, "api") and hasattr(queue, "invoke"):
+
+        @app.api(name="grant")
+        async def grant(wish_id: str = "", token: str = "") -> dict:
+            try:
+                await ensure_worker()
+                return await queue.invoke(wish_id, token)
+            except Exception as exc:
+                reason = (
+                    getattr(exc, "reason", None)
+                    or "the permit fell through; city hall moved on"
+                )
+                return {"ok": False, "wish_id": wish_id, "reason": str(reason)}
+
+    # ------------------------------------------------------------------- /api/turn
+    # The owner's browser fetches its secret invocation token here. The token is
+    # identity-bound (signed cookie) and never broadcast over SSE, so a stranger
+    # tailing /api/stream cannot steal another visitor's turn (verify-fleet
+    # critical, June 12). A plain FastAPI route DOES see the cookie (unlike the
+    # gradio @app.api endpoint), which is why the auth check lives here.
+    if hasattr(queue, "turn_token"):
+
+        @app.get("/api/turn", include_in_schema=False)
+        async def turn(wish_id: str, request: Request, response: Response) -> JSONResponse:
+            await ensure_worker()
+            cid, new_cookie = identity.resolve(request)
+            if new_cookie:
+                _set_identity_cookie(response, request, new_cookie)
+            tok = queue.turn_token(wish_id, cid)
+            if tok is None:
+                return JSONResponse({"error": "not your turn"}, status_code=403)
+            return JSONResponse({"wish_id": wish_id, "token": tok})
+
+    # ------------------------------------------------------------------- /api/state
+    @app.get("/api/state", response_model=StateResponse)
+    async def get_state() -> StateResponse:
+        await ensure_worker()
+        traces = persistence.traces()
+        recent = [
+            _wish_summary(trace, epoch)
+            for epoch, trace in enumerate(traces, start=1)
+        ][-10:][::-1]
+        return StateResponse(
+            world=_world_state(world),
+            queue=_queue_info(queue),
+            wishes_recent=recent,
+            server_now=time.time(),
+        )
+
+    # -------------------------------------------------------------------- /api/wish
+    @app.post("/api/wish", response_model=WishAccepted)
+    async def post_wish(
+        payload: WishRequest, request: Request, response: Response
+    ) -> WishAccepted:
+        await ensure_worker()
+        cid, new_cookie = identity.resolve(request)
+        if new_cookie:
+            _set_identity_cookie(response, request, new_cookie)
+
+        ip_ok, ip_retry = ip_rate_limiter.hit(f"ip:{client_ip(request)}")
+        allowed, retry_after = (
+            rate_limiter.hit(cid) if ip_ok else (False, ip_retry)
+        )
+        if not allowed:
+            raise HTTPException(
+                status_code=429,
+                detail=RATE_LIMIT_REASON,
+                headers={"Retry-After": str(int(retry_after) + 1)},
+            )
+
+        if fast_check is not None:
+            reason = fast_check(payload.text)
+            if reason:
+                raise HTTPException(status_code=400, detail=str(reason))
+
+        try:
+            wish_id, position = await queue.submit(payload.text, cid)
+        except HTTPException:
+            raise
+        except Exception as exc:  # queue full / per-client pending cap (engine policy)
+            log.info("petition refused by queue: %s", exc)
+            # engine.queue_worker raises QueueError subclasses with a readable .reason;
+            # AlreadyPending is a client-pacing problem (429), the rest read as 503.
+            status = int(getattr(exc, "status_code", 0)) or (
+                429 if type(exc).__name__ == "AlreadyPending" else 503
+            )
+            detail = str(getattr(exc, "reason", "") or exc) or QUEUE_FULL_REASON
+            raise HTTPException(status_code=status, detail=detail) from exc
+        return WishAccepted(wish_id=wish_id, position=position)
+
+    # --------------------------------------------------------------------- /api/fix
+    # "Ask the City Engineer": rate-limited per client AND a single global 120 s
+    # cooldown (there is one engineer citywide — every visitor shares the result
+    # anyway, it lands as a world_delta on the SSE stream). The engine's static
+    # assignment gate decides whether there is actually a jam: queue.submit_fix
+    # raises TrafficSmooth (matched by name; the server never imports the engine)
+    # and the client gets a flat 409.
+    if hasattr(queue, "submit_fix"):
+
+        @app.post("/api/fix", response_model=WishAccepted)
+        async def post_fix(request: Request, response: Response) -> WishAccepted:
+            await ensure_worker()
+            cid, new_cookie = identity.resolve(request)
+            if new_cookie:
+                _set_identity_cookie(response, request, new_cookie)
+
+            allowed, retry_after = fix_rate_limiter.hit(f"fix:{cid}")
+            if not allowed:
+                raise HTTPException(
+                    status_code=429,
+                    detail=FIX_RATE_REASON,
+                    headers={"Retry-After": str(int(retry_after) + 1)},
+                )
+            # Peek-then-commit: a 409 must NOT engage the citywide cooldown, or one
+            # visitor's no-op click blocks everyone's engineer for two minutes.
+            if fix_cooldown.remaining(FIX_GLOBAL_KEY) <= 0:
+                raise HTTPException(
+                    status_code=429,
+                    detail=FIX_COOLDOWN_REASON,
+                    headers={"Retry-After": str(int(fix_cooldown.window))},
+                )
+
+            try:
+                wish_id, position = await queue.submit_fix(cid)
+            except HTTPException:
+                raise
+            except Exception as exc:
+                if type(exc).__name__ == "TrafficSmooth":
+                    raise HTTPException(
+                        status_code=409, detail=TRAFFIC_SMOOTH_REASON
+                    ) from exc
+                log.info("fix refused by queue: %s", exc)
+                status = int(getattr(exc, "status_code", 0)) or (
+                    429 if type(exc).__name__ == "AlreadyPending" else 503
+                )
+                detail = str(getattr(exc, "reason", "") or exc) or QUEUE_FULL_REASON
+                raise HTTPException(status_code=status, detail=detail) from exc
+            fix_cooldown.hit(FIX_GLOBAL_KEY)
+            return WishAccepted(wish_id=wish_id, position=position)
+
+    # ------------------------------------------------------------------ /api/stream
+    @app.get("/api/stream")
+    async def stream(
+        limit: Optional[int] = Query(
+            default=None,
+            ge=1,
+            le=10_000,
+            description="debug/test aid: close the stream after N events",
+        ),
+    ) -> StreamingResponse:
+        initial = [
+            {
+                "type": "hello",
+                "world_version": int(world.version),
+                "epoch": int(world.epoch),
+                "server_now": time.time(),
+            },
+            {"type": "queue", **_queue_info(queue).model_dump()},
+        ]
+        return StreamingResponse(
+            hub.event_stream(initial_events=initial, limit=limit),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "X-Accel-Buffering": "no",  # required on Spaces or the proxy buffers
+                "Connection": "keep-alive",
+            },
+        )
+
+    # ----------------------------------------------------------- /api/wishes (ledger)
+    @app.get("/api/wishes", response_model=list[WishSummary])
+    async def wishes_index() -> list[WishSummary]:
+        return [
+            _wish_summary(trace, epoch)
+            for epoch, trace in enumerate(persistence.traces(), start=1)
+        ]
+
+    @app.get("/api/wishes/{wish_id}")
+    async def wish_trace(wish_id: str) -> JSONResponse:
+        trace = persistence.find(wish_id)
+        if trace is None:
+            raise HTTPException(status_code=404, detail=NOT_FOUND_REASON)
+        return JSONResponse(trace)
+
+    # ----------------------------------------------------------------------- static
+    # (No Blocks panel: in Server mode the whole app IS the gradio app — a
+    # Blocks instance would race the runtime's auto-launch for port 7860.)
+
+    def _mount_static() -> None:
+        """Root static mount. A "/" catch-all registered BEFORE gr.Server.launch()
+        shadows the /gradio_api routes gradio adds at launch time (verified June
+        12: the launch self-check 404s and the app dies). So the mount is
+        deferred: _serve() calls this AFTER launch; the plain-FastAPI/uvicorn
+        path mounts immediately below."""
+        if WEB_DIR.is_dir():
+            # gradio's launch registers its own SPA index at "/" (GET+HEAD) —
+            # evict exactly those so the city owns the root; every other
+            # gradio route (/config, /gradio_api/*, assets) must survive for
+            # @gradio/client connectivity.
+            app.router.routes[:] = [
+                r for r in app.router.routes if getattr(r, "path", None) != "/"
+            ]
+            app.mount("/", StaticFiles(directory=str(WEB_DIR), html=True), name="web")
+        else:
+            log.warning("web/ not found at %s; serving API only", WEB_DIR)
+
+            @app.get("/", include_in_schema=False)
+            async def root_placeholder() -> JSONResponse:
+                return JSONResponse({"ok": True, "hint": "frontend not built"})
+
+    app.state.mount_static = _mount_static
+    if mount_web and not hasattr(app, "launch"):
+        _mount_static()
+
+    return app
+
+
+# --------------------------------------------------------------------------- entrypoint
+def _serve(application: FastAPI) -> None:
+    port = int(os.environ.get("PORT", os.environ.get("GRADIO_SERVER_PORT", 7860)))
+    log.info("NEMOCITY listening on http://0.0.0.0:%d", port)
+    if hasattr(application, "launch"):
+        # Gradio Server mode — launch non-blocking so the web root can mount
+        # AFTER gradio registers its /gradio_api routes (order = precedence).
+        # sdk_version 6.16.0 (README) is the pre-SSR gradio: a single Python
+        # process owns the port, no Node proxy — the pattern pareidolia runs
+        # live on the org ZeroGPU. (gradio 6.18 default-SSR tore the process
+        # down right after launch on Spaces, June 14.)
+        application.launch(
+            server_name="0.0.0.0",
+            server_port=port,
+            show_error=False,
+            prevent_thread_lock=True,
+        )
+        mount_static = getattr(application.state, "mount_static", None)
+        if mount_static is not None:
+            mount_static()
+        import time as _time
+
+        while True:  # keep the process alive; the server runs in gradio's thread
+            _time.sleep(3600)
+    else:  # pragma: no cover — gradio-less dev fallback
+        import uvicorn
+
+        uvicorn.run(application, host="0.0.0.0", port=port)
+
+
+# HF Spaces (sdk:gradio) executes this file; locally it's `python app.py`.
+# Test imports leave both conditions false and get no side effects.
+if __name__ == "__main__" or os.environ.get("SPACE_ID"):
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s"
+    )
+    _serve(create_app())

engine/__init__.py

@@ -0,0 +1,42 @@
+"""NEMOCITY deterministic city engine.
+
+The engine owns ALL facts ("her" pattern): city state, the 4-event surface,
+placement geometry, traffic facts, moderation, the serialized petition queue,
+and the prompt summary. The LLM only interprets petitions into tiny JSON —
+it never owns state and never outputs coordinates.
+"""
+
+from .city import CityState
+from .genesis import GENESIS_FEATURES, genesis_features, genesis_world
+from .moderation import Moderator, Verdict
+from .queue_worker import (
+    AlreadyPending,
+    QueueError,
+    QueueFull,
+    QueueWorker,
+    TrafficSmooth,
+)
+from .summary import summarize
+from .tools import TOOL_NAMES, resolve_kind, sanitize_name, validate_call
+from .world import Feature, World
+
+__all__ = [
+    "CityState",
+    "GENESIS_FEATURES",
+    "genesis_features",
+    "genesis_world",
+    "Moderator",
+    "Verdict",
+    "AlreadyPending",
+    "QueueError",
+    "QueueFull",
+    "QueueWorker",
+    "TrafficSmooth",
+    "summarize",
+    "TOOL_NAMES",
+    "resolve_kind",
+    "sanitize_name",
+    "validate_call",
+    "Feature",
+    "World",
+]

engine/city.py

@@ -0,0 +1,246 @@
+"""NEMOCITY derived city state — a pure function of the event list.
+
+CityState is cheap to rebuild (from_events) and supports incremental apply()
+so the queue worker can keep one instance current while a petition lands.
+Nothing here is persisted: occupancy, the road graph, street names, tallies,
+growth radius and road_version are all derived.
+
+Determinism notes (the JS renderer mirrors parts of this):
+* street names: lay_road/apply_fix args carry an explicit name when the engine
+  composed one; events without a name fall back to the curated pool indexed by
+  crc32(event_id);
+* a re-laid road cell takes the LATER event's klass/name (upgrade_avenue
+  repaints in place);
+* building "door" = the road cell 4-adjacent to the footprint with the
+  smallest (cz, cx) — traffic.js must use the same rule.
+
+Pure stdlib.
+"""
+
+from __future__ import annotations
+
+import zlib
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Optional
+
+from . import constants as C
+
+Cell = tuple[int, int]  # (cx, cz)
+
+_NEIGHBORS_4: tuple[Cell, ...] = ((0, -1), (1, 0), (0, 1), (-1, 0))
+
+WATER_CELLS: frozenset[Cell] = frozenset(
+    (cx, cz)
+    for cz in range(C.COORD_MIN, C.COORD_MAX + 1)
+    for cx in C.river_cols(cz)
+)
+
+
+def in_bounds(cx: int, cz: int) -> bool:
+    return C.COORD_MIN <= cx <= C.COORD_MAX and C.COORD_MIN <= cz <= C.COORD_MAX
+
+
+def neighbors4(cell: Cell) -> list[Cell]:
+    cx, cz = cell
+    return [
+        (cx + dx, cz + dz)
+        for dx, dz in _NEIGHBORS_4
+        if in_bounds(cx + dx, cz + dz)
+    ]
+
+
+@dataclass
+class RoadCell:
+    klass: str
+    name: str
+    bridge: bool
+
+
+@dataclass
+class Building:
+    id: str
+    kind: str
+    name: str
+    cx: int
+    cz: int
+    w: int
+    d: int
+    floors: int
+    seed: int
+    t: float
+    cells: tuple[Cell, ...] = field(default_factory=tuple)
+
+    @property
+    def centroid(self) -> tuple[float, float]:
+        return (self.cx + (self.w - 1) / 2.0, self.cz + (self.d - 1) / 2.0)
+
+    def progress(self, now_s: float) -> float:
+        dur = C.BUILDINGS[self.kind]["duration_s"]
+        return min(max((now_s - self.t) / dur, 0.0), 1.0)
+
+
+def _event_fields(ev: Any) -> tuple[str, str, dict, int, float]:
+    if isinstance(ev, dict):
+        return (ev["id"], ev["tool"], ev.get("args") or {},
+                int(ev.get("seed", 0)), float(ev.get("t", 0)))
+    return (ev.id, ev.tool, ev.args or {}, int(ev.seed), float(ev.t))
+
+
+class CityState:
+    """Occupancy + road graph + registries derived from an event list."""
+
+    def __init__(self) -> None:
+        self.roads: dict[Cell, RoadCell] = {}
+        self.buildings: list[Building] = []
+        self.building_cells: dict[Cell, Building] = {}
+        self.road_version: int = 0
+        self._adjacency: Optional[dict[Cell, list[Cell]]] = None
+        self._street_cells: Optional[dict[str, list[Cell]]] = None
+
+    @classmethod
+    def from_events(cls, events: Iterable[Any]) -> "CityState":
+        city = cls()
+        for ev in events or ():
+            city.apply(ev)
+        return city
+
+    # ------------------------------------------------------------------ apply
+
+    def apply(self, ev: Any) -> None:
+        ev_id, tool, args, seed, t = _event_fields(ev)
+        if tool in ("lay_road", "apply_fix"):
+            name = args.get("name") or C.STREET_NAMES[
+                zlib.crc32(ev_id.encode()) % len(C.STREET_NAMES)
+            ]
+            klass = args.get("klass", "street")
+            for cx, cz in args.get("cells") or ():
+                cell = (int(cx), int(cz))
+                if not in_bounds(*cell) or cell in self.building_cells:
+                    continue
+                self.roads[cell] = RoadCell(
+                    klass=klass, name=name, bridge=cell in WATER_CELLS
+                )
+            self.road_version += 1
+            self._adjacency = None
+            self._street_cells = None
+        elif tool == "place_building":
+            b = Building(
+                id=ev_id, kind=args["kind"], name=args.get("name", ""),
+                cx=int(args["cx"]), cz=int(args["cz"]),
+                w=int(args.get("w") or C.BUILDINGS[args["kind"]]["w"]),
+                d=int(args.get("d") or C.BUILDINGS[args["kind"]]["d"]),
+                floors=int(args.get("floors", 1)), seed=seed, t=t,
+            )
+            b.cells = tuple(
+                (b.cx + dx, b.cz + dz) for dx in range(b.w) for dz in range(b.d)
+            )
+            self.buildings.append(b)
+            for cell in b.cells:
+                self.building_cells[cell] = b
+        # "note" mutates nothing
+
+    # ------------------------------------------------------------------ views
+
+    def is_empty(self, cell: Cell) -> bool:
+        return (
+            in_bounds(*cell)
+            and cell not in WATER_CELLS
+            and cell not in self.roads
+            and cell not in self.building_cells
+        )
+
+    def occupancy(self, cell: Cell) -> Optional[str]:
+        """'road' | 'water' | building kind | None (empty/off-grid)."""
+        if cell in self.roads:
+            return "road"
+        if cell in WATER_CELLS:
+            return "water"
+        b = self.building_cells.get(cell)
+        return b.kind if b else None
+
+    @property
+    def adjacency(self) -> dict[Cell, list[Cell]]:
+        """Road graph: node = road cell, edges between 4-adjacent road cells."""
+        if self._adjacency is None:
+            self._adjacency = {
+                cell: [n for n in neighbors4(cell) if n in self.roads]
+                for cell in self.roads
+            }
+        return self._adjacency
+
+    @property
+    def street_cells(self) -> dict[str, list[Cell]]:
+        """Street-name registry; cells in insertion order per name."""
+        if self._street_cells is None:
+            reg: dict[str, list[Cell]] = {}
+            for cell, rc in self.roads.items():
+                reg.setdefault(rc.name, []).append(cell)
+            self._street_cells = reg
+        return self._street_cells
+
+    def street_midpoint(self, name: str) -> Optional[Cell]:
+        cells = self.street_cells.get(name)
+        if not cells:
+            return None
+        return cells[len(cells) // 2]
+
+    def door(self, b: Building) -> Optional[Cell]:
+        """Frontage road cell: smallest (cz, cx) among cells adjacent to the
+        footprint. Mirrored by traffic.js — keep the ordering rule."""
+        adjacent = {
+            n for cell in b.cells for n in neighbors4(cell) if n in self.roads
+        }
+        if not adjacent:
+            return None
+        return min(adjacent, key=lambda c: (c[1], c[0]))
+
+    def population(self, now_s: float) -> int:
+        return int(sum(
+            C.BUILDINGS[b.kind]["residents"] * b.progress(now_s)
+            for b in self.buildings
+        ))
+
+    @property
+    def housing_capacity(self) -> int:
+        return sum(C.BUILDINGS[b.kind]["residents"] for b in self.buildings)
+
+    @property
+    def jobs(self) -> int:
+        return sum(C.BUILDINGS[b.kind]["jobs"] for b in self.buildings)
+
+    @property
+    def growth_radius(self) -> int:
+        r = C.GROWTH_RADIUS_MIN
+        for cell in self.roads:
+            r = max(r, abs(cell[0]), abs(cell[1]))
+        for cell in self.building_cells:
+            r = max(r, abs(cell[0]), abs(cell[1]))
+        return r
+
+    def counts_by_kind(self) -> dict[str, int]:
+        counts: dict[str, int] = {}
+        for b in self.buildings:
+            counts[b.kind] = counts.get(b.kind, 0) + 1
+        return counts
+
+    def find_building(self, text: str) -> Optional[Building]:
+        """Most recent building whose name matches `text` (folded substring,
+        either direction). Returns None when nothing matches."""
+        needle = str(text or "").strip().lower()
+        if not needle:
+            return None
+        for b in reversed(self.buildings):
+            name = b.name.lower()
+            if name and (name in needle or needle in name):
+                return b
+        return None
+
+    def find_street(self, text: str) -> Optional[str]:
+        needle = str(text or "").strip().lower()
+        if not needle:
+            return None
+        for name in self.street_cells:
+            low = name.lower()
+            if low and (low in needle or needle in low):
+                return name
+        return None

engine/constants.py

@@ -0,0 +1,141 @@
+"""NEMOCITY canonical constants — the single source of truth for grid, river,
+buildings, roads, traffic, and placement numbers (ARCHITECTURE.md mirrors these;
+tools/gen_web.py emits the JS copy). Pure data, stdlib only.
+"""
+
+from __future__ import annotations
+
+GRID = 64
+CELL = 4  # world units per cell (1 unit = 1 m)
+COORD_MIN, COORD_MAX = -32, 31  # cell coords (cx, cz) inclusive
+
+CITY_EPOCH_S = 1781222400  # June 12 2026 00:00 UTC
+DAY_S = 240  # one in-game day in real seconds
+
+
+def river_cols(cz: int) -> tuple[int, int]:
+    """Water cell columns for a row. IDENTICAL to riverCols in web constants."""
+    if cz <= -5:
+        return (7, 8)
+    if cz <= 3:
+        return (8, 9)
+    return (9, 10)
+
+
+# kind: w, d, floors (min, max), residents, jobs, attract, duration_s
+BUILDINGS: dict[str, dict] = {
+    "house":        {"w": 1, "d": 1, "floors": (1, 2),  "residents": 4,  "jobs": 0,  "attract": 0, "duration_s": 20},
+    "townhouse":    {"w": 1, "d": 1, "floors": (2, 3),  "residents": 6,  "jobs": 0,  "attract": 0, "duration_s": 20},
+    "apartments":   {"w": 2, "d": 2, "floors": (4, 7),  "residents": 16, "jobs": 0,  "attract": 0, "duration_s": 45},
+    "cafe":         {"w": 1, "d": 1, "floors": (1, 1),  "residents": 0,  "jobs": 3,  "attract": 5, "duration_s": 20},
+    "shop":         {"w": 1, "d": 1, "floors": (1, 2),  "residents": 0,  "jobs": 4,  "attract": 4, "duration_s": 20},
+    "market":       {"w": 1, "d": 2, "floors": (1, 1),  "residents": 0,  "jobs": 8,  "attract": 6, "duration_s": 30},
+    "bank":         {"w": 2, "d": 1, "floors": (2, 4),  "residents": 0,  "jobs": 12, "attract": 2, "duration_s": 30},
+    "office":       {"w": 1, "d": 1, "floors": (3, 8),  "residents": 0,  "jobs": 40, "attract": 1, "duration_s": 30},
+    "tower":        {"w": 2, "d": 2, "floors": (8, 16), "residents": 0,  "jobs": 60, "attract": 2, "duration_s": 45},
+    "school":       {"w": 2, "d": 2, "floors": (1, 2),  "residents": 0,  "jobs": 10, "attract": 3, "duration_s": 30},
+    "hospital":     {"w": 3, "d": 3, "floors": (3, 6),  "residents": 0,  "jobs": 25, "attract": 2, "duration_s": 45},
+    "fire_station": {"w": 2, "d": 1, "floors": (2, 2),  "residents": 0,  "jobs": 8,  "attract": 1, "duration_s": 30},
+    "warehouse":    {"w": 2, "d": 2, "floors": (1, 1),  "residents": 0,  "jobs": 10, "attract": 0, "duration_s": 30},
+    "factory":      {"w": 3, "d": 2, "floors": (1, 2),  "residents": 0,  "jobs": 18, "attract": 0, "duration_s": 45},
+    "park":         {"w": 2, "d": 2, "floors": (0, 0),  "residents": 0,  "jobs": 0,  "attract": 8, "duration_s": 20},
+    "plaza":        {"w": 1, "d": 1, "floors": (0, 0),  "residents": 0,  "jobs": 0,  "attract": 6, "duration_s": 20},
+    "stadium":      {"w": 4, "d": 4, "floors": (1, 1),  "residents": 0,  "jobs": 15, "attract": 9, "duration_s": 45},
+    "church":       {"w": 2, "d": 1, "floors": (1, 1),  "residents": 0,  "jobs": 2,  "attract": 3, "duration_s": 30},
+    "town_hall":    {"w": 2, "d": 2, "floors": (2, 2),  "residents": 0,  "jobs": 6,  "attract": 4, "duration_s": 45},
+}
+
+RESIDENTIAL_KINDS = ("house", "townhouse", "apartments")
+INDUSTRIAL_KINDS = ("factory", "warehouse")
+
+# The model can never pick a kind we lack; keys are space/hyphen-folded to "_".
+SYNONYMS: dict[str, str] = {
+    "skyscraper": "tower", "highrise": "tower", "high_rise": "tower",
+    "apartment": "apartments", "apartment_building": "apartments", "condo": "apartments",
+    "hotel": "apartments",
+    "coffee_shop": "cafe", "coffee": "cafe", "diner": "cafe", "restaurant": "cafe",
+    "bakery": "cafe",
+    "store": "shop", "boutique": "shop", "pharmacy": "shop", "gym": "shop",
+    "mall": "market", "grocery": "market", "supermarket": "market",
+    "police_station": "fire_station", "police": "fire_station", "firehouse": "fire_station",
+    "library": "town_hall", "museum": "town_hall", "city_hall": "town_hall",
+    "temple": "church", "mosque": "church", "chapel": "church",
+    "garden": "park", "playground": "park",
+    "fountain": "plaza", "square": "plaza",
+    "arena": "stadium",
+    "clinic": "hospital",
+    "plant": "factory", "mill": "factory",
+    "home": "house", "cottage": "house", "cabin": "house",
+}
+
+ROAD_CLASSES: dict[str, dict] = {
+    "street": {"capacity": 2, "speed": 1.0},
+    "avenue": {"capacity": 6, "speed": 1.6},
+}
+
+ROAD_DURATION_S = 4  # roads paint in over 4 s client-side
+
+# Curated street-name pool (genesis names — Main St, 1st Ave, Old Bridge,
+# River Rd, Elm St, 2nd St — are fixed in events and deliberately not here).
+STREET_NAMES: tuple[str, ...] = (
+    "Oak St", "Maple Ave", "Cedar Ln", "Birch St", "Willow Way", "Juniper St",
+    "Laurel Ave", "Magnolia Blvd", "Poplar St", "Chestnut St", "Sycamore Ave",
+    "Alder Row", "Hazel St", "Linden Ave", "Aspen Ct", "Rowan St", "Holly Ave",
+    "Ivy Ln", "Clover St", "Fern Way", "Meadow Ln", "Orchard St", "Garden Ave",
+    "Harbor St", "Mill Rd", "Canal St", "Foundry St", "Station Rd", "Depot Ln",
+    "Prospect Ave", "Summit St", "Vista Way", "Sunrise Blvd", "Larkspur St",
+    "Primrose Ave", "Bluebell Ln", "Copper St", "Granite Ave", "Beacon St",
+    "Quay Rd",
+)
+
+# --------------------------------------------------------------------- traffic
+RUSH_HOURS = (8.0, 18.0)  # bell-curve centers in dayHours
+RUSH_SIGMA = 1.2
+RUSH_BASE = 0.35  # rushFactor = base + (1-base) * min(1, bell(8) + bell(18))
+RUSH_AMP = 0.65   # = 1 - RUSH_BASE; mirrored to JS for the same formula
+CAR_RATE = 0.8    # visible cars N = clamp(round(pop * CAR_RATE * rushFactor), MIN, MAX)
+CAR_MIN, CAR_MAX = 8, 120
+EMA_TAU_S = 5.0   # client congestion EMA time constant
+CITIZENS_PER_POP = 5  # pedestrians = clamp(ceil(pop / per), MIN, MAX) — client-side
+CITIZENS_MIN, CITIZENS_MAX = 6, 80
+
+TRIP_ATTRACT_FACTOR = 2.0  # weight = (jobs + 2*attract) / (1 + manhattanDist^1.5)
+TRIP_DIST_EXP = 1.5
+# Static-assignment demand each commuter adds to every cell of their route, at
+# peak rush (rushFactor 1.0). TUNED (June 12, measured): genesis alone puts 3
+# crossers on the Old Bridge -> ratio 0.75 (under the 0.8 fix gate); +3 west
+# houses -> 5 crossers -> ratio 1.25 (>= 1.0, the acceptance test passes with
+# margin). At 0.8 the whole genesis grid read jammed.
+DEMAND_PER_COMMUTER = 0.5
+CONGESTION_COST_FACTOR = 2.0  # A* cost = (1/speed) * (1 + factor*demandRatio)
+TRAFFIC_TOP_CELLS = 15        # traffic index = round(100 * mean(top-N ratios))
+FIX_GATE_RATIO = 0.8          # below this max ratio, /api/fix gets a 409
+JAM_RATIO = 1.0
+FIX_AVOID_RATIO = 0.9         # bypass search forbids cells at/above this ratio
+FIX_NEW_CELL_COST = 3.0       # bypass Dijkstra: cost per NEW road cell
+FIX_WATER_COST_MULT = 4.0     # water crossable at 4x (fixes may build bridges)
+FIX_MAX_NEW_CELLS = 16
+
+# ------------------------------------------------------------------- placement
+GROWTH_RADIUS_MIN = 6
+GROWTH_RING_SLACK = 2     # penalty beyond growth_radius + slack
+SCORE_ANCHOR = 30.0       # +30 * (1 - dist_to_anchor/R)
+SCORE_FRONTAGE = 20.0     # footprint perimeter touches a road
+SCORE_NEIGHBOR = 3.0      # per developed cell in the one-cell ring
+SCORE_NEIGHBOR_CAP = 18.0
+SCORE_RING_PENALTY = 8.0  # -8 * max(0, cheb_from_center - (growth_radius+slack))
+AFF_SHOP_NEAR_HOMES = 12.0     # cafe/shop, residential within 3
+AFF_DOWNTOWN = 10.0            # office/bank/tower: +10*(1 - dist_to_center/12)
+AFF_HOME_NEAR_AMENITY = 8.0    # residential, cafe/shop/park within 4
+AFF_HOME_NEAR_INDUSTRY = -6.0  # residential, factory/warehouse within 3
+AFF_INDUSTRY_NEAR_HOMES = -10.0
+AFF_INDUSTRY_CLUSTER = 8.0     # factory/warehouse, industrial within 4
+AFF_PARK_SPACING = -25.0       # park, another park within 6
+PLACE_R_START = 6
+PLACE_R_STEP = 4
+CONNECTOR_MAX = 8  # connector BFS length cap (cells of new road)
+
+# -------------------------------------------------------------------- petitions
+NAME_MAX_LEN = 24
+INFILL_RATIO = 1.15           # jobs > housing*1.15 -> one bonus home
+INFILL_APARTMENTS_DEFICIT = 16  # jobs-housing gap that upgrades the infill to apartments

engine/genesis.py

@@ -0,0 +1,134 @@
+"""NEMOCITY genesis — epoch 0, exactly as specified in ARCHITECTURE.md.
+
+Roads, then buildings, then a note; all at t = CITY_EPOCH_S, wish_id
+"genesis", seeds crc32-derived. These values are a cross-component contract
+(web/mock/world.json is generated from this list); do NOT edit them.
+
+Validity is asserted at import: every footprint on empty non-water in-bounds
+cells, every building touching a road, bridge cells on water and nothing else.
+"""
+
+from __future__ import annotations
+
+import copy
+import zlib
+
+from . import constants as C
+
+
+def _seed(i: int) -> int:
+    return zlib.crc32(f"genesis:{i}".encode()) & 0x7FFFFFFF
+
+
+def _ev(i: int, tool: str, args: dict) -> dict:
+    return {
+        "id": f"e_{i:06d}", "wish_id": "genesis", "tool": tool,
+        "args": args, "seed": _seed(i), "t": float(C.CITY_EPOCH_S),
+    }
+
+
+def _col(cx: int, cz0: int, cz1: int) -> list[list[int]]:
+    return [[cx, cz] for cz in range(cz0, cz1 + 1)]
+
+
+def _row(cz: int, cx0: int, cx1: int, skip: tuple[int, ...] = ()) -> list[list[int]]:
+    return [[cx, cz] for cx in range(cx0, cx1 + 1) if cx not in skip]
+
+
+def _road(i: int, name: str, klass: str, cells: list[list[int]]) -> dict:
+    return _ev(i, "lay_road", {"cells": cells, "klass": klass, "name": name})
+
+
+def _bld(i: int, kind: str, name: str, cx: int, cz: int, floors: int,
+         hue: int, variant: int) -> dict:
+    spec = C.BUILDINGS[kind]
+    return _ev(i, "place_building", {
+        "kind": kind, "name": name, "cx": cx, "cz": cz,
+        "w": spec["w"], "d": spec["d"], "floors": floors,
+        "hue": hue, "variant": variant,
+    })
+
+
+GENESIS_FEATURES: list[dict] = [
+    # roads (1st Ave skips the river cells; the Old Bridge — street class, the
+    # bottleneck by design — carries the only crossing)
+    _road(0, "Main St", "avenue", _col(0, -12, 12)),
+    _road(1, "1st Ave", "avenue", _row(0, -12, 16, skip=(8, 9))),
+    _road(2, "Old Bridge", "street", [[8, 0], [9, 0]]),
+    _road(3, "River Rd", "street", _col(13, -6, 6)),
+    _road(4, "Elm St", "street", _row(-5, -8, 0)),
+    _road(5, "2nd St", "street", _col(-5, -5, 3)),
+    # downtown west of the river
+    _bld(6, "town_hall", "City Hall", -2, -3, 2, 44, 0),
+    _bld(7, "office", "Meridian Office", 1, -2, 5, 210, 3),
+    _bld(8, "cafe", "Corner Cafe", 1, 1, 1, 18, 1),
+    _bld(9, "market", "Main St Market", -1, 1, 1, 35, 2),
+    _bld(10, "park", "Founders Park", -4, 1, 0, 110, 0),
+    # Elm / 2nd St housing cluster
+    _bld(11, "house", "Elm Cottage", -1, -6, 2, 28, 4),
+    _bld(12, "house", "Rose Cottage", -4, -6, 1, 350, 5),
+    _bld(13, "house", "Sage House", -6, -4, 1, 95, 6),
+    # east of the river — jobs/homes that force bridge commutes from day one
+    _bld(14, "factory", "Riverside Works", 14, -3, 1, 24, 0),
+    _bld(15, "warehouse", "East Depot", 14, 1, 1, 210, 1),
+    _bld(16, "house", "Ferry House", 14, 3, 1, 205, 7),
+    _bld(17, "house", "River Cottage", 14, -5, 2, 16, 2),
+    _ev(18, "note", {"text": "Nemocity is listening. Ask for a building.",
+                     "kind": "milestone"}),
+]
+
+
+def genesis_features() -> list[dict]:
+    """Deep copy of the genesis event list (safe to mutate / load)."""
+    return copy.deepcopy(GENESIS_FEATURES)
+
+
+def genesis_world():
+    """A fresh World seeded with the genesis events."""
+    from .world import World
+
+    return World.load(genesis_features())
+
+
+def _validate() -> None:
+    water = {
+        (cx, cz)
+        for cz in range(C.COORD_MIN, C.COORD_MAX + 1)
+        for cx in C.river_cols(cz)
+    }
+    road: set[tuple[int, int]] = set()
+    for ev in GENESIS_FEATURES:
+        if ev["tool"] != "lay_road":
+            continue
+        name = ev["args"]["name"]
+        for cx, cz in ev["args"]["cells"]:
+            assert C.COORD_MIN <= cx <= C.COORD_MAX and C.COORD_MIN <= cz <= C.COORD_MAX, \
+                f"genesis: road cell off-grid in {name}"
+            on_water = (cx, cz) in water
+            assert on_water == (name == "Old Bridge"), \
+                f"genesis: {name} cell ({cx},{cz}) water mismatch"
+            road.add((cx, cz))
+    occupied: set[tuple[int, int]] = set(road)
+    for ev in GENESIS_FEATURES:
+        if ev["tool"] != "place_building":
+            continue
+        a = ev["args"]
+        cells = [
+            (a["cx"] + dx, a["cz"] + dz)
+            for dx in range(a["w"]) for dz in range(a["d"])
+        ]
+        for c in cells:
+            assert C.COORD_MIN <= c[0] <= C.COORD_MAX and C.COORD_MIN <= c[1] <= C.COORD_MAX, \
+                f"genesis: {a['name']} off-grid"
+            assert c not in water, f"genesis: {a['name']} on water at {c}"
+            assert c not in occupied, f"genesis: {a['name']} overlaps at {c}"
+        touches = any(
+            (cx + dx, cz + dz) in road
+            for cx, cz in cells
+            for dx, dz in ((0, -1), (1, 0), (0, 1), (-1, 0))
+        )
+        assert touches, f"genesis: {a['name']} touches no road"
+        occupied.update(cells)
+
+
+_validate()

engine/moderation.py

@@ -0,0 +1,311 @@
+"""Layered wish moderation. Moderation runs BEFORE execution, always.
+
+Layers (each one a hard gate):
+  1. charset/length — ≤160 printable chars (newlines/tabs are folded to
+     spaces first; true control / zero-width chars are denied).
+  2. wordlist/regex — slurs, sexual content, hate symbols & terms. Robust to
+     leetspeak (n1gg3r), unicode confusables (Cyrillic/Greek lookalikes via an
+     explicit map on top of NFKC), diacritics (NFKD strip) and separator
+     padding (skeleton substring pass).
+  3. optional async LLM judge — an injected callable `judge(text) ->
+     {"allowed": bool, "category": str|None}` (dict, JSON string, or Verdict).
+     DEFAULT-DENY on any judge exception, timeout, or parse failure.
+
+The blocklists below exist solely to keep this content OFF the shared world.
+Rejections are poetic but final.
+
+Pure stdlib. Only `check()` is async (the judge hook may be a coroutine).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import re
+import unicodedata
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+# Petitions are <=160 chars (the BUILD prompt budget); internal name keeps
+# godseed's wish_* wiring.
+MAX_WISH_LEN = 160
+
+POETIC = {
+    "empty": "city hall received a blank form; write a petition",
+    "length": "city hall reads short petitions only — fewer than 160 characters",
+    "charset": "city hall cannot read these characters",
+    "hate": "city hall will not zone for hate; petition DENIED",
+    "sexual": "city hall stamps this petition DENIED",
+    "violence": "this city builds; it does not burn — petition DENIED",
+    "uncertain": "city hall weighed this petition and set it aside",
+    "judged": "city hall declines this petition",
+}
+
+
+@dataclass(frozen=True)
+class Verdict:
+    allowed: bool
+    category: Optional[str]
+    poetic_reason: Optional[str]
+
+
+def _deny(category: str) -> Verdict:
+    return Verdict(False, category, POETIC.get(category, POETIC["judged"]))
+
+
+# --------------------------------------------------------------- normalization
+
+# Unicode lookalikes NFKC does NOT fold (Cyrillic / Greek / phonetic Latin).
+_CONFUSABLES = {
+    # Cyrillic
+    "а": "a", "в": "b", "е": "e", "ё": "e", "є": "e", "і": "i", "ї": "i",
+    "ј": "j", "к": "k", "м": "m", "н": "h", "о": "o", "р": "p", "с": "c",
+    "т": "t", "у": "y", "х": "x", "г": "r", "ѕ": "s", "ԁ": "d", "ԛ": "q",
+    "ԝ": "w", "ь": "b",
+    # Greek
+    "α": "a", "β": "b", "γ": "y", "ε": "e", "ζ": "z", "η": "n", "ι": "i",
+    "κ": "k", "ν": "v", "ο": "o", "ρ": "p", "ς": "s", "σ": "s", "τ": "t",
+    "υ": "u", "χ": "x", "ω": "w",
+    # Latin extras
+    "ɡ": "g", "ɑ": "a", "ı": "i", "ø": "o", "đ": "d", "ƒ": "f",
+}
+
+_LEET = str.maketrans({
+    "0": "o", "1": "i", "2": "z", "3": "e", "4": "a", "5": "s", "6": "g",
+    "7": "t", "8": "b", "9": "g", "@": "a", "$": "s", "!": "i", "+": "t",
+    "|": "l", "€": "e", "£": "l",
+})
+
+# Phonetic Cyrillic→Latin (catches transliterated terms, e.g. "хитлер";
+# distinct from _CONFUSABLES, which folds visual lookalikes only).
+_CYRILLIC_TRANSLIT = {
+    "а": "a", "б": "b", "в": "v", "г": "g", "д": "d", "е": "e", "ё": "e",
+    "ж": "zh", "з": "z", "и": "i", "й": "i", "к": "k", "л": "l", "м": "m",
+    "н": "n", "о": "o", "п": "p", "р": "r", "с": "s", "т": "t", "у": "u",
+    "ф": "f", "х": "h", "ц": "ts", "ч": "ch", "ш": "sh", "щ": "sh",
+    "ъ": "", "ы": "y", "ь": "", "э": "e", "ю": "yu", "я": "ya",
+    "і": "i", "ї": "i", "є": "e", "ѕ": "s", "ј": "j",
+}
+
+
+def _base_fold(text: str) -> str:
+    """NFKC + casefold + diacritic strip (shared by all matching variants)."""
+    s = unicodedata.normalize("NFKC", text).casefold()
+    s = unicodedata.normalize("NFKD", s)
+    return "".join(ch for ch in s if not unicodedata.combining(ch))
+
+
+def _normalize(text: str) -> str:
+    return "".join(_CONFUSABLES.get(ch, ch) for ch in _base_fold(text))
+
+
+def _translit(text: str) -> str:
+    return "".join(_CYRILLIC_TRANSLIT.get(ch, ch) for ch in _base_fold(text))
+
+
+def _leetfold(text: str) -> str:
+    return text.translate(_LEET)
+
+
+def _skeleton(text: str) -> str:
+    """Letters only — defeats spacing/punctuation padding (n.i.g.g.e.r)."""
+    return "".join(ch for ch in text if ch.isalpha())
+
+
+# --------------------------------------------------------------- blocklists
+
+# Token-bounded terms (word-boundary match; safe against raccoon/sussex/etc).
+_TERMS = {
+    "hate": (
+        "nigger", "niggers", "nigga", "niggas", "niglet", "niglets",
+        "faggot", "faggots", "fag", "fags", "dyke", "dykes", "kike", "kikes",
+        "spic", "spics", "chink", "chinks", "gook", "gooks",
+        "wetback", "wetbacks", "beaner", "beaners", "coon", "coons",
+        "jigaboo", "jigaboos", "golliwog", "golliwogs",
+        "tranny", "trannies", "shemale", "shemales", "paki", "pakis",
+        "raghead", "ragheads", "towelhead", "towelheads", "injun", "injuns",
+        "retard", "retards", "retarded",
+        "hitler", "hitlers", "nazi", "nazis", "neonazi", "neonazis",
+        "swastika", "swastikas", "hakenkreuz", "kkk", "klansman", "klansmen",
+        "fuhrer", "goebbels", "himmler", "holocaust", "reich",
+        "gitler", "svastika",  # common Cyrillic transliterations
+        "genocide", "lynch", "lynching", "lynchings",
+    ),
+    "sexual": (
+        "porn", "porno", "pornography", "pornographic",
+        "blowjob", "blowjobs", "handjob", "handjobs", "rimjob", "rimjobs",
+        "cum", "cumshot", "cumshots", "jizz", "semen",
+        "dick", "dicks", "cock", "cocks", "pussy", "pussies",
+        "tits", "titties", "boobs", "penis", "penises", "vagina", "vaginas",
+        "cunt", "cunts", "clit", "clitoris",
+        "whore", "whores", "slut", "sluts", "hentai", "milf", "milfs",
+        "dildo", "dildos", "anal", "anus", "orgasm", "orgasms", "orgy",
+        "orgies", "fellatio", "cunnilingus",
+        "masturbate", "masturbates", "masturbation",
+        "bukkake", "deepthroat", "gangbang", "creampie",
+        "futa", "futanari", "loli", "lolicon", "shota", "shotacon",
+        "rape", "rapes", "raped", "raping", "rapist", "rapists",
+        "molest", "molests", "molested", "molester", "molestation",
+        "pedophile", "pedophiles", "pedo", "pedos",
+        "paedophile", "paedophiles", "incest", "bestiality", "necrophilia",
+        "sex", "sexy", "sexual", "nudes", "boner", "boners",
+    ),
+}
+
+# Multi-word / pattern matches (checked on normalized AND leet-folded text).
+_PHRASES = (
+    (r"heil\s+hitler", "hate"),
+    (r"sieg\s+heil", "hate"),
+    (r"white\s+power", "hate"),
+    (r"white\s+supremacy", "hate"),
+    (r"blood\s+and\s+soil", "hate"),
+    (r"great\s+replacement", "hate"),
+    (r"ethnic\s+cleansing", "hate"),
+    (r"gas\s+the\s+(?:jews|blacks|gays|muslims|immigrants)", "hate"),
+    (r"ku\s+klux", "hate"),
+    (r"\b14\s*/?\s*88\b", "hate"),
+    (r"kill\s+(?:all|every)\b", "violence"),
+    (r"school\s+shoot(?:ing|ings|er|ers)?", "violence"),
+    (r"mass\s+shooting", "violence"),
+    (r"child\s+porn\w*", "sexual"),
+    (r"kiddie\s+porn\w*", "sexual"),
+)
+
+# High-severity substrings checked on the letters-only skeleton (defeats
+# s p a c e d and dotted spellings; terms chosen for near-zero false positives).
+_SKELETON_TERMS = (
+    ("nigger", "hate"), ("nigga", "hate"), ("faggot", "hate"),
+    ("swastika", "hate"), ("svastika", "hate"),
+    ("hakenkreuz", "hate"), ("heilhitler", "hate"),
+    ("siegheil", "hate"), ("kukluxklan", "hate"), ("whitepower", "hate"),
+    ("jigaboo", "hate"), ("porchmonkey", "hate"), ("towelhead", "hate"),
+    ("raghead", "hate"), ("wetback", "hate"),
+    ("blowjob", "sexual"), ("deepthroat", "sexual"), ("childporn", "sexual"),
+    ("bukkake", "sexual"), ("gangbang", "sexual"), ("lolicon", "sexual"),
+    ("cumshot", "sexual"),
+)
+
+# Hate symbols checked on the raw text before any folding.
+_SYMBOLS = ("卐", "卍", "ᛋᛋ")
+
+
+def _compile_tokens(terms: tuple[str, ...]) -> re.Pattern:
+    joined = "|".join(sorted(map(re.escape, terms), key=len, reverse=True))
+    return re.compile(rf"\b(?:{joined})\b")
+
+_TOKEN_RX = {category: _compile_tokens(terms) for category, terms in _TERMS.items()}
+_PHRASE_RX = tuple((re.compile(pattern), category) for pattern, category in _PHRASES)
+
+
+# --------------------------------------------------------------- moderator
+
+class Moderator:
+    """`precheck` = sync layers 1-2 (the API fast path); `check` adds the judge."""
+
+    def __init__(
+        self,
+        judge: Optional[Callable[[str], Any]] = None,
+        judge_timeout: Optional[float] = 30.0,
+    ) -> None:
+        self._judge = judge
+        self._judge_timeout = judge_timeout
+
+    # -- layers 1 + 2 (sync, cheap, deterministic) --
+
+    def precheck(self, text: Any) -> Verdict:
+        """Full gate for USER wish input: length + charset bounds + content."""
+        if not isinstance(text, str):
+            return _deny("empty")
+        # fold benign line breaks/tabs to spaces before the printable gate
+        raw = re.sub(r"\s+", " ", text).strip()
+        if not raw:
+            return _deny("empty")
+        if len(raw) > MAX_WISH_LEN:
+            return _deny("length")
+        if any(not ch.isprintable() for ch in raw):
+            return _deny("charset")
+        return self.check_content(raw)
+
+    def check_content(self, text: Any) -> Verdict:
+        """Content-only check (slurs/hate/sexual/etc.) WITHOUT the wish-input
+        length/charset bounds. Use this to re-moderate MODEL-composed text — the
+        god's reading is intentionally long (~700 chars); applying the 140-char
+        wish limit here silenced every reading (June 12 regression)."""
+        if not isinstance(text, str):
+            return _deny("empty")
+        raw = re.sub(r"\s+", " ", text).strip()
+        if not raw:
+            return _deny("empty")
+
+        for symbol in _SYMBOLS:
+            if symbol in raw:
+                return _deny("hate")
+
+        norm = _normalize(raw)
+        folded = _leetfold(norm)
+        translit = _translit(raw)
+        variants = (norm, folded, translit) if translit != norm else (norm, folded)
+
+        for rx, category in _PHRASE_RX:
+            if any(rx.search(v) for v in variants):
+                return _deny(category)
+        for category, rx in _TOKEN_RX.items():
+            if any(rx.search(v) for v in variants):
+                return _deny(category)
+
+        skeletons = {_skeleton(folded), _skeleton(translit)}
+        for term, category in _SKELETON_TERMS:
+            if any(term in s for s in skeletons):
+                return _deny(category)
+
+        return Verdict(True, None, None)
+
+    # -- layer 3 (async LLM judge, default-deny on uncertainty) --
+
+    async def check(self, text: Any) -> Verdict:
+        verdict = self.precheck(text)
+        if not verdict.allowed or self._judge is None:
+            return verdict
+        try:
+            result = self._judge(text)
+            if inspect.isawaitable(result):
+                if self._judge_timeout:
+                    result = await asyncio.wait_for(result, self._judge_timeout)
+                else:
+                    result = await result
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            return _deny("uncertain")
+        return self._parse_judge(result)
+
+    @staticmethod
+    def _parse_judge(raw: Any) -> Verdict:
+        """Strict parse of the judge's reply; anything murky → deny."""
+        try:
+            if isinstance(raw, Verdict):
+                return raw
+            data = raw
+            if isinstance(data, (bytes, bytearray)):
+                data = data.decode("utf-8", "replace")
+            if isinstance(data, str):
+                start, end = data.find("{"), data.rfind("}")
+                if start < 0 or end <= start:
+                    return _deny("uncertain")
+                data = json.loads(data[start : end + 1])
+            if not isinstance(data, dict):
+                return _deny("uncertain")
+            allowed = data.get("allowed")
+            if isinstance(allowed, str):
+                lowered = allowed.strip().lower()
+                allowed = {"true": True, "false": False}.get(lowered, allowed)
+            if allowed is True:
+                return Verdict(True, None, None)
+            if allowed is False:
+                category = data.get("category")
+                category = str(category) if category else "judged"
+                return Verdict(False, category, POETIC.get(category, POETIC["judged"]))
+            return _deny("uncertain")
+        except Exception:
+            return _deny("uncertain")

engine/placement.py

@@ -0,0 +1,313 @@
+"""NEMOCITY placement — deterministic, NEVER fails, Python-only.
+
+The LLM gives {kind, name, near, floors, hue}; this module turns it into
+exact cells: anchor resolution from the "near" text, a scored candidate
+search over an expanding Chebyshev radius, and an auto-routed road connector
+when the chosen footprint has no frontage. Output is partial event dicts
+({"tool", "args"}) — world.apply assigns id/seed/t.
+
+All randomness is crc32-seeded from (wish_id, indices); no wall clock here.
+"""
+
+from __future__ import annotations
+
+import re
+import zlib
+from collections import deque
+from typing import Any, Optional
+
+from . import constants as C
+from .city import WATER_CELLS, Building, Cell, CityState, in_bounds, neighbors4
+from .tools import street_name_for
+
+_CENTER_WORDS = frozenset(("center", "centre", "downtown", "middle", "heart"))
+_RIVER_WORDS = frozenset(("river", "water", "waterfront", "riverside", "shore"))
+_STREET_SUFFIXES = frozenset(("st", "ave", "rd", "ln", "blvd", "way", "ct", "row"))
+_STOP = frozenset(("the", "a", "an", "of", "near", "by", "next", "to", "at", "in", "on"))
+
+_R_MAX = 2 * C.GRID  # covers the whole grid from any anchor
+
+
+def _u01(key: str) -> float:
+    return (zlib.crc32(key.encode()) & 0xFFFFFFFF) / 0xFFFFFFFF
+
+
+def _tokens(text: str) -> list[str]:
+    return [
+        t for t in re.findall(r"[a-z0-9']+", str(text or "").lower())
+        if t not in _STOP
+    ]
+
+
+def _round_cell(x: float, z: float) -> Cell:
+    cx = min(max(int(round(x)), C.COORD_MIN), C.COORD_MAX)
+    cz = min(max(int(round(z)), C.COORD_MIN), C.COORD_MAX)
+    return (cx, cz)
+
+
+def resolve_anchor(city: CityState, near: Any) -> Cell:
+    """Fuzzy anchor: named building > street > center > river > kind word >
+    centroid of all buildings > (0,0)."""
+    text = str(near or "").strip().lower()
+    toks = _tokens(text)
+    if toks:
+        for b in reversed(city.buildings):
+            name_toks = set(_tokens(b.name))
+            if name_toks and (set(toks) & name_toks):
+                return _round_cell(*b.centroid)
+        for name, cells in city.street_cells.items():
+            low = name.lower()
+            name_toks = set(_tokens(low)) - _STREET_SUFFIXES
+            if low in text or (name_toks and set(toks) & name_toks):
+                return cells[len(cells) // 2]
+        if set(toks) & _CENTER_WORDS:
+            return (0, 0)
+        if set(toks) & _RIVER_WORDS:
+            developed = set(city.roads) | set(city.building_cells)
+            banks = sorted(
+                (c for c in developed if any(n in WATER_CELLS for n in neighbors4(c))),
+                key=lambda c: (max(abs(c[0]), abs(c[1])), c[1], c[0]),
+            )
+            if banks:
+                return banks[0]
+        for t in toks:
+            kind = t if t in C.BUILDINGS else C.SYNONYMS.get(t)
+            if kind:
+                for b in reversed(city.buildings):
+                    if b.kind == kind:
+                        return _round_cell(*b.centroid)
+    if city.buildings:
+        xs = [b.centroid[0] for b in city.buildings]
+        zs = [b.centroid[1] for b in city.buildings]
+        return _round_cell(sum(xs) / len(xs), sum(zs) / len(zs))
+    return (0, 0)
+
+
+# ----------------------------------------------------------------- connectors
+
+def _road_distance_field(city: CityState, max_dist: int) -> dict[Cell, int]:
+    """Multi-source BFS over EMPTY cells from the road network. dist=1 means
+    'this empty cell is adjacent to a road' (= a 1-cell connector)."""
+    dist: dict[Cell, int] = {}
+    queue: deque[Cell] = deque()
+    seeds = set()
+    for road_cell in city.roads:
+        for n in neighbors4(road_cell):
+            if city.is_empty(n) and n not in seeds:
+                seeds.add(n)
+    for cell in sorted(seeds, key=lambda c: (c[1], c[0])):
+        dist[cell] = 1
+        queue.append(cell)
+    while queue:
+        cell = queue.popleft()
+        d = dist[cell]
+        if d >= max_dist:
+            continue
+        for n in neighbors4(cell):
+            if n not in dist and city.is_empty(n):
+                dist[n] = d + 1
+                queue.append(n)
+    return dist
+
+
+def _connector_path(
+    city: CityState, footprint: set[Cell], max_len: int
+) -> Optional[list[Cell]]:
+    """Shortest Manhattan path of NEW road cells from the footprint ring to a
+    cell adjacent to the existing road network. Deterministic BFS order."""
+    starts = sorted(
+        {
+            n for cell in footprint for n in neighbors4(cell)
+            if city.is_empty(n) and n not in footprint
+        },
+        key=lambda c: (c[1], c[0]),
+    )
+    prev: dict[Cell, Optional[Cell]] = {}
+    queue: deque[tuple[Cell, int]] = deque()
+    for s in starts:
+        prev[s] = None
+        queue.append((s, 1))
+    while queue:
+        cell, length = queue.popleft()
+        if any(n in city.roads for n in neighbors4(cell)):
+            path = [cell]
+            while prev[path[-1]] is not None:
+                path.append(prev[path[-1]])
+            path.reverse()
+            return path
+        if length >= max_len:
+            continue
+        for n in neighbors4(cell):
+            if n not in prev and city.is_empty(n) and n not in footprint:
+                prev[n] = cell
+                queue.append((n, length + 1))
+    return None
+
+
+# -------------------------------------------------------------------- scoring
+
+def _rect_cheb(b: Building, cx: int, cz: int, w: int, d: int) -> int:
+    """Exact min Chebyshev distance between a building and a candidate rect."""
+    dx = max(0, b.cx - (cx + w - 1), cx - (b.cx + b.w - 1))
+    dz = max(0, b.cz - (cz + d - 1), cz - (b.cz + b.d - 1))
+    return max(dx, dz)
+
+
+def _affinity(city: CityState, kind: str, cx: int, cz: int, w: int, d: int) -> float:
+    res = ind = amen = park = 10 ** 6
+    for b in city.buildings:
+        dist = _rect_cheb(b, cx, cz, w, d)
+        if b.kind in C.RESIDENTIAL_KINDS:
+            res = min(res, dist)
+        if b.kind in C.INDUSTRIAL_KINDS:
+            ind = min(ind, dist)
+        if b.kind in ("cafe", "shop", "park"):
+            amen = min(amen, dist)
+        if b.kind == "park":
+            park = min(park, dist)
+    score = 0.0
+    if kind in ("cafe", "shop") and res <= 3:
+        score += C.AFF_SHOP_NEAR_HOMES
+    if kind in ("office", "bank", "tower"):
+        dist_c = max(abs(cx), abs(cz))
+        score += C.AFF_DOWNTOWN * (1 - dist_c / 12.0)
+    if kind in C.RESIDENTIAL_KINDS:
+        if amen <= 4:
+            score += C.AFF_HOME_NEAR_AMENITY
+        if ind <= 3:
+            score += C.AFF_HOME_NEAR_INDUSTRY
+    if kind in C.INDUSTRIAL_KINDS:
+        if res <= 3:
+            score += C.AFF_INDUSTRY_NEAR_HOMES
+        if ind <= 4:
+            score += C.AFF_INDUSTRY_CLUSTER
+    if kind == "park" and park <= 6:
+        score += C.AFF_PARK_SPACING
+    return score
+
+
+def _search(
+    city: CityState, kind: str, anchor: Cell, wish_id: str, connector_max: int
+) -> Optional[tuple[Cell, bool]]:
+    """Best (top_left, has_frontage) within the smallest radius that holds a
+    valid candidate, or None."""
+    spec = C.BUILDINGS[kind]
+    w, d = spec["w"], spec["d"]
+    growth = city.growth_radius
+    ring_limit = growth + C.GROWTH_RING_SLACK
+    road_dist = _road_distance_field(city, max(connector_max, 1) + 1)
+    ax, az = anchor
+
+    radius = C.PLACE_R_START
+    while radius <= _R_MAX:
+        best: Optional[tuple[float, Cell, bool]] = None
+        index = 0
+        for cz in range(az - radius, az + radius + 1):
+            for cx in range(ax - radius, ax + radius + 1):
+                index += 1
+                cells = [(cx + dx, cz + dz) for dx in range(w) for dz in range(d)]
+                if not all(city.is_empty(c) for c in cells):
+                    continue
+                footprint = set(cells)
+                ring = {
+                    n for c in cells for n in neighbors4(c) if n not in footprint
+                }
+                frontage = any(n in city.roads for n in ring)
+                if not frontage and not any(
+                    road_dist.get(n, 10 ** 9) <= connector_max for n in ring
+                ):
+                    continue
+                dist_anchor = max(abs(cx - ax), abs(cz - az))
+                score = C.SCORE_ANCHOR * (1 - dist_anchor / radius)
+                if frontage:
+                    score += C.SCORE_FRONTAGE
+                developed = sum(
+                    1 for n in ring if n in city.roads or n in city.building_cells
+                )
+                score += min(C.SCORE_NEIGHBOR * developed, C.SCORE_NEIGHBOR_CAP)
+                score += _affinity(city, kind, cx, cz, w, d)
+                cheb_center = max(abs(cx), abs(cz))
+                score -= C.SCORE_RING_PENALTY * max(0, cheb_center - ring_limit)
+                score += _u01(f"{wish_id}:{index}") * 0.5  # seeded tie-break
+                if best is None or score > best[0]:
+                    best = (score, (cx, cz), frontage)
+        if best is not None:
+            return best[1], best[2]
+        radius += C.PLACE_R_STEP
+    return None
+
+
+# ----------------------------------------------------------------------- place
+
+def place(
+    city: CityState,
+    kind: str,
+    name: str,
+    floors: Any,
+    hue: Any,
+    near: Any,
+    wish_id: str,
+    call_index: int,
+) -> list[dict]:
+    """Resolve a building request into 1-2 events (place_building + optional
+    connector lay_road). Never fails: the radius grows, the connector cap
+    relaxes, and a footprint that fits nowhere degrades to a house."""
+    if kind not in C.BUILDINGS:
+        kind = "house"
+    anchor = resolve_anchor(city, near)
+
+    found = _search(city, kind, anchor, wish_id, C.CONNECTOR_MAX)
+    if found is None:
+        found = _search(city, kind, anchor, wish_id, 2 * C.CONNECTOR_MAX)
+    if found is None and kind != "house":
+        return place(city, "house", name, 1, hue, near, wish_id, call_index)
+    if found is None:  # a 64x64 grid with any road at all always has a slot
+        found = _search(city, kind, anchor, wish_id, 10 ** 6)
+    if found is None:
+        raise RuntimeError("placement impossible: no empty cell on the grid")
+
+    (cx, cz), frontage = found
+    spec = C.BUILDINGS[kind]
+    lo, hi = spec["floors"]
+    base = None
+    if isinstance(floors, (int, float)) and not isinstance(floors, bool):
+        base = int(round(floors))
+    if kind in ("office", "tower"):
+        if base is None:
+            base = (lo + hi) // 2
+        dist_c = max(abs(cx), abs(cz))
+        base = base + round(4 * (1 - dist_c / 10.0))  # taller downtown
+    elif base is None:
+        base = lo + zlib.crc32(f"{wish_id}:{call_index}:floors".encode()) % (hi - lo + 1)
+    final_floors = min(max(base, lo), hi)
+
+    if isinstance(hue, (int, float)) and not isinstance(hue, bool):
+        final_hue = int(round(hue)) % 361
+    else:
+        final_hue = zlib.crc32(f"{wish_id}:{call_index}:hue".encode()) % 360
+    variant = zlib.crc32(f"{wish_id}:{call_index}:variant".encode()) % 8
+
+    events: list[dict] = [{
+        "tool": "place_building",
+        "args": {
+            "kind": kind, "name": str(name or ""), "cx": cx, "cz": cz,
+            "w": spec["w"], "d": spec["d"], "floors": final_floors,
+            "hue": final_hue, "variant": variant,
+        },
+    }]
+    if not frontage:
+        footprint = {
+            (cx + dx, cz + dz) for dx in range(spec["w"]) for dz in range(spec["d"])
+        }
+        path = _connector_path(city, footprint, 2 * C.CONNECTOR_MAX) or \
+            _connector_path(city, footprint, 10 ** 6)
+        if path:
+            events.append({
+                "tool": "lay_road",
+                "args": {
+                    "cells": [[c[0], c[1]] for c in path],
+                    "klass": "street",
+                    "name": street_name_for(f"{wish_id}:{call_index}:road"),
+                },
+            })
+    return events

engine/queue_worker.py

@@ -0,0 +1,719 @@
+"""NEMOCITY petition queue — one city hall, one petition at a time.
+
+A single global asyncio worker serializes every job:
+
+    wish:  pop -> moderate -> planner.grant(text, summary, act, emit)
+           [act(building_req) runs the engine: synonyms -> sanitize ->
+            placement.place -> world.apply -> world_delta per event]
+           -> infill rule -> persist trace -> wish_granted
+    fix:   pop -> traffic snapshot (stats + candidates) -> planner.fix(
+           stats, candidates, act_fix, emit) -> ONE apply_fix event ->
+           persist -> wish_granted
+
+Admission control in `submit`/`submit_fix`: 1 pending job per client, queue
+cap 50. Hourly rate limits + fix cooldowns live in the server, not here.
+`submit_fix` raises TrafficSmooth (-> 409 upstream) when the static
+assignment says there is nothing to fix.
+
+The emit passed to the planner is wrapped: any event missing a wish_id gets
+this job's id injected — so the planner can emit {type:"plan", plan:{...}}
+right after its JSON parses without knowing the wish_id.
+
+Crash-safe by construction: an exception while granting one job emits a
+readable generic wish_rejected and the worker moves on. SSE emit failures
+are swallowed; persist failures are logged but do not undo a grant.
+
+Wire names keep godseed's wish_* verbatim; user-facing copy says petition.
+Stdlib only; this is the only async module in the engine.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import logging
+import re
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from . import constants as C
+from . import placement, tools, traffic
+from .city import CityState
+
+log = logging.getLogger("nemocity.engine.queue")
+
+QUEUE_MAX = 50
+MAX_BUILDINGS_PER_WISH = 3   # act() invocations the planner gets per petition
+MAX_CALLS_PER_WISH = 12      # engine backstop on applied events
+TEXT_PREVIEW_LEN = 60
+_SUBMIT_TEXT_CAP = 500  # keep raw text bounded; moderation still sees >160 and denies
+
+# Browser-invoked granting (ZeroGPU): GPU work must run inside the PETITIONER'S
+# gradio request (their HF auth headers carry the quota — a server-side
+# background spaces.GPU call fails by design). The worker emits your_turn and
+# waits for the browser to fetch its token (authenticated) then invoke().
+INVOCATION_WINDOW_S = 25.0
+GRANT_DEADLINE_S = 150.0  # one-shot 9B runs well under this; bounds a hung grant
+
+QUEUE_FULL_REASON = "city hall is swamped; come back in a few minutes"
+ALREADY_PENDING_REASON = "one petition per visitor at a time; yours is still on the desk"
+WANDERED_REASON = "the petitioner left the counter; city hall moved on"
+INTERRUPTED_REASON = "the review was interrupted; city hall moved on"
+NOT_YOUR_TURN_REASON = "this petition is not at the counter"
+RITE_BEGUN_REASON = "this petition is already being processed"
+CRASH_REASON = "city hall misfiled this petition; please submit it again"
+BUSY_HEAVENS_REASON = "the planning office is busy; offer your petition again in a moment"
+HANDS_FULL_OBSERVATION = "rejected: this petition's permit limit is reached"
+FALLBACK_EPITAPH = "the city granted a home"
+TRAFFIC_SMOOTH_REASON = "Traffic is flowing smoothly."
+FIX_JOB_TEXT = "City Engineer: traffic review"
+INFILL_NOTE = "New families are moving in."
+
+_WISH_ID_RE = re.compile(r"^w_(\d+)$")
+
+
+class QueueError(Exception):
+    """Admission failure; `.reason` is readable and safe to show users."""
+
+    def __init__(self, reason: str) -> None:
+        super().__init__(reason)
+        self.reason = reason
+
+
+class QueueFull(QueueError):
+    pass
+
+
+class AlreadyPending(QueueError):
+    pass
+
+
+class TrafficSmooth(QueueError):
+    """Nothing to fix — the server matches this by type name -> 409."""
+
+
+@dataclass
+class _Item:
+    wish_id: str
+    text: str
+    client_id: str
+    submitted_at: float
+    kind: str = "wish"  # "wish" | "fix"
+
+
+def _trace_get(trace: Any, key: str) -> Any:
+    if isinstance(trace, dict):
+        return trace.get(key)
+    return getattr(trace, key, None)
+
+
+def _trace_set(trace: Any, key: str, value: Any) -> None:
+    try:
+        if isinstance(trace, dict):
+            trace[key] = value
+        else:
+            setattr(trace, key, value)
+    except Exception:  # frozen dataclass etc. — best-effort
+        pass
+
+
+def _epitaph_from_reading(reading: Any) -> Optional[str]:
+    """Salvage the blurb from the model's last sentence so the ledger stays
+    varied when the model omits a clean one."""
+    text = str(reading or "").strip()
+    if not text:
+        return None
+    parts = [p.strip() for p in re.split(r"(?<=[.!?])\s+", text) if p.strip()]
+    return parts[-1][:120] if parts else None
+
+
+def _num(value: Any) -> Optional[float]:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    try:
+        return float(str(value).strip())
+    except (ValueError, TypeError):
+        return None
+
+
+class QueueWorker:
+    """Single serialized worker; construct once, `await start()` at boot.
+
+    Injected collaborators (duck-typed, no engine->mind/server imports):
+      world      engine.world.World (apply/summary/record_epitaph/epoch)
+      moderator  engine.moderation.Moderator (async check)
+      planner    object with `async grant(text, summary, act, emit)` and
+                 (optionally) `async fix(stats, candidates, act_fix, emit)`
+      emit       async callable broadcasting one SSE event dict
+      persist    callable (sync or async) receiving the WishTrace; optional
+    """
+
+    def __init__(
+        self,
+        world: Any,
+        moderator: Any,
+        planner: Any,
+        emit: Any,
+        persist: Any = None,
+        *,
+        max_queue: int = QUEUE_MAX,
+        max_calls_per_wish: int = MAX_CALLS_PER_WISH,
+        next_wish_index: Optional[int] = None,
+        browser_invoked: bool = False,
+        invocation_window: float = INVOCATION_WINDOW_S,
+        grant_deadline: float = GRANT_DEADLINE_S,
+    ) -> None:
+        self._world = world
+        self._moderator = moderator
+        self._planner = planner
+        self._emit = emit
+        self._persist = persist
+        self._max_queue = max_queue
+        self._max_calls = max_calls_per_wish
+        self._queue: asyncio.Queue[_Item] = asyncio.Queue()
+        self._pending: dict[str, str] = {}  # client_id -> wish_id
+        self._current: Optional[_Item] = None
+        self._task: Optional[asyncio.Task] = None
+        self._browser_invoked = browser_invoked
+        self._invocation_window = invocation_window
+        self._grant_deadline = grant_deadline
+        self._awaiting: Optional[dict[str, Any]] = None
+        self._wish_counter = (
+            next_wish_index if next_wish_index is not None else self._derive_wish_counter(world)
+        )
+
+    @staticmethod
+    def _derive_wish_counter(world: Any) -> int:
+        """Continue numbering after the highest persisted w_NNNNNN."""
+        best = 0
+        for feature in getattr(world, "features", ()) or ():
+            match = _WISH_ID_RE.match(getattr(feature, "wish_id", "") or "")
+            if match:
+                best = max(best, int(match.group(1)) + 1)
+        return best or 1  # first-ever petition is w_000001
+
+    def _city(self) -> CityState:
+        return CityState.from_events(getattr(self._world, "features", ()) or ())
+
+    # --------------------------------------------------------------- admission
+
+    def _admit(self, client_id: str) -> None:
+        if client_id in self._pending:
+            raise AlreadyPending(ALREADY_PENDING_REASON)
+        if self._queue.qsize() >= self._max_queue:
+            raise QueueFull(QUEUE_FULL_REASON)
+
+    def _enqueue(self, text: str, client_id: str, kind: str) -> tuple[str, int]:
+        wish_id = f"w_{self._wish_counter:06d}"
+        self._wish_counter += 1
+        item = _Item(
+            wish_id=wish_id, text=text, client_id=client_id,
+            submitted_at=time.time(), kind=kind,
+        )
+        self._pending[client_id] = wish_id
+        self._queue.put_nowait(item)
+        return wish_id, self._queue.qsize() + (1 if self._current else 0)
+
+    async def submit(self, text: Any, client_id: Any) -> tuple[str, int]:
+        """Enqueue a petition. Returns (wish_id, position). Position counts the
+        petition itself plus everyone ahead of it (including the one being
+        granted), so an idle empty queue yields position 1.
+
+        Raises AlreadyPending / QueueFull with readable `.reason`.
+        """
+        text = ("" if text is None else str(text)).strip()[:_SUBMIT_TEXT_CAP]
+        client_id = str(client_id)
+        self._admit(client_id)
+        wish_id, position = self._enqueue(text, client_id, "wish")
+        await self._emit_queue()
+        return wish_id, position
+
+    async def submit_fix(self, client_id: Any) -> tuple[str, int]:
+        """Enqueue a City Engineer job. The static-assignment gate runs HERE:
+        when the worst demand ratio is below the gate there is nothing to fix
+        and TrafficSmooth is raised (the server turns it into a 409). Rate
+        limits and cooldowns live in the server."""
+        client_id = str(client_id)
+        self._admit(client_id)
+        assignment = traffic.assign(self._city(), time.time())
+        if assignment.max_ratio < C.FIX_GATE_RATIO:
+            raise TrafficSmooth(TRAFFIC_SMOOTH_REASON)
+        wish_id, position = self._enqueue(FIX_JOB_TEXT, client_id, "fix")
+        await self._emit_queue()
+        return wish_id, position
+
+    # --------------------------------------------------------------- lifecycle
+
+    async def start(self) -> None:
+        if self._task is None or self._task.done():
+            self._task = asyncio.get_running_loop().create_task(
+                self._run(), name="nemocity-queue-worker"
+            )
+
+    async def stop(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+            self._task = None
+
+    @property
+    def is_running(self) -> bool:
+        return self._task is not None and not self._task.done()
+
+    @property
+    def queue_length(self) -> int:
+        return self._queue.qsize()
+
+    @property
+    def current(self) -> Optional[dict]:
+        if self._current is None:
+            return None
+        return {
+            "wish_id": self._current.wish_id,
+            "text_preview": self._current.text[:TEXT_PREVIEW_LEN],
+        }
+
+    def snapshot(self) -> dict:
+        """The server's QueueLike view: waiting count + the job being granted."""
+        return {"length": self._queue.qsize(), "current": self.current}
+
+    # --------------------------------------------------------------- worker
+
+    async def _run(self) -> None:
+        while True:
+            item = await self._queue.get()
+            self._current = item
+            try:
+                await self._process(item)
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                # one petition must NEVER kill the worker
+                log.exception("wish %s crashed; city hall moves on", item.wish_id)
+                await self._safe_emit(
+                    {"type": "wish_rejected", "wish_id": item.wish_id, "reason": CRASH_REASON}
+                )
+            finally:
+                self._current = None
+                self._pending.pop(item.client_id, None)
+                self._queue.task_done()
+                await self._emit_queue()
+
+    async def _process(self, item: _Item) -> None:
+        if not self._browser_invoked:
+            await self.grant_item(item)
+            return
+
+        # Browser-invoked mode: announce the turn, then wait for the petitioner's
+        # browser to call invoke() (a gradio API request carrying their ZeroGPU
+        # quota). No invocation within the window -> city hall moves on.
+        token = uuid.uuid4().hex
+        loop = asyncio.get_running_loop()
+        started: asyncio.Future[bool] = loop.create_future()
+        done: asyncio.Future[bool] = loop.create_future()
+        self._awaiting = {
+            "wish_id": item.wish_id,
+            "token": token,
+            "client_id": item.client_id,
+            "item": item,
+            "started": started,
+            "done": done,
+            "begun": False,
+        }
+        try:
+            # SECURITY: the token is NOT broadcast. your_turn carries only the
+            # wish_id over the public SSE; the owner's browser fetches the secret
+            # token from GET /api/turn (cookie-authenticated, identity-bound).
+            turn_event = {
+                "type": "your_turn",
+                "wish_id": item.wish_id,
+                "window_s": self._invocation_window,
+            }
+            # Announce in thirds: re-emits cover SSE reconnects and slow tabs.
+            third = max(self._invocation_window / 3.0, 0.01)
+            invoked = False
+            for _ in range(3):
+                await self._safe_emit(turn_event)
+                try:
+                    await asyncio.wait_for(asyncio.shield(started), third)
+                    invoked = True
+                    break
+                except asyncio.TimeoutError:
+                    continue
+            if not invoked:
+                await self._safe_emit(
+                    {"type": "wish_rejected", "wish_id": item.wish_id, "reason": WANDERED_REASON}
+                )
+                return
+            try:
+                await asyncio.wait_for(asyncio.shield(done), self._grant_deadline)
+            except asyncio.TimeoutError:
+                # The invoked grant is hung past any sane petition length; the
+                # queue must not stall behind it.
+                log.error("grant for %s exceeded deadline; moving on", item.wish_id)
+                await self._safe_emit(
+                    {"type": "wish_rejected", "wish_id": item.wish_id, "reason": INTERRUPTED_REASON}
+                )
+        finally:
+            self._awaiting = None
+
+    def turn_token(self, wish_id: Any, client_id: Any) -> Optional[str]:
+        """Return the secret invocation token for the job at the counter — but
+        ONLY to its owner (identity-bound). Returns None when it isn't this
+        caller's turn."""
+        awaiting = self._awaiting
+        if (
+            awaiting is None
+            or awaiting["wish_id"] != str(wish_id)
+            or awaiting["client_id"] != str(client_id)
+        ):
+            return None
+        return awaiting["token"]
+
+    async def invoke(self, wish_id: Any, token: Any) -> dict:
+        """Run the grant for the job at the counter. Called from the petitioner's
+        gradio API request so the GPU work runs in THEIR quota context."""
+        awaiting = self._awaiting
+        if (
+            awaiting is None
+            or awaiting["wish_id"] != str(wish_id)
+            or awaiting["token"] != str(token)
+        ):
+            raise QueueError(NOT_YOUR_TURN_REASON)
+        if awaiting["begun"]:
+            raise QueueError(RITE_BEGUN_REASON)
+        awaiting["begun"] = True
+        if not awaiting["started"].done():
+            awaiting["started"].set_result(True)
+        try:
+            await self.grant_item(awaiting["item"])
+            return {"ok": True, "wish_id": str(wish_id)}
+        except Exception:
+            log.exception("invoked grant for %s crashed", wish_id)
+            await self._safe_emit(
+                {"type": "wish_rejected", "wish_id": str(wish_id), "reason": CRASH_REASON}
+            )
+            return {"ok": False, "wish_id": str(wish_id), "reason": CRASH_REASON}
+        finally:
+            if not awaiting["done"].done():
+                awaiting["done"].set_result(True)
+
+    # ----------------------------------------------------------------- grants
+
+    async def grant_item(self, item: _Item) -> None:
+        """The whole rite for one job; runs in the worker task (server mode) or
+        inside the petitioner's gradio request (browser-invoked mode)."""
+        if item.kind == "fix":
+            await self._grant_fix(item)
+        else:
+            await self._grant_wish(item)
+
+    def _wrap_emit(self, item: _Item):
+        """Planner-facing emit: inject this job's wish_id into any event that
+        lacks one (the plan event, thought tokens)."""
+
+        async def emit(event: dict) -> None:
+            if isinstance(event, dict) and "wish_id" not in event:
+                event = {**event, "wish_id": item.wish_id}
+            await self._safe_emit(event)
+
+        return emit
+
+    async def _apply_events(
+        self, item: _Item, city: CityState, events: list[dict], index: int
+    ) -> tuple[int, int, str]:
+        """world.apply each event; mirror into the live CityState; emit
+        tool_call + world_delta. Returns (next_index, landed, first_obs)."""
+        landed = 0
+        first_obs = ""
+        for call in events:
+            feature, observation = self._world.apply(item.wish_id, index, call)
+            index += 1
+            if not first_obs:
+                first_obs = observation
+            if feature is None:
+                log.warning("engine-composed event rejected: %s", observation)
+                continue
+            landed += 1
+            city.apply(feature)
+            await self._safe_emit(
+                {
+                    "type": "tool_call",
+                    "wish_id": item.wish_id,
+                    "call_index": index - 1,
+                    "tool": feature.tool,
+                    "args": dict(feature.args),
+                }
+            )
+            await self._safe_emit({"type": "world_delta", "feature": feature.to_dict()})
+        return index, landed, first_obs
+
+    async def _grant_wish(self, item: _Item) -> None:
+        await self._safe_emit({"type": "wish_started", "wish_id": item.wish_id, "text": item.text})
+        await self._emit_queue()
+
+        verdict = await self._moderator.check(item.text)
+        if not verdict.allowed:
+            await self._safe_emit(
+                {
+                    "type": "wish_rejected",
+                    "wish_id": item.wish_id,
+                    "reason": verdict.poetic_reason or "city hall declines this petition",
+                }
+            )
+            return
+
+        world_summary = self._world.summary()
+        city = self._city()
+        state = {"index": 0, "acts": 0, "landed": 0, "jobs_anchor": ""}
+
+        async def act(building_req: Any) -> str:
+            """ONE building entry {kind,name,near,floors,hue} -> engine places
+            it (plus an auto-routed connector) and the events land."""
+            if not isinstance(building_req, dict):
+                return "rejected: malformed building request"
+            if state["acts"] >= MAX_BUILDINGS_PER_WISH or state["index"] >= self._max_calls:
+                return HANDS_FULL_OBSERVATION
+            state["acts"] += 1
+            kind = tools.resolve_kind(building_req.get("kind"))
+            name = tools.sanitize_name(
+                building_req.get("name"),
+                default=tools.default_name(kind, item.text, item.wish_id),
+            )
+            events = placement.place(
+                city,
+                kind=kind,
+                name=name,
+                floors=_num(building_req.get("floors")),
+                hue=_num(building_req.get("hue")),
+                near=str(building_req.get("near") or ""),
+                wish_id=item.wish_id,
+                call_index=state["index"],
+            )
+            state["index"], landed, first_obs = await self._apply_events(
+                item, city, events, state["index"]
+            )
+            state["landed"] += landed
+            if landed and C.BUILDINGS[kind]["jobs"] > 0:
+                state["jobs_anchor"] = name
+            return first_obs or "rejected: nothing placed"
+
+        trace = await self._planner.grant(item.text, world_summary, act, self._wrap_emit(item))
+
+        # If the petition built NOTHING and the planner never actually planned —
+        # every turn an error (GPU/model failure) — reject honestly and DON'T
+        # persist an empty trace that pollutes the shared ledger.
+        turns = _trace_get(trace, "turns") or []
+        all_errored = bool(turns) and all(
+            str((t or {}).get("observation") or "").startswith("error:") for t in turns
+        )
+        if state["landed"] == 0 and (not turns or all_errored):
+            await self._safe_emit(
+                {"type": "wish_rejected", "wish_id": item.wish_id, "reason": BUSY_HEAVENS_REASON}
+            )
+            return
+
+        if state["landed"]:
+            await self._apply_infill(item, city, state)
+
+        # SECURITY: the reading + epitaph are model-composed and persist to the
+        # public dataset + ledger. Re-moderate; redact on denial so no unvetted
+        # prose survives in the archive.
+        reading = _trace_get(trace, "reading")
+        if reading and not self._moderator.check_content(reading).allowed:
+            _trace_set(trace, "reading", "city hall read this petition in silence.")
+        epitaph = _trace_get(trace, "epitaph")
+        if not epitaph or not self._moderator.check_content(epitaph).allowed:
+            epitaph = _epitaph_from_reading(_trace_get(trace, "reading")) or FALLBACK_EPITAPH
+            _trace_set(trace, "epitaph", epitaph)
+        self._enrich_trace(trace, item)
+        await self._persist_trace(trace, item)
+
+        self._world.record_epitaph(epitaph)
+        await self._safe_emit(
+            {
+                "type": "wish_granted",
+                "wish_id": item.wish_id,
+                "epitaph": str(epitaph),
+                "epoch": self._world.epoch,
+            }
+        )
+
+    async def _apply_infill(self, item: _Item, city: CityState, state: dict) -> None:
+        """Demand-driven infill: jobs outpacing homes pulls ONE bonus home in
+        near the new jobs (max 1 per petition)."""
+        jobs, housing = city.jobs, city.housing_capacity
+        if jobs <= housing * C.INFILL_RATIO or state["index"] + 2 > self._max_calls:
+            return
+        kind = "apartments" if jobs - housing >= C.INFILL_APARTMENTS_DEFICIT else "house"
+        events = placement.place(
+            city,
+            kind=kind,
+            name=tools.default_name(kind, item.text, item.wish_id + ":infill"),
+            floors=None,
+            hue=None,
+            near=state["jobs_anchor"],
+            wish_id=item.wish_id,
+            call_index=state["index"],
+        )
+        events.append({"tool": "note", "args": {"text": INFILL_NOTE, "kind": "infill"}})
+        state["index"], landed, _ = await self._apply_events(
+            item, city, events, state["index"]
+        )
+        state["landed"] += landed
+
+    async def _grant_fix(self, item: _Item) -> None:
+        await self._safe_emit({"type": "wish_started", "wish_id": item.wish_id, "text": item.text})
+        await self._emit_queue()
+
+        city = self._city()
+        now_s = time.time()
+        stats, candidates = traffic.snapshot(city, now_s)
+        if stats["max_ratio"] < C.FIX_GATE_RATIO or not candidates:
+            await self._safe_emit(
+                {
+                    "type": "wish_rejected",
+                    "wish_id": item.wish_id,
+                    "reason": TRAFFIC_SMOOTH_REASON,
+                }
+            )
+            return
+
+        by_id = {c["id"]: c for c in candidates}
+        best = candidates[0]  # sorted best-predicted-first
+        state = {"index": 0, "landed": 0, "applied": ""}
+
+        def canned_diagnosis(cand: dict) -> str:
+            return (
+                f"{stats['worst']} carries {stats['max_ratio']}x capacity at rush — "
+                f"{cand['desc']} cuts the index "
+                f"{stats['traffic_index']}->{cand['predicted_index']}."
+            )
+
+        async def act_fix(choice: Any) -> str:
+            """The planner's pick {choice, diagnosis, blurb} -> ONE apply_fix
+            event. Invalid/missing choice falls back to the best candidate."""
+            if state["landed"]:
+                return "rejected: the fix is already applied"
+            choice = choice if isinstance(choice, dict) else {}
+            cand = by_id.get(str(choice.get("choice") or "").strip().upper()) or best
+            # model-composed diagnosis goes on the shared world: wordlist-gate it
+            raw = str(choice.get("diagnosis") or "").strip()
+            diagnosis = raw[:200] if raw and self._moderator.check_content(raw).allowed else ""
+            if not diagnosis:
+                diagnosis = canned_diagnosis(cand)
+            call = {
+                "tool": "apply_fix",
+                "args": {
+                    "action": cand["action"],
+                    "cells": cand["cells"],
+                    "klass": cand["klass"],
+                    "name": cand["name"],
+                    "diagnosis": diagnosis,
+                    "metrics_before": {
+                        "traffic_index": stats["traffic_index"],
+                        "worst": stats["worst"] or "",
+                    },
+                    "metrics_predicted": {"traffic_index": cand["predicted_index"]},
+                },
+            }
+            state["index"], landed, obs = await self._apply_events(
+                item, city, [call], state["index"]
+            )
+            state["landed"] += landed
+            if landed:
+                state["applied"] = cand["id"]
+            return obs
+
+        public = [
+            {k: c[k] for k in ("id", "action", "desc", "predicted_index")}
+            for c in candidates
+        ]
+        trace: Any = None
+        planner_fix = getattr(self._planner, "fix", None)
+        if planner_fix is not None:
+            try:
+                trace = await planner_fix(stats, public, act_fix, self._wrap_emit(item))
+            except Exception:
+                log.exception("planner.fix crashed for %s; engine applies best", item.wish_id)
+        if state["landed"] == 0:
+            # parse failure / no planner: the engine applies the best predicted
+            # candidate with the canned diagnosis — a fix ALWAYS lands.
+            await act_fix({"choice": best["id"]})
+
+        epitaph = _trace_get(trace, "epitaph")
+        if not epitaph or not self._moderator.check_content(epitaph).allowed:
+            applied = by_id.get(state["applied"]) or best
+            epitaph = f"The City Engineer opened {applied['name']}."
+        if not isinstance(trace, dict):
+            trace = {"reading": "", "turns": []}
+        trace["epitaph"] = str(epitaph)
+        trace.setdefault("kind", "fix")
+        trace.setdefault("stats", stats)
+        self._enrich_trace(trace, item)
+        await self._persist_trace(trace, item)
+
+        self._world.record_epitaph(epitaph)
+        await self._safe_emit(
+            {
+                "type": "wish_granted",
+                "wish_id": item.wish_id,
+                "epitaph": str(epitaph),
+                "epoch": self._world.epoch,
+            }
+        )
+
+    # --------------------------------------------------------------- helpers
+
+    async def _persist_trace(self, trace: Any, item: _Item) -> None:
+        if self._persist is None or trace is None:
+            return
+        try:
+            result = self._persist(trace)
+            if inspect.isawaitable(result):
+                await result
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            log.exception("persist failed for %s (grant stands)", item.wish_id)
+
+    def _enrich_trace(self, trace: Any, item: _Item) -> None:
+        """Fill trace fields the planner cannot know (wish_id, moderation, ...)."""
+        fields = {
+            "wish_id": item.wish_id,
+            "text": item.text,
+            "submitted_at": item.submitted_at,
+        }
+        try:
+            if isinstance(trace, dict):
+                for key, value in fields.items():
+                    trace.setdefault(key, value)
+                trace.setdefault("moderation", {"allowed": True, "category": None})
+            elif trace is not None:
+                for key, value in fields.items():
+                    if not getattr(trace, key, None):
+                        setattr(trace, key, value)
+                if getattr(trace, "moderation", None) is None:
+                    setattr(trace, "moderation", {"allowed": True, "category": None})
+        except Exception:  # frozen dataclass etc. — enrichment is best-effort
+            log.debug("trace enrichment skipped for %s", item.wish_id, exc_info=True)
+
+    async def _emit_queue(self) -> None:
+        await self._safe_emit(
+            {"type": "queue", "length": self._queue.qsize(), "current": self.current}
+        )
+
+    async def _safe_emit(self, event: dict) -> None:
+        """Broadcast one SSE event; emit failures must never break a grant."""
+        try:
+            await self._emit(event)
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            log.warning("emit failed for event type %s", event.get("type"), exc_info=True)

engine/summary.py

@@ -0,0 +1,79 @@
+"""Compact city description for the LLM prompt (<600 chars, always).
+
+Covers: NEMOCITY, population, building counts by kind, named landmarks and
+streets, traffic index + worst street, growth ring. Duck-types over World
+(no engine.world import — no cycles).
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+from . import constants as C
+from . import traffic
+from .city import CityState
+
+MAX_LEN = 599  # contract: strictly under 600 chars
+
+_MAX_TALLY_KINDS = 6
+_MAX_LANDMARKS = 4
+_MAX_STREETS = 5
+
+_A_OR_AN_VOWEL = "aeiou"
+
+
+def _count_phrase(noun: str, n: int) -> str:
+    noun = noun.replace("_", " ")
+    if n == 1:
+        article = "an" if noun[:1] in _A_OR_AN_VOWEL else "a"
+        return f"{article} {noun}"
+    plural = noun + ("es" if noun.endswith(("s", "x", "z", "ch", "sh")) else "s")
+    return f"{n} {plural}"
+
+
+def summarize(world: Any, now_s: Optional[float] = None) -> str:
+    if now_s is None:
+        now_s = time.time()
+    city = CityState.from_events(getattr(world, "features", ()) or ())
+
+    parts: list[str] = [
+        f"NEMOCITY, pop {city.population(now_s)}, epoch {getattr(world, 'epoch', 0)}"
+    ]
+
+    counts = city.counts_by_kind()
+    if counts:
+        bits = [
+            _count_phrase(kind, counts[kind])
+            for kind in list(counts)[:_MAX_TALLY_KINDS]
+        ]
+        if len(counts) > _MAX_TALLY_KINDS:
+            bits.append("more")
+        parts.append("buildings: " + ", ".join(bits))
+    parts.append(f"jobs {city.jobs}, homes for {city.housing_capacity}")
+
+    landmarks = [
+        b.name for b in reversed(city.buildings)
+        if b.name and C.BUILDINGS[b.kind]["attract"] >= 3
+    ][:_MAX_LANDMARKS]
+    if landmarks:
+        parts.append("landmarks: " + ", ".join(landmarks))
+
+    streets = list(city.street_cells)
+    if streets:
+        tail = f" +{len(streets) - _MAX_STREETS}" if len(streets) > _MAX_STREETS else ""
+        parts.append("streets: " + ", ".join(streets[:_MAX_STREETS]) + tail)
+
+    assignment = traffic.assign(city, now_s)
+    line = f"traffic index {assignment.traffic_index}"
+    if assignment.max_ratio > 0:
+        worst = assignment.top_cells(1)
+        if worst:
+            line += f" (worst: {assignment.net.name(worst[0])} {assignment.ratio(worst[0]):.1f}x)"
+    parts.append(line)
+    parts.append(f"growth ring {city.growth_radius}")
+
+    text = " | ".join(parts)
+    if len(text) > MAX_LEN:
+        text = text[: MAX_LEN - 3] + "..."
+    return text

engine/tools.py

@@ -0,0 +1,279 @@
+"""NEMOCITY event-type specs — validation/clamping for the 4 city event types.
+
+Semantics (godseed lineage):
+* out-of-range NUMBERS are CLAMPED, never rejected;
+* unknown kinds are repaired via SYNONYMS (anything unknown -> house);
+* malformed shapes (bad cells, missing geometry) are rejected with a terse
+  observation string — but the only module that COMPOSES these events is the
+  engine itself (placement/traffic), so rejections mean engine bugs, not model
+  noise. The LLM never outputs coordinates.
+
+Pure stdlib. world.py validates through `validate_call`; queue_worker uses
+`resolve_kind` / `sanitize_name` / `default_name` on model-supplied fields.
+"""
+
+from __future__ import annotations
+
+import re
+import zlib
+from typing import Any, Optional
+
+from . import constants as C
+from .moderation import Moderator
+
+_moderator = Moderator()  # wordlist layers only; no judge
+
+TOOL_NAMES: tuple[str, ...] = ("place_building", "lay_road", "apply_fix", "note")
+
+FIX_ACTIONS = ("new_road", "upgrade_avenue")
+NOTE_KINDS = ("milestone", "infill", "fix")
+
+_FALLBACK_KIND = "house"
+
+
+# ----------------------------------------------------------------- kind resolver
+
+def resolve_kind(value: Any) -> str:
+    """Map model-supplied kind text to a BUILDINGS key. Never fails: synonyms
+    repair, substring rescues, anything else becomes a humble house."""
+    if not isinstance(value, str):
+        return _FALLBACK_KIND
+    v = re.sub(r"[\s\-]+", "_", value.strip().lower()).strip("_")
+    if v in C.BUILDINGS:
+        return v
+    if v in C.SYNONYMS:
+        return C.SYNONYMS[v]
+    if v.endswith("s") and v[:-1] in C.BUILDINGS:
+        return v[:-1]
+    for token, kind in C.SYNONYMS.items():
+        if token in v:
+            return kind
+    for kind in C.BUILDINGS:
+        if kind in v:
+            return kind
+    return _FALLBACK_KIND
+
+
+# ------------------------------------------------------------------ name helpers
+
+_STOPWORDS = frozenset((
+    "a", "an", "the", "and", "or", "of", "for", "with", "near", "by", "at",
+    "in", "on", "to", "please", "build", "make", "add", "put", "want", "like",
+    "new", "some", "my", "our", "me", "us", "city", "town",
+))
+
+
+def sanitize_name(value: Any, default: str = "") -> str:
+    """Printable, wordlist-clean, <=24 chars; falls back to `default`."""
+    if not isinstance(value, str):
+        return default
+    name = "".join(ch for ch in value if ch.isprintable())
+    name = re.sub(r"\s+", " ", name).strip()[: C.NAME_MAX_LEN].strip()
+    if not name or not _moderator.check_content(name).allowed:
+        return default
+    return name
+
+
+def default_name(kind: str, petition_text: str, wish_id: str) -> str:
+    """Deterministic pleasant default derived from petition words."""
+    words = [
+        w for w in re.findall(r"[A-Za-z]+", str(petition_text or ""))
+        if len(w) > 2 and w.lower() not in _STOPWORDS
+        and w.lower() not in C.BUILDINGS and w.lower() not in C.SYNONYMS
+    ]
+    label = kind.replace("_", " ").title()
+    if words:
+        pick = words[zlib.crc32(f"{wish_id}:{kind}".encode()) % len(words)].title()
+        candidate = f"{pick} {label}"[: C.NAME_MAX_LEN].strip()
+        if _moderator.check_content(candidate).allowed:
+            return candidate
+    return f"The {label}"[: C.NAME_MAX_LEN]
+
+
+def street_name_for(key: str) -> str:
+    """Curated street name from a deterministic key (e.g. 'w_000005:1:road')."""
+    return C.STREET_NAMES[zlib.crc32(str(key).encode()) % len(C.STREET_NAMES)]
+
+
+# ------------------------------------------------------------------- primitives
+
+def _err(msg: str) -> tuple[None, str]:
+    return None, f"rejected: {msg}"
+
+
+def _int_in(value: Any, lo: int, hi: int) -> Optional[int]:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        try:
+            value = float(str(value).strip())
+        except (ValueError, TypeError):
+            return None
+    return int(round(min(max(float(value), lo), hi)))
+
+
+def _coerce_cell(cell: Any) -> Optional[list[int]]:
+    if not isinstance(cell, (list, tuple)) or len(cell) < 2:
+        return None
+    cx = _int_in(cell[0], C.COORD_MIN, C.COORD_MAX)
+    cz = _int_in(cell[1], C.COORD_MIN, C.COORD_MAX)
+    if cx is None or cz is None:
+        return None
+    return [cx, cz]
+
+
+def _coerce_cells(raw: Any, max_cells: int = 256) -> Optional[list[list[int]]]:
+    if not isinstance(raw, (list, tuple)) or not raw:
+        return None
+    out: list[list[int]] = []
+    seen: set[tuple[int, int]] = set()
+    for c in list(raw)[:max_cells]:
+        cell = _coerce_cell(c)
+        if cell is None:
+            return None
+        if (cell[0], cell[1]) in seen:
+            continue
+        seen.add((cell[0], cell[1]))
+        out.append(cell)
+    return out
+
+
+def _text(value: Any, max_len: int) -> str:
+    s = "".join(ch for ch in str(value or "") if ch.isprintable())
+    return re.sub(r"\s+", " ", s).strip()[:max_len]
+
+
+# ------------------------------------------------------------------- validators
+
+def _validate_place_building(args: dict):
+    kind = resolve_kind(args.get("kind"))
+    spec = C.BUILDINGS[kind]
+    cx = _int_in(args.get("cx"), C.COORD_MIN, C.COORD_MAX - spec["w"] + 1)
+    cz = _int_in(args.get("cz"), C.COORD_MIN, C.COORD_MAX - spec["d"] + 1)
+    if cx is None or cz is None or args.get("cx") is None or args.get("cz") is None:
+        return _err("place_building needs cx, cz")
+    lo, hi = spec["floors"]
+    floors = _int_in(args.get("floors"), lo, hi)
+    if floors is None:
+        floors = lo
+    hue = _int_in(args.get("hue"), 0, 360)
+    if hue is None:
+        hue = 35
+    variant = _int_in(args.get("variant"), 0, 7)
+    if variant is None:
+        variant = 0
+    name = sanitize_name(args.get("name"), default=f"The {kind.replace('_', ' ').title()}")
+    return {
+        "kind": kind, "name": name, "cx": cx, "cz": cz,
+        "w": spec["w"], "d": spec["d"], "floors": floors,
+        "hue": hue, "variant": variant,
+    }, None
+
+
+def _validate_lay_road(args: dict):
+    cells = _coerce_cells(args.get("cells"))
+    if cells is None:
+        return _err("lay_road needs cells [[cx,cz],...]")
+    klass = str(args.get("klass") or "street").strip().lower()
+    if klass not in C.ROAD_CLASSES:
+        klass = "street"
+    name = sanitize_name(args.get("name"), default="")
+    out = {"cells": cells, "klass": klass}
+    if name:
+        out["name"] = name
+    return out, None
+
+
+def _coerce_metrics(raw: Any) -> dict:
+    out: dict[str, Any] = {}
+    if isinstance(raw, dict):
+        for k, v in list(raw.items())[:6]:
+            key = _text(k, 24)
+            if not key:
+                continue
+            if isinstance(v, bool):
+                continue
+            if isinstance(v, (int, float)):
+                num = round(float(v), 2)
+                out[key] = int(num) if num.is_integer() else num
+            elif isinstance(v, str):
+                out[key] = _text(v, 48)
+    return out
+
+
+def _validate_apply_fix(args: dict):
+    action = str(args.get("action") or "").strip().lower()
+    if action not in FIX_ACTIONS:
+        return _err(f"unknown fix action '{_text(args.get('action'), 24)}'")
+    cells = _coerce_cells(args.get("cells"))
+    if cells is None:
+        return _err("apply_fix needs cells [[cx,cz],...]")
+    klass = str(args.get("klass") or "avenue").strip().lower()
+    if klass not in C.ROAD_CLASSES:
+        klass = "avenue"
+    name = sanitize_name(args.get("name"), default=street_name_for(repr(cells[0])))
+    diagnosis = _text(args.get("diagnosis"), 200)
+    return {
+        "action": action, "cells": cells, "klass": klass, "name": name,
+        "diagnosis": diagnosis,
+        "metrics_before": _coerce_metrics(args.get("metrics_before")),
+        "metrics_predicted": _coerce_metrics(args.get("metrics_predicted")),
+    }, None
+
+
+def _validate_note(args: dict):
+    text = _text(args.get("text"), 140)
+    if not text:
+        return _err("note needs text")
+    if not _moderator.check_content(text).allowed:
+        return _err("those words may not be posted on the city ledger")
+    kind = str(args.get("kind") or "milestone").strip().lower()
+    if kind not in NOTE_KINDS:
+        kind = "milestone"
+    return {"text": text, "kind": kind}, None
+
+
+_VALIDATORS = {
+    "place_building": _validate_place_building,
+    "lay_road": _validate_lay_road,
+    "apply_fix": _validate_apply_fix,
+    "note": _validate_note,
+}
+
+
+def validate_call(tool: Any, args: Any) -> tuple[Optional[dict], Optional[str]]:
+    """Validate one event. Returns (canonical_args, None) or (None, rejection)."""
+    if not isinstance(tool, str) or tool not in _VALIDATORS:
+        return _err(f"unknown tool '{_text(tool, 32)}'")
+    if args is None:
+        args = {}
+    if not isinstance(args, dict):
+        return _err("args must be an object")
+    return _VALIDATORS[tool](args)
+
+
+def as_dict() -> dict:
+    """Plain-JSON view of the event surface (prompt builders may render this)."""
+    return {
+        "place_building": {
+            "kind": {"type": "enum", "values": list(C.BUILDINGS)},
+            "name": {"type": "string", "max_len": C.NAME_MAX_LEN},
+            "cx": {"type": "int", "min": C.COORD_MIN, "max": C.COORD_MAX},
+            "cz": {"type": "int", "min": C.COORD_MIN, "max": C.COORD_MAX},
+            "floors": {"type": "int", "note": "clamped to the kind's range"},
+            "hue": {"type": "int", "min": 0, "max": 360},
+        },
+        "lay_road": {
+            "cells": {"type": "cells", "note": "[[cx,cz],...] engine-routed only"},
+            "klass": {"type": "enum", "values": list(C.ROAD_CLASSES)},
+            "name": {"type": "string", "max_len": C.NAME_MAX_LEN},
+        },
+        "apply_fix": {
+            "action": {"type": "enum", "values": list(FIX_ACTIONS)},
+            "cells": {"type": "cells"},
+            "klass": {"type": "enum", "values": list(C.ROAD_CLASSES)},
+            "diagnosis": {"type": "string", "max_len": 200},
+        },
+        "note": {
+            "text": {"type": "string", "max_len": 140},
+            "kind": {"type": "enum", "values": list(NOTE_KINDS)},
+        },
+    }

engine/traffic.py

@@ -0,0 +1,393 @@
+"""NEMOCITY traffic — the Python static-assignment mirror.
+
+Same trip generation + A* + demand semantics as web/city/traffic.js, from the
+same event list and constants, so the ENGINE owns the facts the LLM sees (the
+live car queueing client-side is presentation and may drift a car or two).
+
+Determinism contract with the JS mirror:
+* mulberry32 (bit-exact port of web/city/rng.js); ONE draw per commuter,
+  seeded `building.seed ^ i`;
+* trip order = building event order, commuter index ascending;
+* destination roulette over completed jobs/attract buildings in event order,
+  weight = (jobs + 2*attract) / (1 + manhattanCentroidDist^1.5);
+* door = adjacent road cell with smallest (cz, cx);
+* incremental loading: each commuter routes by A* with
+  cost(cell) = (1/speed) * (1 + 2*demandRatio(cell)) over demand loaded so
+  far, then adds DEMAND_PER_COMMUTER to every cell of its path.
+
+Stats are evaluated AT PEAK RUSH (rushFactor = 1.0). Pure stdlib.
+"""
+
+from __future__ import annotations
+
+import heapq
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from . import constants as C
+from .city import WATER_CELLS, Building, Cell, CityState, in_bounds, neighbors4
+from .tools import street_name_for
+
+_MIN_CELL_COST = 1.0 / C.ROAD_CLASSES["avenue"]["speed"]  # admissible A* heuristic
+
+
+def mulberry32(seed: int):
+    """Bit-exact port of web/city/rng.js mulberry32 — keep byte-stable."""
+    a = seed & 0xFFFFFFFF
+
+    def rng() -> float:
+        nonlocal a
+        a = (a + 0x6D2B79F5) & 0xFFFFFFFF
+        t = a
+        t = ((t ^ (t >> 15)) * (t | 1)) & 0xFFFFFFFF
+        t = (t ^ ((t + (((t ^ (t >> 7)) * (t | 61)) & 0xFFFFFFFF)) & 0xFFFFFFFF)) & 0xFFFFFFFF
+        return ((t ^ (t >> 14)) & 0xFFFFFFFF) / 4294967296.0
+
+    return rng
+
+
+# -------------------------------------------------------------------- road net
+
+@dataclass
+class RoadNet:
+    """Road cells + class/name, optionally with a candidate fix applied."""
+
+    cells: dict[Cell, tuple[str, str]]  # cell -> (klass, name)
+
+    @classmethod
+    def from_city(cls, city: CityState, fix: Optional[dict] = None) -> "RoadNet":
+        cells = {cell: (rc.klass, rc.name) for cell, rc in city.roads.items()}
+        if fix:
+            if fix["action"] == "new_road":
+                for cx, cz in fix["cells"]:
+                    cells[(cx, cz)] = (fix["klass"], fix["name"])
+            elif fix["action"] == "upgrade_avenue":
+                for cx, cz in fix["cells"]:
+                    cell = (cx, cz)
+                    if cell in cells:
+                        cells[cell] = ("avenue", cells[cell][1])
+        return cls(cells=cells)
+
+    def capacity(self, cell: Cell) -> float:
+        return C.ROAD_CLASSES[self.cells[cell][0]]["capacity"]
+
+    def speed(self, cell: Cell) -> float:
+        return C.ROAD_CLASSES[self.cells[cell][0]]["speed"]
+
+    def name(self, cell: Cell) -> str:
+        return self.cells[cell][1]
+
+    def door(self, b: Building) -> Optional[Cell]:
+        adjacent = {
+            n for cell in b.cells for n in neighbors4(cell) if n in self.cells
+        }
+        if not adjacent:
+            return None
+        return min(adjacent, key=lambda c: (c[1], c[0]))
+
+
+# -------------------------------------------------------------------- trip gen
+
+def trip_table(city: CityState, now_s: float) -> list[tuple[Building, Building]]:
+    """Static OD pairs (gravity model, seeded roulette). Completed buildings
+    only on both ends; recomputed only when buildings change."""
+    completed = [b for b in city.buildings if b.progress(now_s) >= 1.0]
+    homes = [b for b in completed if C.BUILDINGS[b.kind]["residents"] > 0]
+    dests = [
+        b for b in completed
+        if C.BUILDINGS[b.kind]["jobs"] + C.BUILDINGS[b.kind]["attract"] > 0
+    ]
+    if not dests:
+        return []
+    trips: list[tuple[Building, Building]] = []
+    for home in homes:
+        hx, hz = home.centroid
+        weights: list[float] = []
+        for dest in dests:
+            dx, dz = dest.centroid
+            dist = abs(dx - hx) + abs(dz - hz)
+            spec = C.BUILDINGS[dest.kind]
+            weights.append(
+                (spec["jobs"] + C.TRIP_ATTRACT_FACTOR * spec["attract"])
+                / (1 + dist ** C.TRIP_DIST_EXP)
+            )
+        total = sum(weights)
+        if total <= 0:
+            continue
+        for i in range(C.BUILDINGS[home.kind]["residents"]):
+            r = mulberry32((home.seed ^ i) & 0xFFFFFFFF)() * total
+            acc = 0.0
+            chosen = dests[-1]
+            for dest, weight in zip(dests, weights):
+                acc += weight
+                if r < acc:
+                    chosen = dest
+                    break
+            trips.append((home, chosen))
+    return trips
+
+
+# ------------------------------------------------------------------ assignment
+
+@dataclass
+class Assignment:
+    net: RoadNet
+    demand: dict[Cell, float] = field(default_factory=dict)
+    paths: list[tuple[Cell, Cell, tuple[Cell, ...]]] = field(default_factory=list)
+    traffic_index: int = 0
+
+    def ratio(self, cell: Cell) -> float:
+        return self.demand.get(cell, 0.0) / self.net.capacity(cell)
+
+    @property
+    def max_ratio(self) -> float:
+        if not self.net.cells:
+            return 0.0
+        return max((self.ratio(c) for c in self.net.cells), default=0.0)
+
+    def top_cells(self, n: int) -> list[Cell]:
+        return sorted(
+            self.net.cells,
+            key=lambda c: (-self.ratio(c), c[1], c[0]),
+        )[:n]
+
+
+def _astar(net: RoadNet, demand: dict[Cell, float], start: Cell, goal: Cell
+           ) -> Optional[list[Cell]]:
+    if start == goal:
+        return [start]
+
+    def cell_cost(cell: Cell) -> float:
+        ratio = demand.get(cell, 0.0) / net.capacity(cell)
+        return (1.0 / net.speed(cell)) * (1 + C.CONGESTION_COST_FACTOR * ratio)
+
+    def h(cell: Cell) -> float:
+        return (abs(cell[0] - goal[0]) + abs(cell[1] - goal[1])) * _MIN_CELL_COST
+
+    g: dict[Cell, float] = {start: 0.0}
+    prev: dict[Cell, Cell] = {}
+    heap: list[tuple[float, int, int, Cell]] = [(h(start), start[1], start[0], start)]
+    closed: set[Cell] = set()
+    while heap:
+        _, _, _, cell = heapq.heappop(heap)
+        if cell in closed:
+            continue
+        if cell == goal:
+            path = [cell]
+            while path[-1] != start:
+                path.append(prev[path[-1]])
+            path.reverse()
+            return path
+        closed.add(cell)
+        for n in neighbors4(cell):
+            if n not in net.cells or n in closed:
+                continue
+            cand = g[cell] + cell_cost(n)
+            if cand < g.get(n, float("inf")):
+                g[n] = cand
+                prev[n] = cell
+                heapq.heappush(heap, (cand + h(n), n[1], n[0], n))
+    return None
+
+
+def assign(city: CityState, now_s: float, fix: Optional[dict] = None) -> Assignment:
+    """Incremental static assignment at peak rush. <2s for a genesis city."""
+    net = RoadNet.from_city(city, fix)
+    out = Assignment(net=net)
+    for home, dest in trip_table(city, now_s):
+        od, dd = net.door(home), net.door(dest)
+        if od is None or dd is None:
+            continue
+        path = _astar(net, out.demand, od, dd)
+        if path is None:
+            continue
+        for cell in path:
+            out.demand[cell] = out.demand.get(cell, 0.0) + C.DEMAND_PER_COMMUTER
+        out.paths.append((od, dd, tuple(path)))
+    ratios = sorted((out.ratio(c) for c in net.cells), reverse=True)
+    top = ratios[: C.TRAFFIC_TOP_CELLS]
+    if top:
+        # pad: a city with fewer road cells than the window still reads honestly
+        mean = sum(top) / C.TRAFFIC_TOP_CELLS
+        out.traffic_index = int(round(100 * mean))
+    return out
+
+
+# ----------------------------------------------------------------------- stats
+
+def _intersection_name(net: RoadNet, cell: Cell) -> str:
+    names = [net.name(cell)]
+    for n in neighbors4(cell):
+        if n in net.cells and net.name(n) not in names:
+            names.append(net.name(n))
+    return " & ".join(names[:2])
+
+
+def stats(city: CityState, assignment: Assignment) -> dict:
+    net = assignment.net
+    top = [
+        c for c in assignment.top_cells(5) if assignment.ratio(c) > 0
+    ]
+    worst = top[0] if top else None
+    intersections = [
+        c for c in net.cells
+        if sum(1 for n in neighbors4(c) if n in net.cells) >= 3
+    ]
+    worst_x = max(
+        intersections, key=lambda c: (assignment.ratio(c), -c[1], -c[0]), default=None
+    )
+    return {
+        "traffic_index": assignment.traffic_index,
+        "max_ratio": round(assignment.max_ratio, 2),
+        "worst": net.name(worst) if worst else None,
+        "worst_intersection": _intersection_name(net, worst_x) if worst_x else None,
+        "top": [
+            {
+                "street": net.name(c),
+                "cell": [c[0], c[1]],
+                "ratio": round(assignment.ratio(c), 2),
+                "klass": net.cells[c][0],
+            }
+            for c in top
+        ],
+    }
+
+
+# ------------------------------------------------------------------ candidates
+
+def _bypass_candidate(
+    city: CityState, assignment: Assignment, now_s: float
+) -> Optional[dict]:
+    """Engine-routed relief road around the worst cell: Dijkstra over the grid,
+    new cells cost extra, water at 4x (a fix may deliberately bridge), jammed
+    cells forbidden."""
+    net = assignment.net
+    jammed = {
+        c for c in net.cells if assignment.ratio(c) >= C.FIX_AVOID_RATIO
+    }
+    if not jammed:
+        return None
+    worst = min(jammed, key=lambda c: (-assignment.ratio(c), c[1], c[0]))
+    od_counts: dict[tuple[Cell, Cell], int] = {}
+    for od, dd, path in assignment.paths:
+        if worst in path:
+            od_counts[(od, dd)] = od_counts.get((od, dd), 0) + 1
+    if not od_counts:
+        return None
+    (start, goal), _ = min(
+        od_counts.items(), key=lambda kv: (-kv[1], kv[0][0][1], kv[0][0][0])
+    )
+
+    def cost(cell: Cell) -> Optional[float]:
+        if cell in jammed and cell not in (start, goal):
+            return None
+        if cell in net.cells:
+            return 1.0 / net.speed(cell)
+        if cell in city.building_cells:
+            return None
+        if cell in WATER_CELLS:
+            return C.FIX_NEW_CELL_COST * C.FIX_WATER_COST_MULT
+        return C.FIX_NEW_CELL_COST
+
+    dist: dict[Cell, float] = {start: 0.0}
+    prev: dict[Cell, Cell] = {}
+    heap: list[tuple[float, int, int, Cell]] = [(0.0, start[1], start[0], start)]
+    closed: set[Cell] = set()
+    while heap:
+        d, _, _, cell = heapq.heappop(heap)
+        if cell in closed:
+            continue
+        if cell == goal:
+            break
+        closed.add(cell)
+        for n in neighbors4(cell):
+            if n in closed:
+                continue
+            c = cost(n)
+            if c is None:
+                continue
+            cand = d + c
+            if cand < dist.get(n, float("inf")):
+                dist[n] = cand
+                prev[n] = cell
+                heapq.heappush(heap, (cand, n[1], n[0], n))
+    if goal not in prev and goal != start:
+        return None
+    path = [goal]
+    while path[-1] != start:
+        path.append(prev[path[-1]])
+    path.reverse()
+    new_cells = [c for c in path if c not in net.cells]
+    if not new_cells or len(new_cells) > C.FIX_MAX_NEW_CELLS:
+        return None
+    name = street_name_for(f"fix:{city.road_version}:bypass")
+    bridges = sum(1 for c in new_cells if c in WATER_CELLS)
+    fix = {
+        "action": "new_road",
+        "cells": [[c[0], c[1]] for c in new_cells],
+        "klass": "avenue",
+        "name": name,
+    }
+    desc = f"new avenue {name}, {len(new_cells)} cells"
+    if bridges:
+        desc += f" incl. a {bridges}-cell second bridge"
+    fix["desc"] = desc
+    fix["predicted_index"] = assign(city, now_s, fix).traffic_index
+    return fix
+
+
+def _upgrade_candidates(
+    city: CityState, assignment: Assignment, now_s: float, limit: int = 2
+) -> list[dict]:
+    net = assignment.net
+    names: list[str] = []
+    for cell in assignment.top_cells(C.TRAFFIC_TOP_CELLS):
+        klass, name = net.cells[cell]
+        if klass == "street" and assignment.ratio(cell) > 0 and name not in names:
+            names.append(name)
+        if len(names) >= limit:
+            break
+    out = []
+    for name in names:
+        cells = [
+            [c[0], c[1]]
+            for c, (klass, n) in net.cells.items()
+            if n == name and klass == "street"
+        ]
+        if not cells:
+            continue
+        cells.sort(key=lambda c: (c[1], c[0]))
+        fix = {
+            "action": "upgrade_avenue",
+            "cells": cells,
+            "klass": "avenue",
+            "name": name,
+            "desc": f"upgrade {name} to a 6-lane avenue ({len(cells)} cells)",
+        }
+        fix["predicted_index"] = assign(city, now_s, fix).traffic_index
+        out.append(fix)
+    return out
+
+
+def candidates(city: CityState, assignment: Assignment, now_s: float) -> list[dict]:
+    """2-4 pre-validated fixes, best predicted first, ids F1..Fn."""
+    found: list[dict] = []
+    bypass = _bypass_candidate(city, assignment, now_s)
+    if bypass:
+        found.append(bypass)
+    found.extend(_upgrade_candidates(city, assignment, now_s))
+    found.sort(key=lambda f: (f["predicted_index"], f["action"], f["name"]))
+    for i, fix in enumerate(found[:4]):
+        fix["id"] = f"F{i + 1}"
+    return found[:4]
+
+
+def snapshot(city: CityState, now_s: Optional[float] = None) -> tuple[dict, list[dict]]:
+    """(stats, candidates) for the fix mechanic — the engine owns the facts."""
+    if now_s is None:
+        now_s = time.time()
+    assignment = assign(city, now_s)
+    st = stats(city, assignment)
+    cands = candidates(city, assignment, now_s) if assignment.max_ratio > 0 else []
+    return st, cands

engine/world.py

@@ -0,0 +1,205 @@
+"""NEMOCITY world state — the deterministic engine owns ALL facts.
+
+The world is an append-only ordered list of Features (events). City-at-any-
+moment is a pure function of that list; the JS renderer derives all geometry
+from it and engine/city.py derives the Python views.
+
+The LLM never touches this module's internals: the engine composes event
+args (placement/traffic own all coordinates), validation clamps/repairs via
+engine/tools.py, the deterministic seed is crc32(f"{wish_id}:{call_index}"),
+and a terse observation string goes back to the planner loop.
+
+Wire/internal names keep godseed's wish_id/wish_* verbatim (zero-risk reuse);
+user-facing copy says "petition" elsewhere.
+
+Pure stdlib, synchronous, no pydantic.
+"""
+
+from __future__ import annotations
+
+import copy
+import re
+import time
+import zlib
+from dataclasses import dataclass
+from typing import Any, Iterable, Optional
+
+from . import summary as _summary
+from . import tools as _tools
+
+_FEATURE_ID_RE = re.compile(r"^e_(\d+)$")
+
+_EPITAPH_KEEP = 64  # in-memory tail; the full archive lives in traces/wishes.jsonl
+
+
+@dataclass
+class Feature:
+    """One immutable city event. Canonical JSON shape per ARCHITECTURE.md."""
+
+    id: str
+    wish_id: str
+    tool: str
+    args: dict
+    seed: int
+    t: float
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "wish_id": self.wish_id,
+            "tool": self.tool,
+            "args": copy.deepcopy(self.args),
+            "seed": self.seed,
+            "t": self.t,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Feature":
+        return cls(
+            id=d["id"],
+            wish_id=d["wish_id"],
+            tool=d["tool"],
+            args=copy.deepcopy(d.get("args") or {}),
+            seed=int(d.get("seed", 0)),
+            t=d.get("t", 0),
+        )
+
+
+def _seed_for(wish_id: str, call_index: int) -> int:
+    return zlib.crc32(f"{wish_id}:{call_index}".encode("utf-8")) & 0x7FFFFFFF
+
+
+def _observation(feature: Feature) -> str:
+    """Terse 'ok' observation the planner can record."""
+    t, a = feature.tool, feature.args
+    if t == "place_building":
+        return (
+            f"ok: {a['kind']} '{a['name']}' placed at ({a['cx']},{a['cz']}), "
+            f"{a['floors']} floors"
+        )
+    if t == "lay_road":
+        name = a.get("name") or "unnamed"
+        return f"ok: {len(a['cells'])} cells of {a['klass']} laid ({name})"
+    if t == "apply_fix":
+        return f"ok: {a['action']} applied on {a['name']} ({len(a['cells'])} cells)"
+    if t == "note":
+        return "ok: noted on the city ledger"
+    return "ok"  # pragma: no cover — every known tool is handled above
+
+
+class World:
+    """Append-only event list + derived views. Single-threaded (asyncio)."""
+
+    def __init__(self) -> None:
+        self._features: list[Feature] = []
+        self._epitaphs: list[str] = []
+        self._next_index: int = 0
+        self._last_signature: Optional[tuple] = None
+
+    # ------------------------------------------------------------- loading
+
+    @classmethod
+    def load(cls, features: Iterable[Any], epitaphs: Optional[Iterable[str]] = None) -> "World":
+        """Rebuild a world from persisted event dicts (or Feature objects).
+
+        Persisted data is trusted verbatim — values (including seeds) are NOT
+        re-validated, so genesis and replayed traces stay byte-identical.
+        """
+        world = cls()
+        for f in features or ():
+            feature = f if isinstance(f, Feature) else Feature.from_dict(f)
+            world._features.append(feature)
+        world._next_index = world._derive_next_index()
+        world._epitaphs = [str(e)[:120] for e in (epitaphs or ()) if e][-_EPITAPH_KEEP:]
+        return world
+
+    def _derive_next_index(self) -> int:
+        best = -1
+        for f in self._features:
+            m = _FEATURE_ID_RE.match(f.id)
+            if m:
+                best = max(best, int(m.group(1)))
+        return best + 1 if best >= 0 else len(self._features)
+
+    # ------------------------------------------------------------- mutation
+
+    def apply(
+        self,
+        wish_id: str,
+        call_index: int,
+        call: Any,
+        t: Optional[float] = None,
+    ) -> tuple[Optional[Feature], str]:
+        """Validate and apply one event.
+
+        Returns (feature, observation) on success, (None, rejection) otherwise.
+        Out-of-range numbers are clamped; unknown tools/shapes are rejected with
+        a terse observation string. The world only changes on success.
+        """
+        if not isinstance(call, dict):
+            return None, "rejected: malformed call"
+        tool = call.get("tool")
+        if isinstance(tool, str):
+            tool = tool.strip().lower()
+        canonical, err = _tools.validate_call(tool, call.get("args"))
+        if err:
+            return None, err
+        # An identical consecutive call within one wish is refused with a nudge
+        # (small models repeat themselves; the city does not).
+        signature = (str(wish_id), tool, repr(sorted(canonical.items())))
+        if signature == self._last_signature:
+            return None, "rejected: already done; change something, or say done"
+        self._last_signature = signature
+        feature = Feature(
+            id=f"e_{self._next_index:06d}",
+            wish_id=str(wish_id),
+            tool=tool,
+            args=canonical,
+            seed=_seed_for(str(wish_id), int(call_index)),
+            t=time.time() if t is None else t,
+        )
+        self._next_index += 1
+        self._features.append(feature)
+        return feature, _observation(feature)
+
+    def record_epitaph(self, text: Any) -> None:
+        """Record a granted petition's blurb (the ticker shows the last few)."""
+        if text:
+            self._epitaphs.append(str(text)[:120])
+            if len(self._epitaphs) > _EPITAPH_KEEP:
+                del self._epitaphs[: -_EPITAPH_KEEP]
+
+    # ------------------------------------------------------------- views
+
+    @property
+    def features(self) -> tuple[Feature, ...]:
+        return tuple(self._features)
+
+    @property
+    def epitaphs(self) -> tuple[str, ...]:
+        return tuple(self._epitaphs)
+
+    @property
+    def version(self) -> int:
+        return len(self._features)
+
+    @property
+    def epoch(self) -> int:
+        """Number of distinct granted petitions (genesis is epoch 0)."""
+        seen: set[str] = set()
+        for f in self._features:
+            if f.wish_id != "genesis":
+                seen.add(f.wish_id)
+        return len(seen)
+
+    def state_dict(self) -> dict:
+        """Full world state for /api/state and SSE hello consumers."""
+        return {
+            "version": self.version,
+            "epoch": self.epoch,
+            "features": [f.to_dict() for f in self._features],
+        }
+
+    def summary(self, now_s: Optional[float] = None) -> str:
+        """Compact (<600 chars) description for the LLM prompt."""
+        return _summary.summarize(self, now_s)

mind/__init__.py

@@ -0,0 +1,25 @@
+"""GODSEED mind — Agent C.
+
+The Mind interprets a wish, narrates a short Reading aloud, then runs a
+grammar-constrained plan-act-observe loop over the engine's 11-tool DSL.
+It never computes geometry and never owns world state (the "her" pattern):
+the deterministic engine clamps, executes, and records every act.
+
+Public surface:
+    Planner            — async grant(wish, world_summary, act, emit) -> WishTrace dict
+    make_backend       — GODSEED_BACKEND env -> MockBackend | LlamaCppBackend | ZeroGPUBackend
+    judge              — default-deny moderation judgment (injected into engine moderation)
+"""
+
+from .backends import LlamaCppBackend, MockBackend, ZeroGPUBackend, make_backend
+from .moderation_judge import judge
+from .planner import Planner
+
+__all__ = [
+    "Planner",
+    "make_backend",
+    "MockBackend",
+    "LlamaCppBackend",
+    "ZeroGPUBackend",
+    "judge",
+]

mind/backends.py

@@ -0,0 +1,497 @@
+"""Generation backends for the NEMOCITY mind.
+
+Protocol (duck-typed; see `Backend`):
+
+    name: str                       # "mock" | "llamacpp" | "zerogpu"
+    model_id: str                   # human-readable model identifier
+    oneshot: bool                   # always True — NEMOCITY is one-shot only
+    async def generate_stream(prompt: str, grammar: str | None,
+                              max_tokens: int) -> AsyncIterator[str]
+
+`grammar` is a plain string TAG (mind/validate.py), never a real grammar:
+"build" | "fix" | "moderation" select the wanted JSON shape (validation +
+temperature 0.4), a "!strict" suffix means a retry pass at temperature 0,
+None means free text. The protocol signature is byte-compatible with
+godseed's so the copied plumbing keeps working.
+
+Selected via the CITY_BACKEND env: mock (default) | zerogpu | llamacpp.
+
+- MockBackend: deterministic keyword-driven scripts (mind/mock_scripts.py)
+  with small delays so streaming looks alive. Local dev + headless demos.
+- ZeroGPUBackend: transformers + spaces.GPU, Nemotron-Nano-9B-v2 resident on
+  cuda. ONE @spaces.GPU call per petition (the June 12 lesson). Ship path.
+- LlamaCppBackend: llama-cpp-python + a local GGUF; offgrid stretch, not the
+  ship path.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import json
+import os
+import re
+import threading
+from typing import AsyncIterator, Protocol, runtime_checkable
+
+from . import prompts
+from .mock_scripts import build_script, fix_script
+from .validate import (
+    FIX_TAG,
+    base_tag,
+    is_moderation_grammar,
+    is_strict,
+    parse_build,
+    parse_fix,
+    parse_moderation,
+)
+
+
+@runtime_checkable
+class Backend(Protocol):
+    """Structural type for generation backends."""
+
+    name: str
+    model_id: str
+
+    def generate_stream(
+        self, prompt: str, grammar: str | None, max_tokens: int
+    ) -> AsyncIterator[str]: ...
+
+
+# --------------------------------------------------------------------------
+# Mock backend — what demos run on
+# --------------------------------------------------------------------------
+
+_MOCK_DENYLIST: tuple[tuple[re.Pattern[str], str], ...] = (
+    (re.compile(r"\b(nazi|hitler|swastika|kkk|genocide|lynch)\b", re.I), "hate"),
+    (re.compile(r"\b(kill|murder|slaughter|massacre|behead|stab)\b", re.I), "violence"),
+    (re.compile(r"\b(bomb|terror|terrorist|terrorism|shooting)\b", re.I), "violence"),
+    (re.compile(r"\b(rape|porn|sex|sexual|nude|naked|nsfw)\b", re.I), "sexual"),
+    (re.compile(r"\b(suicide|self[- ]?harm|cutting)\b", re.I), "self-harm"),
+)
+
+
+def _chunks(text: str, size: int) -> list[str]:
+    return [text[i : i + size] for i in range(0, len(text), size)]
+
+
+class MockBackend:
+    """Deterministic scripted backend.
+
+    Routing (marker constants from mind/prompts.py):
+      - moderation tag -> keyword-denylist verdict on the text after
+        CANDIDATE_MARKER;
+      - prompts containing FIX_MARKER -> fix script (reads the rendered
+        candidates/numbers back out of the prompt);
+      - everything else -> BUILD JSON keyed on the petition line after the
+        last PETITION_MARKER.
+
+    Token delays come from CITY_MOCK_DELAY (seconds per chunk, default
+    0.012); tests pass delay=0.0 explicitly.
+    """
+
+    name = "mock"
+    model_id = "nemocity-mock-scripts"
+    oneshot = True
+
+    def __init__(self, delay: float | None = None):
+        if delay is None:
+            try:
+                delay = float(os.environ.get("CITY_MOCK_DELAY", "0.012"))
+            except ValueError:
+                delay = 0.012
+        self.delay = max(0.0, delay)
+
+    async def _tick(self) -> None:
+        if self.delay:
+            await asyncio.sleep(self.delay)
+        else:
+            await asyncio.sleep(0)  # stay fair to the event loop
+
+    @staticmethod
+    def _tail(prompt: str, marker: str) -> str:
+        parts = prompt.rsplit(marker, 1)
+        return parts[-1] if len(parts) == 2 else prompt
+
+    def _petition(self, prompt: str) -> str:
+        tail = self._tail(prompt, prompts.PETITION_MARKER)
+        return (tail.splitlines() or [""])[0].strip()
+
+    def _moderate(self, prompt: str) -> dict:
+        tail = self._tail(prompt, prompts.CANDIDATE_MARKER)
+        candidate = (tail.splitlines() or [""])[0].strip()
+        for pattern, category in _MOCK_DENYLIST:
+            if pattern.search(candidate):
+                return {"allowed": False, "category": category}
+        return {"allowed": True, "category": ""}
+
+    async def generate_stream(
+        self, prompt: str, grammar: str | None = None, max_tokens: int = 700
+    ) -> AsyncIterator[str]:
+        if is_moderation_grammar(grammar):
+            verdict = json.dumps(self._moderate(prompt))
+            for chunk in _chunks(verdict, 8):
+                await self._tick()
+                yield chunk
+            return
+
+        if prompts.FIX_MARKER in prompt:
+            payload = fix_script(prompt)
+        else:
+            payload = build_script(self._petition(prompt))
+        for chunk in _chunks(payload, 12):
+            await self._tick()
+            yield chunk
+
+
+# --------------------------------------------------------------------------
+# llama.cpp backend — local GGUF (offgrid stretch; NOT the ship path)
+# --------------------------------------------------------------------------
+
+_THREAD_DONE = object()
+
+
+class LlamaCppBackend:
+    """llama-cpp-python backend (CPU). No grammars — tags only pick the
+    temperature; the lenient parsers + planner fallback cover messy output.
+
+    Lazy: nothing is imported or downloaded until the first generate call.
+    Model resolution order:
+      1. CITY_GGUF env — local path to a .gguf file;
+      2. hf_hub_download(CITY_GGUF_REPO, CITY_GGUF_FILE).
+
+    Generation runs in a thread executor; chunks cross into the event loop
+    through a bounded asyncio.Queue (backpressure included). If the consumer
+    abandons the stream early, a cancel flag stops the producer thread.
+    """
+
+    name = "llamacpp"
+    oneshot = True
+
+    DEFAULT_REPO = "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF"
+    DEFAULT_FILE = "NVIDIA-Nemotron3-Nano-4B-Q4_K_M.gguf"
+
+    def __init__(
+        self,
+        model_path: str | None = None,
+        n_ctx: int = 4096,
+        n_threads: int | None = None,
+    ):
+        self.model_path = model_path or os.environ.get("CITY_GGUF") or None
+        self.repo_id = os.environ.get("CITY_GGUF_REPO", self.DEFAULT_REPO)
+        self.filename = os.environ.get("CITY_GGUF_FILE", self.DEFAULT_FILE)
+        self.n_ctx = n_ctx
+        self.n_threads = n_threads
+        self.model_id = self.model_path or f"{self.repo_id}:{self.filename}"
+        self._llm = None
+        self._lock = threading.Lock()
+
+    # -- lazy model load (thread-safe; called from executor threads) --------
+
+    def _ensure_llm(self):
+        with self._lock:
+            if self._llm is not None:
+                return self._llm
+            from llama_cpp import Llama  # heavy import deferred
+
+            path = self.model_path
+            if not path or not os.path.exists(path):
+                from huggingface_hub import hf_hub_download
+
+                path = hf_hub_download(repo_id=self.repo_id, filename=self.filename)
+            kwargs = {"model_path": path, "n_ctx": self.n_ctx, "verbose": False}
+            threads = self.n_threads or (os.cpu_count() or 4)
+            kwargs["n_threads"] = threads
+            kwargs["n_batch"] = 512  # larger prompt-eval batch -> faster prefill
+            self._llm = Llama(**kwargs)
+            self.model_id = path
+            return self._llm
+
+    async def generate_stream(
+        self, prompt: str, grammar: str | None = None, max_tokens: int = 700
+    ) -> AsyncIterator[str]:
+        loop = asyncio.get_running_loop()
+        queue: asyncio.Queue = asyncio.Queue(maxsize=64)
+        cancelled = threading.Event()
+        if grammar is None:
+            temperature = 0.7
+        else:
+            temperature = 0.0 if is_strict(grammar) else 0.35
+
+        def _put(item) -> bool:
+            """Push from the producer thread; honor cancellation."""
+            future = asyncio.run_coroutine_threadsafe(queue.put(item), loop)
+            while not cancelled.is_set():
+                try:
+                    future.result(timeout=0.25)
+                    return True
+                except concurrent.futures.TimeoutError:
+                    continue
+                except Exception:
+                    return False
+            future.cancel()
+            return False
+
+        def _produce() -> None:
+            try:
+                llm = self._ensure_llm()
+                stream = llm.create_completion(
+                    prompt=prompt,
+                    max_tokens=max_tokens,
+                    stream=True,
+                    temperature=temperature,
+                    top_p=0.9,
+                    repeat_penalty=1.1,
+                )
+                for part in stream:
+                    if cancelled.is_set():
+                        break
+                    text = part["choices"][0].get("text", "")
+                    if text and not _put(text):
+                        break
+            except Exception as exc:  # surfaced to the consumer below
+                _put(exc)
+            finally:
+                _put(_THREAD_DONE)
+
+        producer = loop.run_in_executor(None, _produce)
+        try:
+            while True:
+                item = await queue.get()
+                if item is _THREAD_DONE:
+                    break
+                if isinstance(item, Exception):
+                    raise item
+                yield item
+        finally:
+            cancelled.set()
+            # Drain so a blocked producer can reach its sentinel and exit.
+            while not queue.empty():
+                queue.get_nowait()
+            await producer
+
+
+# --------------------------------------------------------------------------
+# ZeroGPU backend — Nemotron-Nano-9B-v2 (the ship path)
+# --------------------------------------------------------------------------
+
+class ZeroGPUBackend:
+    """transformers + spaces.GPU backend (HF ZeroGPU).
+
+    All heavy imports (torch, transformers, spaces) are deferred to the first
+    generate call so this module imports cleanly anywhere. The GPU-decorated
+    function is built lazily; if `spaces` is unavailable (local dev) the bare
+    function is used.
+
+    No grammar support, so when a tag is supplied the output is validated
+    (mind/validate.py) and regenerated once at temperature ~0 on failure. If
+    both attempts are malformed the raw text is yielded anyway — the
+    planner's retry/fallback path handles it from there.
+
+    Streaming note: tokens are buffered per generation (validation requires
+    the full text) and then yielded in small chunks, so SSE consumers still
+    see incremental output.
+    """
+
+    name = "zerogpu"
+    oneshot = True  # a petition is ONE @spaces.GPU call (ZeroGPU detaches the
+    # GPU between calls; godseed's per-turn loop of ~8 calls crashed on #2)
+
+    # Nemotron-Nano-9B-v2: its nemotron_h arch is IN-TREE in transformers, so it
+    # loads with trust_remote_code=False and runs the kernel-free native Mamba-2
+    # path. The Nemotron-3 4B/30B repos hard-require remote code + mamba-ssm
+    # kernels, which cannot import on the ZeroGPU image (June 12).
+    DEFAULT_MODEL = "nvidia/NVIDIA-Nemotron-Nano-9B-v2"
+    GPU_DURATION_S = 240
+
+    def __init__(self, model_id: str | None = None, max_input_tokens: int = 4096):
+        self.model_id = model_id or os.environ.get(
+            "CITY_HF_MODEL", self.DEFAULT_MODEL
+        )
+        self.max_input_tokens = max_input_tokens
+        self._tokenizer = None
+        self._model = None
+        self._gpu_generate = None
+        self._on_cuda = False
+        self._lock = threading.Lock()
+        # Load weights to CPU at construction (app startup). CRITICAL: do NOT
+        # touch CUDA here. Initializing CUDA in the main process poisons
+        # ZeroGPU's per-request GPU attach (the forked worker inherits a broken
+        # context -> "NVML_SUCCESS INTERNAL ASSERT FAILED" in the CUDA allocator
+        # on every forward, June 12). The model moves to cuda guarded by
+        # `import spaces` below, which virtualizes the placement.
+        self._ensure()
+
+    # -- setup (model resident; cuda placement guarded by spaces) -----------
+
+    def _ensure(self):
+        with self._lock:
+            if self._gpu_generate is not None:
+                return self._gpu_generate
+            import torch  # noqa: F401
+
+            from transformers import AutoModelForCausalLM, AutoTokenizer
+
+            # trust_remote_code MUST stay False: the repo also ships custom code
+            # that hard-requires mamba-ssm kernels (unimportable on ZeroGPU);
+            # False forces the in-tree NemotronH class with its native fallback.
+            self._tokenizer = AutoTokenizer.from_pretrained(self.model_id)
+            self._model = AutoModelForCausalLM.from_pretrained(
+                self.model_id,
+                dtype=torch.bfloat16,  # v5 name (torch_dtype removed in transformers 5)
+                low_cpu_mem_usage=True,
+            )
+            self._model.eval()
+            # Move to cuda ONCE at load, guarded by `import spaces` (the lib
+            # virtualizes it and keeps the model resident across @spaces.GPU
+            # calls). With ONE-SHOT generation a petition is a single GPU call,
+            # so the multi-call NVML crash can't happen — and keeping the model
+            # resident avoids the ~67s CPU->GPU transfer that, done per-call,
+            # ate the whole GPU budget and left no time to generate (June 12).
+            # Resident + one call = ~14s real output.
+            try:
+                import spaces  # noqa: F401
+                self._model.to("cuda")
+            except ImportError:
+                pass  # local/CPU dev
+
+            def _generate(prompt: str, max_new_tokens: int, temperature: float) -> str:
+                import torch as _torch  # noqa: F401
+
+                # Nemotron-Nano-9B-v2 is a reasoning model that THINKS by
+                # default; "/no_think" in the system slot disables it (June 12
+                # bench: raw completion leaked </think> into outputs). The
+                # planner's full completion-style prompt rides as one user turn.
+                if getattr(self._tokenizer, "chat_template", None):
+                    text_in = self._tokenizer.apply_chat_template(
+                        [
+                            {"role": "system", "content": "/no_think"},
+                            {"role": "user", "content": prompt},
+                        ],
+                        tokenize=False,
+                        add_generation_prompt=True,
+                    )
+                else:
+                    text_in = prompt
+                inputs = self._tokenizer(
+                    text_in,
+                    return_tensors="pt",
+                    truncation=True,
+                    max_length=self.max_input_tokens,
+                ).to(self._model.device)
+                with _torch.no_grad():
+                    output = self._model.generate(
+                        **inputs,
+                        max_new_tokens=max_new_tokens,
+                        do_sample=temperature > 0.05,
+                        temperature=max(temperature, 0.05),
+                        top_p=0.9,
+                        pad_token_id=self._tokenizer.eos_token_id,
+                    )
+                new_tokens = output[0][inputs["input_ids"].shape[1]:]
+                text = self._tokenizer.decode(new_tokens, skip_special_tokens=True)
+                # Defensive: strip any (possibly empty) think block that slips out.
+                text = re.sub(r"<think>.*?</think>", "", text, flags=re.S)
+                text = text.replace("<think>", "").replace("</think>", "")
+                return text.strip()
+
+            try:
+                import spaces  # import-guarded at call time, per contract
+
+                self._gpu_generate = spaces.GPU(duration=self.GPU_DURATION_S)(_generate)
+            except Exception:
+                self._gpu_generate = _generate
+            return self._gpu_generate
+
+    @staticmethod
+    def _is_valid(grammar: str, text: str) -> bool:
+        if is_moderation_grammar(grammar):
+            return parse_moderation(text)[1] is None
+        if base_tag(grammar) == FIX_TAG:
+            return parse_fix(text)[1] is None
+        return parse_build(text)[1] is None
+
+    async def _gen(self, generate, prompt: str, max_tokens: int, temperature: float) -> str:
+        """Run one generation, retrying transient ZeroGPU CUDA/NVML failures.
+        Each @spaces.GPU call re-schedules onto a (possibly healthier) GPU, so a
+        retry can clear the intermittent NVML allocator assert seen June 12."""
+        loop = asyncio.get_running_loop()
+        last_exc = None
+        for attempt in range(3):
+            try:
+                return await loop.run_in_executor(None, generate, prompt, max_tokens, temperature)
+            except Exception as exc:  # noqa: BLE001
+                msg = str(exc)
+                transient = any(s in msg for s in ("NVML", "CUDA", "cuda", "device", "out of memory"))
+                last_exc = exc
+                if not transient or attempt == 2:
+                    raise
+                # drop the poisoned cuda placement so the next call re-homes the model
+                self._on_cuda = False
+                import torch as _t
+                try:
+                    _t.cuda.empty_cache()
+                except Exception:
+                    pass
+                await asyncio.sleep(0.5 * (attempt + 1))
+        raise last_exc  # pragma: no cover
+
+    async def generate_stream(
+        self, prompt: str, grammar: str | None = None, max_tokens: int = 700
+    ) -> AsyncIterator[str]:
+        loop = asyncio.get_running_loop()
+        generate = await loop.run_in_executor(None, self._ensure)
+
+        if grammar is None:
+            text = await self._gen(generate, prompt, max_tokens, 0.7)
+        else:
+            temperature = 0.0 if is_strict(grammar) else 0.4
+            strict_prompt = (
+                prompt + "\nReply with exactly one JSON object and nothing else."
+            )
+            text = await self._gen(generate, strict_prompt, max_tokens, temperature)
+            if not self._is_valid(grammar, text):
+                retry_prompt = (
+                    strict_prompt
+                    + "\nYour previous output was malformed. Output ONLY the JSON object."
+                )
+                text = await self._gen(generate, retry_prompt, max_tokens, 0.0)
+            # Still malformed? Yield as-is; the planner retries then falls back.
+
+        for chunk in _chunks(text, 24):
+            await asyncio.sleep(0)
+            yield chunk
+
+
+# --------------------------------------------------------------------------
+# Factory
+# --------------------------------------------------------------------------
+
+_BACKEND_ALIASES = {
+    "mock": "mock",
+    "llamacpp": "llamacpp",
+    "llama": "llamacpp",
+    "gguf": "llamacpp",
+    "zerogpu": "zerogpu",
+    "zero-gpu": "zerogpu",
+    "transformers": "zerogpu",
+}
+
+
+def make_backend(name: str | None = None):
+    """Build the backend selected by `name` or the CITY_BACKEND env.
+
+    Defaults to mock (always works, zero deps beyond stdlib).
+    """
+    raw = (name or os.environ.get("CITY_BACKEND") or "mock").strip().lower()
+    resolved = _BACKEND_ALIASES.get(raw)
+    if resolved == "mock":
+        return MockBackend()
+    if resolved == "llamacpp":
+        return LlamaCppBackend()
+    if resolved == "zerogpu":
+        return ZeroGPUBackend()
+    raise ValueError(
+        f"unknown CITY_BACKEND {raw!r} (expected mock | zerogpu | llamacpp)"
+    )

mind/mock_scripts.py

@@ -0,0 +1,267 @@
+"""Deterministic scripted BUILD/FIX JSON for the MockBackend.
+
+Each petition maps to a category by keyword; each category emits a complete
+BUILD JSON string (parsed by mind/validate.py exactly like real backend
+output), with names and blurbs varied by a crc32 seed of the petition — same
+petition in, same permit out, so demos replay exactly. The category library
+exercises every building kind.
+
+fix_script reads the candidate ids and report numbers back out of the
+rendered fix prompt (the "- F1: desc (predicted index 41)" lines from
+mind/prompts.py — keep the two in lockstep) and picks the best predicted
+index, so mock fixes cite real numbers too.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import re
+import zlib
+
+NAME_MAX = 24
+BLURB_MAX = 140
+
+
+def _seed_for(petition: str) -> int:
+    return zlib.crc32(" ".join(petition.lower().split()).encode("utf-8")) & 0x7FFFFFFF
+
+
+def _entry(kind: str, name: str, near=None, floors=None, hue=None) -> dict:
+    return {"kind": kind, "name": name[:NAME_MAX], "near": near, "floors": floors, "hue": hue}
+
+
+def _plan(blurb: str, buildings: list[dict]) -> dict:
+    return {
+        "intent": "build",
+        "blurb": blurb[:BLURB_MAX],
+        "buildings": buildings[:3],
+        "decline_reason": None,
+    }
+
+
+_STOP_WORDS = {
+    "a", "an", "the", "please", "build", "make", "made", "add", "want",
+    "wants", "need", "needs", "near", "for", "with", "of", "in", "on", "to",
+    "and", "my", "me", "us", "we", "i", "new", "some", "little", "big",
+}
+
+
+def _petition_name(petition: str, suffix: str = "House") -> str:
+    words = [w for w in re.findall(r"[A-Za-z]+", petition) if w.lower() not in _STOP_WORDS]
+    base = " ".join(w.capitalize() for w in words[:2])
+    name = f"{base} {suffix}".strip()
+    return (name[:NAME_MAX].rstrip() or f"Petition {suffix}")[:NAME_MAX]
+
+
+_CAFES = ("Cafe Luna", "The Brass Kettle", "Marigold Coffee", "The Daily Grind", "Cafe Fig")
+_HOUSES = ("Wren Cottage", "Maple End", "The Little Blue", "Juniper House", "Quince Cottage")
+_APTS = ("Linden Court", "The Beacon Flats", "Harbor House", "The Gables", "Rookery Flats")
+_TOWERS = ("Meridian Tower", "The Spindle", "Apex Tower", "Cobalt Point", "The Needle")
+_PARKS = ("Dapple Green", "Whistle Park", "Petal Commons", "Old Elm Green")
+_STADIUMS = ("The Civic Bowl", "Tin Cup Stadium", "The Roaring Yard")
+_CHURCHES = ("The Quiet Spire", "St. Alder's", "Lantern Chapel")
+_SCHOOLS = ("Alder Primary", "Hilltop School", "The Brightwork School")
+_HOSPITALS = ("Riverside General", "St. Junia Hospital", "Bluebell General")
+_FACTORIES = ("The Tin Works", "Cobalt Works", "The Bottling Hall")
+_MARKETS = ("Penny Market", "The Mercantile", "Six Crows Market")
+_BANKS = ("The Counting House", "First Acorn Bank", "The Strongbox")
+_SHOPS = ("The Odd Shelf", "Tortoise & Finch", "The Blue Awning")
+_NEARS = ("downtown", "the park", "Main St", "1st Ave")
+
+
+def _district(petition: str, rng: random.Random) -> dict:
+    flats, cafe, shop = rng.choice(_APTS), rng.choice(_CAFES), rng.choice(_SHOPS)
+    buildings = [
+        _entry("apartments", flats, "downtown", rng.randint(4, 7), rng.choice((25, 35, 200))),
+        _entry("cafe", cafe, "downtown", 1, rng.choice((30, 40, 50))),
+    ]
+    if rng.random() < 0.7:
+        buildings.append(_entry("shop", shop, "downtown", 1, rng.choice((10, 180, 320))))
+    blurb = rng.choice((
+        f"Zoning approved: a new block downtown — {flats} rising with {cafe} on the corner.",
+        f"A whole block takes shape: {flats}, {cafe}, and room for more.",
+    ))
+    return _plan(blurb, buildings)
+
+
+def _river(petition: str, rng: random.Random) -> dict:
+    park, cafe = rng.choice(_PARKS), rng.choice(("The Ferry Light", "Pier Nine Cafe", "The Eddy"))
+    blurb = rng.choice((
+        f"The waterfront gets its due: {park} on the bank, {cafe} watching the water.",
+        f"Permits issued by the river — {park}, and {cafe} for the crossing crowd.",
+    ))
+    return _plan(blurb, [
+        _entry("park", park, "the river"),
+        _entry("cafe", cafe, "the river", 1, rng.choice((35, 45))),
+    ])
+
+
+def _cafe(petition: str, rng: random.Random) -> dict:
+    name = rng.choice(_CAFES)
+    near = rng.choice(_NEARS)
+    blurb = rng.choice((
+        f"{name} opens near {near} — pastries at dawn, lamplight at dusk.",
+        f"Permit granted: {name}, sidewalk tables facing the street.",
+    ))
+    return _plan(blurb, [_entry("cafe", name, near, 1, rng.choice((30, 40, 50)))])
+
+
+def _house(petition: str, rng: random.Random) -> dict:
+    name = rng.choice(_HOUSES)
+    blurb = rng.choice((
+        f"{name} gets its lot — a porch, a chimney, a light in the window.",
+        f"A home is granted: {name}, keys cut while the paint dries.",
+    ))
+    return _plan(blurb, [_entry("house", name, rng.choice(_NEARS), rng.randint(1, 2), rng.choice((20, 35, 200, 350)))])
+
+
+def _apartments(petition: str, rng: random.Random) -> dict:
+    name = rng.choice(_APTS)
+    blurb = rng.choice((
+        f"{name} approved — {rng.randint(4, 7)} floors of new neighbors.",
+        f"Housing first: {name} will fill with families by the weekend.",
+    ))
+    return _plan(blurb, [_entry("apartments", name, rng.choice(_NEARS), rng.randint(4, 7), rng.choice((25, 200, 160)))])
+
+
+def _tower(petition: str, rng: random.Random) -> dict:
+    name = rng.choice(_TOWERS)
+    blurb = rng.choice((
+        f"{name} cleared for the skyline — cranes by morning.",
+        f"Downtown grows up: {name}, {rng.randint(8, 16)} floors against the horizon.",
+    ))
+    return _plan(blurb, [_entry("tower", name, "downtown", rng.randint(8, 16), rng.choice((210, 220, 35)))])
+
+
+def _park(petition: str, rng: random.Random) -> dict:
+    name = rng.choice(_PARKS)
+    blurb = rng.choice((
+        f"Green space wins: {name}, benches and old trees included.",
+        f"{name} is set aside — the city keeps a place to breathe.",
+    ))
+    return _plan(blurb, [_entry("park", name, rng.choice(_NEARS))])
+
+
+def _stadium(petition: str, rng: random.Random) -> dict:
+    name = rng.choice(_STADIUMS)
+    blurb = rng.choice((
+        f"{name} approved — floodlights, roar, and a home team to be named.",
+        f"Game on: {name} takes the big lot.",
+    ))
+    return _plan(blurb, [_entry("stadium", name, "downtown", 1, rng.choice((10, 210)))])
+
+
+def _church(petition: str, rng: random.Random) -> dict:
+    name = rng.choice(_CHURCHES)
+    blurb = f"{name} is granted its steeple — bells on the hour."
+    return _plan(blurb, [_entry("church", name, rng.choice(_NEARS), 1, rng.choice((40, 350)))])
+
+
+def _school(petition: str, rng: random.Random) -> dict:
+    name = rng.choice(_SCHOOLS)
+    blurb = rng.choice((
+        f"{name} chartered — chalk dust and a morning bell.",
+        f"The city invests in small citizens: {name} opens soon.",
+    ))
+    return _plan(blurb, [_entry("school", name, rng.choice(_NEARS), rng.randint(1, 2), 200)])
+
+
+def _hospital(petition: str, rng: random.Random) -> dict:
+    name = rng.choice(_HOSPITALS)
+    blurb = f"{name} approved — the city will be looked after."
+    return _plan(blurb, [_entry("hospital", name, rng.choice(_NEARS), rng.randint(3, 6), 200)])
+
+
+def _bank(petition: str, rng: random.Random) -> dict:
+    name = rng.choice(_BANKS)
+    blurb = f"{name} chartered downtown — marble face, careful ledgers."
+    return _plan(blurb, [_entry("bank", name, "downtown", rng.randint(2, 4), 210)])
+
+
+def _factory(petition: str, rng: random.Random) -> dict:
+    name = rng.choice(_FACTORIES)
+    blurb = rng.choice((
+        f"{name} zoned for the edge of town — jobs by the shift.",
+        f"Industry arrives: {name}, smokestack and all.",
+    ))
+    return _plan(blurb, [_entry("factory", name, "the river", rng.randint(1, 2), 30)])
+
+
+def _market(petition: str, rng: random.Random) -> dict:
+    name = rng.choice(_MARKETS)
+    blurb = rng.choice((
+        f"{name} licensed — stalls up by Saturday.",
+        f"Permit granted: {name}, the street will smell of bread.",
+    ))
+    return _plan(blurb, [_entry("market", name, rng.choice(_NEARS), 1, rng.choice((35, 15)))])
+
+
+def _default(petition: str, rng: random.Random) -> dict:
+    name = _petition_name(petition)
+    blurb = f"City hall reads the petition twice, nods, and grants {name}."
+    return _plan(blurb, [_entry("house", name, rng.choice(_NEARS), rng.randint(1, 2), rng.choice((20, 200, 320)))])
+
+
+# Order matters: most specific first; "house" is the safety net before default.
+_CATEGORIES: tuple[tuple[re.Pattern[str], object], ...] = (
+    (re.compile(r"\b(districts?|downtown|neighbou?rhoods?|blocks?|quarters?|villages?|towns?|suburbs?|expand|grow)\b", re.I), _district),
+    (re.compile(r"\b(rivers?|riverside|waterfront|bridges?|docks?|harbou?rs?|piers?|ferry)\b", re.I), _river),
+    (re.compile(r"\b(caf[eé]s?|coffee|espresso|diners?|restaurants?|baker(?:y|ies)|bistros?|tea|ramen|pizz\w*|brunch|noodles?)\b", re.I), _cafe),
+    (re.compile(r"\b(apartments?|condos?|flats?|hotels?|housing|lofts?)\b", re.I), _apartments),
+    (re.compile(r"\b(towers?|offices?|skyscrapers?|high-?rises?|headquarters|startups?)\b", re.I), _tower),
+    (re.compile(r"\b(stadiums?|arenas?|sports?|football|soccer|baseball|matches?)\b", re.I), _stadium),
+    (re.compile(r"\b(church(?:es)?|temples?|chapels?|mosques?|cathedrals?|shrines?)\b", re.I), _church),
+    (re.compile(r"\b(schools?|librar(?:y|ies)|universit(?:y|ies)|colleges?|academ(?:y|ies)|kids|children)\b", re.I), _school),
+    (re.compile(r"\b(hospitals?|clinics?|doctors?|medical|health)\b", re.I), _hospital),
+    (re.compile(r"\b(banks?|finance|credit|vaults?)\b", re.I), _bank),
+    (re.compile(r"\b(factor(?:y|ies)|industr\w*|plants?|warehouses?|mills?|workshops?)\b", re.I), _factory),
+    (re.compile(r"\b(markets?|malls?|grocer\w*|supermarkets?|shops?|stores?|boutiques?|bazaars?|pharmac\w*)\b", re.I), _market),
+    (re.compile(r"\b(parks?|gardens?|greens?|trees?|playgrounds?|plazas?|squares?|fountains?)\b", re.I), _park),
+    (re.compile(r"\b(houses?|homes?|cottages?|bungalows?|cabins?|townhouses?)\b", re.I), _house),
+)
+
+
+def build_script(petition: str) -> str:
+    """The full BUILD JSON string for a petition. Deterministic: same
+    petition (modulo case/whitespace) always yields the same permit."""
+    petition = (petition or "").strip() or "a small building"
+    rng = random.Random(_seed_for(petition))
+    for pattern, builder in _CATEGORIES:
+        if pattern.search(petition):
+            return json.dumps(builder(petition, rng), ensure_ascii=False)  # type: ignore[operator]
+    return json.dumps(_default(petition, rng), ensure_ascii=False)
+
+
+_CANDIDATE_LINE_RE = re.compile(r"-\s*(F\d+):\s*([^\n(]*)\(predicted index (\d+)\)")
+_TRAFFIC_INDEX_RE = re.compile(r'"traffic_index"\s*:\s*(\d+)')
+_WORST_RE = re.compile(r'"worst"\s*:\s*"([^"]{1,48})"')
+
+
+def fix_script(prompt: str) -> str:
+    """The FIX JSON string, built from the candidates/numbers rendered into
+    the fix prompt by mind/prompts.py. Picks the lowest predicted index."""
+    text = str(prompt or "")
+    m = _WORST_RE.search(text)
+    worst = m.group(1) if m else "the worst crossing"
+    ti = _TRAFFIC_INDEX_RE.search(text)
+    pairs = _CANDIDATE_LINE_RE.findall(text)
+    if pairs:
+        cid, desc, pred = min(pairs, key=lambda p: int(p[2]))
+        desc = " ".join(desc.split()).rstrip(" ,") or "the engine's bypass"
+        if ti:
+            diagnosis = (
+                f"Index {ti.group(1)} with {worst} over capacity; "
+                f"{cid} ({desc}) brings the predicted index to {pred}."
+            )
+        else:
+            diagnosis = f"{worst} is over capacity; {cid} ({desc}) brings the predicted index to {pred}."
+    else:
+        m = re.search(r"\b(F\d+)\b", text)
+        cid = m.group(1) if m else "F1"
+        diagnosis = f"{worst} runs over capacity; applying {cid}."
+    blurb = f"CITY ENGINEER: relief ordered for {worst}."
+    return json.dumps(
+        {"diagnosis": diagnosis[:160], "choice": cid, "blurb": blurb[:120]},
+        ensure_ascii=False,
+    )

mind/moderation_judge.py

@@ -0,0 +1,67 @@
+"""LLM moderation judgment for NEMOCITY — default-deny, always.
+
+This is layer 3 of the engine's moderation stack (engine/moderation.py):
+charset/length checks and the folded wordlist run first; this judge is the
+final yes/no, OFF by default via the CITY_JUDGE env (the server injects
+`judge` with the shared backend only when enabled).
+
+MODERATION_GRAMMAR is the "moderation" tag (mind/validate.py), not a real
+grammar — backends use it to pick the verdict shape.
+
+Hard rule: ANY exception, timeout, or parse failure means NOT allowed. A
+broken judge must fail closed — one slur on a storefront during judging week
+ends every award.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from .prompts import build_moderation_prompt
+from .validate import MODERATION_GRAMMAR, parse_moderation
+
+JUDGE_MAX_TOKENS = 60
+JUDGE_TIMEOUT_S = 30.0
+
+
+async def _collect_verdict(text: str, backend) -> str:
+    prompt = build_moderation_prompt(text)
+    parts: list[str] = []
+    total = 0
+    stream = backend.generate_stream(prompt, MODERATION_GRAMMAR, JUDGE_MAX_TOKENS)
+    try:
+        async for chunk in stream:
+            if not chunk:
+                continue
+            parts.append(chunk)
+            total += len(chunk)
+            if total >= 2000:  # a verdict is ~50 chars; anything huge is broken
+                break
+    finally:
+        try:
+            await stream.aclose()
+        except Exception:
+            pass
+    return "".join(parts)
+
+
+async def judge(text: str, backend, *, timeout_s: float = JUDGE_TIMEOUT_S) -> dict:
+    """Judge a petition. Returns {"allowed": bool, "category": str | None}.
+
+    category is None when allowed; otherwise a short label (from the model,
+    or a synthetic one when the judge itself failed). Default-deny: every
+    failure mode — backend exception, timeout, malformed verdict — returns
+    {"allowed": False, ...}. This function never raises.
+    """
+    try:
+        raw = await asyncio.wait_for(_collect_verdict(text, backend), timeout=timeout_s)
+    except Exception:
+        return {"allowed": False, "category": "judge_error"}
+
+    obj, err = parse_moderation(raw)
+    if err is not None or obj is None:
+        return {"allowed": False, "category": "unreadable_verdict"}
+
+    if obj["allowed"]:
+        return {"allowed": True, "category": None}
+    return {"allowed": False, "category": obj["category"] or "unspecified"}

mind/planner.py

@@ -0,0 +1,324 @@
+"""The Planner — NEMOCITY one-shot mind (no turn loop, ever).
+
+grant(): ONE backend generation turns a petition into the BUILD permit JSON
+(mind/prompts.py), parsed leniently (mind/validate.py), retried once at
+temperature 0 ("!strict" tag) with the parse error in context, then a
+deterministic fallback (one house) — a petition NEVER builds nothing. The
+engine executes every act and owns all placement; the planner never touches
+world state. ONE @spaces.GPU call per petition in the normal path.
+
+Interface (mirrors godseed's planner/queue contract — the queue worker calls
+grant positionally with (wish, world_summary, act, emit)):
+
+    await grant(wish, world_summary, act, emit, wish_id=None) -> trace dict
+        act:  async (building: dict) -> observation str. Called once per
+              building (1..3) with the stable 5-key shape
+              {"kind": str, "name": str, "near": str|None,
+               "floors": int|None, "hue": int|None}.
+        emit: async (event: dict) -> None. Emitted, in order:
+              {"type": "plan", "plan": {...validated BUILD JSON...}}  (once)
+              {"type": "thought_token", "text": ...}  (blurb + per-act lines)
+              wish_id is included in the plan event only when the caller
+              passes it; otherwise the worker injects it before broadcast
+              (the godseed convention).
+
+    await fix(stats, candidates, act_fix, emit, wish_id=None) -> trace dict
+        act_fix: async ({"choice","diagnosis","blurb"}) -> observation str,
+        called exactly once. Parse failure / invalid / missing choice falls
+        back to the candidate with the lowest predicted_index plus a canned
+        diagnosis built from stats.
+
+Trace shape (the queue worker merges wish_id/text/submitted_at/moderation/
+feature_ids, exactly like godseed):
+
+    {"reading": blurb, "turns": [{"thought","call","observation"}...],
+     "epitaph": blurb, "ms_total": int, "model": str, "backend": str,
+     "raw_json": validated plan dict, "raw_text": raw model output,
+     "fallback": bool, "declined": bool, "decline_reason": str|None}
+
+For fix traces reading=diagnosis and epitaph=blurb. A declined petition has
+turns=[] and declined=True — the worker should emit wish_rejected with the
+decline_reason instead of wish_granted.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Awaitable, Callable
+
+from . import prompts
+from .backends import make_backend
+from .validate import BUILD_TAG, FIX_TAG, STRICT_SUFFIX, parse_build, parse_fix
+
+Act = Callable[[dict], Awaitable[str]]
+Emit = Callable[[dict], Awaitable[None]]
+
+FALLBACK_BLURB = "The city granted a home."
+
+_RAW_MAX_CHARS = 6000
+_OBSERVATION_MAX_CHARS = 500
+
+_STOP_WORDS = {
+    "a", "an", "the", "please", "build", "make", "made", "add", "want",
+    "wants", "need", "needs", "near", "for", "with", "of", "in", "on", "to",
+    "and", "my", "me", "us", "we", "i", "new", "some", "little", "big",
+}
+
+
+def _default_name(wish: str) -> str:
+    """A building name derived from the petition's own words."""
+    words = [w for w in re.findall(r"[A-Za-z]+", str(wish or "")) if w.lower() not in _STOP_WORDS]
+    base = " ".join(w.capitalize() for w in words[:2])
+    name = f"{base} House".strip()
+    return (name[:24].rstrip() or "Petition House")[:24]
+
+
+def _fallback_plan(wish: str) -> dict:
+    """The safety net: a petition must never build nothing."""
+    return {
+        "intent": "build",
+        "blurb": FALLBACK_BLURB,
+        "buildings": [
+            {"kind": "house", "name": _default_name(wish), "near": None, "floors": None, "hue": None}
+        ],
+        "decline_reason": None,
+    }
+
+
+def _thought_for(building: dict) -> str:
+    kind = str((building or {}).get("kind") or "building")
+    name = str((building or {}).get("name") or "").strip()
+    return f"Permit issued: {name} ({kind})." if name else f"Permit issued: a {kind}."
+
+
+def _canned_fix(stats: dict, candidate: dict | None) -> tuple[str, str]:
+    """Deterministic diagnosis + blurb citing whatever real numbers we have."""
+    worst = " ".join(str(stats.get("worst") or "the worst crossing").split())[:48]
+    ti = stats.get("traffic_index")
+    pred = (candidate or {}).get("predicted_index")
+    desc = " ".join(str((candidate or {}).get("desc") or "").split())[:80]
+    if isinstance(ti, (int, float)) and not isinstance(ti, bool):
+        diagnosis = f"Traffic index {int(ti)}; {worst} is over capacity."
+    else:
+        diagnosis = f"The network strains at {worst}."
+    if isinstance(pred, (int, float)) and not isinstance(pred, bool):
+        diagnosis += f" {desc or 'The fix'} brings the predicted index to {int(pred)}."
+    blurb = f"City Engineer orders relief at {worst}."
+    return diagnosis[:160], blurb[:120]
+
+
+class Planner:
+    """Grants one petition (or one traffic fix) at a time against an injected
+    backend. Owns prompting, parsing, and pacing; never raises for backend or
+    act misbehavior — it always returns a complete trace."""
+
+    BUILD_MAX_TOKENS = 700
+    FIX_MAX_TOKENS = 300
+
+    def __init__(self, backend=None):
+        self.backend = backend if backend is not None else make_backend()
+
+    # ------------------------------------------------------------------ emit
+
+    @staticmethod
+    async def _safe_emit(emit: Emit, event: dict) -> None:
+        """Broadcast failures must never kill a grant."""
+        try:
+            await emit(event)
+        except Exception:
+            pass
+
+    async def _emit_text(self, emit: Emit, text: str, *, end: str = "\n") -> None:
+        """Stream already-known text as small chunks (the ticker stays alive)."""
+        words = text.split()
+        step = 3
+        for i in range(0, len(words), step):
+            chunk = " ".join(words[i : i + step])
+            if i + step < len(words):
+                chunk += " "
+            await self._safe_emit(emit, {"type": "thought_token", "text": chunk})
+        if end:
+            await self._safe_emit(emit, {"type": "thought_token", "text": end})
+
+    async def _emit_plan(self, emit: Emit, plan: dict, wish_id: str | None) -> None:
+        event = {"type": "plan", "plan": plan}
+        if wish_id is not None:
+            event["wish_id"] = wish_id
+        await self._safe_emit(emit, event)
+
+    # --------------------------------------------------------------- collect
+
+    async def _collect(self, prompt: str, tag: str, max_tokens: int) -> str:
+        parts: list[str] = []
+        total = 0
+        stream = self.backend.generate_stream(prompt, tag, max_tokens)
+        try:
+            async for chunk in stream:
+                if not chunk:
+                    continue
+                parts.append(chunk)
+                total += len(chunk)
+                if total >= _RAW_MAX_CHARS:
+                    break
+        finally:
+            try:
+                await stream.aclose()
+            except Exception:
+                pass
+        return "".join(parts)
+
+    async def _attempt(self, prompt: str, tag: str, max_tokens: int) -> str:
+        try:
+            return await self._collect(prompt, tag, max_tokens)
+        except Exception:
+            return ""  # a dead backend falls through to the parser/fallback
+
+    async def _plan_with_retry(
+        self, prompt: str, tag: str, max_tokens: int, parser
+    ) -> tuple[dict | None, str]:
+        """One generation + one temperature-0 retry. Returns (obj|None, raw)."""
+        raw = await self._attempt(prompt, tag, max_tokens)
+        obj, err = parser(raw)
+        if err is None:
+            return obj, raw
+        retry_prompt = (
+            f"{prompt}\n{prompts.REASK_NOTICE} ({err}). Output ONLY the JSON object."
+        )
+        raw2 = await self._attempt(retry_prompt, tag + STRICT_SUFFIX, max_tokens)
+        obj, err = parser(raw2)
+        if err is None:
+            return obj, raw2
+        return None, raw or raw2
+
+    def _trace(self, *, reading, turns, epitaph, started, raw_json, raw_text,
+               fallback=False, declined=False, decline_reason=None) -> dict:
+        return {
+            "reading": reading,
+            "turns": turns,
+            "epitaph": epitaph,
+            "ms_total": int((time.perf_counter() - started) * 1000),
+            "model": str(getattr(self.backend, "model_id", "unknown")),
+            "backend": str(getattr(self.backend, "name", "unknown")),
+            "raw_json": raw_json,
+            "raw_text": str(raw_text or "")[:_RAW_MAX_CHARS],
+            "fallback": fallback,
+            "declined": declined,
+            "decline_reason": decline_reason,
+        }
+
+    # ----------------------------------------------------------------- grant
+
+    async def grant(
+        self, wish: str, world_summary: str, act: Act, emit: Emit, *, wish_id: str | None = None
+    ) -> dict:
+        """Grant one petition. See the module docstring for the contract."""
+        started = time.perf_counter()
+        wish = str(wish or "")
+        world_summary = str(world_summary or "")
+
+        prompt = prompts.build_build_prompt(wish, world_summary)
+        plan, raw = await self._plan_with_retry(
+            prompt, BUILD_TAG, self.BUILD_MAX_TOKENS, parse_build
+        )
+        fallback = plan is None
+        if fallback:
+            plan = _fallback_plan(wish)
+
+        if plan["intent"] == "decline":
+            await self._emit_plan(emit, plan, wish_id)
+            reason = plan.get("decline_reason") or "the petition could not be read as a building"
+            blurb = plan.get("blurb") or "City hall declines this petition."
+            await self._emit_text(emit, blurb, end="\n\n")
+            return self._trace(
+                reading=blurb, turns=[], epitaph=blurb, started=started,
+                raw_json=plan, raw_text=raw, declined=True, decline_reason=reason,
+            )
+
+        for building in plan["buildings"]:
+            if not building.get("name"):
+                building["name"] = _default_name(wish)
+        blurb = plan.get("blurb") or FALLBACK_BLURB
+        plan["blurb"] = blurb
+
+        await self._emit_plan(emit, plan, wish_id)
+        await self._emit_text(emit, blurb, end="\n\n")
+
+        turns: list[dict] = []
+        for building in plan["buildings"][:3]:
+            thought = _thought_for(building)
+            await self._emit_text(emit, thought)
+            try:
+                observation = await act(building)
+            except Exception as exc:
+                observation = f"error: act failed ({type(exc).__name__})"
+            turns.append({
+                "thought": thought,
+                "call": dict(building),
+                "observation": str(observation or "")[:_OBSERVATION_MAX_CHARS],
+            })
+
+        return self._trace(
+            reading=blurb, turns=turns, epitaph=blurb, started=started,
+            raw_json=plan, raw_text=raw, fallback=fallback,
+        )
+
+    # ------------------------------------------------------------------- fix
+
+    async def fix(
+        self, stats, candidates, act_fix: Act, emit: Emit, *, wish_id: str | None = None
+    ) -> dict:
+        """One traffic fix: {stats, candidates} -> ONE generation -> one
+        act_fix call. Engine pre-validated the candidates; an invalid or
+        missing model choice falls back to the best predicted_index."""
+        started = time.perf_counter()
+        stats = stats if isinstance(stats, dict) else {}
+        candidates = [c for c in (candidates or ()) if isinstance(c, dict)]
+
+        prompt = prompts.build_fix_prompt(stats, candidates)
+        obj, raw = await self._plan_with_retry(
+            prompt, FIX_TAG, self.FIX_MAX_TOKENS, parse_fix
+        )
+
+        by_id = {str(c.get("id")): c for c in candidates if c.get("id")}
+        choice = None
+        if obj and obj.get("choice"):
+            wanted = str(obj["choice"]).strip().lower()
+            for cid in by_id:
+                if cid.lower() == wanted:
+                    choice = cid
+                    break
+
+        fallback = choice is None
+        if fallback:
+            def _pred(c: dict) -> float:
+                value = c.get("predicted_index")
+                ok = isinstance(value, (int, float)) and not isinstance(value, bool)
+                return float(value) if ok else float("inf")
+
+            best = min(candidates, key=_pred) if candidates else None
+            choice = str(best.get("id")) if best and best.get("id") else None
+            diagnosis, blurb = _canned_fix(stats, best)
+        else:
+            canned = _canned_fix(stats, by_id[choice])
+            diagnosis = (obj.get("diagnosis") or "").strip()[:160] or canned[0]
+            blurb = (obj.get("blurb") or "").strip()[:120] or canned[1]
+
+        plan = {"diagnosis": diagnosis, "choice": choice, "blurb": blurb}
+        await self._emit_plan(emit, plan, wish_id)
+        await self._emit_text(emit, diagnosis, end="\n\n")
+
+        try:
+            observation = await act_fix(plan)
+        except Exception as exc:
+            observation = f"error: act failed ({type(exc).__name__})"
+        turns = [{
+            "thought": diagnosis,
+            "call": dict(plan),
+            "observation": str(observation or "")[:_OBSERVATION_MAX_CHARS],
+        }]
+
+        return self._trace(
+            reading=diagnosis, turns=turns, epitaph=blurb, started=started,
+            raw_json=plan, raw_text=raw, fallback=fallback,
+        )

mind/prompts.py

@@ -0,0 +1,311 @@
+"""Prompt construction for the NEMOCITY mind (one-shot BUILD + FIX).
+
+Persona: a terse, warm municipal planner AI running city hall of one shared
+miniature city. The engine owns every fact, coordinate, and placement; the
+model only translates petitions into a tiny permit JSON (no coordinates,
+ever — the "her" pattern).
+
+Kind docs are rendered from engine/constants.py BUILDINGS + SYNONYMS when
+importable (single source of truth). During the parallel build the engine
+may not exist yet, so a vendored copy of the ARCHITECTURE.md table is kept
+here as a fallback (see _VENDORED_* — marked DEVIATION).
+
+Marker constants are load-bearing: MockBackend routes prompts containing
+FIX_MARKER to the fix script, recovers the petition after PETITION_MARKER,
+and judges moderation after CANDIDATE_MARKER. Change them only in lockstep
+with mind/backends.py, mind/mock_scripts.py, and tests/test_mind.py.
+
+GODSEED lesson kept: NO multi-example few-shot (the model copied example
+values verbatim into live plans). ONE inline example shape + "your own
+values, JSON only" carries the format.
+"""
+
+from __future__ import annotations
+
+import json
+
+# --------------------------------------------------------------------------
+# Markers (relied upon by MockBackend and the planner's re-ask path)
+# --------------------------------------------------------------------------
+
+PETITION_MARKER = "PETITION: "
+FIX_MARKER = "TRAFFIC REPORT"
+CANDIDATE_MARKER = "CANDIDATE: "
+REASK_NOTICE = "Your previous reply was not valid JSON"
+
+# --------------------------------------------------------------------------
+# Building table — engine/constants.py is the single source of truth
+# --------------------------------------------------------------------------
+
+KIND_ORDER: tuple[str, ...] = (
+    "house", "townhouse", "apartments", "cafe", "shop", "market", "bank",
+    "office", "tower", "school", "hospital", "fire_station", "warehouse",
+    "factory", "park", "plaza", "stadium", "church", "town_hall",
+)
+
+# DEVIATION: vendored copy of engine/constants.py BUILDINGS (mirrors the
+# ARCHITECTURE.md table exactly). Used only while engine.constants is absent
+# or incompatible — e.g. during the parallel build, or in isolated mind tests.
+_VENDORED_BUILDINGS: dict[str, dict] = {
+    "house":        {"w": 1, "d": 1, "floors": (1, 2),  "residents": 4,  "jobs": 0,  "attract": 0, "duration_s": 20},
+    "townhouse":    {"w": 1, "d": 1, "floors": (2, 3),  "residents": 6,  "jobs": 0,  "attract": 0, "duration_s": 20},
+    "apartments":   {"w": 2, "d": 2, "floors": (4, 7),  "residents": 16, "jobs": 0,  "attract": 0, "duration_s": 45},
+    "cafe":         {"w": 1, "d": 1, "floors": (1, 1),  "residents": 0,  "jobs": 3,  "attract": 5, "duration_s": 20},
+    "shop":         {"w": 1, "d": 1, "floors": (1, 2),  "residents": 0,  "jobs": 4,  "attract": 4, "duration_s": 20},
+    "market":       {"w": 1, "d": 2, "floors": (1, 1),  "residents": 0,  "jobs": 8,  "attract": 6, "duration_s": 30},
+    "bank":         {"w": 2, "d": 1, "floors": (2, 4),  "residents": 0,  "jobs": 12, "attract": 2, "duration_s": 30},
+    "office":       {"w": 1, "d": 1, "floors": (3, 8),  "residents": 0,  "jobs": 40, "attract": 1, "duration_s": 30},
+    "tower":        {"w": 2, "d": 2, "floors": (8, 16), "residents": 0,  "jobs": 60, "attract": 2, "duration_s": 45},
+    "school":       {"w": 2, "d": 2, "floors": (1, 2),  "residents": 0,  "jobs": 10, "attract": 3, "duration_s": 30},
+    "hospital":     {"w": 3, "d": 3, "floors": (3, 6),  "residents": 0,  "jobs": 25, "attract": 2, "duration_s": 45},
+    "fire_station": {"w": 2, "d": 1, "floors": (2, 2),  "residents": 0,  "jobs": 8,  "attract": 1, "duration_s": 30},
+    "warehouse":    {"w": 2, "d": 2, "floors": (1, 1),  "residents": 0,  "jobs": 10, "attract": 0, "duration_s": 30},
+    "factory":      {"w": 3, "d": 2, "floors": (1, 2),  "residents": 0,  "jobs": 18, "attract": 0, "duration_s": 45},
+    "park":         {"w": 2, "d": 2, "floors": (0, 0),  "residents": 0,  "jobs": 0,  "attract": 8, "duration_s": 20},
+    "plaza":        {"w": 1, "d": 1, "floors": (0, 0),  "residents": 0,  "jobs": 0,  "attract": 6, "duration_s": 20},
+    "stadium":      {"w": 4, "d": 4, "floors": (1, 1),  "residents": 0,  "jobs": 15, "attract": 9, "duration_s": 45},
+    "church":       {"w": 2, "d": 1, "floors": (1, 1),  "residents": 0,  "jobs": 2,  "attract": 3, "duration_s": 30},
+    "town_hall":    {"w": 2, "d": 2, "floors": (2, 2),  "residents": 0,  "jobs": 6,  "attract": 4, "duration_s": 45},
+}
+
+# DEVIATION: vendored synonym map (engine/tools.py owns the live one).
+_VENDORED_SYNONYMS: dict[str, str] = {
+    "skyscraper": "tower", "highrise": "tower",
+    "apartment": "apartments", "apartment building": "apartments",
+    "condo": "apartments", "hotel": "apartments",
+    "coffee shop": "cafe", "diner": "cafe", "restaurant": "cafe", "bakery": "cafe",
+    "store": "shop", "boutique": "shop", "pharmacy": "shop", "gym": "shop",
+    "mall": "market", "grocery": "market", "supermarket": "market",
+    "police station": "fire_station", "police": "fire_station",
+    "library": "town_hall", "museum": "town_hall", "city hall": "town_hall",
+    "temple": "church", "mosque": "church", "chapel": "church",
+    "garden": "park", "playground": "park",
+    "fountain": "plaza", "square": "plaza",
+    "arena": "stadium",
+    "clinic": "hospital",
+    "plant": "factory",
+}
+
+
+def _load_tables() -> tuple[dict, dict, bool]:
+    """engine.constants BUILDINGS + SYNONYMS, vendored copies as fallback."""
+    buildings = synonyms = None
+    try:
+        from engine import constants as _c  # type: ignore
+
+        buildings = getattr(_c, "BUILDINGS", None)
+        synonyms = getattr(_c, "SYNONYMS", None)
+    except Exception:
+        # engine/__init__.py may be mid-write during the parallel build while
+        # constants.py itself is already valid — load the file directly.
+        try:
+            import importlib.util
+            from pathlib import Path
+
+            path = Path(__file__).resolve().parents[1] / "engine" / "constants.py"
+            if path.exists():
+                spec = importlib.util.spec_from_file_location("_nemocity_constants", path)
+                mod = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(mod)  # type: ignore[union-attr]
+                buildings = getattr(mod, "BUILDINGS", None)
+                synonyms = getattr(mod, "SYNONYMS", None)
+        except Exception:
+            pass
+    if not isinstance(buildings, dict) or len(buildings) < 10:
+        return dict(_VENDORED_BUILDINGS), dict(_VENDORED_SYNONYMS), False
+    if not isinstance(synonyms, dict) or not synonyms:
+        try:
+            from engine import tools as _t  # type: ignore
+
+            synonyms = getattr(_t, "SYNONYMS", None)
+        except Exception:
+            synonyms = None
+    if not isinstance(synonyms, dict) or not synonyms:
+        synonyms = dict(_VENDORED_SYNONYMS)
+    return buildings, synonyms, True
+
+
+BUILDINGS, SYNONYMS, TABLES_FROM_ENGINE = _load_tables()
+
+
+def kind_names() -> tuple[str, ...]:
+    ordered = tuple(k for k in KIND_ORDER if k in BUILDINGS)
+    return ordered or tuple(BUILDINGS)
+
+
+def _spec_field(spec, names: tuple[str, ...], default=None):
+    if isinstance(spec, dict):
+        for n in names:
+            if spec.get(n) is not None:
+                return spec[n]
+    else:
+        for n in names:
+            value = getattr(spec, n, None)
+            if value is not None:
+                return value
+    return default
+
+
+def _floors_range(spec) -> tuple[int, int]:
+    value = _spec_field(spec, ("floors",))
+    if isinstance(value, (list, tuple)) and len(value) == 2:
+        return int(value[0]), int(value[1])
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return int(value), int(value)
+    lo = _spec_field(spec, ("floors_min", "min_floors"))
+    hi = _spec_field(spec, ("floors_max", "max_floors"))
+    if lo is not None and hi is not None:
+        return int(lo), int(hi)
+    return 1, 1
+
+
+def render_kind_docs() -> str:
+    """One terse model-readable line per kind, from the engine table."""
+    lines = []
+    for kind in kind_names():
+        spec = BUILDINGS[kind]
+        try:
+            w = int(_spec_field(spec, ("w", "width"), 1))
+            d = int(_spec_field(spec, ("d", "depth"), 1))
+            lo, hi = _floors_range(spec)
+            residents = int(_spec_field(spec, ("residents",), 0) or 0)
+            jobs = int(_spec_field(spec, ("jobs",), 0) or 0)
+            attract = int(_spec_field(spec, ("attract",), 0) or 0)
+        except Exception:
+            lines.append(f"- {kind}")
+            continue
+        bits = [f"{w}x{d}"]
+        if hi > lo:
+            bits.append(f"floors {lo}-{hi}")
+        elif lo:
+            bits.append(f"floors {lo}")
+        else:
+            bits.append("open ground")
+        if residents:
+            bits.append(f"{residents} residents")
+        if jobs:
+            bits.append(f"{jobs} jobs")
+        if attract:
+            bits.append(f"draw {attract}")
+        lines.append(f"- {kind}: " + ", ".join(bits))
+    return "\n".join(lines)
+
+
+def render_synonym_line() -> str:
+    groups: dict[str, list[str]] = {}
+    for src, dst in SYNONYMS.items():
+        groups.setdefault(str(dst), []).append(str(src))
+    parts = [f"{'/'.join(sorted(srcs))} -> {dst}" for dst, srcs in sorted(groups.items())]
+    return "Synonyms the engine repairs: " + "; ".join(parts) + "; anything unknown -> house."
+
+
+# --------------------------------------------------------------------------
+# Personas & prompt builders
+# --------------------------------------------------------------------------
+
+PERSONA = """You are City Hall of NEMOCITY, one shared miniature city — a terse, warm
+municipal planner AI. The deterministic engine owns every fact, map, and
+placement; you NEVER output coordinates. You only translate a visitor's
+petition into a small building permit. Build generously: a district,
+neighborhood, or "more homes" petition deserves 2-3 buildings. Never refuse
+a buildable thing — map strange asks to the closest kind on the list.
+Decline only pure nonsense."""
+
+_MAX_PETITION_CHARS = 160
+_MAX_SUMMARY_CHARS = 600
+_MAX_STATS_CHARS = 500
+_MAX_ERROR_CHARS = 160
+
+
+def _one_line(text, limit: int) -> str:
+    """Collapse whitespace/newlines to one bounded line (prompt hygiene)."""
+    return " ".join(str(text or "").split())[:limit]
+
+
+def build_build_prompt(petition: str, world_summary: str) -> str:
+    """The whole petition in ONE model call -> the BUILD permit JSON."""
+    petition_line = _one_line(petition, _MAX_PETITION_CHARS) or "a small building"
+    summary = _one_line(world_summary, _MAX_SUMMARY_CHARS) or (
+        "The city is young; a few blocks stand by the river."
+    )
+    return (
+        f"{PERSONA}\n\n"
+        f'KINDS (the only legal "kind" values):\n'
+        f"{render_kind_docs()}\n"
+        f"{render_synonym_line()}\n\n"
+        f"The city today: {summary}\n\n"
+        f"{PETITION_MARKER}{petition_line}\n\n"
+        "GRANT IT in ONE reply: a single JSON object, nothing else. Example of "
+        "the SHAPE only (its values belong to no petition; never copy them):\n"
+        '{"intent":"build","blurb":"A sunny corner cafe joins the park block.",'
+        '"buildings":[{"kind":"cafe","name":"Cafe Luna","near":"the park",'
+        '"floors":1,"hue":35}],"decline_reason":null}\n'
+        "Rules: 1 to 3 buildings. kind from the list above. name <= 24 chars, "
+        'give it personality. near = a landmark, street, or "downtown" (free '
+        "text; the engine resolves and places everything). floors and hue are "
+        "optional hints. blurb <= 140 chars, warm city-planner voice. Set "
+        'intent "decline" with a decline_reason ONLY for pure nonsense. '
+        "Your own values, JSON only:\n"
+    )
+
+
+def _render_candidates(candidates) -> str:
+    # Line format "- F1: desc (predicted index 41)" is parsed back by
+    # mind/mock_scripts.fix_script — change only in lockstep.
+    lines = []
+    for i, c in enumerate(candidates or ()):
+        c = c if isinstance(c, dict) else {}
+        cid = str(c.get("id") or f"F{i + 1}")
+        desc = _one_line(c.get("desc") or c.get("action") or "engine-routed fix", 80)
+        pred = c.get("predicted_index")
+        suffix = ""
+        if isinstance(pred, (int, float)) and not isinstance(pred, bool):
+            suffix = f" (predicted index {int(pred)})"
+        lines.append(f"- {cid}: {desc}{suffix}")
+    return "\n".join(lines) or "- F1: engine-routed bypass road"
+
+
+def build_fix_prompt(stats, candidates) -> str:
+    """{stats, candidates} in ONE model call -> the FIX choice JSON."""
+    try:
+        stats_line = json.dumps(stats, separators=(",", ":"), ensure_ascii=False)
+    except (TypeError, ValueError):
+        stats_line = str(stats)
+    stats_line = _one_line(stats_line, _MAX_STATS_CHARS)
+    return (
+        "You are the City Engineer of NEMOCITY, a terse municipal traffic AI. "
+        "The deterministic engine measured the road network; every number "
+        "below is real. Pick exactly ONE candidate fix by its id and justify "
+        "it by citing the real numbers (street names, ratios, indexes) from "
+        "the report.\n\n"
+        f"{FIX_MARKER}: {stats_line}\n"
+        "CANDIDATE FIXES (pre-validated by the engine; choose one id):\n"
+        f"{_render_candidates(candidates)}\n\n"
+        "Reply with ONE JSON object, nothing else. Example of the SHAPE only "
+        "(never copy its values):\n"
+        '{"diagnosis":"Old Bridge carries 3.1x capacity at rush; a second '
+        'crossing cuts the index 78 to 41.","choice":"F1","blurb":"Relief is '
+        'coming to Old Bridge."}\n'
+        "diagnosis <= 160 chars and MUST cite the report's real numbers. "
+        "choice = one candidate id. blurb <= 120 chars, news-headline voice. "
+        "Your own values, JSON only:\n"
+    )
+
+
+def build_moderation_prompt(text: str) -> str:
+    """Prompt for the moderation judge (tag-constrained verdict)."""
+    candidate = _one_line(text, _MAX_PETITION_CHARS)
+    return (
+        "You are the gatekeeper of one small public city, seen by children "
+        "and strangers.\n"
+        "Judge only the text below — a building petition someone wants "
+        "granted in the city. Disallow: hate, slurs, harassment, sexual "
+        "content, anything sexual about minors, gore, encouragement of "
+        "self-harm, doxxing, spam, and hate symbols or instructions to shape "
+        "the city into them.\n"
+        "Playful nonsense, mild grumbling, and strange asks are allowed.\n\n"
+        f"{CANDIDATE_MARKER}{candidate}\n\n"
+        'Reply with exactly one JSON object: {"allowed": true|false, '
+        '"category": "<short label, empty if allowed>"}\n'
+        "JUDGMENT: "
+    )

mind/validate.py

@@ -0,0 +1,293 @@
+"""Lenient JSON validation for the NEMOCITY mind (one-shot BUILD + FIX).
+
+NEMOCITY has no GBNF grammars: every backend generates free text and the
+parsers here recover the JSON. The old `grammar` parameter on the Backend
+protocol is repurposed as a plain string TAG telling the backend which shape
+is wanted (temperature + validation), never an actual grammar:
+
+    BUILD_TAG      "build"        BUILD permit JSON
+    FIX_TAG        "fix"          FIX choice JSON
+    MODERATION_TAG "moderation"   moderation verdict JSON
+    None                          free text
+    "<tag>!strict"                retry pass: temperature 0
+
+Parsing is the same strictness for every backend: mock output is trusted but
+parsed identically so the pipeline never special-cases a backend. The engine
+does ALL semantic clamping (kind synonyms, floors ranges, placement) — these
+parsers only guarantee structure.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+BUILD_TAG = "build"
+FIX_TAG = "fix"
+MODERATION_TAG = "moderation"
+STRICT_SUFFIX = "!strict"
+
+# Name kept from godseed so copied call sites (moderation_judge) still work;
+# it is a tag now, not a grammar.
+MODERATION_GRAMMAR = MODERATION_TAG
+
+NAME_MAX_CHARS = 24
+NEAR_MAX_CHARS = 60
+BLURB_MAX_CHARS = 140
+DIAGNOSIS_MAX_CHARS = 160
+FIX_BLURB_MAX_CHARS = 120
+DECLINE_MAX_CHARS = 160
+MAX_BUILDINGS = 3
+
+
+def is_moderation_grammar(grammar: str | None) -> bool:
+    return bool(grammar) and (
+        str(grammar).split("!", 1)[0] == MODERATION_TAG or '"allowed"' in str(grammar)
+    )
+
+
+def base_tag(grammar: str | None) -> str | None:
+    """Tag without the !strict retry suffix."""
+    return None if grammar is None else str(grammar).split("!", 1)[0]
+
+
+def is_strict(grammar: str | None) -> bool:
+    return bool(grammar) and str(grammar).endswith(STRICT_SUFFIX)
+
+
+_THINK_RE = re.compile(r"<think>.*?</think>", re.S)
+_FENCE_RE = re.compile(r"```[a-zA-Z]*")
+
+
+def strip_noise(raw: str) -> str:
+    """Drop <think> blocks and markdown code fences before brace-scanning."""
+    text = _THINK_RE.sub("", str(raw or ""))
+    text = text.replace("<think>", "").replace("</think>", "")
+    return _FENCE_RE.sub("", text)
+
+
+def extract_json_object(raw: str) -> str | None:
+    """Return the first balanced top-level {...} in `raw`, or None.
+
+    Brace-scans with string/escape awareness so JSON embedded in stray prose
+    (a misbehaving unconstrained backend) is still recoverable.
+    """
+    start = raw.find("{")
+    if start < 0:
+        return None
+    depth = 0
+    in_string = False
+    escaped = False
+    for i in range(start, len(raw)):
+        ch = raw[i]
+        if in_string:
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == '"':
+                in_string = False
+            continue
+        if ch == '"':
+            in_string = True
+        elif ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                return raw[start : i + 1]
+    return None
+
+
+def _one_line(text: str, limit: int) -> str:
+    return " ".join(str(text or "").split())[:limit]
+
+
+def _as_int(value) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(round(value))
+    if isinstance(value, str):
+        try:
+            return int(round(float(value.strip())))
+        except ValueError:
+            return None
+    return None
+
+
+def _coerce_building(item) -> dict | None:
+    """One BUILD entry, normalized to a stable 5-key shape; None if unusable.
+
+    kind must be a non-empty string (the engine maps synonyms / unknowns).
+    Unknown keys are dropped; types are coerced; name/near are whitespace-
+    collapsed and clipped.
+    """
+    if not isinstance(item, dict):
+        return None
+    kind = item.get("kind")
+    if not isinstance(kind, str) or not kind.strip():
+        return None
+    name = item.get("name")
+    name = _one_line(name, NAME_MAX_CHARS) if isinstance(name, str) and name.strip() else None
+    near = item.get("near")
+    near = _one_line(near, NEAR_MAX_CHARS) if isinstance(near, str) and near.strip() else None
+    return {
+        "kind": _one_line(kind.lower(), 40),
+        "name": name,
+        "near": near,
+        "floors": _as_int(item.get("floors")),
+        "hue": _as_int(item.get("hue")),
+    }
+
+
+_BUILDING_FRAGMENT_RE = re.compile(r'\{[^{}]*"kind"\s*:\s*"')
+
+
+def parse_build(raw: str) -> tuple[dict | None, str | None]:
+    """Parse a one-shot BUILD reply. Returns (plan, None) or (None, error).
+
+    Plan shape (always fully normalized):
+        {"intent": "build"|"decline", "blurb": str,
+         "buildings": [entry x0..3], "decline_reason": str|None}
+
+    Lenient by design: code fences and <think> blocks are stripped, the outer
+    object is balanced-brace extracted, then salvaged key by key. When the
+    outer JSON is broken, individual {"kind": ...} objects are scraped from
+    the raw text so a truncated array still yields buildings.
+    """
+    if not raw or not str(raw).strip():
+        return None, "empty output"
+    text = strip_noise(str(raw))
+
+    obj = None
+    candidate = extract_json_object(text)
+    if candidate is not None:
+        try:
+            obj = json.loads(candidate)
+        except (json.JSONDecodeError, ValueError):
+            obj = None
+
+    intent = "build"
+    blurb = ""
+    decline_reason = None
+    buildings: list[dict] = []
+    if isinstance(obj, dict):
+        if obj.get("intent") in ("build", "decline"):
+            intent = obj["intent"]
+        b = obj.get("blurb")
+        if isinstance(b, str):
+            blurb = _one_line(b, BLURB_MAX_CHARS)
+        dr = obj.get("decline_reason")
+        if isinstance(dr, str) and dr.strip():
+            decline_reason = _one_line(dr, DECLINE_MAX_CHARS)
+        arr = obj.get("buildings")
+        if isinstance(arr, list):
+            for item in arr:
+                entry = _coerce_building(item)
+                if entry is not None:
+                    buildings.append(entry)
+
+    # Salvage: broken outer object / broken array — scrape balanced
+    # {"kind": ...} fragments straight from the text.
+    if not buildings:
+        for m in _BUILDING_FRAGMENT_RE.finditer(text):
+            frag = extract_json_object(text[m.start():])
+            if not frag:
+                continue
+            try:
+                item = json.loads(frag)
+            except (json.JSONDecodeError, ValueError):
+                continue
+            entry = _coerce_building(item)
+            if entry is not None:
+                buildings.append(entry)
+
+    buildings = buildings[:MAX_BUILDINGS]
+    if intent == "decline" and not buildings:
+        return {
+            "intent": "decline",
+            "blurb": blurb,
+            "buildings": [],
+            "decline_reason": decline_reason or "the petition could not be read as a building",
+        }, None
+    if not buildings:
+        return None, "no usable BUILD JSON"
+    return {"intent": "build", "blurb": blurb, "buildings": buildings, "decline_reason": None}, None
+
+
+_FIX_CHOICE_RE = re.compile(r'"choice"\s*:\s*"([^"]{1,12})"')
+_FIX_DIAGNOSIS_RE = re.compile(r'"diagnosis"\s*:\s*"([^"]{1,300})"')
+_FIX_BLURB_RE = re.compile(r'"blurb"\s*:\s*"([^"]{1,200})"')
+
+
+def parse_fix(raw: str) -> tuple[dict | None, str | None]:
+    """Parse a one-shot FIX reply. Returns (obj, None) or (None, error).
+
+    Obj shape: {"diagnosis": str, "choice": str|None, "blurb": str}.
+    choice is NOT validated against the candidate list here — the planner
+    does that and falls back to the best predicted candidate.
+    """
+    if not raw or not str(raw).strip():
+        return None, "empty output"
+    text = strip_noise(str(raw))
+
+    diagnosis = choice = blurb = None
+    candidate = extract_json_object(text)
+    if candidate is not None:
+        try:
+            obj = json.loads(candidate)
+        except (json.JSONDecodeError, ValueError):
+            obj = None
+        if isinstance(obj, dict):
+            d = obj.get("diagnosis")
+            if isinstance(d, str) and d.strip():
+                diagnosis = _one_line(d, DIAGNOSIS_MAX_CHARS)
+            c = obj.get("choice")
+            if isinstance(c, (str, int)) and not isinstance(c, bool) and str(c).strip():
+                choice = str(c).strip()[:12]
+            b = obj.get("blurb")
+            if isinstance(b, str) and b.strip():
+                blurb = _one_line(b, FIX_BLURB_MAX_CHARS)
+
+    if diagnosis is None and choice is None:
+        # Key-by-key salvage from a broken outer object.
+        m = _FIX_CHOICE_RE.search(text)
+        choice = m.group(1).strip() if m else None
+        m = _FIX_DIAGNOSIS_RE.search(text)
+        diagnosis = _one_line(m.group(1), DIAGNOSIS_MAX_CHARS) if m else None
+        if blurb is None:
+            m = _FIX_BLURB_RE.search(text)
+            blurb = _one_line(m.group(1), FIX_BLURB_MAX_CHARS) if m else None
+
+    if diagnosis is None and choice is None:
+        return None, "no usable FIX JSON"
+    return {"diagnosis": diagnosis or "", "choice": choice, "blurb": blurb or ""}, None
+
+
+def parse_moderation(raw: str) -> tuple[dict | None, str | None]:
+    """Parse a moderation verdict. Returns (obj, None) or (None, error).
+
+    `allowed` must be a real JSON boolean — anything fuzzier than that is a
+    parse error, and parse errors mean DENY upstream (default-deny).
+    """
+    if not raw or not raw.strip():
+        return None, "empty output"
+    candidate = extract_json_object(strip_noise(raw))
+    if candidate is None:
+        return None, "no JSON object found"
+    try:
+        obj = json.loads(candidate)
+    except (json.JSONDecodeError, ValueError) as exc:
+        return None, f"invalid JSON: {exc.msg if hasattr(exc, 'msg') else exc}"
+    if not isinstance(obj, dict):
+        return None, "top level is not a JSON object"
+    allowed = obj.get("allowed")
+    if not isinstance(allowed, bool):
+        return None, '"allowed" is not a boolean'
+    category = obj.get("category")
+    if category is not None and not isinstance(category, str):
+        return None, '"category" is not a string'
+    return {"allowed": allowed, "category": (category or "").strip()[:40]}, None

package.json

@@ -0,0 +1,12 @@
+{
+  "name": "nemocity",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Tooling for the NEMOCITY web client (tools/shot.mjs headless screenshots). web/ itself is plain ES modules with vendored three. If node_modules is absent, shot.mjs falls back to ../glassblower/node_modules/playwright.",
+  "scripts": {
+    "shot": "node tools/shot.mjs"
+  },
+  "devDependencies": {
+    "playwright": "^1.60.0"
+  }
+}

requirements.txt

@@ -0,0 +1,18 @@
+# NEMOCITY deps. Never pin gradio/spaces/torch — the Spaces image force-installs
+# them to match the README `sdk_version` (here 6.16.0, the pre-SSR build proven
+# live on the org ZeroGPU by pareidolia with this exact gr.Server launch pattern).
+#
+# Stage A (CITY_BACKEND=mock): the gorgeous zero-GPU city needs NO ML deps — only
+# the web/API stack below. gradio itself comes from the image.
+fastapi>=0.115
+uvicorn>=0.30
+pydantic>=2.7
+huggingface_hub>=0.30
+
+# Stage B (CITY_BACKEND=zerogpu): uncomment for the live Nemotron-Nano-9B-v2 path.
+# nemotron_h is in-tree from transformers 4.55.4; <5 keeps hub<1.0 compatible with
+# gradio 6.16.0 (the documented working combo). spaces/torch come from the image.
+# transformers>=4.56,<5
+# accelerate>=0.34.0
+# einops
+# sentencepiece

server/__init__.py

@@ -0,0 +1,8 @@
+"""NEMOCITY server package — HTTP/SSE transport layer (AGENT-SERVER).
+
+Modules:
+  schemas      pydantic request/response models for the HTTP API
+  sse          asyncio broadcast hub for /api/stream
+  ratelimit    signed-cookie client identity + sliding-window rate limit
+  persistence  traces/wishes.jsonl store, boot rebuild, optional HF dataset sync
+"""

server/persistence.py

@@ -0,0 +1,221 @@
+"""Trace persistence + boot-time world rebuild + optional HF dataset sync.
+
+The single source of durable truth is ``traces/wishes.jsonl``: one JSON line per
+granted petition (the WishTrace of ARCHITECTURE.md, extended with a ``features``
+array — the engine-clamped, seeded events the petition produced — so the city can be
+rebuilt exactly on boot: genesis + every trace's features, in order).
+
+Dataset sync (both persistence across Space restarts and the published agent-trace
+evidence): when ``HF_TOKEN`` and ``CITY_DATASET`` are set, wishes.jsonl is
+downloaded on boot if the local file is missing and uploaded after each granted
+petition. Every network error is swallowed and logged — the city must never die of
+a flaky connection.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import threading
+from pathlib import Path
+from typing import Any, Optional
+
+log = logging.getLogger("nemocity.persistence")
+
+TRACES_FILENAME = "wishes.jsonl"
+
+
+def trace_features(trace: dict[str, Any]) -> list[dict[str, Any]]:
+    """The full features stored on a trace line (``[]`` for lines without them)."""
+    features = trace.get("features")
+    if isinstance(features, list):
+        return [f for f in features if isinstance(f, dict)]
+    return []
+
+
+def rebuild_features(
+    genesis: list[dict[str, Any]], traces: list[dict[str, Any]]
+) -> list[dict[str, Any]]:
+    """Ordered feature list for boot: genesis + each trace's features, in order."""
+    features: list[dict[str, Any]] = [dict(f) for f in genesis]
+    for trace in traces:
+        found = trace_features(trace)
+        if not found and trace.get("feature_ids"):
+            # A pre-extension line: its features can't be replayed; the world simply
+            # rebuilds without them rather than refusing to boot.
+            log.warning(
+                "trace %s carries feature_ids but no features; skipped in rebuild",
+                trace.get("wish_id"),
+            )
+        features.extend(found)
+    return features
+
+
+class TraceStore:
+    """Append-only JSONL store under ``traces_dir``. Thread-safe appends (uploads
+    run in a worker thread; appends may too, depending on the engine)."""
+
+    def __init__(self, traces_dir: Path | str, filename: str = TRACES_FILENAME) -> None:
+        self.dir = Path(traces_dir)
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.path = self.dir / filename
+        self._lock = threading.Lock()
+
+    def append(
+        self, trace: dict[str, Any], features: Optional[list[dict[str, Any]]] = None
+    ) -> dict[str, Any]:
+        """Write one trace line; returns the dict actually written (trace + features)."""
+        line_obj = dict(trace)
+        if features is not None:
+            line_obj["features"] = features
+        encoded = json.dumps(line_obj, ensure_ascii=False)
+        with self._lock:
+            with self.path.open("a", encoding="utf-8") as fh:
+                fh.write(encoded + "\n")
+        return line_obj
+
+    def load(self) -> list[dict[str, Any]]:
+        """All trace lines, in order. Corrupt lines are skipped with a warning (a
+        half-written final line after a crash must not brick the boot)."""
+        if not self.path.exists():
+            return []
+        traces: list[dict[str, Any]] = []
+        with self.path.open("r", encoding="utf-8") as fh:
+            for lineno, raw in enumerate(fh, start=1):
+                raw = raw.strip()
+                if not raw:
+                    continue
+                try:
+                    obj = json.loads(raw)
+                except json.JSONDecodeError:
+                    log.warning("skipping corrupt trace line %d in %s", lineno, self.path)
+                    continue
+                if isinstance(obj, dict):
+                    traces.append(obj)
+        return traces
+
+
+class DatasetSync:
+    """Mirror wishes.jsonl to/from an HF dataset repo. Inert unless both HF_TOKEN
+    and CITY_DATASET are set; never raises for network problems."""
+
+    def __init__(
+        self,
+        store: TraceStore,
+        token: Optional[str] = None,
+        dataset: Optional[str] = None,
+    ) -> None:
+        self.store = store
+        self.token = token if token is not None else os.environ.get("HF_TOKEN")
+        self.dataset = dataset if dataset is not None else os.environ.get("CITY_DATASET")
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.token and self.dataset)
+
+    def download_if_missing(self) -> bool:
+        """Fetch wishes.jsonl from the dataset when the local file doesn't exist
+        (fresh Space boot). Returns True only if a file was restored."""
+        if not self.enabled or self.store.path.exists():
+            return False
+        try:
+            from huggingface_hub import hf_hub_download
+
+            fetched = hf_hub_download(
+                repo_id=self.dataset,
+                repo_type="dataset",
+                filename=self.store.path.name,
+                token=self.token,
+            )
+            self.store.path.write_bytes(Path(fetched).read_bytes())
+            log.info("restored %s from dataset %s", self.store.path.name, self.dataset)
+            return True
+        except Exception as exc:  # noqa: BLE001 — sync must never crash the app
+            log.warning("dataset download skipped (%s): %s", self.dataset, exc)
+            return False
+
+    def upload(self) -> bool:
+        """Push the current wishes.jsonl to the dataset. Returns success; the next
+        granted wish retries naturally on failure."""
+        if not self.enabled or not self.store.path.exists():
+            return False
+        try:
+            from huggingface_hub import HfApi
+
+            HfApi(token=self.token).upload_file(
+                path_or_fileobj=str(self.store.path),
+                path_in_repo=self.store.path.name,
+                repo_id=self.dataset,
+                repo_type="dataset",
+                commit_message="nemocity: petition granted",
+            )
+            return True
+        except Exception as exc:  # noqa: BLE001 — sync must never crash the app
+            log.warning("dataset upload failed (next wish retries): %s", exc)
+            return False
+
+
+class PersistenceService:
+    """What the rest of the app talks to.
+
+    Boot:   ``features = service.boot(genesis_features)`` (download-if-missing +
+            rebuild). Afterwards ``service.traces()`` serves the ledger from
+            memory — no file reads per request.
+    Wish:   ``await service.record(trace, features)`` — append + fire-and-forget
+            dataset upload off the event loop.
+    """
+
+    def __init__(
+        self, traces_dir: Path | str, sync: Optional[DatasetSync] = None
+    ) -> None:
+        self.store = TraceStore(traces_dir)
+        self.sync = sync if sync is not None else DatasetSync(self.store)
+        self._traces: list[dict[str, Any]] = []
+        self._booted = False
+        self._upload_tasks: set[asyncio.Task[Any]] = set()
+
+    @property
+    def path(self) -> Path:
+        return self.store.path
+
+    def boot(self, genesis: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Restore (if configured) + load traces + return the full ordered feature
+        list (genesis + every trace's features)."""
+        self.sync.download_if_missing()
+        self._traces = self.store.load()
+        self._booted = True
+        return rebuild_features(genesis, self._traces)
+
+    def traces(self) -> list[dict[str, Any]]:
+        """All granted-wish traces in grant order (loads lazily if boot was skipped)."""
+        if not self._booted:
+            self._traces = self.store.load()
+            self._booted = True
+        return self._traces
+
+    def find(self, wish_id: str) -> Optional[dict[str, Any]]:
+        for trace in self.traces():
+            if trace.get("wish_id") == wish_id:
+                return trace
+        return None
+
+    async def record(
+        self, trace: dict[str, Any], features: Optional[list[dict[str, Any]]] = None
+    ) -> dict[str, Any]:
+        """Persist one granted wish, then upload to the dataset in the background.
+        Never raises for sync problems; the append itself is the only hard step."""
+        line_obj = self.store.append(trace, features)
+        self.traces().append(line_obj)
+        if self.sync.enabled:
+            task = asyncio.create_task(asyncio.to_thread(self.sync.upload))
+            # keep a strong reference so the task isn't garbage-collected mid-flight
+            self._upload_tasks.add(task)
+            task.add_done_callback(self._upload_tasks.discard)
+        return line_obj
+
+    async def drain(self) -> None:
+        """Wait for in-flight uploads (shutdown hygiene)."""
+        if self._upload_tasks:
+            await asyncio.gather(*tuple(self._upload_tasks), return_exceptions=True)

server/ratelimit.py

@@ -0,0 +1,137 @@
+"""Client identity + sliding-window rate limiting (in-memory, single process).
+
+Identity: a signed cookie token hashed together with the client IP — stable for a
+visitor, cheap to verify, no accounts. The HMAC secret comes from ``CITY_SECRET``
+(set it on the Space so identities survive restarts) or is generated per-process.
+
+Limit: 3 petitions / hour / client, true sliding window. Denied attempts are NOT
+recorded, so hammering the endpoint never extends the lockout. The Space runs a
+single uvicorn worker, so in-memory state is authoritative.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import secrets
+import time
+from collections import deque
+from typing import Callable, Optional, Tuple
+
+COOKIE_NAME = "nemocity_id"
+DEFAULT_LIMIT = 3
+DEFAULT_WINDOW_SECONDS = 3600.0
+# Defense-in-depth: a per-IP ceiling (several clients can share a NAT, so it is
+# intentionally looser than the per-client limit). Cookie-clearing can mint fresh
+# client ids; this cap bounds that abuse.
+DEFAULT_IP_LIMIT = 12
+
+
+def client_ip(request) -> str:
+    """Best client IP we can get. SECURITY: the FIRST X-Forwarded-For hop is
+    client-controlled (a forged header mints a fresh rate-limit bucket per
+    request — verify-fleet finding). The trustworthy entry is the one the
+    closest trusted proxy appended: the LAST hop. On HF Spaces the edge proxy
+    appends the real client IP, so take the last entry; locally use the peer."""
+    forwarded = request.headers.get("x-forwarded-for", "")
+    if forwarded:
+        hops = [h.strip() for h in forwarded.split(",") if h.strip()]
+        if hops:
+            return hops[-1]
+    return request.client.host if request.client else "unknown"
+
+
+class ClientIdentity:
+    """Mints and verifies the signed visitor cookie; derives the rate-limit id."""
+
+    def __init__(self, secret: Optional[str] = None) -> None:
+        self.secret = secret or os.environ.get("CITY_SECRET") or secrets.token_hex(32)
+
+    def _sign(self, token: str) -> str:
+        return hmac.new(
+            self.secret.encode("utf-8"), token.encode("utf-8"), hashlib.sha256
+        ).hexdigest()[:32]
+
+    def mint(self) -> str:
+        token = secrets.token_hex(8)
+        return f"{token}.{self._sign(token)}"
+
+    def verify(self, cookie_value: Optional[str]) -> Optional[str]:
+        """Return the token if the cookie is authentic, else None."""
+        if not cookie_value or "." not in cookie_value:
+            return None
+        token, _, signature = cookie_value.rpartition(".")
+        if not token or not hmac.compare_digest(signature, self._sign(token)):
+            return None
+        return token
+
+    def resolve(self, request) -> Tuple[str, Optional[str]]:
+        """Return ``(client_id, cookie_to_set)``.
+
+        ``cookie_to_set`` is a freshly minted signed value when the request carried
+        no valid cookie (the caller sets it on the response), else None.
+        ``client_id = sha256(token | ip)`` — signed cookie + IP hash per contract.
+        """
+        token = self.verify(request.cookies.get(COOKIE_NAME))
+        new_cookie: Optional[str] = None
+        if token is None:
+            new_cookie = self.mint()
+            token = new_cookie.split(".", 1)[0]
+        ip = client_ip(request)
+        cid = hashlib.sha256(f"{token}|{ip}".encode("utf-8")).hexdigest()[:16]
+        return cid, new_cookie
+
+
+class RateLimiter:
+    """Sliding-window counter: at most ``limit`` recorded hits per ``window`` seconds
+    per key. ``clock`` is injectable for tests (monotonic seconds)."""
+
+    def __init__(
+        self,
+        limit: int = DEFAULT_LIMIT,
+        window: float = DEFAULT_WINDOW_SECONDS,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.limit = limit
+        self.window = window
+        self.clock = clock
+        self._hits: dict[str, deque[float]] = {}
+        self._last_sweep = clock()
+
+    def hit(self, key: str) -> Tuple[bool, float]:
+        """Try to record one hit for ``key``.
+
+        Returns ``(allowed, retry_after_seconds)``. Denied attempts are not
+        recorded, so the window slides only on real (allowed) wishes.
+        """
+        now = self.clock()
+        hits = self._hits.setdefault(key, deque())
+        while hits and now - hits[0] >= self.window:
+            hits.popleft()
+        if len(hits) >= self.limit:
+            return False, max(0.0, self.window - (now - hits[0]))
+        hits.append(now)
+        self._sweep_if_due(now)
+        return True, 0.0
+
+    def remaining(self, key: str) -> int:
+        now = self.clock()
+        hits = self._hits.get(key)
+        if not hits:
+            return self.limit
+        live = sum(1 for t in hits if now - t < self.window)
+        return max(0, self.limit - live)
+
+    def _sweep_if_due(self, now: float) -> None:
+        """Drop keys whose every hit has expired (bounds memory over long uptimes)."""
+        if now - self._last_sweep < self.window:
+            return
+        self._last_sweep = now
+        stale = [
+            key
+            for key, hits in self._hits.items()
+            if not hits or now - hits[-1] >= self.window
+        ]
+        for key in stale:
+            del self._hits[key]

server/schemas.py

@@ -0,0 +1,88 @@
+"""Pydantic request/response models for the NEMOCITY HTTP API.
+
+Shapes follow ARCHITECTURE.md §HTTP API exactly (wire names keep godseed's wish_*;
+"petition" is user-facing copy only):
+
+  GET  /api/state        -> StateResponse  (includes server_now for the shared sim clock)
+  POST /api/wish {text}  -> WishAccepted   (errors: 400/429/503 with a city-hall `detail`)
+  POST /api/fix          -> WishAccepted   (409 when traffic is flowing smoothly)
+  GET  /api/wishes       -> list[WishSummary]
+  GET  /api/wishes/{id}  -> raw WishTrace dict (passed through, engine-owned shape)
+
+Features and WishTraces are deliberately NOT strict models here: the engine owns those
+shapes and the server passes them through untouched (the "her" pattern — transport never
+reinterprets city facts).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+# The moderation fast-path enforces the real petition limit (<=160 chars) with a
+# readable reason; this transport-level cap only stops abusive megabyte bodies before
+# they reach moderation.
+TRANSPORT_MAX_WISH_CHARS = 2000
+
+
+class WishRequest(BaseModel):
+    """Body of POST /api/wish (a petition)."""
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    text: str = Field(..., min_length=1, max_length=TRANSPORT_MAX_WISH_CHARS)
+
+    @field_validator("text")
+    @classmethod
+    def _not_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("a petition needs words")
+        return value.strip()
+
+
+class WishAccepted(BaseModel):
+    """Response of POST /api/wish and POST /api/fix."""
+
+    wish_id: str
+    position: int = Field(..., ge=1, description="1-based place in the queue")
+
+
+class CurrentWish(BaseModel):
+    """The petition city hall is processing right now."""
+
+    wish_id: str
+    text_preview: str
+
+
+class QueueInfo(BaseModel):
+    length: int = 0
+    current: Optional[CurrentWish] = None
+
+
+class WorldState(BaseModel):
+    """Snapshot of the deterministic city: ordered event list + counters."""
+
+    version: int = Field(..., ge=0, description="total number of features")
+    epoch: int = Field(..., ge=0, description="number of granted petitions")
+    features: list[dict[str, Any]]
+
+
+class WishSummary(BaseModel):
+    """One row of the ledger index (GET /api/wishes)."""
+
+    wish_id: str
+    text: str
+    epitaph: str = ""
+    epoch: int
+    ts: float
+
+
+class StateResponse(BaseModel):
+    """GET /api/state. server_now anchors every client's shared sim clock
+    (simTime = server_now - CITY_EPOCH_S); clients slew toward it, never snap."""
+
+    world: WorldState
+    queue: QueueInfo
+    wishes_recent: list[WishSummary]
+    server_now: float

server/sse.py

@@ -0,0 +1,117 @@
+"""Asyncio broadcast hub for /api/stream (ARCHITECTURE.md §SSE protocol).
+
+One hub, many subscribers; every subscriber receives every published event. Design
+constraints, in order of importance:
+
+  * The producer (the queue worker granting a petition) must NEVER block or fail
+    because a browser tab is slow: each subscriber gets a bounded queue and the OLDEST
+    event is dropped on overflow. A reconnecting client re-syncs via GET /api/state.
+  * Idle connections receive ``{"type": "heartbeat", "server_now": ...}`` every 15s so
+    proxies (and the HF Space router) keep the stream open; server_now lets clients
+    slew their shared sim clock against drift.
+  * Disconnects clean up after themselves: the wire generator unsubscribes in a
+    ``finally`` block, which Starlette triggers on client disconnect.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from typing import Any, AsyncIterator, Iterable, Optional
+
+log = logging.getLogger("nemocity.sse")
+
+HEARTBEAT_SECONDS = 15.0
+DEFAULT_QUEUE_SIZE = 256
+
+
+def format_sse(event: dict[str, Any]) -> str:
+    """Wire-encode one event. Events are plain JSON on the default `message` channel;
+    clients dispatch on ``data.type`` (matches the contract's event objects)."""
+    return f"data: {json.dumps(event, ensure_ascii=False, separators=(',', ':'))}\n\n"
+
+
+class SSEHub:
+    """Fan-out broadcast hub. ``publish`` is synchronous and non-blocking; ``emit`` is
+    the async alias matching the planner's ``emit`` callback signature."""
+
+    def __init__(
+        self,
+        heartbeat: float = HEARTBEAT_SECONDS,
+        max_queue: int = DEFAULT_QUEUE_SIZE,
+    ) -> None:
+        self.heartbeat = heartbeat
+        self.max_queue = max_queue
+        self._subscribers: set[asyncio.Queue[dict[str, Any]]] = set()
+
+    @property
+    def subscriber_count(self) -> int:
+        return len(self._subscribers)
+
+    # ------------------------------------------------------------------ producer side
+    def publish(self, event: dict[str, Any]) -> None:
+        """Deliver ``event`` to every subscriber. Never blocks: when a subscriber's
+        queue is full, its oldest pending event is dropped to make room."""
+        for queue in tuple(self._subscribers):
+            try:
+                queue.put_nowait(event)
+            except asyncio.QueueFull:
+                try:
+                    queue.get_nowait()  # drop the oldest event for this slow client
+                except asyncio.QueueEmpty:  # pragma: no cover — only under a race
+                    pass
+                try:
+                    queue.put_nowait(event)
+                except asyncio.QueueFull:  # pragma: no cover — only under a race
+                    log.debug("subscriber queue still full; event dropped")
+
+    async def emit(self, event: dict[str, Any]) -> None:
+        """Async alias of :meth:`publish` (the planner/queue-worker emit callback)."""
+        self.publish(event)
+
+    # ---------------------------------------------------------------- subscriber side
+    def subscribe(self) -> asyncio.Queue[dict[str, Any]]:
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=self.max_queue)
+        self._subscribers.add(queue)
+        return queue
+
+    def unsubscribe(self, queue: asyncio.Queue[dict[str, Any]]) -> None:
+        self._subscribers.discard(queue)
+
+    async def event_stream(
+        self,
+        initial_events: Iterable[dict[str, Any]] = (),
+        limit: Optional[int] = None,
+    ) -> AsyncIterator[str]:
+        """Async generator yielding wire-format SSE for one client.
+
+        ``initial_events`` (hello / queue snapshot) are sent first, then every
+        broadcast event; a heartbeat is sent whenever ``self.heartbeat`` seconds pass
+        without traffic. Subscription is registered before the first yield so no
+        event published after the request reaches this generator is missed.
+
+        ``limit`` (optional) closes the stream after that many events — a debug/test
+        aid (`curl '/api/stream?limit=20'`); browsers stream unbounded.
+        """
+        queue = self.subscribe()
+        sent = 0
+        try:
+            yield "retry: 3000\n\n"  # client auto-reconnect hint
+            for event in initial_events:
+                yield format_sse(event)
+                sent += 1
+                if limit is not None and sent >= limit:
+                    return
+            while True:
+                try:
+                    event = await asyncio.wait_for(queue.get(), timeout=self.heartbeat)
+                except asyncio.TimeoutError:
+                    event = {"type": "heartbeat", "server_now": time.time()}
+                yield format_sse(event)
+                sent += 1
+                if limit is not None and sent >= limit:
+                    return
+        finally:
+            self.unsubscribe(queue)

tests/test_api.py

@@ -0,0 +1,475 @@
+"""HTTP/SSE layer tests (AGENT-SERVER). Engine and mind are faked — these tests
+exercise only the transport: endpoints, SSE hub, persistence, rate limiting, the
+fix gate, error paths. Wire names keep godseed's wish_* per the contract.
+
+Run:
+  .venv/bin/python -m pytest tests/test_api.py -x -q
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import time
+import zlib
+from pathlib import Path
+from typing import Any, Optional
+
+import pytest
+from fastapi.testclient import TestClient
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from app import (  # noqa: E402
+    FIX_COOLDOWN_REASON,
+    FIX_RATE_REASON,
+    TRAFFIC_SMOOTH_REASON,
+    create_app,
+)
+from server.persistence import PersistenceService, rebuild_features  # noqa: E402
+from server.ratelimit import ClientIdentity, RateLimiter  # noqa: E402
+from server.sse import SSEHub  # noqa: E402
+
+CITY_EPOCH_S = 1781222400.0
+
+# Genesis fixture — a slice of ARCHITECTURE.md epoch-0 shapes (events are
+# byte-compatible with godseed Features: id, wish_id, tool, args, seed, t).
+GENESIS = [
+    {"id": "e_000000", "wish_id": "genesis", "tool": "lay_road",
+     "args": {"cells": [[0, -12], [0, -11], [0, -10]], "klass": "avenue",
+              "name": "Main St"}, "seed": 7, "t": CITY_EPOCH_S},
+    {"id": "e_000001", "wish_id": "genesis", "tool": "lay_road",
+     "args": {"cells": [[8, 0], [9, 0]], "klass": "street", "name": "Old Bridge"},
+     "seed": 11, "t": CITY_EPOCH_S},
+    {"id": "e_000002", "wish_id": "genesis", "tool": "place_building",
+     "args": {"kind": "town_hall", "name": "City Hall", "cx": -2, "cz": -3,
+              "w": 2, "d": 2, "floors": 2, "hue": 35, "variant": 0},
+     "seed": 13, "t": CITY_EPOCH_S},
+    {"id": "e_000003", "wish_id": "genesis", "tool": "note",
+     "args": {"text": "Nemocity is listening. Ask for a building.",
+              "kind": "milestone"}, "seed": 17, "t": CITY_EPOCH_S},
+]
+
+PLAN = {
+    "intent": "build",
+    "blurb": "A little cafe rises near the park.",
+    "buildings": [{"kind": "cafe", "name": "Cafe Luna", "near": "the park"}],
+    "decline_reason": None,
+}
+
+
+# ------------------------------------------------------------------------------- fakes
+class TrafficSmooth(Exception):
+    """Engine gate verdict; the server matches this by TYPE NAME, never by import."""
+
+
+def fake_fast_check(text: str) -> Optional[str]:
+    """Moderation fast path: readable reason or None (engine contract)."""
+    if "forbidden" in text.lower():
+        return "City hall declines this petition; it reeks of the forbidden."
+    if len(text) > 160:
+        return "City hall reads only short petitions; trim yours to fewer words."
+    return None
+
+
+class FakePlanner:
+    """Emits the City Hall paperwork (plan), makes one place_building call,
+    returns a WishTrace-shaped dict."""
+
+    async def grant(self, wish: str, world_summary: str, act, emit) -> dict[str, Any]:
+        await emit({"type": "plan", "plan": PLAN})
+        call = {
+            "tool": "place_building",
+            "args": {"kind": "cafe", "name": "Cafe Luna", "cx": 3, "cz": -2,
+                     "w": 1, "d": 1, "floors": 1, "hue": 35, "variant": 2},
+        }
+        await act(call)
+        return {
+            "text": wish,
+            "submitted_at": time.time(),
+            "moderation": {"allowed": True, "category": None},
+            "plan": PLAN,
+            "epitaph": PLAN["blurb"],
+            "model": "fake", "backend": "fake", "ms_total": 1,
+        }
+
+
+class FakeWorld:
+    def __init__(self, features: Optional[list[dict[str, Any]]] = None) -> None:
+        self.features: list[dict[str, Any]] = list(features or [])
+        self.version = len(self.features)
+        self.epoch = 0
+
+    def apply_feature(self, feature: dict[str, Any]) -> None:
+        self.features.append(feature)
+        self.version += 1
+
+
+class FakeQueueWorker:
+    """Minimal stand-in for engine.queue_worker: pop -> grant -> persist -> emit,
+    plus the City Engineer gate (submit_fix raises TrafficSmooth when smooth)."""
+
+    def __init__(self, world: FakeWorld, hub: SSEHub,
+                 persistence: PersistenceService, planner: FakePlanner,
+                 traffic_smooth: bool = False) -> None:
+        self.world, self.hub, self.persistence, self.planner = (
+            world, hub, persistence, planner)
+        self.traffic_smooth = traffic_smooth
+        self._pending: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        self._wish_counter = 0
+        self._feature_counter = len(world.features)
+        self._current: Optional[dict[str, Any]] = None
+        self._task: Optional[asyncio.Task[None]] = None
+
+    async def start(self) -> None:
+        self._task = asyncio.create_task(self._run())
+
+    async def stop(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            await asyncio.gather(self._task, return_exceptions=True)
+
+    async def submit(self, text: str, client_id: str) -> tuple[str, int]:
+        self._wish_counter += 1
+        wish_id = f"w_{self._wish_counter:06d}"
+        await self._pending.put({"wish_id": wish_id, "text": text})
+        return wish_id, self._pending.qsize()
+
+    async def submit_fix(self, client_id: str) -> tuple[str, int]:
+        if self.traffic_smooth:
+            raise TrafficSmooth("static assignment max demandRatio < 0.8")
+        self._wish_counter += 1
+        return f"w_{self._wish_counter:06d}", 1
+
+    def snapshot(self) -> dict[str, Any]:
+        current = None
+        if self._current is not None:
+            current = {"wish_id": self._current["wish_id"],
+                       "text_preview": self._current["text"][:40]}
+        return {"length": self._pending.qsize() + (1 if current else 0),
+                "current": current}
+
+    async def _run(self) -> None:
+        while True:
+            wish = await self._pending.get()
+            self._current = wish
+            wish_id = wish["wish_id"]
+            # Test-only grace: starlette's TestClient buffers a whole response, so the
+            # SSE test must subscribe AFTER posting; hold the grant briefly so the
+            # subscriber sees every event. The real engine worker has no such wait.
+            deadline = asyncio.get_running_loop().time() + 0.5
+            while (self.hub.subscriber_count == 0
+                   and asyncio.get_running_loop().time() < deadline):
+                await asyncio.sleep(0.005)
+            await self.hub.emit(
+                {"type": "wish_started", "wish_id": wish_id, "text": wish["text"]})
+            features: list[dict[str, Any]] = []
+            call_index = 0
+
+            async def act(call: dict[str, Any]) -> str:
+                nonlocal call_index
+                await self.hub.emit({"type": "tool_call", "wish_id": wish_id,
+                                     "call_index": call_index,
+                                     "tool": call["tool"], "args": call["args"]})
+                feature = {
+                    "id": f"e_{self._feature_counter:06d}",
+                    "wish_id": wish_id,
+                    "tool": call["tool"],
+                    "args": call["args"],
+                    "seed": zlib.crc32(f"{wish_id}:{call_index}".encode()) & 0x7FFFFFFF,
+                    "t": time.time(),
+                }
+                self._feature_counter += 1
+                call_index += 1
+                self.world.apply_feature(feature)
+                features.append(feature)
+                await self.hub.emit({"type": "world_delta", "feature": feature})
+                return f"ok: {call['tool']}"
+
+            async def emit(event: dict[str, Any]) -> None:
+                await self.hub.emit({"wish_id": wish_id, **event})
+
+            trace = await self.planner.grant(wish["text"], "a small city", act, emit)
+            trace["wish_id"] = wish_id
+            trace["feature_ids"] = [f["id"] for f in features]
+            await self.persistence.record(trace, features)
+            self.world.epoch += 1
+            await self.hub.emit({"type": "wish_granted", "wish_id": wish_id,
+                                 "epitaph": trace["epitaph"],
+                                 "epoch": self.world.epoch})
+            self._current = None
+
+
+# ---------------------------------------------------------------------------- fixtures
+def build_api(tmp_path: Path, *, traffic_smooth: bool = False,
+              fix_rate_limiter: Optional[RateLimiter] = None,
+              fix_cooldown: Optional[RateLimiter] = None):
+    persistence = PersistenceService(tmp_path / "traces")
+    features = persistence.boot(GENESIS)
+    world = FakeWorld(features)
+    hub = SSEHub(heartbeat=0.05)  # fast heartbeats pad bounded test streams quickly
+    queue = FakeQueueWorker(world, hub, persistence, FakePlanner(),
+                            traffic_smooth=traffic_smooth)
+    app = create_app(
+        world=world, queue=queue, hub=hub, persistence=persistence,
+        fast_check=fake_fast_check,
+        rate_limiter=RateLimiter(limit=3, window=3600.0),
+        ip_rate_limiter=RateLimiter(limit=100, window=3600.0),
+        fix_rate_limiter=fix_rate_limiter,
+        fix_cooldown=fix_cooldown,
+        identity=ClientIdentity(secret="test-secret"),
+        mount_web=False, mount_panel=False,
+    )
+    return app, queue
+
+
+@pytest.fixture()
+def api(tmp_path: Path):
+    app, _queue = build_api(tmp_path)
+    return app
+
+
+def _poll_state(client: TestClient, predicate, timeout: float = 5.0) -> dict[str, Any]:
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        state = client.get("/api/state").json()
+        if predicate(state):
+            return state
+        time.sleep(0.02)
+    raise AssertionError("condition not reached before timeout")
+
+
+# ------------------------------------------------------------------------------- tests
+def test_post_wish_returns_id_and_position(api) -> None:
+    with TestClient(api) as client:
+        response = client.post("/api/wish", json={"text": "a ramen shop near the park"})
+        assert response.status_code == 200
+        body = response.json()
+        assert body["wish_id"].startswith("w_")
+        assert isinstance(body["position"], int) and body["position"] >= 1
+
+
+def test_state_includes_server_now(api) -> None:
+    with TestClient(api) as client:
+        before = time.time()
+        state = client.get("/api/state").json()
+        after = time.time()
+        assert before <= state["server_now"] <= after
+
+
+def test_sse_stream_emits_petition_lifecycle(api) -> None:
+    """TestClient buffers whole responses, so the stream is bounded with ?limit=N
+    (heartbeats pad it to N) and read after it closes; the fake worker holds the
+    petition until the subscription lands, so every lifecycle event is captured."""
+    with TestClient(api) as client:
+        posted = client.post("/api/wish", json={"text": "a cafe by the bridge"})
+        assert posted.status_code == 200
+        wish_id = posted.json()["wish_id"]
+
+        response = client.get("/api/stream", params={"limit": 16})
+        assert response.status_code == 200
+        assert response.headers["x-accel-buffering"] == "no"
+        assert response.headers["content-type"].startswith("text/event-stream")
+
+        events = [
+            json.loads(line[len("data: "):])
+            for line in response.text.splitlines()
+            if line.startswith("data: ")
+        ]
+        assert len(events) == 16
+        assert events[0]["type"] == "hello"
+        assert events[0]["world_version"] == len(GENESIS)
+        assert events[0]["epoch"] == 0
+        assert events[0]["server_now"] == pytest.approx(time.time(), abs=30)
+        assert events[1]["type"] == "queue"
+
+        for hb in (e for e in events if e["type"] == "heartbeat"):
+            assert isinstance(hb["server_now"], float)
+
+        seen = [e for e in events[2:] if e["type"] != "heartbeat"]
+        types = [e["type"] for e in seen]
+        assert types == ["wish_started", "plan", "tool_call", "world_delta",
+                         "wish_granted"]
+
+        assert seen[0]["wish_id"] == wish_id
+        plan = seen[1]
+        assert plan["plan"] == PLAN  # raw City Hall paperwork passes through intact
+        delta = next(e for e in seen if e["type"] == "world_delta")
+        assert delta["feature"]["tool"] == "place_building"
+        assert delta["feature"]["wish_id"] == wish_id
+        granted = seen[-1]
+        assert granted["epitaph"] and granted["epoch"] == 1
+
+
+def test_state_reflects_new_feature_and_ledger(api) -> None:
+    with TestClient(api) as client:
+        before = client.get("/api/state").json()
+        baseline = len(before["world"]["features"])
+        assert baseline == len(GENESIS)
+        assert before["queue"] == {"length": 0, "current": None}
+
+        wish_id = client.post(
+            "/api/wish", json={"text": "a row of townhouses on Elm St"}
+        ).json()["wish_id"]
+
+        state = _poll_state(
+            client, lambda s: len(s["world"]["features"]) > baseline)
+        newest = state["world"]["features"][-1]
+        assert newest["wish_id"] == wish_id
+        assert newest["seed"] == zlib.crc32(f"{wish_id}:0".encode()) & 0x7FFFFFFF
+        assert state["world"]["version"] == baseline + 1
+        assert state["world"]["epoch"] == 1
+        assert state["wishes_recent"][0]["wish_id"] == wish_id
+
+        index = client.get("/api/wishes").json()
+        assert [w["wish_id"] for w in index] == [wish_id]
+        assert index[0]["epitaph"] == PLAN["blurb"]
+
+        trace = client.get(f"/api/wishes/{wish_id}").json()
+        assert trace["wish_id"] == wish_id
+        assert trace["plan"] == PLAN and trace["feature_ids"] == [newest["id"]]
+        assert trace["features"][0] == newest  # embedded for boot rebuild
+
+        missing = client.get("/api/wishes/w_999999")
+        assert missing.status_code == 404
+
+
+def test_rate_limit_429_on_fourth_wish(api) -> None:
+    with TestClient(api) as client:
+        for i in range(3):
+            ok = client.post("/api/wish", json={"text": f"small petition {i}"})
+            assert ok.status_code == 200, ok.text
+        blocked = client.post("/api/wish", json={"text": "one petition too many"})
+        assert blocked.status_code == 429
+        assert "Retry-After" in blocked.headers
+        detail = blocked.json()["detail"]
+        assert isinstance(detail, str) and detail  # readable, not a stack trace
+
+
+def test_moderation_fast_path_rejects_with_readable_reason(api) -> None:
+    with TestClient(api) as client:
+        response = client.post("/api/wish", json={"text": "a forbidden storefront"})
+        assert response.status_code == 400
+        assert response.json()["detail"] == (
+            "City hall declines this petition; it reeks of the forbidden.")
+        # rejected petitions never reach the city
+        assert len(client.get("/api/state").json()["world"]["features"]) == len(GENESIS)
+
+
+def test_blank_wish_is_unprocessable(api) -> None:
+    with TestClient(api) as client:
+        assert client.post("/api/wish", json={"text": "   "}).status_code == 422
+        assert client.post("/api/wish", json={}).status_code == 422
+
+
+# ---------------------------------------------------------------------- /api/fix tests
+def test_fix_409_when_traffic_smooth_and_cooldown_not_engaged(tmp_path: Path) -> None:
+    app, queue = build_api(tmp_path, traffic_smooth=True)
+    with TestClient(app) as client:
+        smooth = client.post("/api/fix")
+        assert smooth.status_code == 409
+        assert smooth.json()["detail"] == TRAFFIC_SMOOTH_REASON
+        # a no-op click must not block the citywide engineer: jam forms, fix lands
+        queue.traffic_smooth = False
+        fixed = client.post("/api/fix")
+        assert fixed.status_code == 200, fixed.text
+        body = fixed.json()
+        assert body["wish_id"].startswith("w_") and body["position"] >= 1
+
+
+def test_fix_200_when_jammed_then_global_cooldown_429(tmp_path: Path) -> None:
+    app, _queue = build_api(tmp_path)
+    with TestClient(app) as client:
+        first = client.post("/api/fix")
+        assert first.status_code == 200, first.text
+        second = client.post("/api/fix")
+        assert second.status_code == 429
+        assert second.json()["detail"] == FIX_COOLDOWN_REASON
+        assert "Retry-After" in second.headers
+
+
+def test_fix_client_rate_limit_two_per_hour(tmp_path: Path) -> None:
+    # a permissive global cooldown isolates the per-client 2/hr window
+    app, _queue = build_api(
+        tmp_path, fix_cooldown=RateLimiter(limit=100, window=120.0))
+    with TestClient(app) as client:
+        for _ in range(2):
+            assert client.post("/api/fix").status_code == 200
+        blocked = client.post("/api/fix")
+        assert blocked.status_code == 429
+        assert blocked.json()["detail"] == FIX_RATE_REASON
+        assert "Retry-After" in blocked.headers
+
+
+# ------------------------------------------------------------------- unit: components
+def test_sse_hub_drops_oldest_never_blocks() -> None:
+    async def scenario() -> list[int]:
+        hub = SSEHub(heartbeat=0.1, max_queue=3)
+        queue = hub.subscribe()
+        for i in range(6):
+            hub.publish({"type": "n", "i": i})  # never raises, never blocks
+        hub.unsubscribe(queue)
+        kept = []
+        while not queue.empty():
+            kept.append(queue.get_nowait()["i"])
+        return kept
+
+    assert asyncio.run(scenario()) == [3, 4, 5]  # oldest were dropped
+
+
+def test_rate_limiter_sliding_window() -> None:
+    now = [0.0]
+    limiter = RateLimiter(limit=3, window=3600.0, clock=lambda: now[0])
+    key = "client"
+    for t in (0.0, 1000.0, 2000.0):
+        now[0] = t
+        assert limiter.hit(key)[0]
+    now[0] = 2500.0
+    allowed, retry_after = limiter.hit(key)
+    assert not allowed and retry_after == 3600.0 - 2500.0  # until the t=0 hit expires
+    now[0] = 3600.5  # only the t=0 hit has slid out of the window
+    assert limiter.hit(key)[0]
+    assert limiter.remaining(key) == 0  # live: t=1000, t=2000, t=3600.5
+    allowed, _ = limiter.hit(key)
+    assert not allowed  # denied attempts were never recorded, window is exact
+
+
+def test_identity_cookie_roundtrip_and_tamper() -> None:
+    identity = ClientIdentity(secret="s3cret")
+    cookie = identity.mint()
+    token = cookie.split(".", 1)[0]
+    assert identity.verify(cookie) == token
+    assert identity.verify(cookie[:-1] + ("0" if cookie[-1] != "0" else "1")) is None
+    assert identity.verify("garbage") is None
+    assert identity.verify(None) is None
+
+
+def test_persistence_rebuild_survives_corruption(tmp_path: Path) -> None:
+    traces_dir = tmp_path / "traces"
+    first = PersistenceService(traces_dir)
+    first.boot(GENESIS)
+    feature = {"id": "e_000004", "wish_id": "w_000001", "tool": "place_building",
+               "args": {"kind": "house", "name": "Elm Cottage", "cx": -1, "cz": -6,
+                        "w": 1, "d": 1, "floors": 1, "hue": 20, "variant": 1},
+               "seed": 19, "t": CITY_EPOCH_S + 60.0}
+    asyncio.run(first.record(
+        {"wish_id": "w_000001", "text": "a little house", "submitted_at": 1.0,
+         "epitaph": "a home with a clay roof"},
+        [feature],
+    ))
+    # simulate a crash mid-append
+    with first.path.open("a", encoding="utf-8") as fh:
+        fh.write('{"wish_id": "w_000002", "text": "truncat')
+
+    second = PersistenceService(traces_dir)
+    rebuilt = second.boot(GENESIS)
+    assert rebuilt == GENESIS + [feature]
+    assert [t["wish_id"] for t in second.traces()] == ["w_000001"]
+    assert second.find("w_000001")["epitaph"] == "a home with a clay roof"
+    assert second.find("w_000404") is None
+
+
+def test_rebuild_skips_traces_without_embedded_features() -> None:
+    legacy = {"wish_id": "w_000009", "feature_ids": ["e_0009"]}  # no features array
+    assert rebuild_features(GENESIS, [legacy]) == GENESIS

tests/test_engine.py

@@ -0,0 +1,322 @@
+"""Tests for the NEMOCITY deterministic city engine.
+
+Covers: genesis validity + rebuild equality, synonym/clamp/name behavior,
+placement determinism + the never-fails property, the queue worker grant path
+(act -> placement -> events), and the demand-driven infill rule.
+
+Engine tests import no fastapi/mind — pure engine surface.
+"""
+
+import asyncio
+import sys
+import zlib
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from engine import constants as C
+from engine import placement, tools
+from engine.city import WATER_CELLS, CityState
+from engine.genesis import GENESIS_FEATURES, genesis_features
+from engine.moderation import Moderator
+from engine.queue_worker import QueueWorker, TrafficSmooth
+from engine.world import World
+
+NOW = C.CITY_EPOCH_S + 10_000  # everything in genesis long complete
+
+
+def make_world() -> World:
+    return World.load(genesis_features())
+
+
+def make_city(world=None) -> CityState:
+    return CityState.from_events((world or make_world()).features)
+
+
+# --------------------------------------------------------------------- genesis
+
+
+def test_genesis_shape_and_seeds():
+    assert [f["id"] for f in GENESIS_FEATURES] == [f"e_{i:06d}" for i in range(19)]
+    for i, f in enumerate(GENESIS_FEATURES):
+        assert f["wish_id"] == "genesis"
+        assert f["t"] == float(C.CITY_EPOCH_S)
+        assert f["seed"] == zlib.crc32(f"genesis:{i}".encode()) & 0x7FFFFFFF
+    assert GENESIS_FEATURES[-1]["tool"] == "note"
+
+
+def test_genesis_city_facts():
+    city = make_city()
+    assert city.population(NOW) == 20
+    assert city.jobs == 85
+    assert city.housing_capacity == 20
+    assert city.road_version == 6
+    # the Old Bridge is the only crossing, street class, on water
+    for cell in ((8, 0), (9, 0)):
+        rc = city.roads[cell]
+        assert rc.bridge and rc.klass == "street" and rc.name == "Old Bridge"
+    assert all(
+        not rc.bridge for cell, rc in city.roads.items() if rc.name != "Old Bridge"
+    )
+
+
+def test_genesis_buildings_valid():
+    city = CityState()
+    for ev in genesis_features():
+        if ev["tool"] == "place_building":
+            a = ev["args"]
+            cells = [
+                (a["cx"] + dx, a["cz"] + dz)
+                for dx in range(a["w"]) for dz in range(a["d"])
+            ]
+            assert all(city.is_empty(c) for c in cells), a["name"]
+        city.apply(ev)
+    full = make_city()
+    for b in full.buildings:
+        assert full.door(b) is not None, f"{b.name} touches no road"
+
+
+def test_world_rebuild_equality():
+    w1 = make_world()
+    w2 = World.load([f.to_dict() for f in w1.features])
+    assert [f.to_dict() for f in w1.features] == [f.to_dict() for f in w2.features]
+    assert w1.version == w2.version == 19
+    assert w1.epoch == 0
+
+
+# ------------------------------------------------------------ synonyms / clamps
+
+
+def test_resolve_kind_synonyms():
+    assert tools.resolve_kind("skyscraper") == "tower"
+    assert tools.resolve_kind("Coffee Shop") == "cafe"
+    assert tools.resolve_kind("apartment building") == "apartments"
+    assert tools.resolve_kind("police station") == "fire_station"
+    assert tools.resolve_kind("city hall") == "town_hall"
+    assert tools.resolve_kind("grocery") == "market"
+    assert tools.resolve_kind("hotel") == "apartments"
+    assert tools.resolve_kind("ramen stand") == "house"  # unknown -> house
+    assert tools.resolve_kind(None) == "house"
+    assert tools.resolve_kind("towers") == "tower"
+
+
+def test_place_building_clamps():
+    args, err = tools.validate_call("place_building", {
+        "kind": "office", "name": "A" * 80, "cx": -999, "cz": 999,
+        "floors": 99, "hue": 9999, "variant": 42,
+    })
+    assert err is None
+    assert args["floors"] == 8  # office max
+    assert args["cx"] == C.COORD_MIN and args["cz"] == C.COORD_MAX
+    assert len(args["name"]) <= C.NAME_MAX_LEN
+    assert args["hue"] == 360 and args["variant"] == 7
+    assert args["w"] == 1 and args["d"] == 1
+
+
+def test_unknown_tool_rejected():
+    args, err = tools.validate_call("summon_dragon", {})
+    assert args is None and err.startswith("rejected:")
+
+
+def test_sanitize_name_wordlist_and_length():
+    assert tools.sanitize_name("Cafe Luna") == "Cafe Luna"
+    assert tools.sanitize_name("X" * 99) == "X" * C.NAME_MAX_LEN
+    assert tools.sanitize_name("hitler plaza", default="The Plaza") == "The Plaza"
+    assert tools.sanitize_name(None, default="D") == "D"
+    name = tools.default_name("cafe", "a ramen shop near the park", "w_000001")
+    assert 0 < len(name) <= C.NAME_MAX_LEN
+    assert name == tools.default_name("cafe", "a ramen shop near the park", "w_000001")
+
+
+def test_note_moderated():
+    args, err = tools.validate_call("note", {"text": "nazi parade", "kind": "milestone"})
+    assert args is None and err.startswith("rejected:")
+
+
+# ------------------------------------------------------------------- placement
+
+
+def test_placement_deterministic():
+    runs = []
+    for _ in range(2):
+        city = make_city()
+        events = placement.place(
+            city, kind="cafe", name="Cafe Luna", floors=None, hue=None,
+            near="the park", wish_id="w_000007", call_index=0,
+        )
+        runs.append(events)
+    assert runs[0] == runs[1]
+    args = runs[0][0]["args"]
+    assert args["kind"] == "cafe" and args["w"] == 1 and args["d"] == 1
+
+
+def test_placement_near_park_lands_near_park():
+    city = make_city()
+    events = placement.place(
+        city, "cafe", "Cafe Luna", None, None, "the park", "w_000002", 0,
+    )
+    a = events[0]["args"]
+    park = next(b for b in city.buildings if b.kind == "park")
+    px, pz = park.centroid
+    assert abs(a["cx"] - px) <= 6 and abs(a["cz"] - pz) <= 6
+
+
+def test_placement_never_fails_50_requests():
+    world = make_world()
+    city = make_city(world)
+    kinds = list(C.BUILDINGS)
+    nears = ("the park", "downtown", "the river", "Main St", "", "Riverside Works")
+    for i in range(50):
+        kind = kinds[zlib.crc32(f"k:{i}".encode()) % len(kinds)]
+        near = nears[zlib.crc32(f"n:{i}".encode()) % len(nears)]
+        wish_id = f"w_{i + 10:06d}"
+        events = placement.place(city, kind, f"Test {i}", None, None, near, wish_id, 0)
+        assert events and events[0]["tool"] == "place_building"
+        a = events[0]["args"]
+        cells = [
+            (a["cx"] + dx, a["cz"] + dz)
+            for dx in range(a["w"]) for dz in range(a["d"])
+        ]
+        for c in cells:
+            assert city.is_empty(c), f"request {i} ({kind}) overlaps at {c}"
+        for j, ev in enumerate(events):
+            feature, obs = world.apply(wish_id, j, ev, t=NOW)
+            assert feature is not None, obs
+            city.apply(feature)
+        b = city.buildings[-1]
+        assert city.door(b) is not None, f"{kind} #{i} ended up roadless"
+
+
+def test_connector_when_no_frontage():
+    # Anchor far from roads: a remote park forces an auto-routed connector.
+    city = make_city()
+    events = placement.place(city, "stadium", "Big Bowl", None, None, "", "w_000099", 0)
+    for ev in events:
+        args, err = tools.validate_call(ev["tool"], ev["args"])
+        assert err is None
+    if len(events) == 2:
+        assert events[1]["tool"] == "lay_road"
+        assert events[1]["args"]["klass"] == "street"
+        assert 1 <= len(events[1]["args"]["cells"]) <= 2 * C.CONNECTOR_MAX
+
+
+# ----------------------------------------------------------------- queue worker
+
+
+class _OneShotPlanner:
+    """Calls act once per scripted building request, like mind.planner."""
+
+    def __init__(self, requests):
+        self.requests = requests
+
+    async def grant(self, wish, world_summary, act, emit):
+        await emit({"type": "plan", "plan": {"buildings": self.requests}})
+        turns = []
+        for req in self.requests:
+            obs = await act(req)
+            turns.append({"thought": "", "call": req, "observation": obs})
+        return {
+            "reading": "Permit approved.", "turns": turns,
+            "epitaph": "A fine addition to the skyline.",
+            "ms_total": 1, "model": "test", "backend": "test",
+        }
+
+
+def _run_worker(planner, world):
+    events = []
+
+    async def emit(event):
+        events.append(event)
+
+    worker = QueueWorker(
+        world=world, moderator=Moderator(), planner=planner, emit=emit,
+    )
+
+    async def go():
+        wish_id, position = await worker.submit("a tall tower downtown", "client-1")
+        assert position == 1
+        await worker.start()
+        await asyncio.wait_for(worker._queue.join(), 10)
+        await worker.stop()
+        return wish_id
+
+    wish_id = asyncio.run(go())
+    return wish_id, events, worker
+
+
+def test_grant_path_places_building_and_emits():
+    world = make_world()
+    planner = _OneShotPlanner([{"kind": "skyscraper", "name": "Apex Tower",
+                                "near": "downtown", "floors": 12, "hue": 210}])
+    wish_id, events, _ = _run_worker(planner, world)
+    types = [e["type"] for e in events]
+    assert "plan" in types and "wish_granted" in types
+    plan_event = next(e for e in events if e["type"] == "plan")
+    assert plan_event["wish_id"] == wish_id
+    placed = [f for f in world.features if f.wish_id == wish_id and f.tool == "place_building"]
+    assert placed and placed[0].args["kind"] == "tower"  # synonym repaired
+    deltas = [e for e in events if e["type"] == "world_delta"]
+    assert len(deltas) == len([f for f in world.features if f.wish_id == wish_id])
+
+
+def test_infill_rule_one_bonus_home():
+    # Genesis jobs (85) already exceed housing (20) * 1.15 -> a granted petition
+    # that adds MORE jobs must pull in exactly ONE bonus home + note.
+    world = make_world()
+    planner = _OneShotPlanner([{"kind": "office", "name": "More Jobs Inc",
+                                "near": "downtown"}])
+    wish_id, events, _ = _run_worker(planner, world)
+    mine = [f for f in world.features if f.wish_id == wish_id]
+    homes = [f for f in mine if f.tool == "place_building"
+             and f.args["kind"] in C.RESIDENTIAL_KINDS]
+    notes = [f for f in mine if f.tool == "note"]
+    assert len(homes) == 1
+    assert len(notes) == 1 and notes[0].args["kind"] == "infill"
+    # jobs - housing >= 16 -> the infill upgrades to apartments
+    assert homes[0].args["kind"] == "apartments"
+
+
+def test_moderation_rejects_before_planning():
+    world = make_world()
+    planner = _OneShotPlanner([{"kind": "house"}])
+    events = []
+
+    async def emit(event):
+        events.append(event)
+
+    worker = QueueWorker(world=world, moderator=Moderator(), planner=planner, emit=emit)
+
+    async def go():
+        await worker.submit("build a nazi museum", "client-2")
+        await worker.start()
+        await asyncio.wait_for(worker._queue.join(), 10)
+        await worker.stop()
+
+    asyncio.run(go())
+    assert any(e["type"] == "wish_rejected" for e in events)
+    assert world.version == 19  # nothing landed
+
+
+def test_summary_under_600_chars():
+    world = make_world()
+    text = world.summary(NOW)
+    assert len(text) < 600
+    assert "NEMOCITY" in text and "pop 20" in text
+
+
+def test_submit_fix_gate_smooth_when_no_trips():
+    # A roads-only world has zero demand -> TrafficSmooth.
+    world = World.load([f for f in genesis_features() if f["tool"] == "lay_road"])
+    worker = QueueWorker(world=world, moderator=Moderator(), planner=None, emit=_noop)
+
+    async def go():
+        with pytest.raises(TrafficSmooth):
+            await worker.submit_fix("client-3")
+
+    asyncio.run(go())
+
+
+async def _noop(event):
+    return None

tests/test_mind.py

@@ -0,0 +1,363 @@
+"""Tests for the NEMOCITY mind: lenient parsing, salvage, fallback, mock
+grant/fix end-to-end, and the fix invalid-choice path. Async tests run via
+asyncio.run (no pytest-asyncio dependency)."""
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from mind import prompts  # noqa: E402
+from mind.backends import MockBackend  # noqa: E402
+from mind.moderation_judge import judge  # noqa: E402
+from mind.planner import FALLBACK_BLURB, Planner  # noqa: E402
+from mind.validate import BUILD_TAG, STRICT_SUFFIX, parse_build, parse_fix  # noqa: E402
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+class ScriptedBackend:
+    """Yields canned replies in order; records every (prompt, tag) it saw."""
+
+    name = "scripted"
+    model_id = "scripted-test"
+    oneshot = True
+
+    def __init__(self, replies):
+        self.replies = list(replies)
+        self.requests = []
+
+    async def generate_stream(self, prompt, grammar=None, max_tokens=700):
+        self.requests.append((prompt, grammar))
+        text = self.replies.pop(0) if self.replies else ""
+        for i in range(0, len(text), 16):
+            yield text[i : i + 16]
+
+
+class Recorder:
+    def __init__(self, observation="ok: placed"):
+        self.calls = []
+        self.observation = observation
+
+    async def act(self, payload):
+        self.calls.append(payload)
+        return self.observation
+
+
+def collector():
+    events = []
+
+    async def emit(event):
+        events.append(event)
+
+    return events, emit
+
+
+# --------------------------------------------------------------------------
+# parse_build
+# --------------------------------------------------------------------------
+
+def test_parse_build_plain():
+    raw = json.dumps({
+        "intent": "build",
+        "blurb": "A cafe for the corner.",
+        "buildings": [{"kind": "cafe", "name": "Cafe Luna", "near": "the park", "floors": 1, "hue": 35}],
+        "decline_reason": None,
+    })
+    plan, err = parse_build(raw)
+    assert err is None
+    assert plan["intent"] == "build"
+    assert plan["buildings"] == [
+        {"kind": "cafe", "name": "Cafe Luna", "near": "the park", "floors": 1, "hue": 35}
+    ]
+
+
+def test_parse_build_fences_think_and_prose():
+    raw = (
+        "<think>hmm a cafe, where though</think>\n"
+        "Sure! Here is the permit you asked for:\n"
+        "```json\n"
+        '{"intent":"build","blurb":"Done.","buildings":[{"kind":"cafe","name":"Cafe Fig"}]}\n'
+        "```\nHope that helps!"
+    )
+    plan, err = parse_build(raw)
+    assert err is None
+    assert plan["buildings"][0]["kind"] == "cafe"
+    assert plan["buildings"][0]["name"] == "Cafe Fig"
+    assert plan["buildings"][0]["near"] is None
+
+
+def test_parse_build_broken_array_salvage():
+    # Outer object truncated mid-array: the first building is still balanced.
+    raw = (
+        '{"intent":"build","blurb":"Two homes",'
+        '"buildings":[{"kind":"house","name":"Wren Cottage","near":"Elm St"},'
+        '{"kind":"house","name":"Maple'
+    )
+    plan, err = parse_build(raw)
+    assert err is None
+    assert len(plan["buildings"]) == 1
+    assert plan["buildings"][0]["name"] == "Wren Cottage"
+
+
+def test_parse_build_coerce_clip_and_drop():
+    raw = json.dumps({
+        "intent": "build",
+        "blurb": "x" * 300,
+        "buildings": [
+            {"kind": "Tower", "name": "A" * 40, "floors": "12", "hue": 35.7, "mood": "smug"},
+            {"kind": "cafe"},
+            {"kind": "shop", "floors": True},
+            {"kind": "park"},
+            {"kind": "house"},
+        ],
+    })
+    plan, err = parse_build(raw)
+    assert err is None
+    assert len(plan["blurb"]) == 140
+    assert len(plan["buildings"]) == 3  # clipped
+    first = plan["buildings"][0]
+    assert first["kind"] == "tower"
+    assert len(first["name"]) == 24
+    assert first["floors"] == 12
+    assert first["hue"] == 36
+    assert "mood" not in first
+    assert plan["buildings"][2]["floors"] is None  # bools are not floor counts
+
+
+def test_parse_build_decline():
+    plan, err = parse_build('{"intent":"decline","blurb":"","buildings":[],"decline_reason":"pure gibberish"}')
+    assert err is None
+    assert plan["intent"] == "decline"
+    assert plan["buildings"] == []
+    assert plan["decline_reason"] == "pure gibberish"
+
+
+def test_parse_build_garbage():
+    for raw in ("", "   ", "no json here at all", '{"intent":"build","buildings":[]}'):
+        plan, err = parse_build(raw)
+        assert plan is None
+        assert err
+
+
+# --------------------------------------------------------------------------
+# parse_fix
+# --------------------------------------------------------------------------
+
+def test_parse_fix_messy():
+    raw = (
+        "<think></think>The bridge is the problem.\n```\n"
+        '{"diagnosis":"Old Bridge at 3.1x capacity; F1 cuts 78 to 41.","choice":"F1","blurb":"Relief at Old Bridge."}\n```'
+    )
+    obj, err = parse_fix(raw)
+    assert err is None
+    assert obj["choice"] == "F1"
+    assert "3.1x" in obj["diagnosis"]
+
+
+def test_parse_fix_salvage_broken_outer():
+    raw = '{"diagnosis":"Index 78 on Old Bridge.","choice":"F2","blurb":"Fixing'
+    obj, err = parse_fix(raw)
+    assert err is None
+    assert obj["choice"] == "F2"
+    assert obj["diagnosis"] == "Index 78 on Old Bridge."
+
+
+def test_parse_fix_garbage():
+    obj, err = parse_fix("nothing useful")
+    assert obj is None and err
+
+
+# --------------------------------------------------------------------------
+# grant — mock end-to-end
+# --------------------------------------------------------------------------
+
+def test_mock_grant_cafe_end_to_end():
+    planner = Planner(MockBackend(delay=0.0))
+    recorder = Recorder()
+    events, emit = collector()
+    trace = run(planner.grant(
+        "a cozy cafe near the park", "Nemocity: pop 20, 14 buildings.",
+        recorder.act, emit, wish_id="w_000042",
+    ))
+
+    plans = [e for e in events if e.get("type") == "plan"]
+    assert len(plans) == 1
+    assert plans[0]["wish_id"] == "w_000042"
+    assert plans[0]["plan"]["intent"] == "build"
+
+    assert 1 <= len(recorder.calls) <= 3
+    building = recorder.calls[0]
+    assert building["kind"] == "cafe"
+    assert building["name"] and len(building["name"]) <= 24
+    assert set(building) == {"kind", "name", "near", "floors", "hue"}
+
+    assert trace["reading"] == trace["epitaph"] == trace["raw_json"]["blurb"]
+    assert trace["turns"][0]["observation"] == "ok: placed"
+    assert not trace["fallback"] and not trace["declined"]
+    assert any(e.get("type") == "thought_token" for e in events)
+
+
+def test_mock_grant_district_builds_multiple():
+    planner = Planner(MockBackend(delay=0.0))
+    recorder = Recorder()
+    events, emit = collector()
+    trace = run(planner.grant(
+        "a whole new district downtown", "Nemocity: pop 20.", recorder.act, emit,
+    ))
+    assert 2 <= len(recorder.calls) <= 3
+    assert len(trace["turns"]) == len(recorder.calls)
+    kinds = {b["kind"] for b in recorder.calls}
+    assert "apartments" in kinds
+
+
+def test_mock_grant_is_deterministic():
+    planner = Planner(MockBackend(delay=0.0))
+
+    async def grab():
+        recorder = Recorder()
+        _, emit = collector()
+        await planner.grant("a ramen shop", "pop 20", recorder.act, emit)
+        return recorder.calls
+
+    assert run(grab()) == run(grab())
+
+
+def test_grant_fallback_house_on_garbage():
+    backend = ScriptedBackend(["the model rambles with no json", "still rambling"])
+    planner = Planner(backend)
+    recorder = Recorder()
+    events, emit = collector()
+    trace = run(planner.grant("a glittering opera house", "pop 20", recorder.act, emit))
+
+    assert len(backend.requests) == 2
+    assert backend.requests[0][1] == BUILD_TAG
+    assert backend.requests[1][1] == BUILD_TAG + STRICT_SUFFIX
+    assert prompts.REASK_NOTICE in backend.requests[1][0]
+
+    assert trace["fallback"] is True
+    assert trace["epitaph"] == FALLBACK_BLURB
+    assert len(recorder.calls) == 1
+    assert recorder.calls[0]["kind"] == "house"
+    assert 0 < len(recorder.calls[0]["name"]) <= 24
+    assert [e for e in events if e.get("type") == "plan"]
+
+
+def test_grant_survives_act_failure():
+    async def bad_act(_building):
+        raise RuntimeError("engine exploded")
+
+    planner = Planner(MockBackend(delay=0.0))
+    _, emit = collector()
+    trace = run(planner.grant("a small house", "pop 20", bad_act, emit))
+    assert trace["turns"]
+    assert trace["turns"][0]["observation"].startswith("error:")
+
+
+def test_grant_survives_dead_backend():
+    class DeadBackend:
+        name = "dead"
+        model_id = "dead"
+        oneshot = True
+
+        async def generate_stream(self, prompt, grammar=None, max_tokens=700):
+            raise RuntimeError("no gpu")
+            yield ""  # pragma: no cover
+
+    planner = Planner(DeadBackend())
+    recorder = Recorder()
+    _, emit = collector()
+    trace = run(planner.grant("a park", "pop 20", recorder.act, emit))
+    assert trace["fallback"] is True
+    assert recorder.calls[0]["kind"] == "house"
+
+
+# --------------------------------------------------------------------------
+# fix
+# --------------------------------------------------------------------------
+
+_STATS = {"traffic_index": 78, "worst": "Old Bridge"}
+_CANDIDATES = [
+    {"id": "F1", "action": "new_road", "desc": "second bridge at Oak St, 7 cells", "predicted_index": 41},
+    {"id": "F2", "action": "upgrade_avenue", "desc": "widen River Rd", "predicted_index": 55},
+]
+
+
+def test_mock_fix_end_to_end():
+    planner = Planner(MockBackend(delay=0.0))
+    recorder = Recorder(observation="ok: fix applied")
+    events, emit = collector()
+    trace = run(planner.fix(_STATS, _CANDIDATES, recorder.act, emit, wish_id="w_000099"))
+
+    assert len(recorder.calls) == 1
+    fix_call = recorder.calls[0]
+    assert fix_call["choice"] == "F1"  # mock picks the best predicted index
+    assert "78" in fix_call["diagnosis"] or "41" in fix_call["diagnosis"]
+    assert len(fix_call["diagnosis"]) <= 160
+    assert len(fix_call["blurb"]) <= 120
+
+    plans = [e for e in events if e.get("type") == "plan"]
+    assert len(plans) == 1 and plans[0]["wish_id"] == "w_000099"
+    assert trace["reading"] == fix_call["diagnosis"]
+    assert trace["epitaph"] == fix_call["blurb"]
+    assert not trace["fallback"]
+
+
+def test_fix_invalid_choice_falls_back_to_best_predicted():
+    backend = ScriptedBackend(
+        ['{"diagnosis":"I choose a fix that does not exist.","choice":"F9","blurb":"Bold."}']
+    )
+    planner = Planner(backend)
+    recorder = Recorder()
+    _, emit = collector()
+    trace = run(planner.fix(_STATS, _CANDIDATES, recorder.act, emit))
+
+    assert len(backend.requests) == 1  # valid JSON, no retry needed
+    assert recorder.calls[0]["choice"] == "F1"  # lowest predicted_index
+    assert "Old Bridge" in recorder.calls[0]["diagnosis"]
+    assert trace["fallback"] is True
+
+
+def test_fix_parse_failure_falls_back():
+    backend = ScriptedBackend(["garbage", "more garbage"])
+    planner = Planner(backend)
+    recorder = Recorder()
+    _, emit = collector()
+    trace = run(planner.fix(_STATS, _CANDIDATES, recorder.act, emit))
+    assert recorder.calls[0]["choice"] == "F1"
+    assert "78" in recorder.calls[0]["diagnosis"]
+    assert trace["fallback"] is True
+
+
+# --------------------------------------------------------------------------
+# prompts + moderation
+# --------------------------------------------------------------------------
+
+def test_build_prompt_compact_single_example():
+    prompt = prompts.build_build_prompt("a ramen shop near the park", "pop 20")
+    assert prompts.PETITION_MARKER + "a ramen shop near the park" in prompt
+    assert prompt.count('"intent"') == 1  # exactly ONE example shape, no few-shot
+    assert len(prompt) < 4800  # ~1200 token prefill budget
+    for kind in ("house", "tower", "fire_station", "town_hall"):
+        assert f"- {kind}:" in prompt
+
+
+def test_fix_prompt_carries_marker_and_numbers():
+    prompt = prompts.build_fix_prompt(_STATS, _CANDIDATES)
+    assert prompts.FIX_MARKER in prompt
+    assert "(predicted index 41)" in prompt
+    assert '"traffic_index":78' in prompt
+
+
+def test_moderation_judge_mock():
+    backend = MockBackend(delay=0.0)
+    ok = run(judge("a lovely cafe by the river", backend))
+    assert ok == {"allowed": True, "category": None}
+    bad = run(judge("kill them all in the square", backend))
+    assert bad["allowed"] is False

tests/test_traffic.py

@@ -0,0 +1,167 @@
+"""Tests for the NEMOCITY Python traffic mirror (static assignment).
+
+Covers: mulberry32 cross-language equivalence (values pinned from
+web/city/rng.js via node), trip-gen determinism, A* sanity over the bridge,
+genesis bridge demand, fix candidates, the <2s perf budget, and the
+ACCEPTANCE test: genesis + 3 extra west houses jams the Old Bridge
+(demand ratio >= 1.0 at rush).
+"""
+
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from engine import constants as C
+from engine import traffic
+from engine.city import CityState
+from engine.genesis import genesis_features
+from engine.world import World
+
+NOW = C.CITY_EPOCH_S + 10_000
+BRIDGE = ((8, 0), (9, 0))
+
+
+def genesis_city() -> CityState:
+    return CityState.from_events(World.load(genesis_features()).features)
+
+
+def west_growth_world() -> World:
+    """Genesis + 3 extra west houses on 1st Ave (the acceptance scenario)."""
+    world = World.load(genesis_features())
+    for i, (cx, cz) in enumerate(((4, -1), (5, -1), (6, -1))):
+        feature, obs = world.apply(
+            "w_000001", i,
+            {"tool": "place_building", "args": {
+                "kind": "house", "name": f"West House {i + 1}", "cx": cx, "cz": cz,
+                "w": 1, "d": 1, "floors": 1, "hue": 30, "variant": i}},
+            t=C.CITY_EPOCH_S + 60,
+        )
+        assert feature is not None, obs
+    return world
+
+
+# ------------------------------------------------------------------ mulberry32
+
+
+def test_mulberry32_matches_js_reference():
+    # Pinned from web/city/rng.js (node, June 12) — byte-stable contract.
+    expected = {
+        0: (0.26642920868471265, 0.0003297457005828619, 0.22327202744781971),
+        1: (0.62707394058816135, 0.0027357211802154779, 0.52744703995995224),
+        12345: (0.97972826776094735, 0.30675226449966431, 0.484205421525985),
+        0x7FFFFFFF: (0.4290980885270983, 0.12713524978607893, 0.38527749828062952),
+    }
+    for seed, values in expected.items():
+        rng = traffic.mulberry32(seed)
+        for v in values:
+            assert rng() == v
+
+
+# -------------------------------------------------------------------- trip gen
+
+
+def test_trip_table_deterministic():
+    a = traffic.trip_table(genesis_city(), NOW)
+    b = traffic.trip_table(genesis_city(), NOW)
+    assert [(h.id, d.id) for h, d in a] == [(h.id, d.id) for h, d in b]
+    assert len(a) == 20  # one trip per genesis resident
+
+
+def test_trips_only_from_completed_buildings():
+    city = genesis_city()
+    # 1 s after epoch nothing is finished -> no homes emit commuters
+    assert traffic.trip_table(city, C.CITY_EPOCH_S + 1) == []
+
+
+# ------------------------------------------------------------------------- A*
+
+
+def test_astar_crosses_the_only_bridge():
+    city = genesis_city()
+    net = traffic.RoadNet.from_city(city)
+    west_home = next(b for b in city.buildings if b.name == "Elm Cottage")
+    factory = next(b for b in city.buildings if b.kind == "factory")
+    path = traffic._astar(net, {}, net.door(west_home), net.door(factory))
+    assert path is not None
+    assert any(cell in path for cell in BRIDGE)
+    # 4-connected, all on roads
+    for prev_cell, cell in zip(path, path[1:]):
+        assert abs(prev_cell[0] - cell[0]) + abs(prev_cell[1] - cell[1]) == 1
+        assert cell in net.cells
+
+
+def test_assignment_deterministic():
+    a1 = traffic.assign(genesis_city(), NOW)
+    a2 = traffic.assign(genesis_city(), NOW)
+    assert a1.demand == a2.demand
+    assert a1.traffic_index == a2.traffic_index
+
+
+def test_genesis_bridge_carries_demand_but_under_gate():
+    a = traffic.assign(genesis_city(), NOW)
+    ratios = [a.ratio(cell) for cell in BRIDGE]
+    assert all(r > 0 for r in ratios)
+    # the bottleneck-by-design sits NEAR the jam line but below the fix gate
+    assert all(r < C.FIX_GATE_RATIO for r in ratios)
+
+
+# ------------------------------------------------------------------ ACCEPTANCE
+
+
+def test_acceptance_west_growth_jams_old_bridge():
+    city = CityState.from_events(west_growth_world().features)
+    a = traffic.assign(city, NOW)
+    assert max(a.ratio(cell) for cell in BRIDGE) >= C.JAM_RATIO
+
+
+# ------------------------------------------------------------------ candidates
+
+
+def test_snapshot_stats_and_candidates():
+    city = CityState.from_events(west_growth_world().features)
+    stats, candidates = traffic.snapshot(city, NOW)
+    assert stats["max_ratio"] >= C.FIX_GATE_RATIO
+    assert stats["worst"] and stats["top"]
+    assert all(t["street"] for t in stats["top"])
+    assert 2 <= len(candidates) <= 4
+    current = stats["traffic_index"]
+    for i, cand in enumerate(candidates):
+        assert cand["id"] == f"F{i + 1}"
+        assert cand["action"] in ("new_road", "upgrade_avenue")
+        assert cand["cells"] and cand["klass"] in C.ROAD_CLASSES
+        assert cand["desc"]
+        assert cand["predicted_index"] < current  # every fix actually helps
+    # best predicted first (F1 is the engine fallback choice)
+    predicted = [cand["predicted_index"] for cand in candidates]
+    assert predicted == sorted(predicted)
+
+
+def test_candidate_apply_improves_assignment():
+    city = CityState.from_events(west_growth_world().features)
+    base = traffic.assign(city, NOW)
+    _, candidates = traffic.snapshot(city, NOW)
+    fixed = traffic.assign(city, NOW, candidates[0])
+    assert fixed.traffic_index < base.traffic_index
+    assert fixed.traffic_index == candidates[0]["predicted_index"]
+
+
+def test_upgrade_candidate_repaints_in_place():
+    city = CityState.from_events(west_growth_world().features)
+    _, candidates = traffic.snapshot(city, NOW)
+    upgrades = [c for c in candidates if c["action"] == "upgrade_avenue"]
+    for cand in upgrades:
+        for cx, cz in cand["cells"]:
+            assert (cx, cz) in city.roads
+            assert city.roads[(cx, cz)].klass == "street"
+
+
+# ------------------------------------------------------------------------ perf
+
+
+def test_snapshot_under_two_seconds():
+    city = CityState.from_events(west_growth_world().features)
+    started = time.perf_counter()
+    traffic.snapshot(city, NOW)
+    assert time.perf_counter() - started < 2.0

tools/gen_web.py

@@ -0,0 +1,110 @@
+"""Generate web/city/constants.js + web/mock/world.json from engine constants
+and genesis — the ONE source of truth crossing the Python/JS boundary.
+
+Run from the repo root (the integrator runs this; output is deterministic, no
+timestamps):
+
+    python tools/gen_web.py
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from engine import constants as C  # noqa: E402
+from engine.genesis import genesis_features  # noqa: E402
+
+
+def _js(value) -> str:
+    return json.dumps(value, indent=2, sort_keys=False)
+
+
+def constants_js() -> str:
+    buildings = {
+        kind: {
+            "w": spec["w"], "d": spec["d"],
+            "floors": list(spec["floors"]),
+            "residents": spec["residents"], "jobs": spec["jobs"],
+            "attract": spec["attract"],
+            # both spellings: engine uses duration_s, the JS kit reads duration
+            "duration": spec["duration_s"], "duration_s": spec["duration_s"],
+        }
+        for kind, spec in C.BUILDINGS.items()
+    }
+    durations = {kind: spec["duration_s"] for kind, spec in C.BUILDINGS.items()}
+    parts = [
+        "// GENERATED by tools/gen_web.py from engine/constants.py — do not edit.",
+        "// Values are the ARCHITECTURE.md contract; regenerate, never hand-tune.",
+        "",
+        f"export const GRID = {C.GRID};",
+        f"export const CELL = {C.CELL};",
+        f"export const COORD_MIN = {C.COORD_MIN};",
+        f"export const COORD_MAX = {C.COORD_MAX};",
+        f"export const CITY_EPOCH_S = {C.CITY_EPOCH_S};",
+        f"export const DAY_S = {C.DAY_S};",
+        "",
+        "export function riverCols(cz) {",
+        "  return cz <= -5 ? [7, 8] : cz <= 3 ? [8, 9] : [9, 10];",
+        "}",
+        "",
+        f"export const BUILDINGS = {_js(buildings)};",
+        "",
+        f"export const ROAD_CLASSES = {_js(C.ROAD_CLASSES)};",
+        f"export const ROAD_DURATION_S = {C.ROAD_DURATION_S};",
+        f"export const DURATIONS = {_js(durations)};",
+        f"export const SYNONYMS = {_js(C.SYNONYMS)};",
+        f"export const STREET_NAMES = {_js(list(C.STREET_NAMES))};",
+        "",
+        "// traffic (mirrors engine/traffic.py — the Python side owns the facts)",
+        f"export const RUSH_HOURS = {_js(list(C.RUSH_HOURS))};",
+        f"export const RUSH_SIGMA = {C.RUSH_SIGMA};",
+        f"export const RUSH_BASE = {C.RUSH_BASE};",
+        f"export const RUSH_AMP = {C.RUSH_AMP};",
+        f"export const CAR_RATE = {C.CAR_RATE};",
+        f"export const CAR_MIN = {C.CAR_MIN};",
+        f"export const CAR_MAX = {C.CAR_MAX};",
+        f"export const CITIZENS_PER_POP = {C.CITIZENS_PER_POP};",
+        f"export const CITIZENS_MIN = {C.CITIZENS_MIN};",
+        f"export const CITIZENS_MAX = {C.CITIZENS_MAX};",
+        f"export const EMA_TAU_S = {C.EMA_TAU_S};",
+        f"export const TRIP_ATTRACT_FACTOR = {C.TRIP_ATTRACT_FACTOR};",
+        f"export const TRIP_DIST_EXP = {C.TRIP_DIST_EXP};",
+        f"export const DEMAND_PER_COMMUTER = {C.DEMAND_PER_COMMUTER};",
+        f"export const CONGESTION_COST_FACTOR = {C.CONGESTION_COST_FACTOR};",
+        f"export const TRAFFIC_TOP_CELLS = {C.TRAFFIC_TOP_CELLS};",
+        f"export const JAM_RATIO = {C.JAM_RATIO};",
+        f"export const GROWTH_RADIUS_MIN = {C.GROWTH_RADIUS_MIN};",
+        "",
+    ]
+    return "\n".join(parts)
+
+
+def world_json() -> str:
+    features = genesis_features()
+    payload = {
+        "world": {
+            "version": len(features),
+            "epoch": 0,
+            "features": features,
+        }
+    }
+    return json.dumps(payload, indent=2) + "\n"
+
+
+def main() -> None:
+    constants_path = ROOT / "web" / "city" / "constants.js"
+    world_path = ROOT / "web" / "mock" / "world.json"
+    world_path.parent.mkdir(parents=True, exist_ok=True)
+    constants_path.write_text(constants_js(), encoding="utf-8")
+    world_path.write_text(world_json(), encoding="utf-8")
+    print(f"wrote {constants_path.relative_to(ROOT)}")
+    print(f"wrote {world_path.relative_to(ROOT)}")
+
+
+if __name__ == "__main__":
+    main()

tools/shot.mjs

@@ -0,0 +1,163 @@
+// NEMOCITY — headless screenshot harness (the screenshot-and-LOOK loop).
+// Serves web/ itself on a free port (8200-8299), drives the mock city through
+// deterministic seeks (?mock=1&t=<simTime> fixes the shared clock), and saves
+// shots to tools/shots/.
+//
+//   node tools/shot.mjs                       # full suite
+//   node tools/shot.mjs --god-night --street  # subset
+//   node tools/shot.mjs --base http://localhost:8123
+//
+// Playwright resolves from this repo's node_modules if installed, else from
+// the glassblower checkout next door (shares its browser cache).
+import { mkdirSync } from "node:fs";
+import { createServer } from "node:net";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const WEB = path.join(HERE, "..", "web");
+const OUT = path.join(HERE, "shots");
+mkdirSync(OUT, { recursive: true });
+
+const FLAGS = ["--god-day", "--god-night", "--street", "--heatmap", "--construction"];
+const argv = process.argv.slice(2);
+const baseIdx = argv.indexOf("--base");
+let BASE = baseIdx > -1 ? argv[baseIdx + 1] : null;
+const chosen = new Set(argv.filter((a) => FLAGS.includes(a)));
+const want = (k) => chosen.size === 0 || chosen.has(k);
+
+async function loadPlaywright() {
+  try {
+    return await import("playwright");
+  } catch {
+    const fallback = path.resolve(HERE, "../../glassblower/node_modules/playwright/index.mjs");
+    return import(`file://${fallback}`);
+  }
+}
+
+function freePort(start = 8200, end = 8299) {
+  return new Promise((resolve, reject) => {
+    const tryPort = (p) => {
+      if (p > end) return reject(new Error("no free port in 8200-8299"));
+      const srv = createServer();
+      srv.once("error", () => tryPort(p + 1));
+      srv.once("listening", () => srv.close(() => resolve(p)));
+      srv.listen(p, "127.0.0.1");
+    };
+    tryPort(start);
+  });
+}
+
+let server = null;
+if (!BASE) {
+  const port = await freePort();
+  server = spawn("python3", ["-m", "http.server", String(port), "--directory", WEB], {
+    stdio: "ignore",
+  });
+  BASE = `http://127.0.0.1:${port}`;
+  await new Promise((r) => setTimeout(r, 900)); // let it bind
+}
+const cleanup = () => { if (server) { server.kill(); server = null; } };
+process.on("exit", cleanup);
+process.on("SIGINT", () => { cleanup(); process.exit(130); });
+
+const { chromium } = await loadPlaywright();
+const browser = await chromium.launch({
+  headless: true,
+  args: [
+    "--enable-unsafe-swiftshader",
+    "--use-gl=angle",
+    "--use-angle=swiftshader",
+    "--ignore-gpu-blocklist",
+    "--enable-webgl",
+  ],
+});
+
+const page = await browser.newPage({ viewport: { width: 1512, height: 945 }, deviceScaleFactor: 2 });
+const errors = [];
+page.on("console", (m) => { if (m.type() === "error") errors.push("console: " + m.text()); });
+page.on("pageerror", (e) => errors.push("pageerror: " + e.message));
+
+async function open(url) {
+  console.log("->", url);
+  await page.goto(`${BASE}/${url}`, { waitUntil: "networkidle", timeout: 45000 });
+  await page.waitForFunction(() => window.__app && window.__app.ready, { timeout: 30000 });
+  await page.evaluate(() => window.__app.pause(true));
+  await page.evaluate(async () => { if (document.fonts?.ready) await document.fonts.ready; });
+}
+
+async function shot(name) {
+  await page.screenshot({ path: path.join(OUT, name) });
+  const s = await page.evaluate(() => window.__app.stats());
+  console.log(`  shot ${name}  simTime=${s.simTime} calls=${s.calls ?? "?"} tris=${s.triangles ?? "?"} epoch=${s.epoch}`);
+}
+
+// ------------------------------------------------------------------ suite
+// Day page: t=78 -> 07:48, morning rush + low golden sun. The welcome build
+// (Cafe Luna) starts at t0+4 and its delta lands ~t0+7.7 — tick past it so a
+// construction site is alive in the god view.
+const needDayPage = want("--god-day") || want("--heatmap") || want("--construction") || want("--street");
+if (needDayPage) {
+  await open("index.html?mock=1&t=78");
+  await page.evaluate(() => window.__app.tick(14));
+  if (want("--god-day")) await shot("god-day.png");
+
+  if (want("--heatmap")) {
+    await page.evaluate(() => { window.__app.setHeatmap(true); window.__app.tick(3); });
+    await shot("heatmap.png");
+    await page.evaluate(() => { window.__app.setHeatmap(false); window.__app.tick(0.5); });
+  }
+
+  if (want("--construction")) {
+    // apartments script (5 floors -> scaffold + crane), framed close mid-rise
+    await page.evaluate(() => {
+      window.__app.runScript(1); // Elm Court, anchor (1,-8) 2x2
+      window.__app.tick(6);      // through plan + world_delta
+      window.__app.gazeCell(2, -7, 30);
+      window.__app.tick(9);      // floors rising (45 s build)
+    });
+    await shot("construction.png");
+  }
+
+  if (want("--street")) {
+    // low camera down Main St (x=2). Manual override LAST on this page — it
+    // bypasses the rig, so no further rig-driven shots afterwards.
+    await page.evaluate(() => {
+      const a = window.__app.app;
+      window.__app.pause(true);
+      if (a.rig?.streetView) {
+        a.rig.streetView();
+        window.__app.tick(0.5);
+      } else if (a.camera) {
+        a.camera.position.set(2, 5, 60);
+        a.camera.lookAt(2, 2, -20);
+        a.renderOnce?.();
+      } else {
+        console.warn("street shot: no rig.streetView or app.camera exposed");
+      }
+    });
+    await shot("street.png");
+  }
+}
+
+// Night page: t=206 + tick(8) -> 21:24. Lamps, window glow, and the welcome
+// construction site lit in orange.
+if (want("--god-night")) {
+  await open("index.html?mock=1&t=206");
+  await page.evaluate(() => window.__app.tick(8));
+  await shot("god-night.png");
+}
+
+// ------------------------------------------------------------------ wrap
+if (errors.length) {
+  console.log("\npage errors:");
+  for (const e of errors.slice(0, 25)) console.log("   " + e);
+  process.exitCode = 1;
+} else {
+  console.log("\nno page errors");
+}
+
+await browser.close();
+cleanup();
+console.log("done ->", OUT);

web/city/buildings.js

@@ -0,0 +1,827 @@
+// NEMOCITY — the procedural building kit. 19 kinds assembled from shared
+// part-archetype pools: ONE InstancedMesh per geometry archetype citywide
+// (box / gable prism / cylinder / cone / dome) + ONE global emissive window
+// pool + ONE emissive sign pool. Per-instance color carries the facade/roof
+// palette with seeded jitter; whole city stays ~7 draw calls for buildings.
+//
+// Rise convention (construction.js drives, buildings.js owns the meshes):
+// buildings.add() builds the FINISHED building at add time. construction.js
+// masks it via setRise(id, yScale, floorsShown): solid parts + facade sign
+// quads squash vertically (positions and Y-scales * yScale, ground-anchored);
+// windows keep their FINAL matrices and are gated per floor by the aOn
+// attribute (floor < floorsShown). setFinishGlow(id, k, intensity) sweeps the
+// bottom-to-top window light-up at finish via the aBoost attribute.
+//
+// Night windows: pure in-shader stagger — uniform uDaylight (set every frame
+// from update(dt, simTime, daylight); falls back to city.daylightValue) vs a
+// per-instance hash threshold, so windows pop on across dusk with zero CPU.
+import * as THREE from "three";
+import { mulberry32 } from "./rng.js";
+import { CELL, BUILDINGS } from "./constants.js";
+import { PALETTE, FACADES, CIVIC_KINDS, ROOFS, EMISSIVE } from "./palette.js";
+import { clamp, hsl } from "./util.js";
+
+const FLOOR_H = 3;          // m per floor (contract: floors*3)
+const MARGIN = 0.8;         // footprint inset: body = w*CELL - MARGIN
+const WIN_GLOW = new THREE.Color(EMISSIVE.window);
+
+const _m4 = new THREE.Matrix4();
+const _p = new THREE.Vector3();
+const _q = new THREE.Quaternion();
+const _e = new THREE.Euler();
+const _s = new THREE.Vector3();
+const _c = new THREE.Color();
+const _c2 = new THREE.Color();
+
+// ---- instance pools --------------------------------------------------------
+// Grow-in-chunks InstancedMesh wrapper. Freed slots collapse to zero scale and
+// recycle; stored indices stay valid across growth. Dirty-range tracking keeps
+// per-frame uploads to the written span (flush() runs from Buildings.update).
+class Pool {
+  constructor(scene, baseGeo, material, capacity, { shadows = true, extra = null } = {}) {
+    this.scene = scene;
+    this.baseGeo = baseGeo;
+    this.material = material;
+    this.shadows = shadows;
+    this.extraDefs = extra || {};
+    this.top = 0;
+    this.free = [];
+    this.dirty = null; // [min, max] instance index span written this frame
+    this._build(capacity);
+  }
+
+  _build(capacity) {
+    const geo = this.baseGeo.clone();
+    this.extra = {};
+    for (const [name, size] of Object.entries(this.extraDefs)) {
+      const attr = new THREE.InstancedBufferAttribute(new Float32Array(capacity * size), size);
+      attr.setUsage(THREE.DynamicDrawUsage);
+      geo.setAttribute(name, attr);
+      this.extra[name] = attr;
+    }
+    const mesh = new THREE.InstancedMesh(geo, this.material, capacity);
+    mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+    mesh.instanceColor = new THREE.InstancedBufferAttribute(new Float32Array(capacity * 3).fill(1), 3);
+    mesh.count = this.top;
+    mesh.frustumCulled = false;
+    mesh.castShadow = this.shadows;
+    mesh.receiveShadow = this.shadows;
+    mesh.matrixAutoUpdate = false;
+    this.mesh = mesh;
+    this.geo = geo;
+    this.capacity = capacity;
+    this.scene.add(mesh);
+  }
+
+  _grow() {
+    const old = this.mesh, oldExtra = this.extra, oldGeo = this.geo;
+    this._build(this.capacity * 2);
+    this.mesh.instanceMatrix.array.set(old.instanceMatrix.array);
+    this.mesh.instanceColor.array.set(old.instanceColor.array);
+    for (const name of Object.keys(this.extraDefs)) this.extra[name].array.set(oldExtra[name].array);
+    this.mesh.instanceMatrix.needsUpdate = true;
+    this.mesh.instanceColor.needsUpdate = true;
+    for (const name of Object.keys(this.extraDefs)) this.extra[name].needsUpdate = true;
+    this.scene.remove(old);
+    old.dispose();
+    oldGeo.dispose();
+  }
+
+  alloc() {
+    let i = this.free.length ? this.free.pop() : -1;
+    if (i < 0) {
+      if (this.top >= this.capacity) this._grow();
+      i = this.top++;
+      this.mesh.count = this.top;
+    }
+    return i;
+  }
+
+  release(i) {
+    _m4.makeScale(0, 0, 0).setPosition(0, -10, 0);
+    this.setMatrix(i, _m4);
+    this.free.push(i);
+  }
+
+  setMatrix(i, m) {
+    this.mesh.setMatrixAt(i, m);
+    this._mark(i);
+  }
+
+  setColor(i, color) {
+    this.mesh.instanceColor.setXYZ(i, color.r, color.g, color.b);
+    this.mesh.instanceColor.needsUpdate = true;
+  }
+
+  setExtra(name, i, v) {
+    this.extra[name].setX(i, v);
+    this.extra[name].needsUpdate = true; // small attrs: full upload is cheap
+  }
+
+  _mark(i) {
+    if (!this.dirty) this.dirty = [i, i];
+    else {
+      if (i < this.dirty[0]) this.dirty[0] = i;
+      if (i > this.dirty[1]) this.dirty[1] = i;
+    }
+  }
+
+  flush() {
+    if (!this.dirty) return;
+    const attr = this.mesh.instanceMatrix;
+    attr.clearUpdateRanges();
+    attr.addUpdateRange(this.dirty[0] * 16, (this.dirty[1] - this.dirty[0] + 1) * 16);
+    attr.needsUpdate = true;
+    this.dirty = null;
+  }
+
+  dispose() {
+    this.scene.remove(this.mesh);
+    this.mesh.dispose();
+    this.geo.dispose();
+  }
+}
+
+// ---- archetype geometries (all solid geos ground-anchored: y in [0, 1]) ----
+function gablePrismGeo() {
+  // ridge along X, base 1x1, apex y=1; duplicated verts for flat shading
+  const v = [];
+  const quad = (a, b, c, d) => v.push(...a, ...c, ...b, ...a, ...d, ...c); // CCW outward
+  quad([-0.5, 0, -0.5], [0.5, 0, -0.5], [0.5, 1, 0], [-0.5, 1, 0]);   // north slope
+  quad([0.5, 0, 0.5], [-0.5, 0, 0.5], [-0.5, 1, 0], [0.5, 1, 0]);     // south slope
+  v.push(0.5, 0, -0.5, 0.5, 1, 0, 0.5, 0, 0.5);                       // east gable
+  v.push(-0.5, 0, 0.5, -0.5, 1, 0, -0.5, 0, -0.5);                    // west gable
+  const geo = new THREE.BufferGeometry();
+  geo.setAttribute("position", new THREE.Float32BufferAttribute(v, 3));
+  geo.computeVertexNormals();
+  return geo;
+}
+
+// emissive window/sign quads share fog handling with ground.js's water shader
+function windowMaterial() {
+  return new THREE.ShaderMaterial({
+    fog: true,
+    uniforms: THREE.UniformsUtils.merge([THREE.UniformsLib.fog, { uDaylight: { value: 1 } }]),
+    vertexShader: /* glsl */ `
+      attribute float aHash;
+      attribute float aOn;
+      attribute float aBoost;
+      varying float vHash, vOn, vBoost;
+      #include <common>
+      #include <fog_pars_vertex>
+      void main() {
+        vHash = aHash; vOn = aOn; vBoost = aBoost;
+        #ifdef USE_INSTANCING
+        vec4 wp = modelMatrix * instanceMatrix * vec4(position, 1.0);
+        #else
+        vec4 wp = modelMatrix * vec4(position, 1.0);
+        #endif
+        vec4 mvPosition = viewMatrix * wp;
+        gl_Position = projectionMatrix * mvPosition;
+        #include <fog_vertex>
+      }`,
+    fragmentShader: /* glsl */ `
+      #include <common>
+      #include <fog_pars_fragment>
+      uniform float uDaylight;
+      varying float vHash, vOn, vBoost;
+      void main() {
+        if (vOn < 0.5 && vBoost <= 0.01) discard;
+        float night = 1.0 - uDaylight;
+        // dusk stagger: each window pops when night passes its hash threshold
+        // (aHash 2.0 = a permanently dark window)
+        float lit = vOn * smoothstep(vHash, vHash + 0.05, night);
+        float m = max(lit, vBoost);
+        vec3 day = vec3(0.16, 0.19, 0.23) * mix(1.0, 0.35, night); // dark glass
+        vec3 glow = vec3(1.0, 0.788, 0.478) * (1.4 + 0.7 * fract(vHash * 7.91));
+        gl_FragColor = vec4(mix(day, glow, m), 1.0);
+        #include <fog_fragment>
+      }`,
+  });
+}
+
+function signMaterial() {
+  return new THREE.ShaderMaterial({
+    fog: true,
+    side: THREE.DoubleSide,
+    uniforms: THREE.UniformsUtils.merge([THREE.UniformsLib.fog, { uDaylight: { value: 1 } }]),
+    vertexShader: /* glsl */ `
+      attribute float aDay;
+      attribute float aNight;
+      varying float vDay, vNight;
+      varying vec3 vColor;
+      #include <common>
+      #include <fog_pars_vertex>
+      void main() {
+        vDay = aDay; vNight = aNight;
+        vColor = vec3(1.0);
+        #ifdef USE_INSTANCING_COLOR
+        vColor = instanceColor;
+        #endif
+        #ifdef USE_INSTANCING
+        vec4 wp = modelMatrix * instanceMatrix * vec4(position, 1.0);
+        #else
+        vec4 wp = modelMatrix * vec4(position, 1.0);
+        #endif
+        vec4 mvPosition = viewMatrix * wp;
+        gl_Position = projectionMatrix * mvPosition;
+        #include <fog_vertex>
+      }`,
+    fragmentShader: /* glsl */ `
+      #include <common>
+      #include <fog_pars_fragment>
+      uniform float uDaylight;
+      varying float vDay, vNight;
+      varying vec3 vColor;
+      void main() {
+        float night = smoothstep(0.25, 0.75, 1.0 - uDaylight);
+        gl_FragColor = vec4(vColor * mix(vDay, vNight, night), 1.0);
+        #include <fog_fragment>
+      }`,
+  });
+}
+
+// ---- Buildings -------------------------------------------------------------
+export class Buildings {
+  constructor(scene, quality, city = null) {
+    this.scene = scene;
+    this.quality = quality || { instances: 1 };
+    this.city = city;
+    this.items = new Map(); // id -> record
+    this._daylight = 1;
+
+    const solid = new THREE.MeshStandardMaterial({
+      roughness: 0.85, metalness: 0, envMapIntensity: 0.25,
+    });
+    this.pools = {
+      box: new Pool(scene, new THREE.BoxGeometry(1, 1, 1).translate(0, 0.5, 0), solid, 1024),
+      gable: new Pool(scene, gablePrismGeo(), solid, 256),
+      cyl: new Pool(scene, new THREE.CylinderGeometry(0.5, 0.5, 1, 10).translate(0, 0.5, 0), solid, 512),
+      cone: new Pool(scene, new THREE.ConeGeometry(0.5, 1, 7).translate(0, 0.5, 0), solid, 512),
+      dome: new Pool(scene, new THREE.SphereGeometry(0.5, 12, 6, 0, Math.PI * 2, 0, Math.PI / 2), solid, 16),
+      win: new Pool(scene, new THREE.PlaneGeometry(1, 1), windowMaterial(), 2048,
+        { shadows: false, extra: { aHash: 1, aOn: 1, aBoost: 1 } }),
+      sign: new Pool(scene, new THREE.PlaneGeometry(1, 1), signMaterial(), 256,
+        { shadows: false, extra: { aDay: 1, aNight: 1 } }),
+    };
+  }
+
+  /** Footprint/height info for construction.js. */
+  getInfo(id) {
+    const r = this.items.get(id);
+    if (!r) return null;
+    return { x: r.x, z: r.z, W: r.W, D: r.D, kind: r.kind, floors: r.floors, height: r.height };
+  }
+
+  /** world.js skeleton calls addFeature(f, opts); keep both names. */
+  addFeature(f) { return this.add(f); }
+
+  add(f) {
+    if (!f || f.tool !== "place_building" || !f.args || this.items.has(f.id)) return;
+    const a = f.args;
+    const spec = BUILDINGS[a.kind] || BUILDINGS.house;
+    const kind = BUILDINGS[a.kind] ? a.kind : "house";
+    const w = a.w ?? spec.w, d = a.d ?? spec.d;
+    const floors = clamp(a.floors ?? Math.round((spec.floors[0] + spec.floors[1]) / 2),
+      spec.floors[0], spec.floors[1]);
+    const variant = a.variant ?? 0;
+    const rng = mulberry32(((f.seed ?? 1) ^ Math.imul(variant, 0x9e3779b9)) >>> 0);
+
+    const rec = {
+      id: f.id, kind, floors,
+      x: a.cx * CELL + (w * CELL) / 2, z: a.cz * CELL + (d * CELL) / 2,
+      W: w * CELL - MARGIN, D: d * CELL - MARGIN,
+      height: Math.max(1, floors) * FLOOR_H,
+      parts: [],    // { pool, idx, x, y, z, sx, sy, sz, rx, ry, rz } — y squashes
+      windows: [],  // { idx, floor, yFrac } — fixed matrices, aOn/aBoost gated
+      yScale: 1, floorsShown: floors,
+      blob: null,
+    };
+
+    // facade + roof colors, seeded jitter +-6deg hue +-5% lightness
+    if (CIVIC_KINDS.includes(kind)) _c.set(PALETTE.civic);
+    else if (kind === "fire_station") _c.set("#BD6B6E");
+    else if (a.hue != null) hsl(a.hue, 0.42, 0.72, _c);
+    else _c.set(FACADES[Math.floor(rng() * FACADES.length)]);
+    _c.offsetHSL((rng() * 2 - 1) * (6 / 360), 0, (rng() * 2 - 1) * 0.05);
+    const facade = _c.clone();
+    _c2.set(ROOFS[kind] || "#D9D5CB").offsetHSL(0, 0, (rng() * 2 - 1) * 0.03);
+    const roof = _c2.clone();
+
+    const builder = KIND_BUILDERS[kind] || KIND_BUILDERS.house;
+    builder(this, rec, rng, facade, roof);
+
+    if (this.city && this.city.ground && this.city.ground.addBlob) {
+      rec.blob = this.city.ground.addBlob(rec.x, rec.z, Math.max(w, d) * CELL * 1.25, 0.22);
+    }
+    this.items.set(f.id, rec);
+    this._writeMatrices(rec);
+  }
+
+  remove(id) {
+    const r = this.items.get(id);
+    if (!r) return;
+    for (const p of r.parts) p.pool.release(p.idx);
+    for (const wn of r.windows) this.pools.win.release(wn.idx);
+    if (r.blob) r.blob.release();
+    this.items.delete(id);
+  }
+
+  reset() {
+    for (const id of [...this.items.keys()]) this.remove(id);
+  }
+
+  /**
+   * Construction mask. yScale in [0, ~1.1] (easeOutBack may overshoot),
+   * floorsShown = completed floors whose windows show at FINAL positions.
+   */
+  setRise(id, yScale, floorsShown) {
+    const r = this.items.get(id);
+    if (!r) return;
+    r.yScale = Math.max(0, yScale);
+    this._writeMatrices(r);
+    if (floorsShown !== r.floorsShown) {
+      r.floorsShown = floorsShown;
+      for (const wn of r.windows) {
+        this.pools.win.setExtra("aOn", wn.idx, wn.floor < floorsShown ? 1 : 0);
+      }
+    }
+  }
+
+  /**
+   * Finish beat: windows light bottom-to-top. k in [0,1] = sweep position,
+   * intensity fades the celebration glow back to normal night behavior;
+   * intensity 0 clears.
+   */
+  setFinishGlow(id, k, intensity = 1) {
+    const r = this.items.get(id);
+    if (!r) return;
+    for (const wn of r.windows) {
+      const b = intensity * clamp((k - wn.yFrac + 0.06) / 0.12, 0, 1);
+      this.pools.win.setExtra("aBoost", wn.idx, b);
+    }
+  }
+
+  update(dt, simTime, daylight) {
+    this._daylight = daylight ?? (this.city ? this.city.daylightValue : this._daylight);
+    this.pools.win.material.uniforms.uDaylight.value = this._daylight;
+    this.pools.sign.material.uniforms.uDaylight.value = this._daylight;
+    for (const pool of Object.values(this.pools)) pool.flush();
+  }
+
+  // ---- internals -----------------------------------------------------------
+  _writeMatrices(r) {
+    const k = r.yScale;
+    for (const p of r.parts) {
+      _p.set(p.x, p.y * k, p.z);
+      _e.set(p.rx, p.ry, p.rz);
+      _q.setFromEuler(_e);
+      _s.set(p.sx, Math.max(p.sy * k, 0.0001), p.sz);
+      _m4.compose(_p, _q, _s);
+      p.pool.setMatrix(p.idx, _m4);
+    }
+  }
+
+  /** Solid/sign part; ground-anchored, vertically squashed by setRise. */
+  _part(r, poolName, color, x, y, z, sx, sy, sz, ry = 0, rx = 0, rz = 0, extra = null) {
+    const pool = this.pools[poolName];
+    const idx = pool.alloc();
+    pool.setColor(idx, color);
+    if (extra) for (const [name, v] of Object.entries(extra)) pool.setExtra(name, idx, v);
+    r.parts.push({ pool, idx, x, y, z, sx, sy, sz, rx, ry, rz });
+  }
+
+  /** One window quad at its FINAL spot (never squashed; aOn gates per floor). */
+  _window(r, rng, x, y, z, ry, wW, wH, floor, yFrac) {
+    const pool = this.pools.win;
+    const idx = pool.alloc();
+    _p.set(x, y, z);
+    _e.set(0, ry, 0);
+    _q.setFromEuler(_e);
+    _s.set(wW, wH, 1);
+    _m4.compose(_p, _q, _s);
+    pool.setMatrix(idx, _m4);
+    pool.setExtra("aHash", idx, rng() < 0.15 ? 2.0 : rng());
+    pool.setExtra("aOn", idx, 1);
+    pool.setExtra("aBoost", idx, 0);
+    r.windows.push({ idx, floor, yFrac });
+  }
+
+  /** Window grids on the 4 facades of a box spanning [floor0, floor0+floors). */
+  _windowsBox(r, rng, xc, zc, W, D, floor0, floors, totalFloors,
+    { density = 1, wW = 0.62, wH = 1.05, skip = 0.1 } = {}) {
+    density *= this.quality.instances ?? 1;
+    const faces = [
+      [0, D / 2 + 0.03, 0, W],            // +z
+      [0, -(D / 2 + 0.03), Math.PI, W],   // -z
+      [W / 2 + 0.03, 0, Math.PI / 2, D],  // +x
+      [-(W / 2 + 0.03), 0, -Math.PI / 2, D], // -x
+    ];
+    for (let fl = 0; fl < floors; fl++) {
+      const y = (floor0 + fl) * FLOOR_H + FLOOR_H * 0.52;
+      const yFrac = (floor0 + fl + 0.5) / Math.max(totalFloors, 1);
+      for (const [ox, oz, ry, len] of faces) {
+        const n = Math.max(1, Math.round((len / 1.8) * density));
+        for (let i = 0; i < n; i++) {
+          if (rng() < skip) continue;
+          const u = ((i + 0.5) / n - 0.5) * (len - 0.9);
+          const x = ry === 0 || ry === Math.PI ? xc + u : xc + ox;
+          const z = ry === 0 || ry === Math.PI ? zc + oz : zc + u;
+          this._window(r, rng, x, y, z, ry, wW, wH, floor0 + fl, yFrac);
+        }
+      }
+    }
+  }
+
+  /** Tree: trunk + 1-2 stacked canopy cones; casts shadow, gets a small blob. */
+  _tree(r, rng, x, z, scale = 1) {
+    const h = (1.6 + rng() * 1.3) * scale;
+    _c.set("#7A5A3C").offsetHSL(0, 0, (rng() * 2 - 1) * 0.04);
+    this._part(r, "cyl", _c, x, 0, z, 0.22 * scale, h * 0.45, 0.22 * scale);
+    _c.set(PALETTE.park).offsetHSL((rng() * 2 - 1) * 0.03, 0, (rng() * 2 - 1) * 0.06);
+    const cw = (1.3 + rng() * 0.7) * scale;
+    this._part(r, "cone", _c, x, h * 0.35, z, cw, h * 0.85, cw);
+    if (rng() < 0.5) this._part(r, "cone", _c, x, h * 0.75, z, cw * 0.7, h * 0.55, cw * 0.7);
+    if (this.city && this.city.ground && this.city.ground.addBlob) {
+      // park trees share the building record lifetime; released in remove()
+      const blob = this.city.ground.addBlob(x, z, cw * 1.1, 0.16);
+      r.parts.push({ pool: { release: () => blob.release(), setMatrix() {} }, idx: 0, x, y: 0, z, sx: 0, sy: 0, sz: 0, rx: 0, ry: 0, rz: 0, _blob: true });
+    }
+  }
+
+  _bench(r, rng, x, z, ry) {
+    _c.set("#8A6B4F").offsetHSL(0, 0, (rng() * 2 - 1) * 0.05);
+    this._part(r, "box", _c, x, 0.28, z, 1.1, 0.1, 0.4, ry);
+    this._part(r, "box", _c, x, 0, z, 1.0, 0.3, 0.32, ry);
+  }
+
+  _fountain(r, rng, x, z, scale = 1) {
+    _c.set(PALETTE.sidewalk).offsetHSL(0, 0, -0.04);
+    this._part(r, "cyl", _c, x, 0, z, 3.2 * scale, 0.5, 3.2 * scale);
+    _c.set(PALETTE.water).offsetHSL(0, 0, 0.06);
+    this._part(r, "cyl", _c, x, 0.3, z, 2.7 * scale, 0.28, 2.7 * scale);
+    _c.set(PALETTE.sidewalk);
+    this._part(r, "cyl", _c, x, 0.4, z, 0.5 * scale, 1.1 * scale, 0.5 * scale);
+  }
+}
+
+// ---- per-kind silhouettes ---------------------------------------------------
+// Each builder fills rec.parts/rec.windows via b._part/b._windowsBox. All parts
+// are positioned in WORLD space around (rec.x, rec.z); y = ground offset.
+// Signature pieces per the Visual Bible: water towers on apartments, AC
+// clusters, cafe awning + tables + neon, sawtooth + smokestack factory,
+// hospital cross, church steeple, stadium masts, town_hall dome.
+
+function bodyAndFlatRoof(b, r, facade, roof, { W = r.W, D = r.D, H = r.height, x = r.x, z = r.z } = {}) {
+  b._part(r, "box", facade, x, 0, z, W, H, D);
+  b._part(r, "box", roof, x, H, z, W + 0.25, 0.22, D + 0.25);
+}
+
+function acBoxes(b, r, rng, n, roofY, W, D) {
+  _c.set("#B9B4A8");
+  for (let i = 0; i < n; i++) {
+    b._part(r, "box", _c, r.x + (rng() - 0.5) * W * 0.55, roofY + 0.2, r.z + (rng() - 0.5) * D * 0.55,
+      0.7 + rng() * 0.5, 0.45, 0.6 + rng() * 0.4, rng() * Math.PI);
+  }
+}
+
+function neonSign(b, r, rng, x, y, z, ry, w, h) {
+  _c.set(rng() < 0.5 ? EMISSIVE.neonTeal : EMISSIVE.neonPink);
+  b._part(r, "sign", _c, x, y, z, w, h, 1, ry, 0, 0, { aDay: 0.3, aNight: 1.9 });
+}
+
+function doorQuad(b, r, x, y, z, ry, w, h) {
+  _c.set("#4A4038");
+  b._part(r, "sign", _c, x, y, z, w, h, 1, ry, 0, 0, { aDay: 1.0, aNight: 0.7 });
+}
+
+const KIND_BUILDERS = {
+  house(b, r, rng, facade, roof) {
+    const H = r.height;
+    b._part(r, "box", facade, r.x, 0, r.z, r.W, H, r.D);
+    const ry = rng() < 0.5 ? 0 : Math.PI / 2;
+    b._part(r, "gable", roof, r.x, H, r.z, (ry ? r.D : r.W) + 0.4, 1.3, (ry ? r.W : r.D) + 0.4, ry);
+    _c.set("#6E5546");
+    b._part(r, "box", _c, r.x + r.W * 0.28, H + 0.5, r.z - r.D * 0.2, 0.4, 1.3, 0.4); // chimney
+    doorQuad(b, r, r.x, 1.05, r.z + r.D / 2 + 0.03, 0, 0.9, 2.1);
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 0, r.floors, r.floors, { density: 0.8 });
+    if (rng() < 0.4) b._tree(r, rng, r.x - r.W * 0.62 - 0.6, r.z + r.D * 0.4, 0.7);
+  },
+
+  townhouse(b, r, rng, facade, roof) {
+    const W = r.W * 0.88, H = r.height;
+    b._part(r, "box", facade, r.x, 0, r.z, W, H, r.D);
+    b._part(r, "gable", roof, r.x, H, r.z, r.D + 0.4, 1.5, W + 0.3, Math.PI / 2);
+    _c.set("#6E5546");
+    b._part(r, "box", _c, r.x - W * 0.25, H + 0.7, r.z, 0.35, 1.4, 0.35);
+    _c.copy(facade).offsetHSL(0, 0, -0.12);
+    b._part(r, "box", _c, r.x, 0, r.z + r.D / 2 + 0.3, 1.3, 0.45, 0.8); // stoop
+    doorQuad(b, r, r.x, 1.1, r.z + r.D / 2 + 0.03, 0, 0.85, 2.1);
+    b._windowsBox(r, rng, r.x, r.z, W, r.D, 0, r.floors, r.floors, { density: 0.8, wH: 1.25 });
+  },
+
+  apartments(b, r, rng, facade, roof) {
+    const H = r.height;
+    bodyAndFlatRoof(b, r, facade, roof);
+    // water tower: 4 legs + tank + cone cap
+    const tx = r.x + r.W * 0.22, tz = r.z - r.D * 0.22;
+    _c.set("#5C5247");
+    for (const [lx, lz] of [[-0.5, -0.5], [0.5, -0.5], [-0.5, 0.5], [0.5, 0.5]]) {
+      b._part(r, "box", _c, tx + lx * 0.9, H, tz + lz * 0.9, 0.14, 1.1, 0.14);
+    }
+    _c.set("#8A6B4F").offsetHSL(0, 0, (rng() - 0.5) * 0.06);
+    b._part(r, "cyl", _c, tx, H + 1.1, tz, 1.7, 1.5, 1.7);
+    _c.offsetHSL(0, 0, -0.1);
+    b._part(r, "cone", _c, tx, H + 2.6, tz, 1.9, 0.8, 1.9);
+    acBoxes(b, r, rng, 2, H, r.W * 0.7, r.D * 0.7);
+    // fire-escape strip: vertical rail + per-floor landings on one facade
+    _c.set("#3F454F");
+    const fx = r.x - r.W * 0.28, fz = r.z + r.D / 2 + 0.18;
+    b._part(r, "box", _c, fx, 0.4, fz, 0.1, H - 1, 0.1);
+    for (let i = 1; i < r.floors; i++) b._part(r, "box", _c, fx, i * FLOOR_H - 0.1, fz, 1.7, 0.09, 0.5);
+    doorQuad(b, r, r.x + r.W * 0.2, 1.1, r.z + r.D / 2 + 0.03, 0, 1.1, 2.2);
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 0, r.floors, r.floors);
+  },
+
+  cafe(b, r, rng, facade, roof) {
+    const H = r.height;
+    bodyAndFlatRoof(b, r, facade, roof);
+    acBoxes(b, r, rng, 1, H, r.W * 0.6, r.D * 0.6);
+    const front = r.z + r.D / 2;
+    _c.set(["#E07856", "#7FB69E", "#F2CC8F"][Math.floor(rng() * 3)]);
+    b._part(r, "box", _c, r.x, H * 0.72, front + 0.55, r.W * 0.95, 0.08, 1.3, 0, -0.42); // awning
+    doorQuad(b, r, r.x - r.W * 0.22, 1.05, front + 0.03, 0, 0.85, 2.1);
+    // big warm display window + neon sign above the awning
+    _c.set("#FFE9C2");
+    b._part(r, "sign", _c, r.x + r.W * 0.18, 1.5, front + 0.03, r.W * 0.45, 1.5, 1, 0, 0, 0, { aDay: 0.55, aNight: 1.4 });
+    neonSign(b, r, rng, r.x, H - 0.45, front + 0.06, 0, r.W * 0.7, 0.55);
+    // sidewalk tables under the awning
+    _c.set(PALETTE.sidewalk);
+    const nt = 2 + Math.floor(rng() * 2);
+    for (let i = 0; i < nt; i++) {
+      b._part(r, "cyl", _c, r.x + (rng() - 0.5) * r.W * 0.8, 0, front + 1.0 + rng() * 0.5, 0.5, 0.72, 0.5);
+    }
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 0, 1, 1, { density: 0.6 });
+  },
+
+  shop(b, r, rng, facade, roof) {
+    const H = r.height;
+    bodyAndFlatRoof(b, r, facade, roof);
+    const front = r.z + r.D / 2;
+    if (rng() < 0.6) {
+      _c.set(["#8FB8D8", "#E07856", "#A9B98A"][Math.floor(rng() * 3)]);
+      b._part(r, "box", _c, r.x, 2.5, front + 0.5, r.W * 0.9, 0.08, 1.1, 0, -0.4);
+    }
+    _c.set("#FFE9C2");
+    b._part(r, "sign", _c, r.x - r.W * 0.12, 1.45, front + 0.03, r.W * 0.55, 1.4, 1, 0, 0, 0, { aDay: 0.55, aNight: 1.35 });
+    doorQuad(b, r, r.x + r.W * 0.3, 1.0, front + 0.03, 0, 0.8, 2.0);
+    // corner sign pole with a neon blade sign
+    _c.set("#3F454F");
+    const px = r.x + r.W / 2 + 0.25, pz = front - 0.3;
+    b._part(r, "box", _c, px, 0, pz, 0.16, H + 1.4, 0.16);
+    neonSign(b, r, rng, px, H + 0.5, pz, Math.PI / 2, 1.4, 0.8);
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 1, Math.max(r.floors - 1, 0), r.floors, { density: 0.8 });
+  },
+
+  market(b, r, rng, facade, roof) {
+    const H = r.height;
+    bodyAndFlatRoof(b, r, facade, roof);
+    // stall awnings march down the long (z) side; crates by the entrance
+    const sx = r.x + r.W / 2;
+    for (let i = 0; i < 3; i++) {
+      _c.set(["#E07856", "#F2CC8F", "#7FB69E"][i % 3]).offsetHSL(0, 0, (rng() - 0.5) * 0.06);
+      b._part(r, "box", _c, sx + 0.5, H * 0.62, r.z + (i - 1) * (r.D / 3.2), 1.2, 0.08, r.D / 3.6, 0, 0, 0.42);
+    }
+    _c.set("#A98B5F");
+    for (let i = 0; i < 3; i++) {
+      b._part(r, "box", _c, r.x - r.W * 0.3 + rng() * 0.8, 0, r.z + r.D / 2 + 0.6 + rng() * 0.4, 0.55, 0.55, 0.55, rng());
+    }
+    doorQuad(b, r, r.x, 1.25, r.z + r.D / 2 + 0.03, 0, 2.2, 2.5);
+    neonSign(b, r, rng, r.x, H - 0.4, r.z + r.D / 2 + 0.06, 0, r.W * 0.55, 0.5);
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 0, 1, 1, { density: 0.5 });
+  },
+
+  bank(b, r, rng, facade, roof) {
+    const H = r.height;
+    _c.copy(facade).offsetHSL(0, 0, -0.08);
+    b._part(r, "box", _c, r.x, 0, r.z, r.W + 0.6, 0.4, r.D + 0.9); // stepped base
+    b._part(r, "box", facade, r.x, 0.4, r.z, r.W, H - 0.4, r.D);
+    b._part(r, "box", roof, r.x, H, r.z, r.W + 0.35, 0.3, r.D + 0.35); // cornice
+    const front = r.z + r.D / 2;
+    for (let i = 0; i < 4; i++) {
+      const cx = r.x + ((i / 3) - 0.5) * r.W * 0.7;
+      b._part(r, "cyl", facade, cx, 0.4, front + 0.45, 0.42, H * 0.78, 0.42);
+    }
+    _c.copy(facade).offsetHSL(0, 0, -0.05);
+    b._part(r, "gable", _c, r.x, H * 0.82, front + 0.3, r.W * 0.82, 1.1, 1.1); // pediment
+    doorQuad(b, r, r.x, 1.3, front + 0.03, 0, 1.2, 2.6);
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 1, Math.max(r.floors - 1, 0), r.floors, { density: 0.7, wH: 1.3 });
+  },
+
+  office(b, r, rng, facade, roof) {
+    const H = r.height;
+    bodyAndFlatRoof(b, r, facade, roof);
+    _c.copy(facade).offsetHSL(0, 0, -0.18);
+    b._part(r, "box", _c, r.x, 0, r.z, r.W + 0.08, FLOOR_H * 0.9, r.D + 0.08); // lobby band
+    acBoxes(b, r, rng, 2, H, r.W * 0.6, r.D * 0.6);
+    doorQuad(b, r, r.x, 1.15, r.z + r.D / 2 + 0.08, 0, 1.3, 2.3);
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 1, r.floors - 1, r.floors, { density: 1.1, wW: 0.7 });
+  },
+
+  tower(b, r, rng, facade, roof) {
+    const f1 = Math.max(2, Math.round(r.floors * 0.55));
+    const f2 = Math.max(1, Math.round(r.floors * 0.3));
+    const f3 = Math.max(0, r.floors - f1 - f2);
+    const tiers = [[0, f1, 1], [f1, f2, 0.78], f3 > 0 ? [f1 + f2, f3, 0.6] : null].filter(Boolean);
+    for (const [floor0, n, scale] of tiers) {
+      const W = r.W * scale, D = r.D * scale, y0 = floor0 * FLOOR_H, h = n * FLOOR_H;
+      b._part(r, "box", facade, r.x, y0, r.z, W, h, D);
+      b._part(r, "box", roof, r.x, y0 + h, r.z, W + 0.2, 0.22, D + 0.2);
+      b._windowsBox(r, rng, r.x, r.z, W, D, floor0, n, r.floors, { density: 1.1, wW: 0.7 });
+    }
+    _c.set("#3F454F");
+    b._part(r, "box", _c, r.x, r.height, r.z, 0.18, 2.6, 0.18); // roof mast
+    _c.set(EMISSIVE.signalRed);
+    b._part(r, "sign", _c, r.x, r.height + 2.3, r.z + 0.12, 0.3, 0.3, 1, 0, 0, 0, { aDay: 0.5, aNight: 2.2 });
+    doorQuad(b, r, r.x, 1.3, r.z + r.D / 2 + 0.03, 0, 1.6, 2.6);
+  },
+
+  school(b, r, rng, facade, roof) {
+    const H = r.height;
+    b._part(r, "box", facade, r.x, 0, r.z, r.W, H, r.D);
+    b._part(r, "gable", roof, r.x, H, r.z, r.W + 0.4, 1.6, r.D + 0.4);
+    // flagpole + little flag by the entrance
+    _c.set("#C9C4B8");
+    const px = r.x - r.W * 0.32, pz = r.z + r.D / 2 + 0.8;
+    b._part(r, "box", _c, px, 0, pz, 0.1, 5.2, 0.1);
+    _c.set(PALETTE.accent);
+    b._part(r, "sign", _c, px + 0.55, 4.6, pz, 1.0, 0.6, 1, Math.PI / 2, 0, 0, { aDay: 1.0, aNight: 0.8 });
+    doorQuad(b, r, r.x, 1.25, r.z + r.D / 2 + 0.03, 0, 1.8, 2.5);
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 0, r.floors, r.floors, { density: 1.1, wW: 0.75 });
+  },
+
+  hospital(b, r, rng, facade, roof) {
+    const H = r.height;
+    bodyAndFlatRoof(b, r, facade, roof);
+    acBoxes(b, r, rng, 3, H, r.W * 0.6, r.D * 0.6);
+    // emissive red cross above the entrance (reads in daylight too)
+    const front = r.z + r.D / 2 + 0.06;
+    _c.set(EMISSIVE.signalRed);
+    b._part(r, "sign", _c, r.x, H - 1.6, front, 0.6, 1.8, 1, 0, 0, 0, { aDay: 1.0, aNight: 2.2 });
+    b._part(r, "sign", _c, r.x, H - 1.0, front, 1.8, 0.6, 1, 0, 0, 0, { aDay: 1.0, aNight: 2.2 });
+    _c.copy(facade).offsetHSL(0, 0, -0.1);
+    b._part(r, "box", _c, r.x, 0, r.z + r.D / 2 + 0.6, 3.4, 2.8, 1.4); // entrance canopy block
+    doorQuad(b, r, r.x, 1.2, r.z + r.D / 2 + 1.34, 0, 2.2, 2.4);
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 0, r.floors, r.floors, { density: 0.9 });
+  },
+
+  fire_station(b, r, rng, facade, roof) {
+    const H = r.height;
+    bodyAndFlatRoof(b, r, facade, roof);
+    const front = r.z + r.D / 2 + 0.04;
+    _c.set("#8C857A");
+    for (const sx of [-0.25, 0.25]) {
+      b._part(r, "sign", _c, r.x + sx * r.W, 1.4, front, r.W * 0.36, 2.8, 1, 0, 0, 0, { aDay: 1.0, aNight: 1.3 });
+    }
+    // hose tower with an amber beacon
+    _c.copy(facade).offsetHSL(0, 0, -0.05);
+    const tx = r.x - r.W * 0.32, tz = r.z - r.D * 0.25;
+    b._part(r, "box", _c, tx, 0, tz, 1.5, H + 2.4, 1.5);
+    b._part(r, "box", roof, tx, H + 2.4, tz, 1.7, 0.2, 1.7);
+    _c.set(EMISSIVE.signalAmber);
+    b._part(r, "sign", _c, tx, H + 1.7, tz + 0.78, 0.5, 0.4, 1, 0, 0, 0, { aDay: 0.7, aNight: 2.0 });
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 1, Math.max(r.floors - 1, 0), r.floors, { density: 0.8 });
+  },
+
+  warehouse(b, r, rng, facade, roof) {
+    const H = Math.max(r.height, 3.6);
+    r.height = H + 1.4;
+    b._part(r, "box", facade, r.x, 0, r.z, r.W, H, r.D);
+    b._part(r, "gable", roof, r.x, H, r.z, r.W + 0.4, 1.4, r.D + 0.4);
+    _c.copy(facade).offsetHSL(0, 0, -0.12);
+    b._part(r, "box", _c, r.x, 0, r.z + r.D / 2 + 0.55, r.W * 0.7, 0.7, 1.1); // loading dock
+    _c.set("#5C5247");
+    for (const sx of [-0.22, 0.22]) {
+      b._part(r, "sign", _c, r.x + sx * r.W, 1.5, r.z + r.D / 2 + 0.03, r.W * 0.3, 2.6, 1, 0, 0, 0, { aDay: 1.0, aNight: 1.1 });
+    }
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 0, 1, 1, { density: 0.4, wH: 0.7 });
+  },
+
+  factory(b, r, rng, facade, roof) {
+    const H = r.height;
+    b._part(r, "box", facade, r.x, 0, r.z, r.W, H, r.D);
+    // sawtooth roofline: a row of narrow gable prisms along x
+    const n = 4;
+    for (let i = 0; i < n; i++) {
+      b._part(r, "gable", roof, r.x + ((i + 0.5) / n - 0.5) * r.W, H, r.z, r.D + 0.3, 1.2, r.W / n, Math.PI / 2);
+    }
+    // smokestack with a dark band
+    const sx = r.x - r.W * 0.38, sz = r.z - r.D * 0.3;
+    _c.set("#9A6B5A").offsetHSL(0, 0, (rng() - 0.5) * 0.05);
+    b._part(r, "cyl", _c, sx, 0, sz, 1.1, H + 6.5, 1.1);
+    _c.set("#3F454F");
+    b._part(r, "cyl", _c, sx, H + 5.6, sz, 1.16, 0.7, 1.16);
+    doorQuad(b, r, r.x + r.W * 0.25, 1.3, r.z + r.D / 2 + 0.03, 0, 2.0, 2.6);
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 0, 1, 1, { density: 0.5, wH: 0.8 });
+  },
+
+  park(b, r, rng, facade, roof) {
+    // no walls: trees (2-5 per cell), benches, central fountain
+    r.height = 3;
+    const w = Math.round((r.W + MARGIN) / CELL), d = Math.round((r.D + MARGIN) / CELL);
+    const x0 = r.x - (w * CELL) / 2, z0 = r.z - (d * CELL) / 2;
+    const density = b.quality.instances ?? 1;
+    for (let cz = 0; cz < d; cz++) {
+      for (let cx = 0; cx < w; cx++) {
+        const n = Math.max(1, Math.round((2 + Math.floor(rng() * 4)) * density));
+        for (let i = 0; i < n; i++) {
+          const tx = x0 + (cx + 0.18 + rng() * 0.64) * CELL;
+          const tz = z0 + (cz + 0.18 + rng() * 0.64) * CELL;
+          if (Math.abs(tx - r.x) < 2.6 && Math.abs(tz - r.z) < 2.6) continue; // keep the fountain clear
+          b._tree(r, rng, tx, tz, 0.8 + rng() * 0.5);
+        }
+      }
+    }
+    b._fountain(r, rng, r.x, r.z, 0.8);
+    for (let i = 0; i < 3; i++) {
+      const ang = rng() * Math.PI * 2;
+      b._bench(r, rng, r.x + Math.cos(ang) * 3.6, r.z + Math.sin(ang) * 3.6, ang + Math.PI / 2);
+    }
+  },
+
+  plaza(b, r, rng, facade, roof) {
+    r.height = 2.5;
+    b._fountain(r, rng, r.x, r.z, 0.55);
+    b._bench(r, rng, r.x - 1.3, r.z + 1.1, 0.6);
+    b._bench(r, rng, r.x + 1.3, r.z - 1.0, -2.2);
+    b._tree(r, rng, r.x + 1.2, r.z + 1.2, 0.65);
+    _c.set(PALETTE.sidewalk).offsetHSL(0, 0, -0.06);
+    for (const [px, pz] of [[-1.3, -1.3], [1.3, 1.3], [-1.3, 1.3], [1.3, -1.3]]) {
+      b._part(r, "box", _c, r.x + px, 0, r.z + pz, 0.5, 0.5, 0.5);
+    }
+  },
+
+  stadium(b, r, rng, facade, roof) {
+    const wallH = 4.5;
+    r.height = wallH + 5.5;
+    _c.copy(facade).offsetHSL(0, 0, -0.04);
+    b._part(r, "cyl", _c, r.x, 0, r.z, r.W * 0.98, wallH, r.D * 0.8); // elliptical bowl
+    _c.copy(roof).offsetHSL(0, 0, -0.06);
+    b._part(r, "cyl", _c, r.x, wallH, r.z, r.W * 0.86, 0.25, r.D * 0.68); // rim
+    _c.set(PALETTE.park).offsetHSL(0, 0.08, 0.03);
+    b._part(r, "cyl", _c, r.x, wallH - 0.5, r.z, r.W * 0.78, 0.9, r.D * 0.62); // the pitch
+    _c.set("#3F454F");
+    for (const [mx, mz] of [[-1, -1], [1, -1], [-1, 1], [1, 1]]) {
+      const px = r.x + mx * r.W * 0.42, pz = r.z + mz * r.D * 0.36;
+      b._part(r, "box", _c, px, 0, pz, 0.28, wallH + 5.5, 0.28);
+      _c2.set(EMISSIVE.headlight);
+      b._part(r, "sign", _c2, px - mx * 0.5, wallH + 4.6, pz, 1.1, 0.6, 1, mx > 0 ? -Math.PI / 2 : Math.PI / 2,
+        0, 0, { aDay: 0.5, aNight: 2.0 });
+      _c.set("#3F454F");
+    }
+    doorQuad(b, r, r.x, 1.4, r.z + r.D * 0.8 / 2 + 0.03, 0, 2.6, 2.8);
+  },
+
+  church(b, r, rng, facade, roof) {
+    const H = Math.max(r.height, 4.2);
+    b._part(r, "box", facade, r.x, 0, r.z, r.W, H, r.D);
+    b._part(r, "gable", roof, r.x, H, r.z, r.W + 0.4, 2.0, r.D + 0.4);
+    // steeple on the entry end: base + spire + cross
+    const sx = r.x - r.W * 0.32;
+    b._part(r, "box", facade, sx, 0, r.z, 1.6, H + 3.2, 1.6);
+    b._part(r, "gable", roof, sx, H + 3.2, r.z, 1.8, 2.4, 1.8);
+    _c.set("#6E5546");
+    b._part(r, "box", _c, sx, H + 5.5, r.z, 0.12, 1.1, 0.12);
+    b._part(r, "box", _c, sx, H + 6.1, r.z, 0.6, 0.12, 0.12);
+    r.height = H + 6.6;
+    doorQuad(b, r, sx, 1.3, r.z + r.D / 2 + 0.03, 0, 1.2, 2.6);
+    _c.set(EMISSIVE.window);
+    b._part(r, "sign", _c, r.x + r.W * 0.2, H * 0.6, r.z + r.D / 2 + 0.03, 0.7, 1.6, 1, 0, 0, 0, { aDay: 0.5, aNight: 1.5 });
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 0, 1, 1, { density: 0.5, wH: 1.4, wW: 0.5 });
+  },
+
+  town_hall(b, r, rng, facade, roof) {
+    const H = r.height;
+    _c.copy(facade).offsetHSL(0, 0, -0.08);
+    b._part(r, "box", _c, r.x, 0, r.z + r.D / 2 + 0.5, r.W * 0.6, 0.35, 1.4); // steps
+    b._part(r, "box", _c, r.x, 0, r.z + r.D / 2 + 0.2, r.W * 0.7, 0.6, 0.9);
+    b._part(r, "box", facade, r.x, 0, r.z, r.W, H, r.D);
+    b._part(r, "box", roof, r.x, H, r.z, r.W + 0.3, 0.3, r.D + 0.3);
+    const front = r.z + r.D / 2;
+    for (let i = 0; i < 4; i++) {
+      const cx = r.x + ((i / 3) - 0.5) * r.W * 0.55;
+      b._part(r, "cyl", facade, cx, 0.6, front + 0.5, 0.4, H - 0.6, 0.4);
+    }
+    _c.copy(facade).offsetHSL(0, 0, -0.05);
+    b._part(r, "gable", _c, r.x, H * 0.88, front + 0.35, r.W * 0.68, 1.0, 1.1); // pediment
+    _c.set("#7FB69E").offsetHSL(0, 0, -0.02);
+    b._part(r, "dome", _c, r.x, H + 0.3, r.z, 3.4, 4.4, 3.4);
+    _c.set("#C9C4B8");
+    b._part(r, "box", _c, r.x + r.W * 0.36, H, r.z - r.D * 0.3, 0.1, 3.4, 0.1); // flagpole
+    _c.set(PALETTE.accent);
+    b._part(r, "sign", _c, r.x + r.W * 0.36 + 0.5, H + 2.9, r.z - r.D * 0.3, 0.9, 0.55, 1, Math.PI / 2, 0, 0, { aDay: 1.0, aNight: 0.9 });
+    r.height = H + 2.5;
+    doorQuad(b, r, r.x, 1.4, front + 0.03, 0, 1.5, 2.8);
+    b._windowsBox(r, rng, r.x, r.z, r.W, r.D, 0, r.floors, r.floors, { density: 0.9, wH: 1.3 });
+  },
+};

web/city/camera.js

@@ -0,0 +1,286 @@
+// NEMOCITY — the orbit rig over the diorama. Eased spherical targets (the
+// godseed camera idiom): left-drag pans by grabbing the ground plane,
+// right-drag / two-finger orbits, wheel zooms toward the cursor. gaze() eases
+// over to frame a world point on world_delta; userHold pauses auto-motion
+// whenever a hand is on the camera. landing() plays the contract's T0->T10 s
+// choreography (low dolly behind Main St traffic -> crane to the 38 deg god
+// view -> 0.5 deg/s drift); any input cancels it. update(dt) is sim-time only.
+import * as THREE from "three";
+import { GRID, CELL } from "./constants.js";
+import { DEG, clamp, lerp, easeInOut } from "./util.js";
+
+const PLOT_HALF = (GRID * CELL) / 2;   // 128 m
+const BOUND = PLOT_HALF * 1.2;         // pan/gaze bounds: city plot +20%
+const PITCH_MIN = 15 * DEG, PITCH_MAX = 80 * DEG;
+const H_MIN = 8, H_MAX = 160;          // camera height clamp, m
+const DIST_MIN = 12, DIST_MAX = 340;
+const EASE = 3.0;                      // exp smoothing rate (1 - e^(-dt*EASE))
+const HOLD_S = 6;                      // user-control override after any input
+const DRIFT = 0.5 * DEG;               // post-landing drift, rad/s
+
+// landing: T0-3.5 dolly forward low over Main St, T3.5-7 crane to god view,
+// T7+ drift. God pose: 38 deg pitch, downtown left-third, ~86 m height.
+const DOLLY_END = 3.5, CRANE_END = 7, DOLLY_M = 22;
+const GOD = { look: new THREE.Vector3(10, 0, -4), yaw: 0.55, pitch: 38 * DEG, dist: 140 };
+
+const _v = new THREE.Vector3();
+const _a = new THREE.Vector3();
+const _b = new THREE.Vector3();
+const _ndc = new THREE.Vector2();
+const _ray = new THREE.Raycaster();
+const _plane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
+
+export class CameraRig {
+  constructor(camera, dom) {
+    this.camera = camera;
+    this.dom = dom;
+    this.look = new THREE.Vector3();
+    this.lookT = new THREE.Vector3();
+    this.yaw = 0; this.yawT = 0;
+    this.pitch = 0.6; this.pitchT = 0.6;
+    this.dist = 120; this.distT = 120;
+    this.userHold = 0;
+    this.gazeHold = 0;
+    this._drift = false;   // set when the landing settles; cleared on input
+    this._landing = null;
+    this._adopt();
+    this._bind(dom);
+  }
+
+  /** Derive spherical state from wherever the camera currently is. */
+  _adopt() {
+    const dir = this.camera.getWorldDirection(_v);
+    const t = dir.y < -0.05 ? this.camera.position.y / -dir.y : 60;
+    this.look.copy(this.camera.position).addScaledVector(dir, clamp(t, 10, 380));
+    this.look.y = 0;
+    _a.copy(this.camera.position).sub(this.look);
+    this.dist = Math.max(DIST_MIN, _a.length());
+    this.pitch = Math.asin(clamp(_a.y / this.dist, -1, 1));
+    this.yaw = Math.atan2(_a.x, _a.z);
+    this.lookT.copy(this.look);
+    this.yawT = this.yaw;
+    this.pitchT = this.pitch;
+    this.distT = this.dist;
+  }
+
+  _apply() {
+    const cp = Math.cos(this.pitch), sp = Math.sin(this.pitch);
+    this.camera.position.set(
+      this.look.x + this.dist * cp * Math.sin(this.yaw),
+      this.look.y + this.dist * sp,
+      this.look.z + this.dist * cp * Math.cos(this.yaw)
+    );
+    this.camera.lookAt(this.look);
+  }
+
+  _clampLook(v) {
+    v.x = clamp(v.x, -BOUND, BOUND);
+    v.z = clamp(v.z, -BOUND, BOUND);
+    v.y = 0;
+  }
+
+  /** Ray through (clientX, clientY) intersected with the ground plane. */
+  _groundPoint(cx, cy, out) {
+    const r = this.dom.getBoundingClientRect();
+    _ndc.set(((cx - r.left) / r.width) * 2 - 1, -((cy - r.top) / r.height) * 2 + 1);
+    _ray.setFromCamera(_ndc, this.camera);
+    return _ray.ray.intersectPlane(_plane, out);
+  }
+
+  /** Any input: pause auto-motion, cancel landing + drift. */
+  _userInput() {
+    this.userHold = HOLD_S;
+    this.gazeHold = 0;
+    this._drift = false;
+    if (this._landing) {
+      this._landing = null;
+      this._adopt();
+    }
+  }
+
+  _bind(dom) {
+    if (!dom) return;
+    const pointers = new Map(); // pointerId -> {x, y}
+    let mode = null;            // "pan" | "orbit" | "touch"
+    const grab = new THREE.Vector3();
+    let hasGrab = false;
+    let pinch = 0, midX = 0, midY = 0;
+
+    const touchState = () => {
+      const [p, q] = [...pointers.values()];
+      pinch = Math.hypot(p.x - q.x, p.y - q.y);
+      midX = (p.x + q.x) / 2;
+      midY = (p.y + q.y) / 2;
+    };
+
+    dom.addEventListener("pointerdown", (e) => {
+      this._userInput();
+      dom.setPointerCapture?.(e.pointerId);
+      pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
+      if (pointers.size === 2) {
+        mode = "touch";
+        hasGrab = false;
+        touchState();
+      } else if (e.button === 2 || e.button === 1) {
+        mode = "orbit";
+      } else {
+        mode = "pan";
+        hasGrab = !!this._groundPoint(e.clientX, e.clientY, grab);
+      }
+    });
+
+    dom.addEventListener("pointermove", (e) => {
+      const p = pointers.get(e.pointerId);
+      if (!p) return;
+      const dx = e.clientX - p.x, dy = e.clientY - p.y;
+      p.x = e.clientX; p.y = e.clientY;
+      this.userHold = HOLD_S;
+      if (mode === "touch" && pointers.size === 2) {
+        const pm = pinch, mx = midX, my = midY;
+        touchState();
+        this.yawT -= (midX - mx) * 0.005;
+        this.pitchT = clamp(this.pitchT + (midY - my) * 0.004, PITCH_MIN, PITCH_MAX);
+        if (pinch > 1) this.distT = clamp(this.distT * (pm / pinch), DIST_MIN, DIST_MAX);
+      } else if (mode === "orbit") {
+        this.yawT -= dx * 0.005;
+        this.pitchT = clamp(this.pitchT + dy * 0.004, PITCH_MIN, PITCH_MAX);
+      } else if (mode === "pan" && hasGrab) {
+        // keep the grabbed ground point under the cursor (1:1 pan)
+        if (this._groundPoint(e.clientX, e.clientY, _v)) {
+          _a.copy(grab).sub(_v);
+          _a.y = 0;
+          this.look.add(_a);
+          this._clampLook(this.look);
+          this.lookT.copy(this.look);
+          this._apply();
+        }
+      }
+    });
+
+    const end = (e) => {
+      pointers.delete(e.pointerId);
+      if (pointers.size === 0) mode = null;
+      else if (pointers.size === 1) {
+        mode = "pan";
+        const [p] = [...pointers.values()];
+        hasGrab = !!this._groundPoint(p.x, p.y, grab);
+      }
+    };
+    dom.addEventListener("pointerup", end);
+    dom.addEventListener("pointercancel", end);
+    dom.addEventListener("contextmenu", (e) => e.preventDefault());
+
+    dom.addEventListener("wheel", (e) => {
+      e.preventDefault();
+      this._userInput();
+      const f = clamp(1 + e.deltaY * 0.0011, 0.55, 1.6);
+      const at = this._groundPoint(e.clientX, e.clientY, _v);
+      this.distT = clamp(this.distT * f, DIST_MIN, DIST_MAX);
+      if (at) {
+        this.lookT.lerp(_v, 1 - f); // zoom toward / away from the cursor
+        this._clampLook(this.lookT);
+      }
+    }, { passive: false });
+  }
+
+  /** Ease over to frame a world point (called on world_delta). Refused while
+   *  a hand is on the camera or the landing choreography is playing. */
+  gaze(point, { hold = 5 } = {}) {
+    if (this.userHold > 0 || this._landing) return;
+    if (!point) { this.gazeHold = 0; return; }
+    this.lookT.set(point.x, 0, point.z);
+    this._clampLook(this.lookT);
+    this.distT = clamp(this.distT, 36, 90); // close enough that a build reads
+    this.gazeHold = hold;
+  }
+
+  /** Start the T0->T10 s landing choreography from the current camera pose. */
+  landing() {
+    this.userHold = 0;
+    this.gazeHold = 0;
+    this._drift = false;
+    this._landing = { t: 0, p0: this.camera.position.clone() };
+  }
+
+  _updateLanding(dt) {
+    const L = this._landing;
+    L.t += dt;
+    if (L.t < DOLLY_END) {
+      // constant-speed dolly forward along the avenue; the look offset matches
+      // scene.js's boot lookAt exactly so T0 (the screenshot frame) has no pop
+      const u = L.t / DOLLY_END;
+      this.camera.position.set(L.p0.x, L.p0.y, L.p0.z - DOLLY_M * u);
+      this.look.set(L.p0.x, 3, this.camera.position.z - 70);
+      this.camera.lookAt(this.look);
+    } else if (L.t < CRANE_END) {
+      // single eased crane up + pull back to the god view
+      const k = easeInOut((L.t - DOLLY_END) / (CRANE_END - DOLLY_END));
+      _a.set(L.p0.x, L.p0.y, L.p0.z - DOLLY_M);
+      const cp = Math.cos(GOD.pitch), sp = Math.sin(GOD.pitch);
+      _b.set(
+        GOD.look.x + GOD.dist * cp * Math.sin(GOD.yaw),
+        GOD.dist * sp,
+        GOD.look.z + GOD.dist * cp * Math.cos(GOD.yaw)
+      );
+      this.camera.position.lerpVectors(_a, _b, k);
+      this.camera.position.y += Math.sin(k * Math.PI) * 6; // crane bulge
+      _v.set(L.p0.x, 3, _a.z - 70);
+      this.look.lerpVectors(_v, GOD.look, k);
+      this.camera.lookAt(this.look);
+    } else {
+      // settle into orbit state; the T7+ drift runs in the normal update path
+      this._landing = null;
+      this.look.copy(GOD.look);
+      this.lookT.copy(GOD.look);
+      this.yaw = this.yawT = GOD.yaw;
+      this.pitch = this.pitchT = GOD.pitch;
+      this.dist = this.distT = GOD.dist;
+      this._drift = true;
+      this._apply();
+    }
+  }
+
+  /** Screen-space y in [0,1] of the gaze target — feeds post.setFocusY. */
+  focusScreenY() {
+    _v.copy(this.look).project(this.camera);
+    return clamp(_v.y * 0.5 + 0.5, 0, 1);
+  }
+
+  /** Camera height (m) — main.js lerps tilt-shift amount over 60 -> 25 m. */
+  height() {
+    return this.camera.position.y;
+  }
+
+  /** Convenience: the contract's 60 -> 25 m tilt-shift amount lerp. */
+  tiltShiftAmount() {
+    return clamp((this.height() - 25) / 35, 0, 1);
+  }
+
+  /** Current gaze target (FPV spawns near this: fpv.enter(rig.lookPoint())). */
+  lookPoint() {
+    return this.look.clone();
+  }
+
+  update(dt) {
+    if (this._landing) {
+      this._updateLanding(dt);
+      return;
+    }
+    if (this.userHold > 0) this.userHold -= dt;
+    if (this.gazeHold > 0) this.gazeHold -= dt;
+    else if (this._drift && this.userHold <= 0) this.yawT += DRIFT * dt;
+
+    this.pitchT = clamp(this.pitchT, PITCH_MIN, PITCH_MAX);
+    const sp = Math.sin(this.pitchT);
+    this.distT = clamp(this.distT,
+      Math.max(DIST_MIN, H_MIN / sp), Math.min(DIST_MAX, H_MAX / sp));
+    this._clampLook(this.lookT);
+
+    const k = 1 - Math.exp(-dt * EASE);
+    this.yaw = lerp(this.yaw, this.yawT, k);
+    this.pitch = lerp(this.pitch, this.pitchT, k);
+    this.dist = lerp(this.dist, this.distT, k * 0.8);
+    this.look.lerp(this.lookT, k * 0.9);
+    this._apply();
+  }
+}

web/city/citizens.js

@@ -0,0 +1,297 @@
+// NEMOCITY — citizens. Instanced capsule+head pedestrians on sidewalk loops:
+// each walks a BFS route along road cells between a seeded home and a seeded
+// destination (attract-weighted for leisure walkers, jobs-weighted for
+// commuters), offset onto the sidewalk edge. Position is a PURE function of
+// absolute simTime (the godseed life.js idiom — there-and-back wave with dwell
+// plateaus), so replay/seek/shared sync are exact. Daypart spawn-weighting
+// (cafes/parks midday + dusk) picks WHICH pool entries are visible, never
+// where anyone stands. Hidden beyond 180 m of the camera; small quality
+// halves the visible count.
+import * as THREE from "three";
+import { GRID, CELL, CITIZENS_PER_POP, CITIZENS_MIN, CITIZENS_MAX } from "./constants.js";
+import { clamp, cellKey, dayHours } from "./util.js";
+import { mulberry32 } from "./rng.js";
+import { FACADES } from "./palette.js";
+import { ROAD_Y } from "./roads.js";
+import { buildingsFromEvents, buildProgress, computePopulation, pathPoint } from "./traffic.js";
+
+const HALF = GRID / 2;
+const POOL = CITIZENS_MAX;
+const HIDE_DIST_SQ = 180 * 180;
+const LEGS = ["#3E4A5C", "#6B5D4F", "#7A8294", "#4F5D54", "#54485E"].map((h) => new THREE.Color(h));
+const SKIN = ["#F0C8A0", "#C89878", "#8D5524", "#FFDBB4", "#A86B3C"].map((h) => new THREE.Color(h));
+const SHIRTS = FACADES.map((h) => new THREE.Color(h));
+
+const _m = new THREE.Matrix4();
+const _q = new THREE.Quaternion();
+const _e = new THREE.Euler();
+const _p = new THREE.Vector3();
+const _s = new THREE.Vector3();
+const ZERO = new THREE.Matrix4().makeScale(0, 0, 0);
+const _pos = { x: 0, y: 0, z: 0 };
+const _tan = { x: 0, z: 0 };
+
+export class Citizens {
+  constructor(scene, quality, city = null) {
+    this.scene = scene;
+    this.quality = quality;
+    this.city = city;
+    this.camera = null; // setCamera() enables the 180 m hide
+    this.group = new THREE.Group();
+    this.group.matrixAutoUpdate = false;
+    scene.add(this.group);
+
+    const mk = (geo) => {
+      const mat = new THREE.MeshStandardMaterial({ roughness: 0.9, metalness: 0, envMapIntensity: 0.25 });
+      const m = new THREE.InstancedMesh(geo, mat, POOL);
+      m.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+      m.count = POOL;
+      m.frustumCulled = false;
+      this.group.add(m);
+      return m;
+    };
+    // origin at the feet; legs box + torso capsule (shirt) + head sphere
+    this.legs = mk(new THREE.BoxGeometry(0.3, 0.62, 0.24).translate(0, 0.31, 0));
+    this.torso = mk(new THREE.CapsuleGeometry(0.17, 0.36, 3, 8).translate(0, 0.85, 0));
+    this.head = mk(new THREE.SphereGeometry(0.13, 8, 7).translate(0, 1.27, 0));
+    for (let i = 0; i < POOL; i++) {
+      this.legs.setMatrixAt(i, ZERO);
+      this.torso.setMatrixAt(i, ZERO);
+      this.head.setMatrixAt(i, ZERO);
+    }
+
+    this._defs = new Array(POOL).fill(null);
+    this._leisureOrder = [];
+    this._workOrder = [];
+    this._eventsSeen = -1;
+    this._versionSeen = -1;
+    this._popAcc = 1e9;
+    this._pop = 0;
+    this._blobs = null;
+  }
+
+  setCamera(camera) {
+    this.camera = camera;
+  }
+
+  // ---- pool rebuild (events changed: homes/dests/roads may differ) ----------
+  _rebuild(simTime) {
+    const city = this.city;
+    this._eventsSeen = city.events.length;
+    this._versionSeen = city.roadVersion;
+
+    // road graph + per-cell walk surface (bridge decks walkable for peds)
+    const surf = new Map();
+    for (const [key, rec] of city.roadCells) surf.set(key, rec.bridge ? ROAD_Y.deck : ROAD_Y.road);
+    for (const [key] of city.roadCells) {
+      if (surf.get(key) !== ROAD_Y.road) continue;
+      const [cx, cz] = key.split(",").map(Number);
+      for (const [dx, dz] of [[0, -1], [1, 0], [0, 1], [-1, 0]]) {
+        if (surf.get(cellKey(cx + dx, cz + dz)) === ROAD_Y.deck) { surf.set(key, ROAD_Y.ramp); break; }
+      }
+    }
+
+    const buildings = buildingsFromEvents(city.events);
+    const homes = [], leisure = [], work = [];
+    for (const b of buildings) {
+      if (buildProgress(b, simTime) < 1) continue;
+      if (b.def.residents > 0) homes.push(b);
+      if (b.def.attract > 0) leisure.push(b);
+      if (b.def.jobs > 0) work.push(b);
+    }
+
+    const roulette = (rng, list, weightOf) => {
+      let total = 0;
+      for (const b of list) total += weightOf(b);
+      if (total <= 0) return null;
+      let r = rng() * total;
+      for (const b of list) {
+        r -= weightOf(b);
+        if (r <= 0) return b;
+      }
+      return list[list.length - 1];
+    };
+
+    for (let i = 0; i < POOL; i++) {
+      const rng = mulberry32((0x517ec1 + Math.imul(i, 0x9e3779b9)) >>> 0);
+      const isLeisure = rng() < 0.55;
+      const home = roulette(rng, homes, (b) => b.def.residents);
+      const destList = isLeisure && leisure.length ? leisure : work;
+      const dest = roulette(rng, destList, (b) => (isLeisure ? b.def.attract : b.def.jobs));
+      let def = null;
+      if (home && dest) {
+        const a = this._gate(home, surf);
+        const b = this._gate(dest, surf);
+        if (a && b && !(a[0] === b[0] && a[1] === b[1])) {
+          const cellsPath = this._bfs(a, b, surf);
+          if (cellsPath && cellsPath.length > 1) {
+            def = this._makeDef(i, rng, isLeisure, cellsPath, surf);
+          }
+        }
+      }
+      this._defs[i] = def;
+      this.legs.setColorAt(i, LEGS[Math.floor((def ? def.r1 : 0) * LEGS.length) % LEGS.length]);
+      this.torso.setColorAt(i, SHIRTS[Math.floor((def ? def.r2 : 0) * SHIRTS.length) % SHIRTS.length]);
+      this.head.setColorAt(i, SKIN[Math.floor((def ? def.r3 : 0) * SKIN.length) % SKIN.length]);
+    }
+    this.legs.instanceColor.needsUpdate = true;
+    this.torso.instanceColor.needsUpdate = true;
+    this.head.instanceColor.needsUpdate = true;
+
+    // visibility orderings: leisure walkers first vs commuters first
+    const lei = [], wrk = [];
+    for (let i = 0; i < POOL; i++) {
+      if (!this._defs[i]) continue;
+      (this._defs[i].leisure ? lei : wrk).push(i);
+    }
+    this._leisureOrder = lei.concat(wrk);
+    this._workOrder = wrk.concat(lei);
+  }
+
+  _makeDef(i, rng, leisure, cellsPath, surf) {
+    // sidewalk polyline: cell centers pushed to a fixed side of the road
+    const side = rng() < 0.5 ? 1 : -1;
+    const off = (1.45 + rng() * 0.45) * side;
+    const n = cellsPath.length;
+    const pts = new Float32Array(n * 3);
+    for (let k = 0; k < n; k++) {
+      const [cx, cz] = cellsPath[k];
+      const [pcx, pcz] = cellsPath[Math.max(k - 1, 0)];
+      const [ncx, ncz] = cellsPath[Math.min(k + 1, n - 1)];
+      let tx = ncx - pcx, tz = ncz - pcz;
+      const tl = Math.hypot(tx, tz) || 1;
+      tx /= tl; tz /= tl;
+      pts[k * 3] = cx * CELL + CELL / 2 + (-tz) * off;
+      pts[k * 3 + 1] = surf.get(cellKey(cx, cz)) ?? ROAD_Y.road;
+      pts[k * 3 + 2] = cz * CELL + CELL / 2 + tx * off;
+    }
+    const speed = 1.25 + rng() * 0.5; // m/s
+    const tWalk = ((n - 1) * CELL) / speed;
+    const tDwell = 4 + rng() * 8;
+    const period = 2 * (tWalk + tDwell);
+    return {
+      leisure, pts, n, tWalk, tDwell, period,
+      phase: rng() * period,
+      bobPhase: rng() * 6.28,
+      scale: 0.92 + rng() * 0.16,
+      r1: rng(), r2: rng(), r3: rng(),
+    };
+  }
+
+  _gate(b, surf) {
+    for (let r = 1; r <= 8; r++) {
+      for (let z = b.cz - r; z < b.cz + b.d + r; z++) {
+        for (let x = b.cx - r; x < b.cx + b.w + r; x++) {
+          const ring = Math.max(
+            Math.max(b.cx - x, x - (b.cx + b.w - 1)),
+            Math.max(b.cz - z, z - (b.cz + b.d - 1)));
+          if (ring !== r || x < -HALF || x >= HALF || z < -HALF || z >= HALF) continue;
+          if (surf.has(cellKey(x, z))) return [x, z];
+        }
+      }
+    }
+    return null;
+  }
+
+  _bfs(a, b, surf) {
+    const start = cellKey(a[0], a[1]), goal = cellKey(b[0], b[1]);
+    const came = new Map([[start, null]]);
+    let frontier = [a];
+    while (frontier.length) {
+      const next = [];
+      for (const [cx, cz] of frontier) {
+        for (const [dx, dz] of [[0, -1], [1, 0], [0, 1], [-1, 0]]) {
+          const nx = cx + dx, nz = cz + dz;
+          const key = cellKey(nx, nz);
+          if (!surf.has(key) || came.has(key)) continue;
+          came.set(key, cellKey(cx, cz));
+          if (key === goal) {
+            const path = [];
+            for (let k = key; k; k = came.get(k)) path.push(k.split(",").map(Number));
+            return path.reverse();
+          }
+          next.push([nx, nz]);
+        }
+      }
+      frontier = next;
+    }
+    return null;
+  }
+
+  // ---- per-frame -------------------------------------------------------------
+  update(dt, simTime) {
+    const city = this.city;
+    if (!city) return;
+    if (city.events.length !== this._eventsSeen || city.roadVersion !== this._versionSeen) {
+      this._rebuild(simTime);
+    }
+    this._popAcc += dt;
+    if (this._popAcc >= 1) {
+      this._popAcc = 0;
+      this._pop = computePopulation(city.events, simTime);
+    }
+    if (!this._blobs && city.ground && city.ground.addBlob) {
+      this._blobs = [];
+      for (let i = 0; i < POOL; i++) this._blobs.push(city.ground.addBlob(0, 0, 0, 0));
+    }
+
+    let count = clamp(Math.ceil(this._pop / CITIZENS_PER_POP), CITIZENS_MIN, CITIZENS_MAX);
+    if (this.quality && this.quality.small) count = Math.ceil(count / 2);
+
+    // daypart spawn-weighting: cafes/parks crowd midday and dusk
+    const h = dayHours(simTime);
+    const leisureTime = (h >= 10.5 && h <= 14.5) || (h >= 16.5 && h <= 20.5);
+    const order = leisureTime ? this._leisureOrder : this._workOrder;
+
+    const camX = this.camera ? this.camera.position.x : 0;
+    const camZ = this.camera ? this.camera.position.z : 0;
+    const shown = new Uint8Array(POOL);
+    let placed = 0;
+    for (const i of order) {
+      if (placed >= count) break;
+      const def = this._defs[i];
+      if (!def || shown[i]) continue;
+      shown[i] = 1;
+      placed++;
+      // there-and-back wave with dwell plateaus — pure fn of absolute simTime
+      const w = (((simTime + def.phase) % def.period) + def.period) % def.period;
+      let u, dir, walking;
+      if (w < def.tWalk) { u = (w / def.tWalk) * (def.n - 1); dir = 1; walking = true; }
+      else if (w < def.tWalk + def.tDwell) { u = def.n - 1; dir = 1; walking = false; }
+      else if (w < 2 * def.tWalk + def.tDwell) {
+        u = (1 - (w - def.tWalk - def.tDwell) / def.tWalk) * (def.n - 1);
+        dir = -1; walking = true;
+      } else { u = 0; dir = -1; walking = false; }
+      pathPoint(def.pts, def.n, u, _pos, _tan);
+      if (this.camera) {
+        const ddx = _pos.x - camX, ddz = _pos.z - camZ;
+        if (ddx * ddx + ddz * ddz > HIDE_DIST_SQ) {
+          this._hide(i);
+          continue;
+        }
+      }
+      const yaw = Math.atan2(_tan.x * dir, _tan.z * dir);
+      const bob = (walking ? 0.035 : 0.008) * Math.sin(2 * Math.PI * 1.5 * simTime + def.bobPhase);
+      _e.set(0, yaw, 0);
+      _q.setFromEuler(_e);
+      _p.set(_pos.x, _pos.y + bob, _pos.z);
+      _s.setScalar(def.scale);
+      _m.compose(_p, _q, _s);
+      this.legs.setMatrixAt(i, _m);
+      this.torso.setMatrixAt(i, _m);
+      this.head.setMatrixAt(i, _m);
+      if (this._blobs) this._blobs[i].set(_pos.x, _pos.z, 0.7, 0.16);
+    }
+    for (let i = 0; i < POOL; i++) if (!shown[i]) this._hide(i);
+    this.legs.instanceMatrix.needsUpdate = true;
+    this.torso.instanceMatrix.needsUpdate = true;
+    this.head.instanceMatrix.needsUpdate = true;
+  }
+
+  _hide(i) {
+    this.legs.setMatrixAt(i, ZERO);
+    this.torso.setMatrixAt(i, ZERO);
+    this.head.setMatrixAt(i, ZERO);
+    if (this._blobs) this._blobs[i].set(0, 0, 0, 0);
+  }
+}

web/city/constants.js

@@ -0,0 +1,402 @@
+// GENERATED by tools/gen_web.py from engine/constants.py — do not edit.
+// Values are the ARCHITECTURE.md contract; regenerate, never hand-tune.
+
+export const GRID = 64;
+export const CELL = 4;
+export const COORD_MIN = -32;
+export const COORD_MAX = 31;
+export const CITY_EPOCH_S = 1781222400;
+export const DAY_S = 240;
+
+export function riverCols(cz) {
+  return cz <= -5 ? [7, 8] : cz <= 3 ? [8, 9] : [9, 10];
+}
+
+export const BUILDINGS = {
+  "house": {
+    "w": 1,
+    "d": 1,
+    "floors": [
+      1,
+      2
+    ],
+    "residents": 4,
+    "jobs": 0,
+    "attract": 0,
+    "duration": 20,
+    "duration_s": 20
+  },
+  "townhouse": {
+    "w": 1,
+    "d": 1,
+    "floors": [
+      2,
+      3
+    ],
+    "residents": 6,
+    "jobs": 0,
+    "attract": 0,
+    "duration": 20,
+    "duration_s": 20
+  },
+  "apartments": {
+    "w": 2,
+    "d": 2,
+    "floors": [
+      4,
+      7
+    ],
+    "residents": 16,
+    "jobs": 0,
+    "attract": 0,
+    "duration": 45,
+    "duration_s": 45
+  },
+  "cafe": {
+    "w": 1,
+    "d": 1,
+    "floors": [
+      1,
+      1
+    ],
+    "residents": 0,
+    "jobs": 3,
+    "attract": 5,
+    "duration": 20,
+    "duration_s": 20
+  },
+  "shop": {
+    "w": 1,
+    "d": 1,
+    "floors": [
+      1,
+      2
+    ],
+    "residents": 0,
+    "jobs": 4,
+    "attract": 4,
+    "duration": 20,
+    "duration_s": 20
+  },
+  "market": {
+    "w": 1,
+    "d": 2,
+    "floors": [
+      1,
+      1
+    ],
+    "residents": 0,
+    "jobs": 8,
+    "attract": 6,
+    "duration": 30,
+    "duration_s": 30
+  },
+  "bank": {
+    "w": 2,
+    "d": 1,
+    "floors": [
+      2,
+      4
+    ],
+    "residents": 0,
+    "jobs": 12,
+    "attract": 2,
+    "duration": 30,
+    "duration_s": 30
+  },
+  "office": {
+    "w": 1,
+    "d": 1,
+    "floors": [
+      3,
+      8
+    ],
+    "residents": 0,
+    "jobs": 40,
+    "attract": 1,
+    "duration": 30,
+    "duration_s": 30
+  },
+  "tower": {
+    "w": 2,
+    "d": 2,
+    "floors": [
+      8,
+      16
+    ],
+    "residents": 0,
+    "jobs": 60,
+    "attract": 2,
+    "duration": 45,
+    "duration_s": 45
+  },
+  "school": {
+    "w": 2,
+    "d": 2,
+    "floors": [
+      1,
+      2
+    ],
+    "residents": 0,
+    "jobs": 10,
+    "attract": 3,
+    "duration": 30,
+    "duration_s": 30
+  },
+  "hospital": {
+    "w": 3,
+    "d": 3,
+    "floors": [
+      3,
+      6
+    ],
+    "residents": 0,
+    "jobs": 25,
+    "attract": 2,
+    "duration": 45,
+    "duration_s": 45
+  },
+  "fire_station": {
+    "w": 2,
+    "d": 1,
+    "floors": [
+      2,
+      2
+    ],
+    "residents": 0,
+    "jobs": 8,
+    "attract": 1,
+    "duration": 30,
+    "duration_s": 30
+  },
+  "warehouse": {
+    "w": 2,
+    "d": 2,
+    "floors": [
+      1,
+      1
+    ],
+    "residents": 0,
+    "jobs": 10,
+    "attract": 0,
+    "duration": 30,
+    "duration_s": 30
+  },
+  "factory": {
+    "w": 3,
+    "d": 2,
+    "floors": [
+      1,
+      2
+    ],
+    "residents": 0,
+    "jobs": 18,
+    "attract": 0,
+    "duration": 45,
+    "duration_s": 45
+  },
+  "park": {
+    "w": 2,
+    "d": 2,
+    "floors": [
+      0,
+      0
+    ],
+    "residents": 0,
+    "jobs": 0,
+    "attract": 8,
+    "duration": 20,
+    "duration_s": 20
+  },
+  "plaza": {
+    "w": 1,
+    "d": 1,
+    "floors": [
+      0,
+      0
+    ],
+    "residents": 0,
+    "jobs": 0,
+    "attract": 6,
+    "duration": 20,
+    "duration_s": 20
+  },
+  "stadium": {
+    "w": 4,
+    "d": 4,
+    "floors": [
+      1,
+      1
+    ],
+    "residents": 0,
+    "jobs": 15,
+    "attract": 9,
+    "duration": 45,
+    "duration_s": 45
+  },
+  "church": {
+    "w": 2,
+    "d": 1,
+    "floors": [
+      1,
+      1
+    ],
+    "residents": 0,
+    "jobs": 2,
+    "attract": 3,
+    "duration": 30,
+    "duration_s": 30
+  },
+  "town_hall": {
+    "w": 2,
+    "d": 2,
+    "floors": [
+      2,
+      2
+    ],
+    "residents": 0,
+    "jobs": 6,
+    "attract": 4,
+    "duration": 45,
+    "duration_s": 45
+  }
+};
+
+export const ROAD_CLASSES = {
+  "street": {
+    "capacity": 2,
+    "speed": 1.0
+  },
+  "avenue": {
+    "capacity": 6,
+    "speed": 1.6
+  }
+};
+export const ROAD_DURATION_S = 4;
+export const DURATIONS = {
+  "house": 20,
+  "townhouse": 20,
+  "apartments": 45,
+  "cafe": 20,
+  "shop": 20,
+  "market": 30,
+  "bank": 30,
+  "office": 30,
+  "tower": 45,
+  "school": 30,
+  "hospital": 45,
+  "fire_station": 30,
+  "warehouse": 30,
+  "factory": 45,
+  "park": 20,
+  "plaza": 20,
+  "stadium": 45,
+  "church": 30,
+  "town_hall": 45
+};
+export const SYNONYMS = {
+  "skyscraper": "tower",
+  "highrise": "tower",
+  "high_rise": "tower",
+  "apartment": "apartments",
+  "apartment_building": "apartments",
+  "condo": "apartments",
+  "hotel": "apartments",
+  "coffee_shop": "cafe",
+  "coffee": "cafe",
+  "diner": "cafe",
+  "restaurant": "cafe",
+  "bakery": "cafe",
+  "store": "shop",
+  "boutique": "shop",
+  "pharmacy": "shop",
+  "gym": "shop",
+  "mall": "market",
+  "grocery": "market",
+  "supermarket": "market",
+  "police_station": "fire_station",
+  "police": "fire_station",
+  "firehouse": "fire_station",
+  "library": "town_hall",
+  "museum": "town_hall",
+  "city_hall": "town_hall",
+  "temple": "church",
+  "mosque": "church",
+  "chapel": "church",
+  "garden": "park",
+  "playground": "park",
+  "fountain": "plaza",
+  "square": "plaza",
+  "arena": "stadium",
+  "clinic": "hospital",
+  "plant": "factory",
+  "mill": "factory",
+  "home": "house",
+  "cottage": "house",
+  "cabin": "house"
+};
+export const STREET_NAMES = [
+  "Oak St",
+  "Maple Ave",
+  "Cedar Ln",
+  "Birch St",
+  "Willow Way",
+  "Juniper St",
+  "Laurel Ave",
+  "Magnolia Blvd",
+  "Poplar St",
+  "Chestnut St",
+  "Sycamore Ave",
+  "Alder Row",
+  "Hazel St",
+  "Linden Ave",
+  "Aspen Ct",
+  "Rowan St",
+  "Holly Ave",
+  "Ivy Ln",
+  "Clover St",
+  "Fern Way",
+  "Meadow Ln",
+  "Orchard St",
+  "Garden Ave",
+  "Harbor St",
+  "Mill Rd",
+  "Canal St",
+  "Foundry St",
+  "Station Rd",
+  "Depot Ln",
+  "Prospect Ave",
+  "Summit St",
+  "Vista Way",
+  "Sunrise Blvd",
+  "Larkspur St",
+  "Primrose Ave",
+  "Bluebell Ln",
+  "Copper St",
+  "Granite Ave",
+  "Beacon St",
+  "Quay Rd"
+];
+
+// traffic (mirrors engine/traffic.py — the Python side owns the facts)
+export const RUSH_HOURS = [
+  8.0,
+  18.0
+];
+export const RUSH_SIGMA = 1.2;
+export const RUSH_BASE = 0.35;
+export const RUSH_AMP = 0.65;
+export const CAR_RATE = 0.8;
+export const CAR_MIN = 8;
+export const CAR_MAX = 120;
+export const CITIZENS_PER_POP = 5;
+export const CITIZENS_MIN = 6;
+export const CITIZENS_MAX = 80;
+export const EMA_TAU_S = 5.0;
+export const TRIP_ATTRACT_FACTOR = 2.0;
+export const TRIP_DIST_EXP = 1.5;
+export const DEMAND_PER_COMMUTER = 0.5;
+export const CONGESTION_COST_FACTOR = 2.0;
+export const TRAFFIC_TOP_CELLS = 15;
+export const JAM_RATIO = 1.0;
+export const GROWTH_RADIUS_MIN = 6;

web/city/construction.js

@@ -0,0 +1,406 @@
+// NEMOCITY — construction FX: dirt lot -> orange scaffold pop -> (crane on
+// >=4 floors) -> floor-by-floor rise -> scaffold drop + sparkle + name label.
+// Everything is a pure function of absolute simTime: progress =
+// clamp((CITY_EPOCH_S + simTime - ev.t) / DURATION(kind), 0, 1), so late
+// joiners, seek() and timelapse all replay the exact same build.
+//
+// Convention with buildings.js (which owns every building mesh): this module
+// only computes the staged rise and calls buildings.setRise(id, yScale,
+// floorsShown) + buildings.setFinishGlow(id, k, intensity). Sites self-remove
+// ~6.5 s after completion; re-seeking BACKWARD across a finished build needs a
+// city.reset() replay (sites are re-added from the event list).
+// lay_road paint-in is roads.js's job; this module ignores road events.
+import * as THREE from "three";
+import { mulberry32 } from "./rng.js";
+import { CITY_EPOCH_S, CELL, BUILDINGS } from "./constants.js";
+import { PALETTE, EMISSIVE } from "./palette.js";
+import { clamp, easeOutBack } from "./util.js";
+
+const P_DIRT = 0.12, P_SCAF = 0.30, P_TOP = 0.90; // contract stage boundaries
+const GREEN = { park: true, plaza: true };        // no scaffold/crane/barriers
+const FINISH_S = 6.2;                             // label fade window after completion
+const SPARKS = 14;
+
+const _m4 = new THREE.Matrix4();
+const _p = new THREE.Vector3();
+const _q = new THREE.Quaternion();
+const _s = new THREE.Vector3();
+const _c = new THREE.Color();
+
+// ---- shared geometries/materials (never disposed per-site) -----------------
+function scaffoldGeo() {
+  // unit frame [-0.5,0.5] x [0,1] x [-0.5,0.5]: box edges + rings + diagonals
+  const v = [];
+  const seg = (a, b) => v.push(...a, ...b);
+  const c = (x, y, z) => [x, y, z];
+  for (const y of [0, 1 / 3, 2 / 3, 1]) {
+    seg(c(-0.5, y, -0.5), c(0.5, y, -0.5));
+    seg(c(0.5, y, -0.5), c(0.5, y, 0.5));
+    seg(c(0.5, y, 0.5), c(-0.5, y, 0.5));
+    seg(c(-0.5, y, 0.5), c(-0.5, y, -0.5));
+  }
+  for (const [x, z] of [[-0.5, -0.5], [0.5, -0.5], [0.5, 0.5], [-0.5, 0.5]]) {
+    seg(c(x, 0, z), c(x, 1, z));
+  }
+  seg(c(-0.5, 0, -0.5), c(0.5, 1 / 3, -0.5)); // a few cross braces
+  seg(c(0.5, 1 / 3, 0.5), c(-0.5, 2 / 3, 0.5));
+  seg(c(-0.5, 2 / 3, -0.5), c(-0.5, 1, 0.5));
+  const geo = new THREE.BufferGeometry();
+  geo.setAttribute("position", new THREE.Float32BufferAttribute(v, 3));
+  return geo;
+}
+
+const GEO = {
+  scaffold: scaffoldGeo(),
+  box: new THREE.BoxGeometry(1, 1, 1).translate(0, 0.5, 0),
+  barrier: new THREE.BoxGeometry(0.42, 0.38, 0.42).translate(0, 0.19, 0),
+  dirt: new THREE.PlaneGeometry(1, 1).rotateX(-Math.PI / 2),
+  ring: new THREE.RingGeometry(0.72, 1, 28).rotateX(-Math.PI / 2),
+  spark: new THREE.OctahedronGeometry(0.13, 0),
+};
+const CRANE_STEEL = new THREE.MeshStandardMaterial({
+  color: new THREE.Color(EMISSIVE.construction).multiplyScalar(0.85),
+  roughness: 0.6, metalness: 0.3, envMapIntensity: 0.25,
+});
+const CRANE_DARK = new THREE.MeshStandardMaterial({
+  color: "#3F454F", roughness: 0.7, metalness: 0.2, envMapIntensity: 0.25,
+});
+
+export class Construction {
+  constructor(scene, quality, city = null) {
+    this.scene = scene;
+    this.quality = quality || { instances: 1 };
+    this.city = city;
+    this.sites = new Map();
+    this.simTime = null; // last update() sim clock; null until the first tick
+  }
+
+  get _buildings() {
+    return this.city ? this.city.buildings : null;
+  }
+
+  /** world.js skeleton calls addFeature(f, opts); keep both names. */
+  addFeature(f) { return this.add(f); }
+
+  add(f) {
+    if (!f || f.tool !== "place_building" || !f.args || this.sites.has(f.id)) return;
+    const a = f.args;
+    const spec = BUILDINGS[a.kind] || BUILDINGS.house;
+    const kind = BUILDINGS[a.kind] ? a.kind : "house";
+    const dur = spec.duration;
+    if (this.simTime != null && CITY_EPOCH_S + this.simTime - f.t > dur + FINISH_S) return;
+
+    const w = a.w ?? spec.w, d = a.d ?? spec.d;
+    const floors = Math.max(1, clamp(a.floors ?? Math.round((spec.floors[0] + spec.floors[1]) / 2),
+      spec.floors[0], spec.floors[1]));
+    const x = a.cx * CELL + (w * CELL) / 2, z = a.cz * CELL + (d * CELL) / 2;
+    const W = w * CELL, D = d * CELL;
+    const info = this._buildings && this._buildings.getInfo(f.id);
+    const height = info ? info.height : Math.max(floors * 3, 3);
+    const shownCap = info ? info.floors : floors; // park/plaza have 0 window floors
+    const rng = mulberry32(((f.seed ?? 1) ^ 0x5bd1e995) >>> 0);
+    const green = !!GREEN[kind];
+
+    const group = new THREE.Group();
+    group.position.set(x, 0, z);
+    this.scene.add(group);
+
+    const site = {
+      f, id: f.id, kind, dur, green, floors, shownCap, W, D, height, x, z, group,
+      mats: [], glowDone: false, labelMade: false, label: null,
+    };
+
+    // dirt lot decal (slightly beyond the footprint)
+    site.dirtMat = new THREE.MeshStandardMaterial({
+      color: new THREE.Color(PALETTE.dirt).offsetHSL(0, 0, -0.05),
+      roughness: 1, metalness: 0, transparent: true, opacity: 0,
+      depthWrite: false, envMapIntensity: 0.25,
+    });
+    site.dirt = new THREE.Mesh(GEO.dirt, site.dirtMat);
+    site.dirt.scale.set(W * 1.3, 1, D * 1.3);
+    site.dirt.position.y = 0.015;
+    site.dirt.renderOrder = 1;
+    group.add(site.dirt);
+    site.mats.push(site.dirtMat);
+
+    // dust ring (re-triggered at every stage/floor transition)
+    site.ringMat = new THREE.MeshBasicMaterial({
+      color: new THREE.Color(PALETTE.dirt).offsetHSL(0, 0, 0.1), transparent: true,
+      opacity: 0, blending: THREE.AdditiveBlending, depthWrite: false,
+    });
+    site.ring = new THREE.Mesh(GEO.ring, site.ringMat);
+    site.ring.position.y = 0.04;
+    site.ring.visible = false;
+    group.add(site.ring);
+    site.mats.push(site.ringMat);
+
+    // transition times (s after ev.t) that kick a dust ring
+    site.transitions = green
+      ? [0, dur * 0.2, dur * 0.85, dur]
+      : [0, dur * P_DIRT, dur * P_SCAF,
+        ...Array.from({ length: floors }, (_, i) => dur * (P_SCAF + (P_TOP - P_SCAF) * ((i + 1) / floors))),
+        dur];
+
+    if (!green) {
+      site.scafMat = new THREE.LineBasicMaterial({
+        color: EMISSIVE.construction, transparent: true, opacity: 0.9,
+      });
+      site.scaffold = new THREE.LineSegments(GEO.scaffold, site.scafMat);
+      site.scaffold.scale.set(W - 0.1, 0.0001, D - 0.1);
+      group.add(site.scaffold);
+      site.mats.push(site.scafMat);
+
+      // barrier cubes, two alternating amber blink phases
+      site.blinkA = new THREE.MeshBasicMaterial({ color: EMISSIVE.signalAmber });
+      site.blinkB = new THREE.MeshBasicMaterial({ color: EMISSIVE.signalAmber });
+      site.mats.push(site.blinkA, site.blinkB);
+      site.barriers = new THREE.Group();
+      const bx = W / 2 + 0.7, bz = D / 2 + 0.7;
+      const spots = [[-bx, -bz], [bx, -bz], [-bx, bz], [bx, bz]];
+      if (w > 1 || d > 1) spots.push([0, -bz], [0, bz], [-bx, 0], [bx, 0]);
+      spots.forEach(([px, pz], i) => {
+        const m = new THREE.Mesh(GEO.barrier, i % 2 ? site.blinkA : site.blinkB);
+        m.position.set(px + (rng() - 0.5) * 0.3, 0, pz + (rng() - 0.5) * 0.3);
+        m.rotation.y = rng() * Math.PI;
+        site.barriers.add(m);
+      });
+      site.barriers.scale.setScalar(0.0001);
+      group.add(site.barriers);
+
+      if (floors >= 4) site.crane = this._makeCrane(site, rng);
+    }
+
+    // finish sparkle burst (seeded, despawns; pure fn of age)
+    site.sparkMat = new THREE.MeshBasicMaterial({
+      color: EMISSIVE.streetlamp, transparent: true, opacity: 1,
+      blending: THREE.AdditiveBlending, depthWrite: false,
+    });
+    site.sparks = new THREE.InstancedMesh(GEO.spark, site.sparkMat, SPARKS);
+    site.sparks.count = 0;
+    site.sparks.frustumCulled = false;
+    group.add(site.sparks);
+    site.mats.push(site.sparkMat);
+    site.sparkSeeds = Array.from({ length: SPARKS }, () => ({
+      az: rng() * Math.PI * 2,
+      r0: 0.4 + rng() * 0.8,
+      vr: 2.2 + rng() * 2.6,
+      vy: 3.2 + rng() * 3.4,
+      size: 0.7 + rng() * 0.8,
+    }));
+
+    // mask the finished building until the rise begins
+    if (this._buildings) this._buildings.setRise(f.id, 0, 0);
+    this.sites.set(f.id, site);
+  }
+
+  _makeCrane(site, rng) {
+    const mastH = site.height + 6;
+    const jibL = Math.max(site.W, site.D) * 0.9 + 3;
+    const g = new THREE.Group();
+    const corner = [[1, 1], [1, -1], [-1, 1], [-1, -1]][Math.floor(rng() * 4)];
+    g.position.set(corner[0] * (site.W / 2 + 1.6), 0, corner[1] * (site.D / 2 + 1.6));
+    g.scale.setScalar(0.0001);
+    const mast = new THREE.Mesh(GEO.box, CRANE_STEEL);
+    mast.scale.set(0.5, mastH, 0.5);
+    g.add(mast);
+    const base = new THREE.Mesh(GEO.box, CRANE_DARK);
+    base.scale.set(1.6, 0.5, 1.6);
+    g.add(base);
+    const jib = new THREE.Group();
+    jib.position.y = mastH;
+    g.add(jib);
+    const cab = new THREE.Mesh(GEO.box, CRANE_DARK);
+    cab.scale.set(0.9, 0.9, 0.9);
+    cab.position.y = -0.9;
+    jib.add(cab);
+    const arm = new THREE.Mesh(GEO.box, CRANE_STEEL);
+    arm.scale.set(jibL, 0.32, 0.32);
+    arm.position.x = jibL / 2;
+    arm.position.y = -0.32;
+    jib.add(arm);
+    const counter = new THREE.Mesh(GEO.box, CRANE_STEEL);
+    counter.scale.set(jibL * 0.35, 0.32, 0.32);
+    counter.position.x = -jibL * 0.175;
+    counter.position.y = -0.32;
+    jib.add(counter);
+    const weight = new THREE.Mesh(GEO.box, CRANE_DARK);
+    weight.scale.set(0.7, 1.1, 1.1);
+    weight.position.set(-jibL * 0.33, -1.1, 0);
+    jib.add(weight);
+    const cable = new THREE.Mesh(GEO.box, CRANE_DARK);
+    cable.scale.set(0.05, 1, 0.05);
+    jib.add(cable);
+    const hook = new THREE.Mesh(GEO.box, CRANE_STEEL);
+    hook.scale.set(0.4, 0.4, 0.4);
+    jib.add(hook);
+    site.group.add(g);
+    return { group: g, jib, cable, hook, mastH, jibR: jibL * 0.72, phase: rng() * Math.PI * 2 };
+  }
+
+  update(dt, simTime) {
+    this.simTime = simTime;
+    const now = CITY_EPOCH_S + simTime;
+    const B = this._buildings;
+    for (const site of [...this.sites.values()]) {
+      const age = now - site.f.t;
+      if (age > site.dur + FINISH_S + 0.3) {
+        this._finalize(site);
+        continue;
+      }
+      const p = clamp(age / site.dur, 0, 1);
+      const post = Math.max(0, age - site.dur); // seconds past completion
+      const fade = clamp(1 - post / 0.9, 0, 1); // scaffold/crane/barrier out
+
+      // ---- staged rise ----
+      let yScale = 0, floorsShown = 0, scafK = 0;
+      if (site.green) {
+        yScale = p <= 0.2 ? 0 : clamp(easeOutBack((p - 0.2) / 0.65), 0, 1.06);
+        if (p > 0.85) yScale = 1;
+        floorsShown = p > 0.85 ? site.floors : 0;
+      } else if (p <= P_DIRT) {
+        // dirt + dust only
+      } else if (p <= P_SCAF) {
+        scafK = easeOutBack((p - P_DIRT) / (P_SCAF - P_DIRT));
+      } else if (p <= P_TOP) {
+        scafK = 1;
+        const fF = ((p - P_SCAF) / (P_TOP - P_SCAF)) * site.floors;
+        const done = Math.min(Math.floor(fF), site.floors);
+        yScale = Math.min((done + easeOutBack(fF - done)) / site.floors, 1.06);
+        floorsShown = done;
+      } else {
+        scafK = 1;
+        yScale = 1;
+        floorsShown = site.floors;
+      }
+      if (B) B.setRise(site.id, yScale, Math.min(floorsShown, site.shownCap));
+
+      // ---- dirt + dust ring ----
+      site.dirtMat.opacity = 0.85 * (age >= site.dur ? clamp(1 - post / 2.5, 0, 1) : 1);
+      let ringK = -1;
+      for (let i = site.transitions.length - 1; i >= 0; i--) {
+        const t = site.transitions[i];
+        if (age >= t && age - t < 0.9) { ringK = (age - t) / 0.9; break; }
+        if (t < age - 0.9) break;
+      }
+      site.ring.visible = ringK >= 0;
+      if (ringK >= 0) {
+        const fp = Math.max(site.W, site.D);
+        site.ring.scale.setScalar(fp * (0.5 + 0.55 * ringK));
+        site.ringMat.opacity = (1 - ringK) * (1 - ringK) * 0.55;
+      }
+
+      // ---- scaffold / barriers / crane ----
+      if (!site.green) {
+        const scafY = Math.max(site.height + 0.5, 1) * scafK * Math.max(fade, 0.0001);
+        site.scaffold.scale.y = Math.max(scafY, 0.0001);
+        site.scafMat.opacity = 0.9 * fade;
+        site.scaffold.visible = scafK > 0 && fade > 0;
+        site.barriers.scale.setScalar(Math.max(scafK * fade, 0.0001));
+        const blink = Math.pow(Math.max(0, Math.sin(simTime * 5)), 2);
+        _c.set(EMISSIVE.signalAmber).multiplyScalar(0.25 + 1.7 * blink);
+        site.blinkA.color.copy(_c);
+        _c.set(EMISSIVE.signalAmber).multiplyScalar(0.25 + 1.7 * (1 - blink));
+        site.blinkB.color.copy(_c);
+        if (site.crane) {
+          const cr = site.crane;
+          const inK = easeOutBack(clamp((p - P_DIRT) / 0.06, 0, 1));
+          cr.group.scale.setScalar(Math.max(inK * fade, 0.0001));
+          cr.jib.rotation.y = cr.phase + 0.15 * simTime;
+          const hookY = clamp(yScale, 0, 1) * site.height + 1.5;
+          const drop = Math.max(cr.mastH - 1 - hookY, 0.5);
+          cr.cable.position.set(cr.jibR, -0.45 - drop, 0);
+          cr.cable.scale.y = drop;
+          cr.hook.position.set(cr.jibR, -0.45 - drop, 0);
+        }
+      }
+
+      // ---- finish beat: window sweep, sparkle, floating label ----
+      if (!site.glowDone && B) {
+        if (p > P_TOP && age < site.dur) {
+          B.setFinishGlow(site.id, (p - P_TOP) / (1 - P_TOP), 1);
+        } else if (age >= site.dur) {
+          const intensity = clamp(1 - post / 3, 0, 1);
+          B.setFinishGlow(site.id, 1, intensity);
+          if (intensity <= 0) site.glowDone = true;
+        }
+      }
+      if (age >= site.dur) {
+        this._sparkles(site, post);
+        this._label(site, post);
+      }
+    }
+  }
+
+  _sparkles(site, t) {
+    if (t > 1.4) { site.sparks.count = 0; return; }
+    site.sparks.count = SPARKS;
+    const k = t / 1.4;
+    site.sparkMat.opacity = 1 - k;
+    _q.identity();
+    for (let i = 0; i < SPARKS; i++) {
+      const sd = site.sparkSeeds[i];
+      const rr = sd.r0 + sd.vr * t;
+      _p.set(Math.cos(sd.az) * rr, Math.max(site.height + sd.vy * t - 4.5 * t * t, 0.1), Math.sin(sd.az) * rr);
+      _s.setScalar(Math.max(sd.size * (1 - k), 0.001));
+      _m4.compose(_p, _q, _s);
+      site.sparks.setMatrixAt(i, _m4);
+    }
+    site.sparks.instanceMatrix.needsUpdate = true;
+  }
+
+  _label(site, t) {
+    if (!site.labelMade) {
+      site.labelMade = true;
+      const a = site.f.args;
+      const name = a.name || site.kind.replace(/_/g, " ").replace(/\b\w/g, (ch) => ch.toUpperCase());
+      const m = /^w_0*(\d+)$/.exec(site.f.wish_id || "");
+      const text = m ? `${name} — built for visitor #${m[1]}` : name;
+      const canvas = document.createElement("canvas");
+      canvas.width = 1024;
+      canvas.height = 128;
+      const ctx = canvas.getContext("2d");
+      ctx.font = "600 46px 'Bricolage Grotesque', 'Schibsted Grotesk', sans-serif";
+      ctx.textAlign = "center";
+      ctx.textBaseline = "middle";
+      ctx.lineWidth = 8;
+      ctx.strokeStyle = "rgba(42,38,32,0.85)";
+      ctx.fillStyle = "#FCF9F2";
+      ctx.strokeText(text, 512, 66, 1000);
+      ctx.fillText(text, 512, 66, 1000);
+      const tex = new THREE.CanvasTexture(canvas);
+      const mat = new THREE.SpriteMaterial({ map: tex, transparent: true, depthTest: false });
+      const sprite = new THREE.Sprite(mat);
+      sprite.scale.set(18, 2.25, 1);
+      sprite.renderOrder = 10;
+      site.group.add(sprite);
+      site.label = { sprite, mat, tex };
+      site.mats.push(mat);
+    }
+    const L = site.label;
+    L.sprite.position.y = site.height + 2.4 + 0.45 * t;
+    L.mat.opacity = Math.min(t / 0.35, 1) * clamp(1 - (t - 4.5) / 1.5, 0, 1);
+    L.sprite.visible = L.mat.opacity > 0.01;
+  }
+
+  _finalize(site) {
+    const B = this._buildings;
+    if (B) {
+      B.setRise(site.id, 1, site.shownCap);
+      B.setFinishGlow(site.id, 1, 0);
+    }
+    this._dispose(site);
+    this.sites.delete(site.id);
+  }
+
+  _dispose(site) {
+    this.scene.remove(site.group);
+    if (site.sparks) site.sparks.dispose();
+    if (site.label) site.label.tex.dispose();
+    for (const m of site.mats) m.dispose();
+  }
+
+  reset() {
+    for (const site of this.sites.values()) this._dispose(site);
+    this.sites.clear();
+  }
+}

web/city/fpv.js

@@ -0,0 +1,218 @@
+// NEMOCITY — "Walk the streets". Pointer-lock first person: WASD + Shift
+// (5 / 9 m/s, exponential accel), eye 1.65 m, integrated in the fixed-step
+// via scene.js's setFPV rig-swap hook. Collision is occupancy-grid only —
+// a r=0.35 m circle axis-slid against ground.isWalkable, clamped to the plot
+// minus a 2-cell margin (soft velocity damp + body.fpv-edge vignette hint).
+// Tilt-shift goes to 0 on enter (DoF in first person is nauseating) and is
+// restored from the rig's height lerp on exit. Exit is pointerlockchange
+// (releasing the lock), never a keydown trap.
+import * as THREE from "three";
+import { PointerLockControls } from "three/addons/controls/PointerLockControls.js";
+import { GRID, CELL } from "./constants.js";
+import { clamp, cellToWorld, worldToCell, cellKey } from "./util.js";
+
+const EYE = 1.65;
+const WALK = 5, RUN = 9;            // m/s (contract)
+const ACCEL = 9;                    // exp accel/decel rate
+const R = 0.35;                     // player collision circle, m
+const PLOT_HALF = (GRID * CELL) / 2;
+const BOUND = PLOT_HALF - 2 * CELL; // plot minus 2-cell margin
+const SOFT = 6;                     // soft-edge damp band, m
+const SPAWN_SEARCH = 16;            // Chebyshev rings searched for a road cell
+const FADE_MS = 300;
+
+/** main.js hides the Walk affordance on touch devices (v0: no mobile FPV). */
+export const isTouchDevice = () =>
+  "ontouchstart" in window || (navigator.maxTouchPoints || 0) > 0;
+
+const _dir = new THREE.Vector3();
+const _euler = new THREE.Euler(0, 0, 0, "YXZ");
+
+export class FPV {
+  constructor(camera, dom, ground, onExit) {
+    this.camera = camera;
+    this.dom = dom;
+    this.ground = ground;
+    this.onExit = onExit;
+    this.active = false;
+    this.vel = new THREE.Vector2();  // world-space (x, z) velocity
+    this.keys = new Set();
+    this._app = null;
+    this._rig = null;
+    this._roads = null;              // optional roadCells Map (setRoadLookup)
+    this._edge = false;
+
+    this.controls = new PointerLockControls(camera, dom);
+    this.controls.minPolarAngle = 0.12;
+    this.controls.maxPolarAngle = Math.PI - 0.25;
+    this.controls.addEventListener("unlock", () => this.exit());
+
+    document.addEventListener("keydown", (e) => {
+      if (this.active) this.keys.add(e.code);
+    });
+    document.addEventListener("keyup", (e) => this.keys.delete(e.code));
+  }
+
+  /** Wire the F-key toggle + app/rig refs. Call once from main.js:
+   *  fpv.bindKeys(app, rig). Enter spawns near rig.lookPoint(). */
+  bindKeys(app, rig) {
+    this._app = app;
+    this._rig = rig;
+    window.addEventListener("keydown", (e) => {
+      if (e.code !== "KeyF" || isTouchDevice()) return;
+      const t = e.target;
+      if (t && (t.tagName === "INPUT" || t.tagName === "TEXTAREA" || t.isContentEditable)) return;
+      if (this.active) this.exit();
+      else this.enter(rig.lookPoint());
+    });
+    return this;
+  }
+
+  /** Prefer spawning on real road cells (pass world.roadCells); without it the
+   *  spawn search falls back to the ground occupancy mirror. */
+  setRoadLookup(roadCells) {
+    this._roads = roadCells;
+  }
+
+  _isRoad(cx, cz) {
+    const key = cellKey(cx, cz);
+    if (this._roads) return this._roads.has(key);
+    return this.ground._occ?.get(key) === "road"; // occupancy mirror fallback
+  }
+
+  /** Nearest walkable road cell to a world point (rings outward), falling
+   *  back to any walkable cell. Returns a clamped world [x, z]. */
+  _spawn(p) {
+    const [scx, scz] = worldToCell(p?.x ?? 0, p?.z ?? 0);
+    let road = null, walk = null;
+    for (let r = 0; r <= SPAWN_SEARCH && !road; r++) {
+      for (let cz = scz - r; cz <= scz + r && !road; cz++) {
+        for (let cx = scx - r; cx <= scx + r; cx++) {
+          if (Math.max(Math.abs(cx - scx), Math.abs(cz - scz)) !== r) continue;
+          if (!this.ground.isWalkable(cx, cz)) continue;
+          if (!walk) walk = [cx, cz];
+          if (this._isRoad(cx, cz)) { road = [cx, cz]; break; }
+        }
+      }
+    }
+    const [cx, cz] = road || walk || [scx, scz];
+    const [x, z] = cellToWorld(cx, cz);
+    return [clamp(x, -BOUND + 1, BOUND - 1), clamp(z, -BOUND + 1, BOUND - 1)];
+  }
+
+  /** Drop to the street near spawnNear ({x, z} or Vector3). Must be called
+   *  from a user gesture (pointer lock requirement). */
+  enter(spawnNear) {
+    if (this.active) return;
+    this.active = true;
+    const [x, z] = this._spawn(spawnNear);
+    // level the view: keep yaw, zero pitch, street-level eye
+    _euler.setFromQuaternion(this.camera.quaternion, "YXZ");
+    _euler.x = 0;
+    _euler.z = 0;
+    this.camera.quaternion.setFromEuler(_euler);
+    this.camera.position.set(x, EYE + this.ground.heightAt(x, z), z);
+    this.vel.set(0, 0);
+    this.keys.clear();
+    document.body.classList.add("fpv-fade");
+    setTimeout(() => {
+      document.body.classList.remove("fpv-fade");
+      if (this.active) document.body.classList.add("fpv-on");
+    }, FADE_MS);
+    this._app?.setFPV(this);          // scene.js rig-swap hook
+    this._app?.post?.setTiltShift(0); // hard requirement: no DoF in FPV
+    this.controls.lock();             // sync, inside the user gesture
+  }
+
+  /** Leave FPV (pointer unlock, F toggle, or programmatic). Restores the orbit
+   *  rig via onExit(playerPos) — main.js gazes the rig over the player. */
+  exit() {
+    if (!this.active) return;
+    this.active = false;
+    if (this.controls.isLocked) this.controls.unlock();
+    const pos = this.camera.position.clone();
+    document.body.classList.add("fpv-fade");
+    document.body.classList.remove("fpv-on");
+    if (this._edge) {
+      this._edge = false;
+      document.body.classList.remove("fpv-edge");
+    }
+    setTimeout(() => document.body.classList.remove("fpv-fade"), FADE_MS);
+    this._app?.setFPV(null);
+    if (this._app?.post && this._rig) {
+      this._app.post.setTiltShift(this._rig.tiltShiftAmount());
+    }
+    this.onExit?.(pos);
+  }
+
+  /** True if the r=0.35 circle, swept over [x0,x1]x[z0,z1], overlaps any
+   *  non-walkable cell. */
+  _blocked(x0, x1, z0, z1) {
+    const [ax, az] = worldToCell(Math.min(x0, x1) - R, Math.min(z0, z1) - R);
+    const [bx, bz] = worldToCell(Math.max(x0, x1) + R, Math.max(z0, z1) + R);
+    for (let cz = az; cz <= bz; cz++) {
+      for (let cx = ax; cx <= bx; cx++) {
+        if (!this.ground.isWalkable(cx, cz)) return true;
+      }
+    }
+    return false;
+  }
+
+  /** Called from the scene fixed-step (setFPV hook); input-driven, dt only. */
+  update(dt) {
+    if (!this.active) return;
+    const k = this.keys;
+    let fx = 0, fz = 0; // strafe right / forward intent
+    if (k.has("KeyW") || k.has("ArrowUp")) fz += 1;
+    if (k.has("KeyS") || k.has("ArrowDown")) fz -= 1;
+    if (k.has("KeyD") || k.has("ArrowRight")) fx += 1;
+    if (k.has("KeyA") || k.has("ArrowLeft")) fx -= 1;
+    const speed = k.has("ShiftLeft") || k.has("ShiftRight") ? RUN : WALK;
+
+    // camera-yaw basis flattened to the ground plane
+    this.camera.getWorldDirection(_dir);
+    _dir.y = 0;
+    if (_dir.lengthSq() < 1e-6) _dir.set(0, 0, -1);
+    _dir.normalize();
+    let tx = 0, tz = 0;
+    if (fx || fz) {
+      const n = 1 / Math.hypot(fx, fz);
+      tx = (_dir.x * fz + -_dir.z * fx) * n * speed;
+      tz = (_dir.z * fz + _dir.x * fx) * n * speed;
+    }
+    const a = 1 - Math.exp(-dt * ACCEL);
+    this.vel.x += (tx - this.vel.x) * a;
+    this.vel.y += (tz - this.vel.y) * a;
+
+    // soft edge: damp the outward component approaching the plot margin
+    const p = this.camera.position;
+    if (this.vel.x * Math.sign(p.x) > 0) {
+      this.vel.x *= clamp((BOUND - Math.abs(p.x)) / SOFT, 0, 1);
+    }
+    if (this.vel.y * Math.sign(p.z) > 0) {
+      this.vel.y *= clamp((BOUND - Math.abs(p.z)) / SOFT, 0, 1);
+    }
+
+    // axis-slide: test X then Z displacement independently, cancel only the
+    // blocked axis (sliding along building walls)
+    let nx = p.x + this.vel.x * dt;
+    if (this._blocked(p.x, nx, p.z, p.z)) {
+      nx = p.x;
+      this.vel.x = 0;
+    }
+    let nz = p.z + this.vel.y * dt;
+    if (this._blocked(nx, nx, p.z, nz)) {
+      nz = p.z;
+      this.vel.y = 0;
+    }
+    nx = clamp(nx, -BOUND, BOUND);
+    nz = clamp(nz, -BOUND, BOUND);
+    p.set(nx, EYE + this.ground.heightAt(nx, nz), nz);
+
+    const edge = Math.max(Math.abs(nx), Math.abs(nz)) > BOUND - SOFT;
+    if (edge !== this._edge) {
+      this._edge = edge;
+      document.body.classList.toggle("fpv-edge", edge);
+    }
+  }
+}

web/city/ground.js

@@ -0,0 +1,336 @@
+// NEMOCITY — the table the miniature city stands on: chunked vertex-colored
+// lawn, the recessed river, per-cell tinting (park/dirt/road undercoat), one
+// shared contact-shadow blob InstancedMesh, and the occupancy mirror that FPV
+// collision + citizens walk against. Roads themselves are drawn by roads.js;
+// ground only undercoats their cells so lawn never peeks through.
+import * as THREE from "three";
+import { mulberry32 } from "./rng.js";
+import { GRID, CELL, riverCols } from "./constants.js";
+import { cellKey } from "./util.js";
+import { PALETTE } from "./palette.js";
+
+const HALF = GRID / 2;
+const CHUNK = 16;               // cells per chunk side -> 4x4 chunks
+const WATER_Y = -0.15;
+const BLOB_Y = 0.035;           // above road quads (y=0.02), below curbs
+const BLOB_MAX = 2048;
+
+// type -> [hex, lightness jitter amplitude]
+const TINTS = {
+  lawn: [PALETTE.lawn, 0.03],
+  park: [PALETTE.park, 0.02],
+  dirt: [PALETTE.dirt, 0.015],
+  road: [PALETTE.asphalt, 0],
+  plaza: [PALETTE.sidewalk, 0.01],
+};
+
+const _m4 = new THREE.Matrix4();
+const _color = new THREE.Color();
+
+export class Ground {
+  constructor(scene, quality) {
+    this.scene = scene;
+    this.quality = quality;
+    this.group = new THREE.Group();
+    this.group.matrixAutoUpdate = false;
+    scene.add(this.group);
+
+    this._occ = null;          // occupancy Map mirror (set by City)
+    this._roadKeys = new Set();
+    this._cells = new Map();   // cellKey -> { attr, offset } for tintCell
+    this._water = new Set();
+    for (let cz = -HALF; cz < HALF; cz++) {
+      for (const cx of riverCols(cz)) this._water.add(cellKey(cx, cz));
+    }
+
+    this._buildChunks();
+    this._buildWater();
+    this._buildBlobs();
+  }
+
+  // ---- lawn chunks -------------------------------------------------------
+  _buildChunks() {
+    const mat = new THREE.MeshStandardMaterial({
+      vertexColors: true, roughness: 0.95, metalness: 0, envMapIntensity: 0.25,
+    });
+    for (let cj = 0; cj < GRID / CHUNK; cj++) {
+      for (let ci = 0; ci < GRID / CHUNK; ci++) {
+        const pos = [], col = [], nrm = [], idx = [];
+        for (let lz = 0; lz < CHUNK; lz++) {
+          for (let lx = 0; lx < CHUNK; lx++) {
+            const cx = -HALF + ci * CHUNK + lx;
+            const cz = -HALF + cj * CHUNK + lz;
+            if (this._water.has(cellKey(cx, cz))) continue;
+            const base = pos.length / 3;
+            const x0 = cx * CELL, z0 = cz * CELL;
+            pos.push(x0, 0, z0, x0 + CELL, 0, z0, x0, 0, z0 + CELL, x0 + CELL, 0, z0 + CELL);
+            this._cellColor(cx, cz, "lawn", _color);
+            for (let k = 0; k < 4; k++) {
+              col.push(_color.r, _color.g, _color.b);
+              nrm.push(0, 1, 0);
+            }
+            idx.push(base, base + 2, base + 1, base + 1, base + 2, base + 3);
+            this._cells.set(cellKey(cx, cz), { offset: base });
+          }
+        }
+        const geo = new THREE.BufferGeometry();
+        geo.setAttribute("position", new THREE.Float32BufferAttribute(pos, 3));
+        geo.setAttribute("normal", new THREE.Float32BufferAttribute(nrm, 3));
+        geo.setAttribute("color", new THREE.Float32BufferAttribute(col, 3));
+        geo.setIndex(idx);
+        const mesh = new THREE.Mesh(geo, mat);
+        mesh.receiveShadow = true;
+        mesh.matrixAutoUpdate = false;
+        this.group.add(mesh);
+        // patch the cell records of this chunk with its color attribute
+        const attr = geo.attributes.color;
+        for (let lz = 0; lz < CHUNK; lz++) {
+          for (let lx = 0; lx < CHUNK; lx++) {
+            const key = cellKey(-HALF + ci * CHUNK + lx, -HALF + cj * CHUNK + lz);
+            const rec = this._cells.get(key);
+            if (rec && !rec.attr) rec.attr = attr;
+          }
+        }
+      }
+    }
+  }
+
+  /** Seeded per-cell color: base tint hex + lightness jitter from (cx,cz). */
+  _cellColor(cx, cz, type, out = new THREE.Color()) {
+    const [hex, jit] = TINTS[type] || TINTS.lawn;
+    out.set(hex);
+    if (jit > 0) {
+      const rng = mulberry32((((cx + HALF) * 73856093) ^ ((cz + HALF) * 19349663)) >>> 0);
+      out.offsetHSL(0, 0, (rng() * 2 - 1) * jit);
+    }
+    return out;
+  }
+
+  /** Recolor one cell. type: lawn | park | dirt | road | plaza. */
+  tintCell(cx, cz, type) {
+    const rec = this._cells.get(cellKey(cx, cz));
+    if (!rec || !rec.attr) return;
+    this._cellColor(cx, cz, type, _color);
+    for (let k = 0; k < 4; k++) rec.attr.setXYZ(rec.offset + k, _color.r, _color.g, _color.b);
+    rec.attr.needsUpdate = true;
+  }
+
+  /** Undercoat road cells in asphalt so lawn never peeks under roads.js quads.
+   *  Accepts the City roadCells Map (or any iterable of cell keys); append-only. */
+  setRoadCells(roadCells) {
+    const keys = roadCells && roadCells.keys ? roadCells.keys() : roadCells || [];
+    for (const key of keys) {
+      if (this._roadKeys.has(key)) continue;
+      this._roadKeys.add(key);
+      const [cx, cz] = key.split(",").map(Number);
+      this.tintCell(cx, cz, "road");
+    }
+  }
+
+  // ---- river ---------------------------------------------------------------
+  _buildWater() {
+    const pos = [], col = [], idx = [];
+    const water = new THREE.Color(PALETTE.water);
+    const v = new THREE.Color();
+    const dark = (x, centerX) => {
+      // darken 12% at the river centerline, fading out across one cell
+      const t = Math.max(0, 1 - Math.abs(x - centerX) / CELL);
+      v.copy(water).multiplyScalar(1 - 0.12 * t);
+      return v;
+    };
+    const bankPos = [], bankCol = [], bankIdx = [];
+    const bank = new THREE.Color(PALETTE.dirt).multiplyScalar(0.72);
+    for (let cz = -HALF; cz < HALF; cz++) {
+      const cols = riverCols(cz);
+      const centerX = (cols[0] + 1) * CELL;
+      for (const cx of cols) {
+        const base = pos.length / 3;
+        const x0 = cx * CELL, z0 = cz * CELL;
+        const corners = [[x0, z0], [x0 + CELL, z0], [x0, z0 + CELL], [x0 + CELL, z0 + CELL]];
+        for (const [x, z] of corners) {
+          pos.push(x, WATER_Y, z);
+          const c = dark(x, centerX);
+          col.push(c.r, c.g, c.b);
+        }
+        idx.push(base, base + 2, base + 1, base + 1, base + 2, base + 3);
+        // dirt bank wall on each edge facing non-water (off-grid counts as water)
+        const edges = [
+          [0, -1, x0, z0, x0 + CELL, z0],
+          [0, 1, x0, z0 + CELL, x0 + CELL, z0 + CELL],
+          [-1, 0, x0, z0, x0, z0 + CELL],
+          [1, 0, x0 + CELL, z0, x0 + CELL, z0 + CELL],
+        ];
+        for (const [dx, dz, ax, az, bx, bz] of edges) {
+          const ncx = cx + dx, ncz = cz + dz;
+          const offGrid = ncx < -HALF || ncx >= HALF || ncz < -HALF || ncz >= HALF;
+          if (offGrid || this._water.has(cellKey(ncx, ncz))) continue;
+          const b = bankPos.length / 3;
+          bankPos.push(ax, 0, az, bx, 0, bz, ax, WATER_Y, az, bx, WATER_Y, bz);
+          for (let k = 0; k < 4; k++) bankCol.push(bank.r, bank.g, bank.b);
+          bankIdx.push(b, b + 2, b + 1, b + 1, b + 2, b + 3);
+        }
+      }
+    }
+
+    const geo = new THREE.BufferGeometry();
+    geo.setAttribute("position", new THREE.Float32BufferAttribute(pos, 3));
+    geo.setAttribute("aTint", new THREE.Float32BufferAttribute(col, 3));
+    geo.setIndex(idx);
+    this._waterMat = new THREE.ShaderMaterial({
+      fog: true,
+      uniforms: THREE.UniformsUtils.merge([THREE.UniformsLib.fog, { uTime: { value: 0 } }]),
+      vertexShader: /* glsl */ `
+        attribute vec3 aTint;
+        varying vec3 vColor;
+        varying vec3 vWp;
+        #include <common>
+        #include <fog_pars_vertex>
+        void main() {
+          vColor = aTint;
+          vec4 wp = modelMatrix * vec4(position, 1.0);
+          vWp = wp.xyz;
+          vec4 mvPosition = viewMatrix * wp;
+          gl_Position = projectionMatrix * mvPosition;
+          #include <fog_vertex>
+        }`,
+      fragmentShader: /* glsl */ `
+        #include <common>
+        #include <fog_pars_fragment>
+        uniform float uTime;
+        varying vec3 vColor;
+        varying vec3 vWp;
+        void main() {
+          float w = 1.0 + 0.05 * sin(uTime * 0.9 + vWp.x * 0.23 + vWp.z * 0.17);
+          gl_FragColor = vec4(vColor * w, 1.0);
+          #include <fog_fragment>
+        }`,
+    });
+    this.water = new THREE.Mesh(geo, this._waterMat);
+    this.water.matrixAutoUpdate = false;
+    this.group.add(this.water);
+
+    const bGeo = new THREE.BufferGeometry();
+    bGeo.setAttribute("position", new THREE.Float32BufferAttribute(bankPos, 3));
+    bGeo.setAttribute("color", new THREE.Float32BufferAttribute(bankCol, 3));
+    bGeo.setIndex(bankIdx);
+    bGeo.computeVertexNormals();
+    const banks = new THREE.Mesh(bGeo, new THREE.MeshStandardMaterial({
+      vertexColors: true, roughness: 1, metalness: 0, side: THREE.DoubleSide, envMapIntensity: 0.25,
+    }));
+    banks.matrixAutoUpdate = false;
+    this.group.add(banks);
+  }
+
+  // ---- contact-shadow blobs (fake AO under buildings/trees/cars) -----------
+  _buildBlobs() {
+    const canvas = document.createElement("canvas");
+    canvas.width = canvas.height = 128;
+    const ctx = canvas.getContext("2d");
+    const g = ctx.createRadialGradient(64, 64, 4, 64, 64, 64);
+    g.addColorStop(0, "rgba(0,0,0,0.9)");
+    g.addColorStop(0.55, "rgba(0,0,0,0.42)");
+    g.addColorStop(1, "rgba(0,0,0,0)");
+    ctx.fillStyle = g;
+    ctx.fillRect(0, 0, 128, 128);
+    const tex = new THREE.CanvasTexture(canvas);
+
+    const geo = new THREE.PlaneGeometry(1, 1).rotateX(-Math.PI / 2);
+    this._blobOpacity = new THREE.InstancedBufferAttribute(new Float32Array(BLOB_MAX), 1);
+    this._blobOpacity.setUsage(THREE.DynamicDrawUsage);
+    geo.setAttribute("aOpacity", this._blobOpacity);
+    const mat = new THREE.ShaderMaterial({
+      transparent: true, depthWrite: false,
+      uniforms: { tMap: { value: tex } },
+      vertexShader: /* glsl */ `
+        attribute float aOpacity;
+        varying vec2 vUv;
+        varying float vOp;
+        void main() {
+          vUv = uv;
+          vOp = aOpacity;
+          #ifdef USE_INSTANCING
+          vec4 wp = modelMatrix * instanceMatrix * vec4(position, 1.0);
+          #else
+          vec4 wp = modelMatrix * vec4(position, 1.0);
+          #endif
+          gl_Position = projectionMatrix * viewMatrix * wp;
+        }`,
+      fragmentShader: /* glsl */ `
+        uniform sampler2D tMap;
+        varying vec2 vUv;
+        varying float vOp;
+        void main() {
+          float a = texture2D(tMap, vUv).a * vOp;
+          if (a < 0.004) discard;
+          gl_FragColor = vec4(0.09, 0.075, 0.06, a);
+        }`,
+    });
+    this.blobs = new THREE.InstancedMesh(geo, mat, BLOB_MAX);
+    this.blobs.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+    this.blobs.count = 0;
+    this.blobs.frustumCulled = false;
+    this.blobs.renderOrder = 2;
+    this.group.add(this.blobs);
+    this._blobFree = [];
+    this._blobTop = 0;
+  }
+
+  /**
+   * Allocate one contact-shadow quad. scale = world units across; buildings use
+   * footprint*1.25 @ opacity 0.22, trees ~0.5*canopy, cars/citizens their own.
+   * Returns { index, set(x,z,scale,opacity), release() }.
+   */
+  addBlob(x, z, scale, opacity) {
+    const i = this._blobFree.length ? this._blobFree.pop() : this._blobTop < BLOB_MAX ? this._blobTop++ : -1;
+    if (i < 0) return { index: -1, set() {}, release() {} }; // pool exhausted: silent no-op
+    this.blobs.count = this._blobTop;
+    const write = (x, z, scale, opacity) => {
+      _m4.makeScale(scale, 1, scale).setPosition(x, BLOB_Y, z);
+      this.blobs.setMatrixAt(i, _m4);
+      this.blobs.instanceMatrix.needsUpdate = true;
+      this._blobOpacity.setX(i, opacity);
+      this._blobOpacity.needsUpdate = true;
+    };
+    write(x, z, scale, opacity);
+    return {
+      index: i,
+      set: write,
+      release: () => {
+        write(0, 0, 0, 0);
+        this._blobFree.push(i);
+      },
+    };
+  }
+
+  // ---- occupancy mirror -----------------------------------------------------
+  /** Mirror the City's occupancy Map (cellKey -> water|road|building|park|plaza). */
+  setOccupancy(map) {
+    this._occ = map;
+  }
+
+  /** Roads/sidewalk/park/plaza/empty are walkable; buildings and water are not.
+   *  Bridge cells carry "road" occupancy, so they pass. */
+  isWalkable(cx, cz) {
+    if (cx < -HALF || cx >= HALF || cz < -HALF || cz >= HALF) return false;
+    const v = this._occ ? this._occ.get(cellKey(cx, cz)) : undefined;
+    return v !== "building" && v !== "water";
+  }
+
+  /** Flat city: the walkable plane is y=0 everywhere. */
+  heightAt() {
+    return 0;
+  }
+
+  /** Repaint everything lawn (City.reset re-applies roads/parks afterwards). */
+  reset() {
+    this._roadKeys.clear();
+    for (const key of this._cells.keys()) {
+      const [cx, cz] = key.split(",").map(Number);
+      this.tintCell(cx, cz, "lawn");
+    }
+  }
+
+  update(dt, simTime) {
+    this._waterMat.uniforms.uTime.value = simTime;
+  }
+}

web/city/palette.js

@@ -0,0 +1,78 @@
+// NEMOCITY — the Visual Bible palette ("Golden Hour Toybox"). Every hex the
+// renderer uses lives here; constants.js holds only engine-mirrored values.
+
+export const PALETTE = {
+  lawn: "#8FC474",        // ±3% per-cell lightness jitter via vertex colors
+  park: "#6FB257",
+  dirt: "#CFB78F",        // construction dirt lot
+  water: "#58AFC7",       // darken 12% toward river center
+  sidewalk: "#D6D2C4",    // 0.06 u curb lip
+  asphalt: "#565B66",     // warm dark gray, never black
+  marking: "#F5F1E6",     // lane markings warm-white
+  centerline: "#EFC75E",  // avenue double yellow
+  civic: "#F8F4EA",       // bank / town_hall / hospital / church facades
+  accent: "#E07856",      // terracotta UI primary
+};
+
+// 8 facade hexes; per-instance seeded jitter: ±6° hue, ±5% lightness.
+export const FACADES = [
+  "#F4E9D0", // cream
+  "#E07856", // terracotta
+  "#F2CC8F", // butter
+  "#EC9AA2", // coral
+  "#8FB8D8", // powder blue
+  "#7FB69E", // dusty teal
+  "#A9B98A", // sage
+  "#BD6B6E", // brick
+];
+export const CIVIC_KINDS = ["bank", "town_hall", "hospital", "church"];
+
+// kind -> roof hex (clay houses/church, slate apartments/school,
+// charcoal offices/towers, gravel flat commercial). park/plaza have no roof.
+export const ROOFS = {
+  house: "#C06B4F", townhouse: "#C06B4F", church: "#C06B4F",
+  apartments: "#5C6470", school: "#5C6470",
+  office: "#3F454F", tower: "#3F454F",
+  cafe: "#D9D5CB", shop: "#D9D5CB", market: "#D9D5CB", bank: "#D9D5CB",
+  hospital: "#D9D5CB", fire_station: "#D9D5CB", warehouse: "#D9D5CB",
+  factory: "#D9D5CB", stadium: "#D9D5CB", town_hall: "#D9D5CB",
+};
+
+// Night money colors (emissive only — bloom threshold keeps day pastels matte).
+export const EMISSIVE = {
+  window: "#FFC97A",
+  streetlamp: "#FFD9A0",
+  headlight: "#FFF6DC",
+  taillight: "#FF5340",
+  signalRed: "#FF5340",
+  signalAmber: "#FFB13D",
+  signalGreen: "#43D17C",
+  neonTeal: "#45E0C0",
+  neonPink: "#FF6FA6",
+  construction: "#FF8A3D",
+  congestion: "#E84F3D", // jammed-road additive underglow
+};
+
+export const SKY = {
+  day:   { zenith: "#7BC1E8", horizon: "#FFE9C2" },
+  night: { zenith: "#141C36", horizon: "#2C3760" }, // indigo, never black
+};
+
+// Fog color = the horizon color of the current sky blend.
+export const FOG = {
+  day:   { near: 140, far: 420 },
+  night: { near: 100, far: 360 },
+};
+
+// Sun (the ONE shadow-casting DirectionalLight) keyframes for sky.js.
+export const SUN = {
+  golden: { color: "#FFCE96", intensity: 2.4, elev: 28, az: 235 },
+  noon:   { color: "#FFE3BB", intensity: 2.8, elev: 62 },
+  dusk:   { color: "#FF9E62", intensity: 1.2 },
+  moon:   { color: "#8FA8D8", intensity: 0.15 },
+};
+
+export const HEMI = {
+  day:   { sky: "#BCD7EA", ground: "#C7B18E", intensity: 0.6 },
+  night: { sky: "#2B3450", ground: "#161B28", intensity: 0.3 },
+};

web/city/replay.js

@@ -0,0 +1,98 @@
+// GODSEED — wish performance scripts. Converts a WishTrace (+ its features)
+// into a timed event list, and runs it against sim time. Drives both the
+// ?mock=1 looping demo feed and Genesis Log replays — same liturgy either way.
+
+const READ_WORD = 0.16;   // seconds per reading word (the god reads slowly)
+const THINK_WORD = 0.085; // seconds per thought word
+const CALL_SETTLE = 3.1;  // camera move + world delta animation
+const GAP = 0.55;
+
+function words(text) {
+  return String(text ?? "").split(/(\s+)/).filter((w) => w.length);
+}
+
+/**
+ * Build a timed event script from a WishTrace-shaped object.
+ * trace: {wish_id, text, reading, turns:[{thought, call|null, observation}], epitaph}
+ * features: ordered Feature[] minted by this wish (one per accepted call).
+ * Events: {at, type:'started'|'token'|'phase'|'call'|'delta'|'granted', ...}
+ */
+export function buildWishScript(trace, features) {
+  const ev = [];
+  let t = 0;
+  let fi = 0;
+  ev.push({ at: t, type: "started", wish_id: trace.wish_id, text: trace.text });
+  t += 0.8;
+
+  ev.push({ at: t, type: "phase", phase: "reading" });
+  for (const w of words(trace.reading)) {
+    ev.push({ at: t, type: "token", text: w });
+    if (w.trim()) t += READ_WORD * (0.7 + Math.min(w.length, 9) * 0.06);
+  }
+  t += GAP * 1.6;
+
+  for (const turn of trace.turns ?? []) {
+    ev.push({ at: t, type: "phase", phase: "turn" });
+    for (const w of words(turn.thought)) {
+      ev.push({ at: t, type: "token", text: w });
+      if (w.trim()) t += THINK_WORD * (0.7 + Math.min(w.length, 9) * 0.06);
+    }
+    t += GAP;
+    if (turn.call) {
+      const rejected = String(turn.observation ?? "").startsWith("rejected");
+      ev.push({ at: t, type: "call", call: turn.call });
+      if (!rejected && fi < features.length) {
+        ev.push({ at: t + 0.4, type: "delta", feature: features[fi++] });
+        t += CALL_SETTLE;
+      } else {
+        t += 0.9;
+      }
+      if (turn.observation) {
+        ev.push({ at: t, type: "token", text: `\n› ${turn.observation}\n` });
+        t += GAP;
+      }
+    }
+  }
+
+  t += 0.6;
+  ev.push({ at: t, type: "granted", wish_id: trace.wish_id, epitaph: trace.epitaph });
+  return { events: ev, duration: t + 0.5 };
+}
+
+/** Runs an event script against monotonically increasing sim time. */
+export class ScriptRunner {
+  constructor(handlers = {}) {
+    this.handlers = handlers;
+    this.events = null;
+    this.i = 0;
+    this.t0 = 0;
+  }
+
+  start(script, now) {
+    this.events = script.events;
+    this.duration = script.duration;
+    this.i = 0;
+    this.t0 = now;
+  }
+
+  get active() {
+    return !!this.events && this.i < this.events.length;
+  }
+
+  get done() {
+    return !!this.events && this.i >= this.events.length;
+  }
+
+  cancel() {
+    this.events = null;
+  }
+
+  update(now) {
+    if (!this.events) return;
+    const local = now - this.t0;
+    while (this.i < this.events.length && this.events[this.i].at <= local) {
+      const e = this.events[this.i++];
+      this.handlers[e.type]?.(e);
+    }
+  }
+}

web/city/rng.js

@@ -0,0 +1,56 @@
+// GODSEED — deterministic randomness.
+// Every feature carries an engine-assigned seed; the renderer is a pure
+// function of (feature list, seeds). mulberry32 here MUST stay byte-stable.
+
+/** mulberry32 PRNG — returns a function yielding floats in [0,1). */
+export function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function () {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Integer lattice hash → [0,1). Stable across calls; used by value noise. */
+function hash3i(x, y, z, seed) {
+  let h = (x * 374761393 + y * 668265263 + z * 2147483647 + seed * 144665) | 0;
+  h = Math.imul(h ^ (h >>> 13), 1274126177);
+  h ^= h >>> 16;
+  return (h >>> 0) / 4294967296;
+}
+
+function smooth(t) {
+  return t * t * (3 - 2 * t);
+}
+
+/** 3D value noise in [0,1], seeded. */
+export function valueNoise3(x, y, z, seed) {
+  const ix = Math.floor(x), iy = Math.floor(y), iz = Math.floor(z);
+  const fx = smooth(x - ix), fy = smooth(y - iy), fz = smooth(z - iz);
+  const c000 = hash3i(ix, iy, iz, seed), c100 = hash3i(ix + 1, iy, iz, seed);
+  const c010 = hash3i(ix, iy + 1, iz, seed), c110 = hash3i(ix + 1, iy + 1, iz, seed);
+  const c001 = hash3i(ix, iy, iz + 1, seed), c101 = hash3i(ix + 1, iy, iz + 1, seed);
+  const c011 = hash3i(ix, iy + 1, iz + 1, seed), c111 = hash3i(ix + 1, iy + 1, iz + 1, seed);
+  const x00 = c000 + (c100 - c000) * fx;
+  const x10 = c010 + (c110 - c010) * fx;
+  const x01 = c001 + (c101 - c001) * fx;
+  const x11 = c011 + (c111 - c011) * fx;
+  const y0 = x00 + (x10 - x00) * fy;
+  const y1 = x01 + (x11 - x01) * fy;
+  return y0 + (y1 - y0) * fz;
+}
+
+/** Fractal value noise in [0,1], seeded; `oct` octaves. */
+export function fbm3(x, y, z, seed, oct = 3) {
+  let sum = 0, amp = 0.5, f = 1, norm = 0;
+  for (let i = 0; i < oct; i++) {
+    sum += valueNoise3(x * f, y * f, z * f, seed + i * 1013) * amp;
+    norm += amp;
+    amp *= 0.5;
+    f *= 2.07;
+  }
+  return sum / norm;
+}

web/city/roads.js

@@ -0,0 +1,481 @@
+// NEMOCITY — roads. Flat quads y=0.02 in ONE InstancedMesh with per-instance
+// UV offsets into a procedurally painted 512x512 canvas atlas (8 tiles; dashes,
+// stop lines, crosswalks and 6px soft dark edges baked — zero extra geometry).
+// Bridges get a raised deck (y=0.5) + railings + sloped ramp quads on approach
+// cells. Sidewalk curb strips appear on road cells that face zoned cells, and
+// instanced lamp posts (pole + emissive head + additive light-pool quad at
+// night) stand on every 3rd road cell. revealRoad() sweeps new cells in over
+// 4 s along laid order. Everything rebuilds idempotently from the City maps.
+import * as THREE from "three";
+import { mulberry32 } from "./rng.js";
+import { CELL } from "./constants.js";
+import { cellKey, clamp, easeOutBack } from "./util.js";
+import { PALETTE, EMISSIVE } from "./palette.js";
+
+// Road surface heights; traffic.js drives car y from these (keep in sync).
+export const ROAD_Y = { road: 0.02, ramp: 0.27, deck: 0.52 };
+
+const QMAX = 768;   // road quads + plaza paving + ramps (contract: road cells <= 600)
+const CURB_MAX = 1024;
+const LAMP_MAX = 256;
+const DECK_MAX = 48;
+const RAIL_MAX = 96;
+const REVEAL_S = 4;     // total sweep
+const REVEAL_POP = 0.9; // per-cell scale-in inside the sweep
+
+const TILES = { street: 0, avenue: 1, cross: 2, walk: 3, tee: 4, dead: 5, dirt: 6, plaza: 7 };
+const uvOf = (k) => [(k % 4) * 0.25, k < 4 ? 0.5 : 0]; // CanvasTexture flipY: row 0 = top half
+const DIRS = [[0, -1, 1], [1, 0, 2], [0, 1, 4], [-1, 0, 8]]; // dx, dz, mask bit (N E S W)
+const RAMP_PITCH = Math.atan2(ROAD_Y.deck - ROAD_Y.road, CELL);
+
+const _m4 = new THREE.Matrix4();
+const _q = new THREE.Quaternion();
+const _e = new THREE.Euler();
+const _s = new THREE.Vector3();
+const _p = new THREE.Vector3();
+
+// ---- atlas ------------------------------------------------------------------
+function paintAtlas() {
+  const cv = document.createElement("canvas");
+  cv.width = cv.height = 512;
+  const x = cv.getContext("2d");
+  const rng = mulberry32(0x70ad5);
+  const T = 128;
+  const at = (k) => [(k % 4) * T, k < 4 ? 0 : T];
+
+  const base = (k, hex = PALETTE.asphalt) => {
+    const [ox, oy] = at(k);
+    x.fillStyle = hex;
+    x.fillRect(ox, oy, T, T);
+    for (let i = 0; i < 90; i++) {
+      x.fillStyle = rng() < 0.5 ? "rgba(255,255,255,0.05)" : "rgba(0,0,0,0.07)";
+      x.fillRect(ox + rng() * (T - 2), oy + rng() * (T - 2), 1 + rng() * 2, 1 + rng() * 2);
+    }
+  };
+  // 6px-class soft dark edge baked on a CLOSED side (fake AO; n = tile top)
+  const edge = (k, side) => {
+    const [ox, oy] = at(k);
+    const E = 8;
+    const g =
+      side === "n" ? x.createLinearGradient(0, oy, 0, oy + E)
+      : side === "s" ? x.createLinearGradient(0, oy + T, 0, oy + T - E)
+      : side === "w" ? x.createLinearGradient(ox, 0, ox + E, 0)
+      : x.createLinearGradient(ox + T, 0, ox + T - E, 0);
+    g.addColorStop(0, "rgba(20,18,16,0.42)");
+    g.addColorStop(1, "rgba(20,18,16,0)");
+    x.fillStyle = g;
+    if (side === "n") x.fillRect(ox, oy, T, E);
+    else if (side === "s") x.fillRect(ox, oy + T - E, T, E);
+    else if (side === "w") x.fillRect(ox, oy, E, T);
+    else x.fillRect(ox + T - E, oy, E, T);
+  };
+  const dashesV = (k, cx, w = 3, y0 = 6, y1 = T) => {
+    const [ox, oy] = at(k);
+    x.fillStyle = PALETTE.marking;
+    for (let y = y0; y < y1 - 6; y += 22) x.fillRect(ox + cx - w / 2, oy + y, w, 12);
+  };
+  const lineV = (k, cx, color, w = 3) => {
+    const [ox, oy] = at(k);
+    x.fillStyle = color;
+    x.fillRect(ox + cx - w / 2, oy + 4, w, T - 8);
+  };
+
+  base(TILES.street); edge(TILES.street, "w"); edge(TILES.street, "e");
+  dashesV(TILES.street, 64);
+
+  base(TILES.avenue); edge(TILES.avenue, "w"); edge(TILES.avenue, "e");
+  lineV(TILES.avenue, 60, PALETTE.centerline); lineV(TILES.avenue, 68, PALETTE.centerline);
+  lineV(TILES.avenue, 9, PALETTE.marking, 2); lineV(TILES.avenue, 119, PALETTE.marking, 2);
+  dashesV(TILES.avenue, 34, 2); dashesV(TILES.avenue, 94, 2);
+
+  base(TILES.cross);
+  { const [ox, oy] = at(TILES.cross);            // manhole for charm
+    x.fillStyle = "rgba(0,0,0,0.18)"; x.beginPath();
+    x.arc(ox + 84, oy + 46, 6, 0, Math.PI * 2); x.fill(); }
+
+  base(TILES.walk); edge(TILES.walk, "w"); edge(TILES.walk, "e");
+  { const [ox, oy] = at(TILES.walk);             // zebra toward tile top + stop line
+    x.fillStyle = PALETTE.marking;
+    for (let i = 0; i < 7; i++) x.fillRect(ox + 14 + i * 15, oy + 8, 9, 22);
+    x.fillRect(ox + 66, oy + 38, 54, 5); }       // stop line, right lane (heading north)
+  dashesV(TILES.walk, 64, 3, 52);
+
+  base(TILES.tee); edge(TILES.tee, "w");         // closed side = W at rot 0
+  dashesV(TILES.tee, 64);
+  { const [ox, oy] = at(TILES.tee);
+    x.fillStyle = PALETTE.marking;
+    for (let x0 = 70; x0 < T - 8; x0 += 22) x.fillRect(ox + x0, oy + 62, 12, 3); }
+
+  base(TILES.dead); edge(TILES.dead, "n"); edge(TILES.dead, "w"); edge(TILES.dead, "e");
+  { const [ox, oy] = at(TILES.dead);             // parking bays along the right side
+    x.fillStyle = PALETTE.marking;
+    x.fillRect(ox + 96, oy + 10, 2, 108);
+    for (let y = 10; y <= 118; y += 18) x.fillRect(ox + 96, oy + y, 30, 2); }
+
+  base(TILES.dirt, PALETTE.dirt);
+  for (const s of ["n", "s", "w", "e"]) edge(TILES.dirt, s);
+  { const [ox, oy] = at(TILES.dirt);
+    for (let i = 0; i < 60; i++) {
+      x.fillStyle = "rgba(90,70,45,0.16)";
+      x.fillRect(ox + rng() * (T - 3), oy + rng() * (T - 3), 2 + rng() * 2, 2 + rng() * 2);
+    } }
+
+  base(TILES.plaza, PALETTE.sidewalk);
+  { const [ox, oy] = at(TILES.plaza);            // paving grid
+    x.fillStyle = "rgba(0,0,0,0.10)";
+    for (let i = 32; i < T; i += 32) { x.fillRect(ox + i, oy, 1, T); x.fillRect(ox, oy + i, T, 1); } }
+
+  const tex = new THREE.CanvasTexture(cv);
+  tex.colorSpace = THREE.SRGBColorSpace;
+  tex.anisotropy = 4;
+  return tex;
+}
+
+// tile + Y rotation from the 4-neighbor road mask (N1 E2 S4 W8).
+// interMask marks neighbor dirs that are intersections (for crosswalk approach).
+function tileFor(mask, klass, interMask) {
+  const straight = klass === "avenue" ? TILES.avenue : TILES.street;
+  const H = Math.PI / 2;
+  switch (mask) {
+    case 15: return [TILES.cross, 0];
+    case 7: return [TILES.tee, 0];        // missing W -> closed W
+    case 11: return [TILES.tee, H];       // missing S
+    case 13: return [TILES.tee, Math.PI]; // missing E
+    case 14: return [TILES.tee, -H];      // missing N
+    case 5:                                // N-S straight
+      if (interMask & 1) return [TILES.walk, 0];
+      if (interMask & 4) return [TILES.walk, Math.PI];
+      return [straight, 0];
+    case 10:                               // E-W straight
+      if (interMask & 2) return [TILES.walk, -H];
+      if (interMask & 8) return [TILES.walk, H];
+      return [straight, H];
+    case 1: return [TILES.dead, Math.PI]; // open N
+    case 2: return [TILES.dead, H];       // open E
+    case 4: return [TILES.dead, 0];       // open S
+    case 8: return [TILES.dead, -H];      // open W
+    default: return mask ? [TILES.cross, 0] : [straight, 0]; // corners + orphan
+  }
+}
+
+export class Roads {
+  constructor(scene, quality, city = null) {
+    this.scene = scene;
+    this.quality = quality;
+    this.city = city;
+    this.roadCellSet = new Set(); // ground/others may consult this
+    this.atlasTexture = paintAtlas();
+
+    this.group = new THREE.Group();
+    this.group.matrixAutoUpdate = false;
+    scene.add(this.group);
+
+    // ---- road/plaza/ramp quads: ONE InstancedMesh, per-instance uv offset --
+    const quadGeo = new THREE.PlaneGeometry(CELL, CELL).rotateX(-Math.PI / 2);
+    this._uvOffset = new THREE.InstancedBufferAttribute(new Float32Array(QMAX * 2), 2);
+    quadGeo.setAttribute("aUvOffset", this._uvOffset);
+    const quadMat = new THREE.MeshStandardMaterial({
+      map: this.atlasTexture, roughness: 0.96, metalness: 0, envMapIntensity: 0.25,
+    });
+    quadMat.onBeforeCompile = (sh) => {
+      sh.vertexShader = sh.vertexShader
+        .replace("#include <common>", "#include <common>\nattribute vec2 aUvOffset;")
+        .replace("#include <uv_vertex>", "#include <uv_vertex>\nvMapUv = uv * vec2(0.25, 0.5) + aUvOffset;");
+    };
+    this.quads = new THREE.InstancedMesh(quadGeo, quadMat, QMAX);
+    this.quads.receiveShadow = true;
+    this.quads.frustumCulled = false;
+    this.quads.count = 0;
+    this.group.add(this.quads);
+    this._quadInfo = []; // per-instance { x, y, z, yaw, pitch } for reveal recompose
+
+    // ---- sidewalk curbs ----------------------------------------------------
+    const curbGeo = new THREE.BoxGeometry(CELL * 0.98, 0.12, 0.55);
+    const curbMat = new THREE.MeshStandardMaterial({
+      color: PALETTE.sidewalk, roughness: 0.92, metalness: 0, envMapIntensity: 0.25,
+    });
+    this.curbs = new THREE.InstancedMesh(curbGeo, curbMat, CURB_MAX);
+    this.curbs.receiveShadow = true;
+    this.curbs.frustumCulled = false;
+    this.curbs.count = 0;
+    this.group.add(this.curbs);
+
+    // ---- bridge decks + railings ------------------------------------------
+    const deckGeo = new THREE.BoxGeometry(CELL, ROAD_Y.deck - 0.02, CELL);
+    const deckMat = new THREE.MeshStandardMaterial({
+      color: "#B9B4A6", roughness: 0.9, metalness: 0, envMapIntensity: 0.25,
+    });
+    this.decks = new THREE.InstancedMesh(deckGeo, deckMat, DECK_MAX);
+    this.decks.frustumCulled = false;
+    this.decks.count = 0;
+    this.group.add(this.decks);
+    const railGeo = new THREE.BoxGeometry(CELL * 1.02, 0.42, 0.1);
+    const railMat = new THREE.MeshStandardMaterial({
+      color: "#E8E4D8", roughness: 0.85, metalness: 0, envMapIntensity: 0.25,
+    });
+    this.rails = new THREE.InstancedMesh(railGeo, railMat, RAIL_MAX);
+    this.rails.frustumCulled = false;
+    this.rails.count = 0;
+    this.group.add(this.rails);
+
+    // ---- lamp posts: pole + emissive head + night light-pool quad ----------
+    const poleGeo = new THREE.CylinderGeometry(0.045, 0.06, 2.7, 6).translate(0, 1.35, 0);
+    const poleMat = new THREE.MeshStandardMaterial({
+      color: "#3E444E", roughness: 0.7, metalness: 0.2, envMapIntensity: 0.25,
+    });
+    this.lampPoles = new THREE.InstancedMesh(poleGeo, poleMat, LAMP_MAX);
+    this.lampPoles.frustumCulled = false;
+    this.lampPoles.count = 0;
+    this.group.add(this.lampPoles);
+    const headGeo = new THREE.BoxGeometry(0.5, 0.09, 0.15).translate(0.22, 2.66, 0);
+    this._headMat = new THREE.MeshStandardMaterial({
+      color: "#4A505A", roughness: 0.6, metalness: 0.2,
+      emissive: new THREE.Color(EMISSIVE.streetlamp), emissiveIntensity: 0,
+    });
+    this.lampHeads = new THREE.InstancedMesh(headGeo, this._headMat, LAMP_MAX);
+    this.lampHeads.frustumCulled = false;
+    this.lampHeads.count = 0;
+    this.group.add(this.lampHeads);
+    const poolGeo = new THREE.PlaneGeometry(3.2, 3.2).rotateX(-Math.PI / 2);
+    this._poolMat = new THREE.ShaderMaterial({
+      transparent: true, depthWrite: false, blending: THREE.AdditiveBlending,
+      uniforms: { uDaylight: { value: 1 } },
+      vertexShader: /* glsl */ `
+        varying vec2 vUv;
+        void main() {
+          vUv = uv;
+          #ifdef USE_INSTANCING
+          gl_Position = projectionMatrix * viewMatrix * modelMatrix * instanceMatrix * vec4(position, 1.0);
+          #else
+          gl_Position = projectionMatrix * viewMatrix * modelMatrix * vec4(position, 1.0);
+          #endif
+        }`,
+      fragmentShader: /* glsl */ `
+        uniform float uDaylight;
+        varying vec2 vUv;
+        void main() {
+          float night = 1.0 - smoothstep(0.18, 0.5, uDaylight);
+          float r = length(vUv - 0.5) * 2.0;
+          float g = max(0.0, 1.0 - r);
+          gl_FragColor = vec4(vec3(1.0, 0.85, 0.63) * g * g * 0.55 * night, 1.0);
+        }`,
+    });
+    this.lampPools = new THREE.InstancedMesh(poolGeo, this._poolMat, LAMP_MAX);
+    this.lampPools.frustumCulled = false;
+    this.lampPools.renderOrder = 3;
+    this.lampPools.count = 0;
+    this.group.add(this.lampPools);
+
+    this._eventQuads = new Map(); // eventId -> [quad instance indices, laid order]
+    this._reveals = [];
+    this._daylight = 1;
+    this._seenVersion = -1;
+    this._seenEvents = -1;
+  }
+
+  _writeQuad(i, s) {
+    const r = this._quadInfo[i];
+    _e.set(r.pitch, r.yaw, 0, "YXZ");
+    _q.setFromEuler(_e);
+    _p.set(r.x, r.y, r.z);
+    _s.set(s, 1, s * (r.pitch ? 1.01 : 1)); // ramps stretch to meet the deck
+    _m4.compose(_p, _q, _s);
+    this.quads.setMatrixAt(i, _m4);
+  }
+
+  /**
+   * Full rebuild from the City maps. roadCells: Map cellKey -> {klass, name,
+   * bridge, eventId}; occupancy (optional): Map cellKey -> type, used for
+   * sidewalk curbs next to zoned cells + plaza paving. Idempotent, call on
+   * every road OR building mutation (auto-called from update() when a city
+   * reference was passed to the constructor).
+   */
+  rebuild(roadCells, occupancy = null) {
+    const recs = new Map(); // key -> { cx, cz, rec }
+    this.roadCellSet.clear();
+    for (const [key, rec] of roadCells) {
+      const [cx, cz] = key.split(",").map(Number);
+      recs.set(key, { cx, cz, rec });
+      this.roadCellSet.add(key);
+    }
+    const maskOf = (cx, cz, pred) => {
+      let m = 0;
+      for (const [dx, dz, bit] of DIRS) {
+        const n = recs.get(cellKey(cx + dx, cz + dz));
+        if (n && (!pred || pred(n))) m |= bit;
+      }
+      return m;
+    };
+
+    let qi = 0, ci = 0, di = 0, ri = 0, li = 0;
+    this._quadInfo.length = 0;
+    this._eventQuads.clear();
+    const zoned = (key) => {
+      const v = occupancy ? occupancy.get(key) : undefined;
+      return v === "building" || v === "park" || v === "plaza";
+    };
+    const addQuad = (x, y, z, yaw, pitch, tile, eventId) => {
+      if (qi >= QMAX) return;
+      this._quadInfo[qi] = { x, y, z, yaw, pitch };
+      const [u, v] = uvOf(tile);
+      this._uvOffset.setXY(qi, u, v);
+      this._writeQuad(qi, 1);
+      if (eventId) {
+        let list = this._eventQuads.get(eventId);
+        if (!list) this._eventQuads.set(eventId, (list = []));
+        list.push(qi);
+      }
+      qi++;
+    };
+
+    for (const { cx, cz, rec } of recs.values()) {
+      const x = cx * CELL + CELL / 2, z = cz * CELL + CELL / 2;
+      const mask = maskOf(cx, cz);
+      const interMask = maskOf(cx, cz, (n) => {
+        let c = 0;
+        for (const [dx, dz] of DIRS) if (recs.has(cellKey(n.cx + dx, n.cz + dz))) c++;
+        return c >= 3;
+      });
+      const [tile, yaw] = tileFor(mask, rec.klass, interMask);
+
+      let bridgeNbr = null;
+      if (!rec.bridge) {
+        for (const [dx, dz] of DIRS) {
+          const n = recs.get(cellKey(cx + dx, cz + dz));
+          if (n && n.rec.bridge) { bridgeNbr = [dx, dz]; break; }
+        }
+      }
+      if (rec.bridge) {
+        addQuad(x, ROAD_Y.deck, z, yaw, 0, tile, rec.eventId);
+        if (di < DECK_MAX) {
+          _m4.identity().setPosition(x, 0.02 + (ROAD_Y.deck - 0.02) / 2 - 0.01, z);
+          this.decks.setMatrixAt(di++, _m4);
+        }
+        // railings flank the travel axis (E/W neighbors -> deck runs east-west)
+        const axisEW = (mask & 2) !== 0 || (mask & 8) !== 0;
+        for (const side of [-1, 1]) {
+          if (ri >= RAIL_MAX) break;
+          _e.set(0, axisEW ? 0 : Math.PI / 2, 0);
+          _q.setFromEuler(_e);
+          const off = (CELL / 2 - 0.08) * side;
+          _p.set(x + (axisEW ? 0 : off), ROAD_Y.deck + 0.21, z + (axisEW ? off : 0));
+          _m4.compose(_p, _q, _s.set(1, 1, 1));
+          this.rails.setMatrixAt(ri++, _m4);
+        }
+      } else if (bridgeNbr) {
+        // sloped ramp quad rising toward the bridge neighbor
+        const rampYaw = Math.atan2(-bridgeNbr[0], -bridgeNbr[1]);
+        addQuad(x, (ROAD_Y.road + ROAD_Y.deck) / 2, z, rampYaw, RAMP_PITCH, tile, rec.eventId);
+      } else {
+        addQuad(x, ROAD_Y.road, z, yaw, 0, tile, rec.eventId);
+      }
+
+      // curbs on edges that face zoned cells
+      for (const [dx, dz] of DIRS) {
+        if (ci >= CURB_MAX || rec.bridge) break;
+        if (!zoned(cellKey(cx + dx, cz + dz))) continue;
+        const along = dz !== 0 ? 0 : Math.PI / 2; // curb runs perpendicular to dir
+        _e.set(0, along, 0);
+        _q.setFromEuler(_e);
+        _p.set(x + dx * (CELL / 2 - 0.3), 0, z + dz * (CELL / 2 - 0.3));
+        _m4.compose(_p, _q, _s.set(1, 1, 1));
+        this.curbs.setMatrixAt(ci++, _m4);
+      }
+
+      // lamp posts every 3rd road cell, straights only, alternating sides
+      const isStraight = mask === 5 || mask === 10;
+      if (isStraight && li < LAMP_MAX && ((cx + cz * 2) % 3 + 3) % 3 === 0 && !rec.bridge) {
+        const side = (cx + cz) & 1 ? 1 : -1;
+        const ns = mask === 5;
+        const lx = ns ? x + side * 1.55 : x;
+        const lz = ns ? z : z + side * 1.55;
+        const yawL = ns ? (side > 0 ? Math.PI : 0) : (side > 0 ? -Math.PI / 2 : Math.PI / 2);
+        _e.set(0, yawL, 0);
+        _q.setFromEuler(_e);
+        _p.set(lx, 0, lz);
+        _m4.compose(_p, _q, _s.set(1, 1, 1));
+        this.lampPoles.setMatrixAt(li, _m4);
+        this.lampHeads.setMatrixAt(li, _m4);
+        // light pool sits under the head, pushed toward the roadway
+        const px = ns ? lx - side * 0.55 : lx;
+        const pz = ns ? lz : lz - side * 0.55;
+        _m4.identity().setPosition(px, 0.045, pz);
+        this.lampPools.setMatrixAt(li, _m4);
+        li++;
+      }
+    }
+
+    // plaza paving quads from occupancy (atlas plaza tile)
+    if (occupancy) {
+      for (const [key, v] of occupancy) {
+        if (v !== "plaza" || this.roadCellSet.has(key)) continue;
+        const [cx, cz] = key.split(",").map(Number);
+        addQuad(cx * CELL + CELL / 2, ROAD_Y.road, cz * CELL + CELL / 2, 0, 0, TILES.plaza, null);
+      }
+    }
+
+    this.quads.count = qi;
+    this.curbs.count = ci;
+    this.decks.count = di;
+    this.rails.count = ri;
+    this.lampPoles.count = li;
+    this.lampHeads.count = li;
+    this.lampPools.count = li;
+    this._uvOffset.needsUpdate = true;
+    for (const m of [this.quads, this.curbs, this.decks, this.rails,
+      this.lampPoles, this.lampHeads, this.lampPools]) m.instanceMatrix.needsUpdate = true;
+    // a reveal in flight keeps its cells collapsed across rebuilds
+    for (const rv of this._reveals) {
+      rv.idxs = this._eventQuads.get(rv.eventId) || [];
+      for (const i of rv.idxs) this._writeQuad(i, 0.0001);
+    }
+  }
+
+  /** Paint-in hook: sweep the event's cells from scale 0 over 4 s of simTime. */
+  revealRoad(eventId, t0) {
+    const idxs = this._eventQuads.get(eventId);
+    if (!idxs || !idxs.length) return;
+    for (const i of idxs) this._writeQuad(i, 0.0001);
+    this.quads.instanceMatrix.needsUpdate = true;
+    this._reveals.push({ eventId, t0, idxs });
+  }
+
+  /** 0 = night, 1 = day. Lamp heads + light pools react. */
+  setDaylight(d) {
+    this._daylight = clamp(d, 0, 1);
+    this._headMat.emissiveIntensity = (1 - smoothNight(this._daylight)) * 2.4;
+    this._poolMat.uniforms.uDaylight.value = this._daylight;
+  }
+
+  update(dt, simTime) {
+    if (this.city) {
+      if (this.city.roadVersion !== this._seenVersion || this.city.events.length !== this._seenEvents) {
+        this._seenVersion = this.city.roadVersion;
+        this._seenEvents = this.city.events.length;
+        this.rebuild(this.city.roadCells, this.city.occupancy);
+      }
+      if (typeof this.city.daylightValue === "number") this.setDaylight(this.city.daylightValue);
+    }
+    if (!this._reveals.length) return;
+    for (let r = this._reveals.length - 1; r >= 0; r--) {
+      const rv = this._reveals[r];
+      const n = Math.max(rv.idxs.length, 1);
+      for (let k = 0; k < rv.idxs.length; k++) {
+        const start = (k / n) * (REVEAL_S - REVEAL_POP);
+        const s = easeOutBack(clamp((simTime - rv.t0 - start) / REVEAL_POP, 0, 1));
+        this._writeQuad(rv.idxs[k], Math.max(s, 0.0001));
+      }
+      if (simTime - rv.t0 >= REVEAL_S) {
+        for (const i of rv.idxs) this._writeQuad(i, 1);
+        this._reveals.splice(r, 1);
+      }
+    }
+    this.quads.instanceMatrix.needsUpdate = true;
+  }
+}
+
+// daylight 1 -> 0 night ramp shared by lamp intensity
+function smoothNight(d) {
+  const t = clamp((d - 0.18) / (0.5 - 0.18), 0, 1);
+  return t * t * (3 - 2 * t);
+}

web/city/scene.js

@@ -0,0 +1,269 @@
+// NEMOCITY — scene bootstrap shared by index (live) and replay/timelapse.
+// Fixed-step simulation decoupled from rAF (headless Chromium throttles rAF —
+// hard-won glassblower learning). Golden Hour Toybox post chain: RenderPass ->
+// UnrealBloomPass (daylight-lerped) -> tilt-shift H -> tilt-shift V (+ grade)
+// -> OutputPass, on an MSAA HalfFloat target. The camera rig is installed by
+// main.js via setRig(); FPV swaps in via setFPV() (rig-swap hook).
+import * as THREE from "three";
+import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
+import { RenderPass } from "three/addons/postprocessing/RenderPass.js";
+import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js";
+import { ShaderPass } from "three/addons/postprocessing/ShaderPass.js";
+import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
+import { RoomEnvironment } from "three/addons/environments/RoomEnvironment.js";
+import { City } from "./world.js";
+import { SKY, FOG } from "./palette.js";
+import { clamp, lerp } from "./util.js";
+
+const STEP = 1 / 60;
+
+// bloom day/night keyframes (strength, radius, threshold) — pastel facades must
+// NOT glow in daylight; night windows/neon do the talking.
+const BLOOM_DAY = [0.32, 0.35, 0.85];
+const BLOOM_NIGHT = [0.70, 0.45, 0.62];
+const EXPOSURE_DAY = 1.05;
+const EXPOSURE_NIGHT = 0.92;
+
+export function detectQuality() {
+  const small = Math.min(window.innerWidth, window.innerHeight) < 700
+    || /Mobi|Android|iPhone|iPad/i.test(navigator.userAgent)
+    || (navigator.hardwareConcurrency || 8) <= 4;
+  return {
+    small,
+    instances: small ? 0.55 : 1,
+    pixelRatio: Math.min(window.devicePixelRatio || 1, small ? 1.7 : 2),
+    shadowMapSize: small ? 1024 : 2048,
+    msaaSamples: small ? 2 : 4,
+  };
+}
+
+// Classic separable 9-tap gaussian tilt-shift. Per-fragment radius grows from
+// zero inside the focus band: maxBlur * smoothstep(bandHalf, bandHalf+falloff,
+// abs(vUv.y - focusY)). The V pass folds in the color grade (saturation +8%,
+// warm shadow lift +0.02, vignette 0.25/0.75) so it runs even at amount 0.
+function tiltShiftShader(horizontal) {
+  const dir = horizontal ? "vec2(1.0, 0.0)" : "vec2(0.0, 1.0)";
+  const grade = horizontal ? "" : /* glsl */ `
+        float l = dot(c, vec3(0.2126, 0.7152, 0.0722));
+        c = mix(vec3(l), c, 1.08);
+        c += vec3(0.020, 0.012, 0.004) * (1.0 - l);
+        float d = length(vUv - 0.5);
+        c *= 1.0 - 0.25 * smoothstep(0.25, 0.75, d);`;
+  return {
+    uniforms: {
+      tDiffuse: { value: null },
+      resolution: { value: new THREE.Vector2(1, 1) }, // device pixels
+      focusY: { value: 0.45 },
+      amount: { value: 1.0 },
+      maxBlur: { value: 2.2 }, // px, scaled by pixelRatio at setup
+    },
+    vertexShader: /* glsl */ `
+      varying vec2 vUv;
+      void main() {
+        vUv = uv;
+        gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+      }`,
+    fragmentShader: /* glsl */ `
+      uniform sampler2D tDiffuse;
+      uniform vec2 resolution;
+      uniform float focusY, amount, maxBlur;
+      varying vec2 vUv;
+      void main() {
+        float r = maxBlur * amount * smoothstep(0.13, 0.35, abs(vUv.y - focusY));
+        vec2 o = ${dir} * (r / resolution);
+        vec3 c = vec3(0.0);
+        c += texture2D(tDiffuse, vUv - o * 4.0).rgb * 0.0510;
+        c += texture2D(tDiffuse, vUv - o * 3.0).rgb * 0.0918;
+        c += texture2D(tDiffuse, vUv - o * 2.0).rgb * 0.1200;
+        c += texture2D(tDiffuse, vUv - o * 1.0).rgb * 0.1531;
+        c += texture2D(tDiffuse, vUv).rgb * 0.1633;
+        c += texture2D(tDiffuse, vUv + o * 1.0).rgb * 0.1531;
+        c += texture2D(tDiffuse, vUv + o * 2.0).rgb * 0.1200;
+        c += texture2D(tDiffuse, vUv + o * 3.0).rgb * 0.0918;
+        c += texture2D(tDiffuse, vUv + o * 4.0).rgb * 0.0510;
+        ${grade}
+        gl_FragColor = vec4(c, 1.0);
+      }`,
+  };
+}
+
+export function createCityApp(canvas, { interactive = true } = {}) {
+  const quality = detectQuality();
+  const renderer = new THREE.WebGLRenderer({
+    canvas, antialias: false, alpha: false, powerPreference: "high-performance",
+  });
+  renderer.setPixelRatio(quality.pixelRatio);
+  renderer.setSize(window.innerWidth, window.innerHeight);
+  renderer.toneMapping = THREE.ACESFilmicToneMapping;
+  renderer.toneMappingExposure = EXPOSURE_DAY;
+  renderer.outputColorSpace = THREE.SRGBColorSpace;
+  renderer.shadowMap.enabled = true;
+  renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color(SKY.day.horizon);
+  scene.fog = new THREE.Fog(SKY.day.horizon, FOG.day.near, FOG.day.far); // sky.js retints per daylight
+
+  // T+0 frame IS the screenshot: low (~9 m) over Main St (cx=0 -> x=2),
+  // looking north up the avenue. The landing choreography (camera.js) takes
+  // over from this pose; until a rig is installed the frame just holds.
+  const camera = new THREE.PerspectiveCamera(42, window.innerWidth / window.innerHeight, 0.1, 1500);
+  camera.position.set(2, 9, 70);
+  camera.lookAt(2, 3, 0);
+
+  // subtle PMREM environment so pastel facades catch light (no external HDR)
+  const pmrem = new THREE.PMREMGenerator(renderer);
+  scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.06).texture;
+  pmrem.dispose();
+
+  const world = new City(scene, quality);
+
+  // ---- post chain on an MSAA HalfFloat target ----------------------------
+  const bufSize = renderer.getDrawingBufferSize(new THREE.Vector2());
+  const target = new THREE.WebGLRenderTarget(bufSize.x, bufSize.y, {
+    samples: quality.msaaSamples, type: THREE.HalfFloatType,
+  });
+  const composer = new EffectComposer(renderer, target);
+  composer.addPass(new RenderPass(scene, camera));
+  const bloom = new UnrealBloomPass(
+    new THREE.Vector2(window.innerWidth, window.innerHeight), ...BLOOM_DAY
+  );
+  composer.addPass(bloom);
+  const tiltH = new ShaderPass(tiltShiftShader(true));
+  const tiltV = new ShaderPass(tiltShiftShader(false));
+  for (const p of [tiltH, tiltV]) {
+    p.uniforms.maxBlur.value = 2.2 * quality.pixelRatio;
+    p.uniforms.resolution.value.copy(bufSize);
+  }
+  composer.addPass(tiltH);
+  composer.addPass(tiltV);
+  composer.addPass(new OutputPass());
+  composer.setSize(window.innerWidth, window.innerHeight); // normalize pass sizes
+
+  let daylight = 1;
+  const post = {
+    /** s in [0,1]: 0 = night, 1 = full day. Lerps bloom + exposure. */
+    setDaylight(s) {
+      daylight = clamp(s, 0, 1);
+      bloom.strength = lerp(BLOOM_NIGHT[0], BLOOM_DAY[0], daylight);
+      bloom.radius = lerp(BLOOM_NIGHT[1], BLOOM_DAY[1], daylight);
+      bloom.threshold = lerp(BLOOM_NIGHT[2], BLOOM_DAY[2], daylight);
+      renderer.toneMappingExposure = lerp(EXPOSURE_NIGHT, EXPOSURE_DAY, daylight);
+    },
+    /** 1 = full miniature blur (god view), 0 = off (FPV — hard requirement). */
+    setTiltShift(amount) {
+      const a = clamp(amount, 0, 1);
+      tiltH.uniforms.amount.value = a;
+      tiltV.uniforms.amount.value = a;
+    },
+    /** Screen-space y (0 bottom .. 1 top) of the focus band — track orbit target. */
+    setFocusY(y) {
+      const v = clamp(y, 0, 1);
+      tiltH.uniforms.focusY.value = v;
+      tiltV.uniforms.focusY.value = v;
+    },
+  };
+
+  // ---- fixed-step sim ------------------------------------------------------
+  let simTime = 0;
+  let acc = 0;
+  let timeScale = 1; // main.js slews ±2% toward the server clock; never snaps
+  let lastWall = performance.now() / 1000;
+  let paused = false;
+  let rig = null;          // orbit rig (camera.js), installed by main.js
+  let fpvController = null; // when set, it owns the camera; rig is skipped
+  const tickHooks = [];
+
+  function step(dt) {
+    simTime += dt;
+    for (const h of tickHooks) h(simTime, dt);
+    world.update(dt, simTime);
+    if (fpvController) fpvController.update(dt);
+    else if (rig) rig.update(dt);
+  }
+
+  function render() {
+    composer.render();
+  }
+
+  function frame() {
+    requestAnimationFrame(frame);
+    const now = performance.now() / 1000;
+    const dt = Math.min(now - lastWall, 0.1);
+    lastWall = now;
+    if (paused) return;
+    acc += dt * timeScale;
+    let guard = 0;
+    while (acc >= STEP && guard++ < 8) {
+      step(STEP);
+      acc -= STEP;
+    }
+    render();
+  }
+
+  function onResize() {
+    const w = window.innerWidth, h = window.innerHeight;
+    camera.aspect = w / h;
+    camera.updateProjectionMatrix();
+    renderer.setSize(w, h);
+    composer.setSize(w, h);
+    bloom.resolution.set(w, h);
+    renderer.getDrawingBufferSize(bufSize);
+    tiltH.uniforms.resolution.value.copy(bufSize);
+    tiltV.uniforms.resolution.value.copy(bufSize);
+  }
+  window.addEventListener("resize", onResize);
+
+  return {
+    scene, camera, renderer, composer, bloom, world, quality, post, interactive,
+    get simTime() { return simTime; },
+    get rig() { return rig; },
+    get fpv() { return fpvController; },
+    /** Install the orbit rig (camera.js). scene.js never imports wave-2 files. */
+    setRig(r) { rig = r; },
+    /** Rig-swap hook: pass an FPV controller to own the camera, null to exit. */
+    setFPV(controllerOrNull) { fpvController = controllerOrNull; },
+    onTick(fn) { tickHooks.push(fn); },
+    offTick(fn) {
+      const i = tickHooks.indexOf(fn);
+      if (i >= 0) tickHooks.splice(i, 1);
+    },
+    start() { paused = false; requestAnimationFrame(frame); },
+    pause(v = true) { paused = v; },
+    /** ±2% clock slew lives here: scale wall dt feeding the fixed-step loop. */
+    setTimeScale(k) { timeScale = clamp(k, 0.5, 2); },
+    /** Hard clock set (boot only). City state is a pure fn of simTime — safe. */
+    setSimTime(t) { simTime = Math.max(0, t); },
+    /** advance the sim by `seconds` in fixed steps, then render once (headless-safe) */
+    tick(seconds = STEP) {
+      const n = Math.max(1, Math.round(seconds / STEP));
+      for (let i = 0; i < n; i++) step(STEP);
+      render();
+    },
+    /** Deterministic seek to an absolute sim time. Jumps (pure-fn motion makes
+     *  that exact), then runs 1 s of fixed steps so iterative presentation
+     *  (traffic CA, congestion EMA) settles to its steady state at t. */
+    seek(t) {
+      paused = true;
+      t = Math.max(0, t);
+      const lead = Math.min(t, 1);
+      simTime = t - lead;
+      const n = Math.round(lead / STEP);
+      for (let i = 0; i < n; i++) step(STEP);
+      render();
+    },
+    renderOnce: render,
+    stats() {
+      return {
+        simTime: +simTime.toFixed(2),
+        calls: renderer.info.render.calls,
+        triangles: renderer.info.render.triangles,
+        features: world.events.length,
+        roadCells: world.roadCells.size,
+        daylight: +daylight.toFixed(2),
+        camHeight: +camera.position.y.toFixed(1),
+        fpv: !!fpvController,
+      };
+    },
+  };
+}

web/city/sky.js

@@ -0,0 +1,263 @@
+// NEMOCITY — sky, sun and the day-night cycle. Owns the ONE shadow-casting
+// DirectionalLight (sun by day, moon by night — both fade to 0 at the swap so
+// it never pops), the hemisphere fill, the gradient sky dome + stars, and
+// scene.fog/background retinting. Everything is a pure function of simTime via
+// daylight()/dayHours() — no wall clock, no unseeded randomness.
+import * as THREE from "three";
+import { mulberry32 } from "./rng.js";
+import { GRID, CELL } from "./constants.js";
+import { SKY, FOG, SUN, HEMI } from "./palette.js";
+import { clamp, lerp, smoothstep, dayHours } from "./util.js";
+
+const PLOT_HALF = (GRID * CELL) / 2; // 128 m
+const SUN_DIST = 300;                // light sits this far along its direction
+const DOME_R = 640;                  // inside camera far (1500), outside fog far
+const STAR_R = 615;
+const STAR_COUNT = 420;
+
+// Day window: sunrise centered 5.5 h, sunset centered 19.5 h (contract).
+const DAWN = 5.5, DUSK = 19.5, DAY_LEN = DUSK - DAWN, NIGHT_LEN = 24 - DAY_LEN;
+const NOON_ELEV = 62, MOON_ELEV = 44, GOLDEN_ELEV = 28;
+
+/** daylight(simTime) in [0,1] — transitions ~1.5 h wide around dawn/dusk. */
+export function daylight(simTime) {
+  const h = dayHours(simTime);
+  return smoothstep(DAWN - 0.75, DAWN + 0.75, h)
+    * (1 - smoothstep(DUSK - 0.75, DUSK + 0.75, h));
+}
+
+// compass azimuth (deg from north, cw) + elevation (deg) -> world unit dir
+// toward the light. +X east, -Z north (contract axes).
+function lightDir(azDeg, elevDeg, out) {
+  const a = azDeg * Math.PI / 180, e = elevDeg * Math.PI / 180;
+  const ce = Math.cos(e);
+  return out.set(ce * Math.sin(a), Math.sin(e), -ce * Math.cos(a));
+}
+
+const _dir = new THREE.Vector3();
+const _fwd = new THREE.Vector3();
+const _right = new THREE.Vector3();
+const _upv = new THREE.Vector3();
+const _off = new THREE.Vector3();
+const _ca = new THREE.Color();
+const _cb = new THREE.Color();
+const UP = new THREE.Vector3(0, 1, 0);
+
+export class Sky {
+  constructor(scene, renderer, quality) {
+    // tolerate (scene, quality) wiring — renderer is optional
+    if (renderer && renderer.shadowMap === undefined && quality === undefined) {
+      quality = renderer;
+      renderer = null;
+    }
+    this.scene = scene;
+    this.daylight = 1;
+    this._mapSize = quality?.shadowMapSize ?? 2048;
+
+    // keyframe colors (palette is the single source)
+    this._golden = new THREE.Color(SUN.golden.color);
+    this._noon = new THREE.Color(SUN.noon.color);
+    this._dusk = new THREE.Color(SUN.dusk.color);
+    this._moon = new THREE.Color(SUN.moon.color);
+    this._zenithDay = new THREE.Color(SKY.day.zenith);
+    this._zenithNight = new THREE.Color(SKY.night.zenith);
+    this._horizonDay = new THREE.Color(SKY.day.horizon);
+    this._horizonNight = new THREE.Color(SKY.night.horizon);
+    this._hemiSkyDay = new THREE.Color(HEMI.day.sky);
+    this._hemiSkyNight = new THREE.Color(HEMI.night.sky);
+    this._hemiGndDay = new THREE.Color(HEMI.day.ground);
+    this._hemiGndNight = new THREE.Color(HEMI.night.ground);
+
+    // the ONE shadow-casting DirectionalLight (contract: NO AmbientLight)
+    this.sun = new THREE.DirectionalLight(SUN.golden.color, SUN.golden.intensity);
+    this.sun.castShadow = true;
+    this.sun.shadow.mapSize.set(this._mapSize, this._mapSize);
+    this.sun.shadow.bias = -0.00035;
+    this.sun.shadow.normalBias = 0.5;
+    scene.add(this.sun);
+    scene.add(this.sun.target);
+
+    this.hemi = new THREE.HemisphereLight(HEMI.day.sky, HEMI.day.ground, HEMI.day.intensity);
+    scene.add(this.hemi);
+
+    this._buildDome();
+    this._buildStars();
+    this.refit({ minX: -PLOT_HALF, maxX: PLOT_HALF, minZ: -PLOT_HALF, maxZ: PLOT_HALF });
+  }
+
+  /** Ortho shadow frustum fit to city bounds +10% (re-fit only on growth).
+   *  bounds: { minX, maxX, minZ, maxZ } in world meters (Box3 min/max also ok). */
+  refit(b) {
+    const minX = b.minX ?? b.min?.x ?? -PLOT_HALF;
+    const maxX = b.maxX ?? b.max?.x ?? PLOT_HALF;
+    const minZ = b.minZ ?? b.min?.z ?? -PLOT_HALF;
+    const maxZ = b.maxZ ?? b.max?.z ?? PLOT_HALF;
+    this._center = new THREE.Vector3((minX + maxX) / 2, 0, (minZ + maxZ) / 2);
+    // bounding circle covers every sun azimuth without per-frame refits;
+    // +24 m headroom for tall casters (tower ~48 m)
+    this._radius = Math.hypot((maxX - minX) / 2, (maxZ - minZ) / 2) * 1.1 + 24;
+    const cam = this.sun.shadow.camera;
+    cam.left = -this._radius;
+    cam.right = this._radius;
+    cam.top = this._radius;
+    cam.bottom = -this._radius;
+    cam.near = Math.max(1, SUN_DIST - this._radius - 60);
+    cam.far = SUN_DIST + this._radius + 60;
+    cam.updateProjectionMatrix();
+  }
+
+  _buildDome() {
+    const geo = new THREE.SphereGeometry(DOME_R, 32, 16);
+    this._domeMat = new THREE.ShaderMaterial({
+      side: THREE.BackSide,
+      depthWrite: false,
+      uniforms: {
+        uZenith: { value: this._zenithDay.clone() },
+        uHorizon: { value: this._horizonDay.clone() },
+        uSunDir: { value: new THREE.Vector3(0, 1, 0) },
+        uGlowColor: { value: this._golden.clone() },
+        uGlow: { value: 0 },
+      },
+      vertexShader: /* glsl */ `
+        varying vec3 vDir;
+        void main() {
+          vDir = position;
+          gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+        }`,
+      fragmentShader: /* glsl */ `
+        uniform vec3 uZenith, uHorizon, uSunDir, uGlowColor;
+        uniform float uGlow;
+        varying vec3 vDir;
+        void main() {
+          vec3 d = normalize(vDir);
+          float t = pow(clamp(d.y, 0.0, 1.0), 0.62);
+          vec3 c = mix(uHorizon, uZenith, t);
+          // warm bloom around a low sun — the golden-hour horizon
+          float g = uGlow * pow(max(dot(d, uSunDir), 0.0), 8.0) * (1.0 - t);
+          c += uGlowColor * g;
+          gl_FragColor = vec4(c, 1.0);
+        }`,
+    });
+    this.dome = new THREE.Mesh(geo, this._domeMat);
+    this.dome.matrixAutoUpdate = false;
+    this.dome.frustumCulled = false;
+    this.scene.add(this.dome);
+  }
+
+  _buildStars() {
+    const rng = mulberry32(20260612);
+    const pos = new Float32Array(STAR_COUNT * 3);
+    const col = new Float32Array(STAR_COUNT * 3);
+    for (let i = 0; i < STAR_COUNT; i++) {
+      const a = rng() * Math.PI * 2;
+      const y = 0.06 + rng() * 0.94; // upper hemisphere only
+      const r = Math.sqrt(Math.max(0, 1 - y * y));
+      pos[i * 3] = Math.cos(a) * r * STAR_R;
+      pos[i * 3 + 1] = y * STAR_R;
+      pos[i * 3 + 2] = Math.sin(a) * r * STAR_R;
+      const b = 0.45 + rng() * 0.55;
+      col[i * 3] = b;
+      col[i * 3 + 1] = b;
+      col[i * 3 + 2] = Math.min(1, b * (1 + rng() * 0.18)); // faint blue cast
+    }
+    const geo = new THREE.BufferGeometry();
+    geo.setAttribute("position", new THREE.BufferAttribute(pos, 3));
+    geo.setAttribute("color", new THREE.BufferAttribute(col, 3));
+    this._starMat = new THREE.PointsMaterial({
+      size: 1.7, sizeAttenuation: false, vertexColors: true,
+      transparent: true, opacity: 0, depthWrite: false, fog: false,
+    });
+    this.stars = new THREE.Points(geo, this._starMat);
+    this.stars.matrixAutoUpdate = false;
+    this.stars.frustumCulled = false;
+    this.stars.visible = false;
+    this.scene.add(this.stars);
+  }
+
+  /** Place the light along dir and texel-snap the frustum center so shadow
+   *  edges don't shimmer as the frustum translates. */
+  _placeSun(azDeg, elevDeg) {
+    lightDir(azDeg, elevDeg, _dir);
+    const c = this._center;
+    this.sun.position.set(
+      c.x + _dir.x * SUN_DIST, _dir.y * SUN_DIST, c.z + _dir.z * SUN_DIST
+    );
+    this.sun.target.position.set(c.x, 0, c.z);
+    _fwd.copy(_dir).negate();
+    _right.crossVectors(_fwd, UP).normalize();
+    _upv.crossVectors(_right, _fwd);
+    const texel = (2 * this._radius) / this._mapSize;
+    const sx = this.sun.target.position.dot(_right);
+    const sy = this.sun.target.position.dot(_upv);
+    _off.copy(_right).multiplyScalar(Math.round(sx / texel) * texel - sx)
+      .addScaledVector(_upv, Math.round(sy / texel) * texel - sy);
+    this.sun.position.add(_off);
+    this.sun.target.position.add(_off);
+    this.sun.target.updateMatrixWorld();
+  }
+
+  /** Drives sun/moon, hemi, dome, stars, fog. Returns daylight in [0,1]
+   *  (world.js stores it; main.js feeds app.post.setDaylight). */
+  update(dt, simTime) {
+    const d = daylight(simTime);
+    const h = dayHours(simTime);
+    this.daylight = d;
+
+    let elev, az, glow;
+    const isDay = h > DAWN && h < DUSK;
+    if (isDay) {
+      const u = (h - DAWN) / DAY_LEN;
+      elev = NOON_ELEV * Math.sin(Math.PI * u);
+      az = 100 + 160 * u; // east -> south -> west; az 235 at evening golden hour
+      if (elev < GOLDEN_ELEV) {
+        const k = smoothstep(6, GOLDEN_ELEV, elev);
+        _ca.lerpColors(this._dusk, this._golden, k);
+        this.sun.intensity = lerp(SUN.dusk.intensity, SUN.golden.intensity, k);
+      } else {
+        const k = smoothstep(GOLDEN_ELEV, NOON_ELEV, elev);
+        _ca.lerpColors(this._golden, this._noon, k);
+        this.sun.intensity = lerp(SUN.golden.intensity, SUN.noon.intensity, k);
+      }
+      this.sun.intensity *= smoothstep(0, 5, elev); // fade out at the horizon
+      this.sun.color.copy(_ca);
+      glow = 0.55 * (1 - smoothstep(2, 30, elev)) * smoothstep(0, 2, elev);
+    } else {
+      const u = (((h - DUSK) + 24) % 24) / NIGHT_LEN;
+      elev = MOON_ELEV * Math.sin(Math.PI * u);
+      az = 100 + 160 * u;
+      this.sun.color.copy(this._moon);
+      this.sun.intensity = SUN.moon.intensity * smoothstep(0, 6, elev);
+      glow = 0;
+    }
+    this._placeSun(az, Math.max(elev, 0.5));
+
+    // hemisphere fill day -> night
+    this.hemi.color.lerpColors(this._hemiSkyNight, this._hemiSkyDay, d);
+    this.hemi.groundColor.lerpColors(this._hemiGndNight, this._hemiGndDay, d);
+    this.hemi.intensity = lerp(HEMI.night.intensity, HEMI.day.intensity, d);
+
+    // dome gradient + sun glow
+    const u = this._domeMat.uniforms;
+    u.uZenith.value.lerpColors(this._zenithNight, this._zenithDay, d);
+    u.uHorizon.value.lerpColors(this._horizonNight, this._horizonDay, d);
+    lightDir(az, Math.max(elev, 0), u.uSunDir.value);
+    u.uGlowColor.value.copy(this.sun.color);
+    u.uGlow.value = glow;
+
+    // stars fade in as daylight dies
+    const starOp = 0.9 * (1 - smoothstep(0.08, 0.45, d));
+    this._starMat.opacity = starOp;
+    this.stars.visible = starOp > 0.02;
+
+    // fog + background track the blended horizon (contract: fog = horizon color)
+    _cb.lerpColors(this._horizonNight, this._horizonDay, d);
+    if (this.scene.fog) {
+      this.scene.fog.color.copy(_cb);
+      this.scene.fog.near = lerp(FOG.night.near, FOG.day.near, d);
+      this.scene.fog.far = lerp(FOG.night.far, FOG.day.far, d);
+    }
+    if (this.scene.background?.isColor) this.scene.background.copy(_cb);
+
+    return d;
+  }
+}

web/city/traffic.js

@@ -0,0 +1,559 @@
+// NEMOCITY — traffic. The client-side presentation mirror of engine/traffic.py:
+// road graph from 4-adjacency, gravity trip generation from event seeds,
+// congestion-aware A* with a per-road_version path cache, and a 10 Hz queueing
+// cellular automaton (scalar progress per car, capacity holds, deterministic
+// priority = lower car index). Congestion EMA (tau 5 s) feeds the Traffic
+// Index, the heatmap overlay, jam underglow strips and the City Engineer
+// alert. carStates() interpolates the 10 Hz state for 60 fps rendering.
+// All randomness is mulberry32 from event seeds; ticking is fixed-step.
+import * as THREE from "three";
+import {
+  GRID, CELL, CITY_EPOCH_S, BUILDINGS, ROAD_CLASSES,
+  RUSH_SIGMA, RUSH_BASE, RUSH_AMP, CAR_RATE, CAR_MIN, CAR_MAX,
+} from "./constants.js";
+import { clamp, lerp, bell, dayHours } from "./util.js";
+import { mulberry32 } from "./rng.js";
+import { EMISSIVE } from "./palette.js";
+import { ROAD_Y } from "./roads.js";
+
+const HALF = GRID / 2;
+const NCELL = GRID * GRID;
+const TICK = 0.1;   // 10 Hz CA
+const TAU = 5;      // congestion EMA time constant (s)
+const QCAP = 768;   // overlay instances (contract: road cells <= 600)
+const cid = (cx, cz) => (cx + HALF) + (cz + HALF) * GRID;
+const idX = (id) => (id % GRID) - HALF;
+const idZ = (id) => ((id / GRID) | 0) - HALF;
+const idKey = (id) => `${idX(id)},${idZ(id)}`;
+const px = (id) => idX(id) * CELL + CELL / 2;
+const pz = (id) => idZ(id) * CELL + CELL / 2;
+
+const _m4 = new THREE.Matrix4();
+const _c = new THREE.Color();
+const COL_GREEN = new THREE.Color(EMISSIVE.signalGreen);
+const COL_AMBER = new THREE.Color(EMISSIVE.signalAmber);
+const COL_RED = new THREE.Color(EMISSIVE.congestion);
+
+/** place_building features -> [{kind, name, seed, t, cx, cz, w, d, def, x, z}]. */
+export function buildingsFromEvents(events) {
+  const out = [];
+  for (const f of events || []) {
+    if (!f || f.tool !== "place_building" || !f.args) continue;
+    const a = f.args;
+    const def = BUILDINGS[a.kind];
+    if (!def || a.cx == null || a.cz == null) continue;
+    const w = a.w ?? def.w, d = a.d ?? def.d;
+    out.push({
+      kind: a.kind, name: a.name || "", seed: (f.seed ?? 0) >>> 0, t: f.t ?? CITY_EPOCH_S,
+      cx: a.cx, cz: a.cz, w, d, def,
+      x: a.cx + (w - 1) / 2, z: a.cz + (d - 1) / 2, // footprint center, cell units
+    });
+  }
+  return out;
+}
+
+export const buildProgress = (b, simTime) =>
+  clamp((CITY_EPOCH_S + simTime - b.t) / Math.max(b.def.duration, 1), 0, 1);
+
+/** population = sum residents * build_progress over place_building events. */
+export function computePopulation(events, simTime) {
+  let pop = 0;
+  for (const b of buildingsFromEvents(events)) pop += b.def.residents * buildProgress(b, simTime);
+  return pop;
+}
+
+/**
+ * Clamped quadratic B-spline through xyz control triplets in `pts` (n points).
+ * u in [0, n-1]; fills outPos {x,y,z} and outTan {x,z} (unnormalized).
+ * Shared by cars (cell-center paths) and citizens (sidewalk polylines).
+ */
+export function pathPoint(pts, n, u, outPos, outTan) {
+  const seg = clamp(Math.floor(u), 0, Math.max(n - 2, 0));
+  const f = clamp(u - seg, 0, 1);
+  const i0 = Math.max(seg - 1, 0) * 3, i1 = seg * 3, i2 = Math.min(seg + 1, n - 1) * 3;
+  const w0 = 0.5 * (1 - f) * (1 - f), w2 = 0.5 * f * f, w1 = 1 - w0 - w2;
+  outPos.x = w0 * pts[i0] + w1 * pts[i1] + w2 * pts[i2];
+  outPos.y = w0 * pts[i0 + 1] + w1 * pts[i1 + 1] + w2 * pts[i2 + 1];
+  outPos.z = w0 * pts[i0 + 2] + w1 * pts[i1 + 2] + w2 * pts[i2 + 2];
+  if (outTan) {
+    outTan.x = (f - 1) * pts[i0] + (1 - 2 * f) * pts[i1] + f * pts[i2];
+    outTan.z = (f - 1) * pts[i0 + 2] + (1 - 2 * f) * pts[i1 + 2] + f * pts[i2 + 2];
+  }
+}
+
+export class Traffic {
+  /**
+   * cityView = the City instance: needs .roadCells, .roadVersion, .events,
+   * .scene (overlay meshes). Street names for alerts come from the roadCells
+   * records (the engine already names runs per event in lay_road args — the
+   * client never re-derives crc32 names; documented simplification).
+   */
+  constructor(city) {
+    this.city = city;
+    this.onAlert = null; // ({cellKey, streetName}) — wire to the HUD chip
+
+    this.cap = new Float32Array(NCELL);
+    this.spd = new Float32Array(NCELL);
+    this.surfY = new Float32Array(NCELL);
+    this.occ = new Int16Array(NCELL);
+    this.cong = new Float32Array(NCELL);
+    this.jamSince = new Float32Array(NCELL).fill(-1);
+    this.roadIds = [];
+    this.cars = [];
+    this.commuters = [];
+    this.buildings = [];
+
+    this._pathCache = new Map();
+    this._stale = [];
+    this._g = new Float64Array(NCELL);
+    this._came = new Int32Array(NCELL);
+    this._closed = new Uint8Array(NCELL);
+
+    this._acc = 0;
+    this._slowAcc = 1e9; // force first sync
+    this._heatAcc = 1e9;
+    this._eventsSeen = -1;
+    this._versionSeen = -1;
+    this._completedSeen = -1;
+    this._alertUntil = -Infinity;
+    this._states = [];
+    this._heatOn = false;
+    this._buildOverlays();
+  }
+
+  // ---- overlays: heatmap (toggle) + jam underglow (always) -----------------
+  _buildOverlays() {
+    const geo = new THREE.PlaneGeometry(CELL * 0.94, CELL * 0.94).rotateX(-Math.PI / 2);
+    const heatMat = new THREE.MeshBasicMaterial({
+      transparent: true, opacity: 0.45, depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    this.heatMesh = new THREE.InstancedMesh(geo, heatMat, QCAP);
+    this.heatMesh.count = 0;
+    this.heatMesh.frustumCulled = false;
+    this.heatMesh.renderOrder = 4;
+    this.heatMesh.visible = false;
+    const jamGeo = new THREE.PlaneGeometry(CELL * 0.98, CELL * 0.98).rotateX(-Math.PI / 2);
+    this._jamMat = new THREE.MeshBasicMaterial({
+      color: EMISSIVE.congestion, transparent: true, opacity: 0.4,
+      depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    this.jamMesh = new THREE.InstancedMesh(jamGeo, this._jamMat, QCAP);
+    this.jamMesh.count = 0;
+    this.jamMesh.frustumCulled = false;
+    this.jamMesh.renderOrder = 4;
+    if (this.city && this.city.scene) {
+      this.city.scene.add(this.heatMesh);
+      this.city.scene.add(this.jamMesh);
+    }
+  }
+
+  setHeatmap(on) {
+    this._heatOn = !!on;
+    this.heatMesh.visible = this._heatOn;
+  }
+
+  // ---- derived state rebuilds ----------------------------------------------
+  _rebuildRoads() {
+    this.cap.fill(0);
+    this.spd.fill(0);
+    this.roadIds.length = 0;
+    for (const [key, rec] of this.city.roadCells) {
+      const [cx, cz] = key.split(",").map(Number);
+      const id = cid(cx, cz);
+      const rc = ROAD_CLASSES[rec.klass] || ROAD_CLASSES.street;
+      this.cap[id] = rc.capacity;
+      this.spd[id] = rc.speed;
+      this.surfY[id] = rec.bridge ? ROAD_Y.deck : ROAD_Y.road;
+      this.roadIds.push(id);
+    }
+    const yRoad = Math.fround(ROAD_Y.road), yDeck = Math.fround(ROAD_Y.deck); // Float32Array storage
+    for (const id of this.roadIds) { // bridge approaches ride the ramp
+      if (this.surfY[id] !== yRoad) continue;
+      for (const nb of [id - 1, id + 1, id - GRID, id + GRID]) {
+        if (nb >= 0 && nb < NCELL && this.surfY[nb] === yDeck && this.cap[nb]) {
+          this.surfY[id] = ROAD_Y.ramp;
+          break;
+        }
+      }
+    }
+    this._versionSeen = this.city.roadVersion;
+    this._pathCache.clear(); // cache keys on road_version implicitly
+    this._stale = this.cars.slice(); // incremental re-solve <= 20/frame
+    this.occ.fill(0);
+    for (const car of this.cars) if (!car.parked) this.occ[car.cell]++;
+    // overlay matrices follow the road set
+    for (let i = 0; i < this.roadIds.length && i < QCAP; i++) {
+      const id = this.roadIds[i];
+      _m4.identity().setPosition(px(id), this.surfY[id] + 0.04, pz(id));
+      this.heatMesh.setMatrixAt(i, _m4);
+      this.heatMesh.setColorAt(i, COL_GREEN);
+    }
+    this.heatMesh.count = Math.min(this.roadIds.length, QCAP);
+    this.heatMesh.instanceMatrix.needsUpdate = true;
+    if (this.heatMesh.instanceColor) this.heatMesh.instanceColor.needsUpdate = true;
+  }
+
+  _rebuildTrips(simTime) {
+    this.buildings = buildingsFromEvents(this.city.events);
+    const homes = [], dests = [];
+    let completed = 0;
+    for (const b of this.buildings) {
+      if (buildProgress(b, simTime) < 1) continue;
+      completed++;
+      if (b.def.residents > 0) homes.push(b);
+      if (b.def.jobs + b.def.attract > 0) dests.push(b);
+    }
+    this.commuters.length = 0;
+    for (const h of homes) {
+      const hGate = this._gateFor(h);
+      if (hGate < 0) continue;
+      for (let i = 0; i < h.def.residents; i++) {
+        const seed = (h.seed ^ i) >>> 0;
+        const rng = mulberry32(seed);
+        let total = 0;
+        for (const d of dests) total += this._tripWeight(h, d);
+        if (total <= 0) break;
+        let r = rng() * total, dest = dests[dests.length - 1];
+        for (const d of dests) {
+          r -= this._tripWeight(h, d);
+          if (r <= 0) { dest = d; break; }
+        }
+        const dGate = this._gateFor(dest);
+        if (dGate < 0 || dGate === hGate) continue;
+        this.commuters.push({ seed, home: hGate, dest: dGate });
+      }
+    }
+    this._eventsSeen = this.city.events.length;
+    this._completedSeen = completed;
+  }
+
+  _tripWeight(h, d) {
+    const md = Math.abs(h.x - d.x) + Math.abs(h.z - d.z);
+    return (d.def.jobs + 2 * d.def.attract) / (1 + Math.pow(md, 1.5));
+  }
+
+  /** Nearest road cell id to a building footprint (Chebyshev rings, r<=8). */
+  _gateFor(b) {
+    if (b._gate !== undefined && b._gateV === this._versionSeen) return b._gate;
+    let gate = -1;
+    outer:
+    for (let r = 1; r <= 8 && gate < 0; r++) {
+      for (let z = b.cz - r; z < b.cz + b.d + r; z++) {
+        for (let x = b.cx - r; x < b.cx + b.w + r; x++) {
+          const dring = Math.max(
+            Math.max(b.cx - x, x - (b.cx + b.w - 1)),
+            Math.max(b.cz - z, z - (b.cz + b.d - 1)));
+          if (dring !== r || x < -HALF || x >= HALF || z < -HALF || z >= HALF) continue;
+          const id = cid(x, z);
+          if (this.cap[id] > 0) { gate = id; break outer; }
+        }
+      }
+    }
+    b._gate = gate;
+    b._gateV = this._versionSeen;
+    return gate;
+  }
+
+  // ---- car pool -------------------------------------------------------------
+  rushFactor(simTime) {
+    const h = dayHours(simTime);
+    return RUSH_BASE + RUSH_AMP * Math.min(1, bell(h, 8, RUSH_SIGMA) + bell(h, 18, RUSH_SIGMA));
+  }
+
+  population(simTime) {
+    let pop = 0;
+    for (const b of this.buildings) pop += b.def.residents * buildProgress(b, simTime);
+    return pop;
+  }
+
+  _syncCars(simTime) {
+    const target = this.commuters.length
+      ? Math.min(clamp(Math.round(this.population(simTime) * CAR_RATE * this.rushFactor(simTime)), CAR_MIN, CAR_MAX), CAR_MAX)
+      : 0;
+    while (this.cars.length > target) {
+      const c = this.cars.pop();
+      if (!c.parked) this.occ[c.cell]--;
+    }
+    while (this.cars.length < target) {
+      const j = this.cars.length;
+      const cm = this.commuters[j % this.commuters.length];
+      this.cars.push(this._makeCar(j, cm));
+    }
+  }
+
+  _makeCar(j, cm) {
+    const rng = mulberry32((cm.seed ^ 0x6a09e667) >>> 0);
+    const path = this._route(cm.home, cm.dest);
+    const L = path.length;
+    const car = {
+      idx: j, seed: cm.seed, home: cm.home, dest: cm.dest, path,
+      p: 0, pPrev: 0, dir: 1, dwell: 0, cell: path[0], rng,
+      speedFactor: 0, colorIdx: cm.seed % 7, _refresh: false, parked: false,
+    };
+    if (L > 1) { // seeded phase offset along the full home->work->home loop
+      const u = rng() * 2 * (L - 1);
+      if (u > L - 1) { car.dir = -1; car.p = 2 * (L - 1) - u; }
+      else car.p = u;
+      car.pPrev = car.p;
+      car.cell = path[Math.round(car.p)];
+    }
+    this.occ[car.cell]++;
+    return car;
+  }
+
+  // ---- A* (congestion-aware), cached per road_version ------------------------
+  _route(h, d) {
+    const key = h * NCELL + d;
+    const hit = this._pathCache.get(key);
+    if (hit) return hit;
+    const g = this._g, came = this._came, closed = this._closed;
+    g.fill(Infinity);
+    closed.fill(0);
+    g[h] = 0;
+    came[h] = -1;
+    const dx = idX(d), dz = idZ(d);
+    const hCost = (id) => (Math.abs(idX(id) - dx) + Math.abs(idZ(id) - dz)) * 0.625;
+    const open = [h];
+    while (open.length) {
+      let bi = 0, bf = Infinity;
+      for (let i = 0; i < open.length; i++) {
+        const f = g[open[i]] + hCost(open[i]);
+        if (f < bf) { bf = f; bi = i; }
+      }
+      const cur = open[bi];
+      open[bi] = open[open.length - 1];
+      open.pop();
+      if (cur === d) break;
+      if (closed[cur]) continue;
+      closed[cur] = 1;
+      const cx = idX(cur);
+      const nbs = [cx > -HALF ? cur - 1 : -1, cx < HALF - 1 ? cur + 1 : -1, cur - GRID, cur + GRID];
+      for (const nb of nbs) {
+        if (nb < 0 || nb >= NCELL || !this.cap[nb] || closed[nb]) continue;
+        const c = g[cur] + (1 / this.spd[nb]) * (1 + 2 * this.cong[nb]);
+        if (c < g[nb]) {
+          g[nb] = c;
+          came[nb] = cur;
+          open.push(nb);
+        }
+      }
+    }
+    let path;
+    if (g[d] === Infinity) path = [h];
+    else {
+      path = [];
+      for (let n = d; n !== -1; n = came[n]) path.push(n);
+      path.reverse();
+    }
+    this._pathCache.set(key, path);
+    return path;
+  }
+
+  _resolveStale() {
+    let budget = 20;
+    while (budget-- > 0 && this._stale.length) {
+      const car = this._stale.pop();
+      if (this.cars[car.idx] !== car) continue;
+      const path = this._route(car.home, car.dest);
+      if (path === car.path || path.length < 2) continue;
+      const at = path.indexOf(car.cell);
+      if (at >= 0) { // seamless swap: same cell exists on the new route
+        car.path = path;
+        car.p = car.pPrev = at;
+        car._refresh = false;
+      } else {
+        car._refresh = true; // finish this leg on the old road, swap at the dwell
+      }
+    }
+  }
+
+  // ---- 10 Hz queueing cellular automaton -------------------------------------
+  _tick(dt, simTime) {
+    // cars in index order = deterministic intersection priority (lower wins)
+    for (const car of this.cars) {
+      car.pPrev = car.p;
+      const path = car.path, L = path.length;
+      if (L < 2) { car.speedFactor = 0; continue; }
+      if (car.dwell > 0) {
+        car.dwell -= dt;
+        car.speedFactor = 0;
+        if (car.dwell <= 0) { // pull back out of the parking spot
+          car.dir = -car.dir;
+          car.parked = false;
+          this.occ[car.cell]++;
+          if (car._refresh) {
+            const path2 = this._route(car.home, car.dest);
+            if (path2.length > 1) {
+              car.path = path2;
+              car.p = car.pPrev = car.dir > 0 ? 0 : path2.length - 1;
+              car._refresh = false;
+            }
+          }
+        }
+        continue;
+      }
+      const nextIdx = car.dir > 0
+        ? Math.min(Math.floor(car.p) + 1, L - 1)
+        : Math.max(Math.ceil(car.p) - 1, 0);
+      const next = path[nextIdx];
+      const cur = path[Math.round(car.p)];
+      const capN = Math.max(this.cap[next], 1);
+      const occN = next === car.cell ? this.occ[next] - 1 : this.occ[next];
+      let speed = 0;
+      if (next === car.cell || occN < 2 * capN) { // hold when next is saturated
+        speed = (this.spd[cur] || 1) * clamp(capN / Math.max(occN, 1), 0.25, 1);
+      }
+      car.speedFactor = speed / (this.spd[cur] || 1);
+      car.p += car.dir * speed * dt;
+      const nc = path[Math.round(car.p)];
+      if (nc !== car.cell) {
+        this.occ[car.cell]--;
+        this.occ[nc]++;
+        car.cell = nc;
+      }
+      // U-turn / park + dwell 10-20 s seeded at each end (parked cars leave occ)
+      if ((car.dir > 0 && car.p >= L - 1) || (car.dir < 0 && car.p <= 0)) {
+        car.p = car.dir > 0 ? L - 1 : 0;
+        car.dwell = 10 + 10 * car.rng();
+        car.parked = true;
+        this.occ[car.cell]--;
+      }
+    }
+    // congestion EMA + sustained-jam alert
+    const k = dt / TAU;
+    for (const id of this.roadIds) {
+      const ratio = this.occ[id] / Math.max(this.cap[id], 0.001);
+      this.cong[id] += (ratio - this.cong[id]) * k;
+      if (this.cong[id] >= 1) {
+        if (this.jamSince[id] < 0) this.jamSince[id] = simTime;
+        else if (simTime - this.jamSince[id] >= 10 && simTime >= this._alertUntil) {
+          this._alertUntil = simTime + 60; // once per 60 s
+          if (this.onAlert) {
+            const key = idKey(id);
+            const rec = this.city.roadCells.get(key);
+            this.onAlert({ cellKey: key, streetName: rec && rec.name ? rec.name : "an unnamed street" });
+          }
+        }
+      } else this.jamSince[id] = -1;
+    }
+  }
+
+  /** Traffic Index = round(100 * mean of the top-15 congested road cells). */
+  trafficIndex() {
+    const top = [];
+    for (const id of this.roadIds) {
+      const c = this.cong[id];
+      if (top.length < 15) {
+        top.push(c);
+        if (top.length === 15) top.sort((a, b) => a - b);
+      } else if (c > top[0]) {
+        top[0] = c;
+        top.sort((a, b) => a - b);
+      }
+    }
+    if (!top.length) return 0;
+    let s = 0;
+    for (const c of top) s += c;
+    return Math.round(100 * (s / top.length));
+  }
+
+  _updateOverlays() {
+    const n = Math.min(this.roadIds.length, QCAP);
+    let jam = 0;
+    for (let i = 0; i < n; i++) {
+      const id = this.roadIds[i];
+      const c = this.cong[id];
+      _c.copy(c < 0.5 ? COL_GREEN : c < 1 ? COL_AMBER : COL_RED);
+      this.heatMesh.setColorAt(i, _c);
+      if (c >= 1 && jam < QCAP) { // underglow strip, independent of the toggle
+        _m4.identity().setPosition(px(id), this.surfY[id] + 0.035, pz(id));
+        this.jamMesh.setMatrixAt(jam++, _m4);
+      }
+    }
+    this.jamMesh.count = jam;
+    this.jamMesh.instanceMatrix.needsUpdate = true;
+    if (this.heatMesh.instanceColor) this.heatMesh.instanceColor.needsUpdate = true;
+  }
+
+  /** Explicit invalidation hooks (update() also self-detects from the City). */
+  onRoadsChanged() { this._versionSeen = -1; }
+  onBuildingsChanged() { this._eventsSeen = -1; }
+
+  update(dt, simTime) {
+    const city = this.city;
+    if (city.roadVersion !== this._versionSeen) this._rebuildRoads();
+    if (city.events.length !== this._eventsSeen) {
+      this._rebuildTrips(simTime);
+      this._syncCars(simTime);
+    }
+    this._slowAcc += dt;
+    if (this._slowAcc >= 2) { // completions tick in + rush bell resizing
+      this._slowAcc = 0;
+      let completed = 0;
+      for (const b of this.buildings) if (buildProgress(b, simTime) >= 1) completed++;
+      if (completed !== this._completedSeen) this._rebuildTrips(simTime);
+      this._syncCars(simTime);
+    }
+    this._resolveStale();
+    this._acc += dt;
+    let guard = 0;
+    while (this._acc >= TICK && guard++ < 10) {
+      this._acc -= TICK;
+      this._tick(TICK, simTime);
+    }
+    this._heatAcc += dt;
+    if (this._heatAcc >= 0.5) { // 2 Hz instanceColor refresh
+      this._heatAcc = 0;
+      this._updateOverlays();
+    }
+    this._jamMat.opacity = 0.3 + 0.15 * Math.sin(simTime * 5); // pure fn of simTime
+  }
+
+  /**
+   * Render states interpolated between CA ticks. Each entry:
+   * {i, x, y, z, yaw, speedFactor, colorIdx, headlight}; y is the road surface
+   * (bridge decks/ramps included) and the right-lane lateral offset is already
+   * baked in. Dwelling (parked) cars are omitted. The array is reused.
+   */
+  carStates() {
+    const alpha = clamp(this._acc / TICK, 0, 1);
+    const out = this._states;
+    let n = 0;
+    const pos = { x: 0, y: 0, z: 0 }, tan = { x: 0, z: 0 };
+    for (const car of this.cars) {
+      const path = car.path, L = path.length;
+      if (L < 2 || car.dwell > 0) continue;
+      const u = clamp(lerp(car.pPrev, car.p, alpha), 0, L - 1);
+      this._evalCar(path, L, u, pos, tan);
+      tan.x *= car.dir;
+      tan.z *= car.dir;
+      const tl = Math.hypot(tan.x, tan.z) || 1;
+      const fx = tan.x / tl, fz = tan.z / tl;
+      const lane = this.cap[car.cell] >= 6 ? 1.15 : 0.8; // wider offset on avenues
+      const st = out[n] || (out[n] = {});
+      st.i = car.idx;
+      st.x = pos.x + (-fz) * lane;
+      st.z = pos.z + fx * lane;
+      st.y = pos.y;
+      st.yaw = Math.atan2(fx, fz);
+      st.speedFactor = car.speedFactor;
+      st.colorIdx = car.colorIdx;
+      st.headlight = 1;
+      n++;
+    }
+    out.length = n;
+    return out;
+  }
+
+  _evalCar(path, n, u, outPos, outTan) {
+    const seg = clamp(Math.floor(u), 0, Math.max(n - 2, 0));
+    const f = clamp(u - seg, 0, 1);
+    const i0 = path[Math.max(seg - 1, 0)], i1 = path[seg], i2 = path[Math.min(seg + 1, n - 1)];
+    const w0 = 0.5 * (1 - f) * (1 - f), w2 = 0.5 * f * f, w1 = 1 - w0 - w2;
+    outPos.x = w0 * px(i0) + w1 * px(i1) + w2 * px(i2);
+    outPos.y = w0 * this.surfY[i0] + w1 * this.surfY[i1] + w2 * this.surfY[i2];
+    outPos.z = w0 * pz(i0) + w1 * pz(i1) + w2 * pz(i2);
+    outTan.x = (f - 1) * px(i0) + (1 - 2 * f) * px(i1) + f * px(i2);
+    outTan.z = (f - 1) * pz(i0) + (1 - 2 * f) * pz(i1) + f * pz(i2);
+  }
+}

web/city/util.js

@@ -0,0 +1,71 @@
+// NEMOCITY — shared math + grid helpers. Pure functions only; everything the
+// sim or renderer derives must be a function of (events, simTime), never of
+// wall clock or unseeded randomness.
+import * as THREE from "three";
+import { CELL, DAY_S } from "./constants.js";
+
+export const DEG = Math.PI / 180;
+
+export const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
+export const lerp = (a, b, t) => a + (b - a) * t;
+
+export const smoothstep = (e0, e1, x) => {
+  const t = clamp((x - e0) / (e1 - e0), 0, 1);
+  return t * t * (3 - 2 * t);
+};
+
+export const easeOutBack = (x) => {
+  x = clamp(x, 0, 1);
+  const c1 = 1.70158, c3 = c1 + 1;
+  return 1 + c3 * Math.pow(x - 1, 3) + c1 * Math.pow(x - 1, 2);
+};
+
+export const easeInOut = (x) => {
+  x = clamp(x, 0, 1);
+  return x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2;
+};
+
+/** Cell coords -> world position of the CELL CENTER, as [x, z]. */
+export const cellToWorld = (cx, cz) => [cx * CELL + CELL / 2, cz * CELL + CELL / 2];
+
+/** World position -> containing cell, as [cx, cz]. */
+export const worldToCell = (x, z) => [Math.floor(x / CELL), Math.floor(z / CELL)];
+
+/** Canonical map key for a cell: "cx,cz". */
+export const cellKey = (cx, cz) => `${cx},${cz}`;
+
+/** Manhattan distance between [cx,cz] pairs. */
+export const manhattan = (a, b) => Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]);
+
+/** Chebyshev distance between [cx,cz] pairs. */
+export const chebyshev = (a, b) => Math.max(Math.abs(a[0] - b[0]), Math.abs(a[1] - b[1]));
+
+/** Unit gaussian bell. rushFactor caps the SUM of two bells at 1, not this. */
+export const bell = (x, mu, sigma) => Math.exp(-((x - mu) * (x - mu)) / (2 * sigma * sigma));
+
+/** simTime (s) -> in-game hour of day in [0, 24). One day = DAY_S real seconds. */
+export const dayHours = (simTime) => (((simTime % DAY_S) + DAY_S) % DAY_S) / DAY_S * 24;
+
+/** hue (deg, any range) + s,l in [0,1] -> THREE.Color. */
+export function hsl(h, s, l, out = new THREE.Color()) {
+  return out.setHSL((((h % 360) + 360) % 360) / 360, clamp(s, 0, 1), clamp(l, 0, 1));
+}
+
+/**
+ * cityCenter(features) -> [x, z] world units: centroid of every place_building
+ * footprint center (genesis included), fallback [0, 0]. The camera's default
+ * frame and the engine's "center" anchor agree because both average the same
+ * event list.
+ */
+export function cityCenter(features) {
+  let sx = 0, sz = 0, n = 0;
+  for (const f of features || []) {
+    if (!f || f.tool !== "place_building" || !f.args) continue;
+    const a = f.args;
+    if (a.cx == null || a.cz == null) continue;
+    sx += (a.cx + (a.w ?? 1) / 2) * CELL;
+    sz += (a.cz + (a.d ?? 1) / 2) * CELL;
+    n++;
+  }
+  return n ? [sx / n, sz / n] : [0, 0];
+}