# Inkhaven 1.3.25 — World Simulation

_Inkhaven gains an actual simulated world. A new **`inkhaven realworld`**
compiler turns a structured `world.hjson` into a coherent, physically-grounded
world — sky, terrain, climate, rivers, and settlements — materialized into a new
**World** system book, with a proposal queue that turns its cities into real
Place records you accept one by one. This is the first slice of RFC WORLD-4 (the
compiler half; the fact-checker follows). It also **completes RFC PANE-1**: the
Output pane gains its remaining actions and becomes the default launch view._

_Reference: [WORLD-4_PLAN.md](../PROPOSALS/WORLD-4_PLAN.md) ·
[PANE-1_PLAN.md](../PROPOSALS/PANE-1_PLAN.md)_

> **Naming note.** The simulation RFC was authored as "WORLD-1", but WORLD-1/2/3
> are the shipped *consistency* pillar (facts / drift / world report, 1.3.8–1.3.11).
> The simulation track is **WORLD-4** — a different thing that *builds* a world
> rather than checking one.

## The world compiler — `inkhaven realworld`

Write a `world.hjson` at the project root (start one with `inkhaven realworld new
<name>`), then compile it. Five deterministic layers run in dependency order,
each a pure function of `(definition, seed)` — same inputs, same world, every
time:

1. **Astronomy** — closed-form planetary physics. Year length from Kepler's third
   law (in the planet's own days), with a flag when your declared calendar
   diverges from the computed year; daily insolation by latitude band; per-moon
   synodic periods and lunations; tidal forcing (a close light moon correctly
   out-tides a far heavy one); season markers anchored to your calendar.
2. **Geology** — seed → tectonic plates (Voronoi boundaries, classified
   convergent / divergent / transform from relative plate motion) → a procedural
   heightmap with mountain uplift along convergent belts → continents, sea
   coverage, mountain ranges, and mineral hints. Or **import a DEM**: point
   `geology.dem` at a heightmap PNG and the compiler uses your terrain instead.
3. **Climate** — a zonal model: global mean from the star's flux, the latitude
   profile from the astronomy insolation, elevation lapse from the heightmap;
   precipitation from the Hadley / Ferrel / Polar belts, modified by
   continentality and orographic rain shadows; Köppen-style biomes and the
   prevailing-wind bands.
4. **Hydrology** — the textbook D8 flow model: flow direction → rainfall-weighted
   accumulation → rivers with a Strahler-style order → lakes → watersheds →
   settlement priors (river mouths, confluences, fertile valleys).
5. **Demographics** — biome carrying-capacity sets the population; the hydrology
   priors become a Rank-Size settlement hierarchy of cities, towns, and villages,
   with plausible social role types.

Each layer **materializes** into the new **World** system book (10th, after
Artefacts) as structured paragraphs — `World / Astronomy`, `Geology`, `Climate`,
`Hydrology`, `Demographics` — and the heightmap is written as a grayscale PNG
asset. Re-compiling is idempotent (it updates in place, never duplicates), and
astronomy through hydrology are compiler-owned facts that re-assert each run.

```
inkhaven realworld new Velmaron
inkhaven realworld compile --layer astronomy
inkhaven realworld compile --layer geology --materialize
inkhaven realworld compile --layer climate --json
# … hydrology, demographics …
```

## The proposal queue — the author always wins

Demographics is the first layer that **proposes** rather than asserts. Its
settlements don't silently become Places; they enter a **proposal queue** with
deterministic, pronounceable names, and you decide:

```
inkhaven realworld propose                      # seed the queue from the world
inkhaven realworld proposals list               # review names + rationale
inkhaven realworld proposals accept <id>        # commit one as a Place
inkhaven realworld proposals reject <id>        # never re-proposed
inkhaven realworld proposals accept-all
inkhaven realworld places                       # the accepted Place ↔ World links
```

Accepting creates a prose Place under the **Places** book and records a **Place ↔
World cross-reference** (climate zone, biome, hydrology basis, coordinates) keyed
to it — the join the fact-checker will use. Re-running `propose` never
re-proposes a site you already accepted or rejected.

## In the editor — `Ctrl+B W`

`Ctrl+B W` opens the **World overview**: the definition, the compiled astronomy,
per-layer status, and whether it's materialized. It's an actionable hub:

- **`C`** compiles every layer, materializes them, and seeds the proposal queue.
- **`P`** opens the proposal queue — `↑↓` navigate, `Enter` accepts (commits the
  Place), `r` rejects.

So you can build and curate an entire world without leaving the editor.
*(Distraction-free / focus mode moved from `Ctrl+B W` to **`Ctrl+B Shift+W`** to
free the World prefix.)*

## PANE-1 completed — the Output pane comes of age

The Output pane (1.3.24) gains its remaining actions and is now the **default
right-side pane on a project's first launch** (returning to a project restores
whichever pane you left):

- **Per-kind `Enter`** — a `translation_result` inserts its target at the cursor,
  a `lexicon_proposal` promotes its words into the Dictionary, an
  `ai_task_complete` jumps to its paragraph.
- **`e`** on a translation — edit + remember in one gesture (insert *and* commit
  the pair to memory).
- **`ai_task_complete`** notifications — a long AI task (the deep world refresh, a
  full-chapter fact-check) drops a single completion notice in Output, so you can
  switch panes during it and still be told.
- Focusing the AI prompt now switches the right pane to AI, so a one-shot AI op
  always surfaces its output.
- A bare Bund `print` / `println` is **mirrored into Output**, one message per
  line, so script output is reliably visible.
- New **`Ctrl+B D`** chord — a *deterministic* (rule-based) translation of the
  open paragraph into a conlang, routed to Output (the AI translation `Ctrl+B Q`
  is unchanged). **Lexicon proposals** (`generate-lexicon`) and **variety
  renderings** (`lect`) also route to Output, with `Enter`-accept on proposals.
- Status-line cosmetic pass; full docs ([`OUTPUT_PANE.md`](../OUTPUT_PANE.md) +
  tutorial 75).

## New dependencies

The geology layer adds two pure-Rust crates: **`noise`** (the procedural
heightmap) and **`delaunator`** (Voronoi plate boundaries). The `image` crate
(already in tree) handles DEM import and the heightmap PNG. Everything else —
astronomy, climate, hydrology, demographics, the proposal queue, all of PANE-1 —
is **zero new dependencies**, reusing the in-tree DuckDB, ratatui, and Bund
machinery. Determinism uses an in-tree seeded PRNG, never `rand`.

## Compatibility

Non-breaking. The new **World** system book is seeded into existing projects on
next open (it slots in after Artefacts); existing Places, Characters, and
Artefacts are untouched. The `world.hjson` and the proposal queue are opt-in —
projects that never run `realworld` are unaffected.

Tests 1582 → 1613.
