Project-M/Docs/Vault/06_Roadmap/Lantern_World_Model_Spike.md

title, date, tags, status, permalink

title	date	tags	status	permalink
LANTERN — World-Model Design Spike (Phase 0.3, ★review-first)	2026-07-13	roadmap lantern netcode world-model design-spike phase-0 review-first	reviewed	gamevault/06-roadmap/lantern-world-model-spike

LANTERN — World-Model Design Spike (pocket-graph + seed-pinning)

[!success] REVIEW COMPLETE (2026-07-13, DR-049_Lantern_World_Model_Design). The design review ran (wf_aa6fb661-e25, 18 findings) → the review-hardened design is World_Model_Build_Spec and the proposal it hardened is Lantern_World_Model_Design_Proposal. This brief is kept as the record of the problem framing + the hazards the review was told to attack. The design half of Phase 0.3's gate is passed (the in-engine A0 style-proof scene remains the other open Phase-0 gate).

★ REVIEW-FIRST — this is a BRIEF, not a design. Phase 0.3 of Roadmap_Lantern_Slice, adopted under DR-048_Lantern_Adoption_Full_Pivot. This frames the slice's hardest netcode problem and its open questions so the adversarial design review has a target. No world code is written until that review passes (the standing project ritual — validate-netcode-design-before-coding). This doc feeds the review; the review produces the durable Build Spec that feeds the eventual DR.

This gate is one of Phase 0's three exit conditions (with the adoption DR and the A0 style-proof scene). It is currently OPEN — the review has not been run.

The problem in one sentence

Permanence is territory made of light: what a lamp holds is fixed and saved; what is dark re-knots every descent — and this must hold across 2–4 co-op clients under server authority, client prediction, and a per-player light-based information radius, without shipping a determinism nightmare.

The design commitments to honour (from Identity_Lantern)

• The world is a pocket-graph — discrete generated pockets on a graph, not open stitched terrain.
• Permanence = seed-pinning. Dark pockets generate from a per-descent seed; lighting one pins its seed and saves structure deltas. "The dark re-knots" is a seed change, nearly free.
• Light is information, server-enforced. A client is not sent entities outside its lamp radius — relevancy, not gamma. Dimming is a true trade (quiet for blind).
• Session shape: muster at the deepest lit waypoint → Bell down → pockets → Bell recall or lit-road walk home; ~30–40 min hard cap. Lighting a lantern is a save point.
• Loss ceiling: the dark takes frontier pockets, never a whole shelf.

The contract to design (the review's agenda)

1. Pocket generation as a pure function of (worldSeed, pocketId, descentSalt). Deterministic, server- authored. The seed never needs replicating cross-client (the DR-037 feasibility insight holds: the server spawns procedural content as runtime ghosts and clients just receive them — no cross-client determinism problem). Question: what is pocketId (graph node id) and how is the graph itself generated/pinned?
2. Pinning = persist seed + structure deltas. Lighting a waypoint-lantern writes the pocket's seed + its building/harvest deltas to the save. Re-entry regenerates from seed then replays deltas (the born-correct load pattern already proven in Lantern_Strip_Mothball_Inventory). Question: delta granularity (full structure list vs diff), and how banked-light/Lamp state composes.
3. Pocket streaming / replication as runtime ghosts. Only the current + adjacent pockets are live; a pocket's entities spawn as server ghosts when the party enters and despawn on exit. Reuses the GhostRelevancy (SetIsIrrelevant) machinery from the region split — but keyed on pocket occupancy + lamp radius, not a coordinate region. Question: the transit/handoff moment (Bell down, walk between pockets) and how relevancy composes with light radius without a per-tick cost blowup.
4. Muster / Bell transit contract. Muster relocates to the deepest lit waypoint; the Bell is the depth-lock transit. Reuses the run/room lifecycle state machine (Lantern_Strip_Mothball_Inventory). Question: co-op semantics (does the whole party transit together? partial-party descents?).
5. Light-as-information relevancy. Per-player lamp radius drives what is replicated to that client. This is the Phase-1 "relevancy-light prototype" — the ★review-first item flagged there too. Question: is this the SAME mechanism as pocket streaming or a second layer on top, and how do they interact.

Known hazards the review must attack (from CLAUDE.md + prior DRs)

• Relevancy cull re-audit: a 2nd concept sharing an existing tag has repeatedly wiped/blocked cross-region state (DR-031, DR-040). Any pocket/light relevancy scheme must re-audit every query/cull over the tag.
• Shared GLOBAL state rides an UNTAGGED ghost (never a relevancy-tagged one) — the Lamp meter, campaign readout, party Loudness must stay relevant everywhere.
• Prediction determinism: no wall-clock / Time.deltaTime / System.Random in predicted sim; pocket gen is server-authored (not predicted). Tick sentinels through TickUtil.NonZero.
• Per-tick relevancy cost: the region relevancy system already needs cosmetic props to be non-ghost; light-radius relevancy recomputed per player per tick is a cost the review must bound.
• Save additivity: seed-pin schema must be additive/versioned ([MinLoadableVersion, Current]) so old saves load.

Explicit non-goals for the spike

Not designing: the full v1.0 severable fuel-net, the doppelganger relocation AI, shelf-regression, or open terrain (cut). The spike designs the slice's pocket-graph + pinning + streaming + transit only.

Status & next action

OPEN. Next action (not doc work): run the adversarial design-review Workflow (lenses: netcode/relevancy · determinism/prediction · reuse/scope → adversarial critics → synthesis) over this brief + the ground-truth relevancy/lifecycle/save code, producing World_Model_Build_Spec.md. Only then does any world code begin (Phase 2 in the roadmap; Phase 1's combat gym has no world and is not blocked by this).

Related

• Roadmap_Lantern_Slice — Phase 0.3 (this) and Phase 2 (the dark & the pocket-graph, which this gates)
• DR-048_Lantern_Adoption_Full_Pivot — the adoption
• Lantern_Strip_Mothball_Inventory — the relevancy/lifecycle/save salvage this reworks
• Identity_Lantern — the world-model commitments (the tide-line)
• DR-013_M6_Aether_Cycle_Region_Split — the region/relevancy machinery being reworked
• validate-netcode-design-before-coding — the ritual this doc sets up