<!-- GENERATED by starlens/site/tools/reference_pages.py from the engine's sources: do not edit; run it. -->

[[nav: reference | here=formats]]

<div class="doc">

# The world edition (`starlab.edition/1`)

<p class="plain"><a href="../../formats/world-edition.md">this page as plaintext</a></p>

*The format, 2026-10-30 (the editions slice of the replayable-worlds program; `PRACTICES.md` ruling 44, "the line
is Replayable worlds"; the operator's rulings of 2026-10-30: the profile is content beside `meta.lua`, and the
difference tool lives first in the starlab console). Commons: the reference reader is `love-shared/cart/kinds.lua`
(`Kinds.check_edition`, chained from the world and tape readers) and the witness is
`starlens/src/starlens/cartrec.py` (`edition_witness`), run over the open twin's commands. This text is CC BY 4.0,
as every format spec in the house.*

**A world cart is a still, a tape is a run, an edition says where the run can be played.** A `starlab.world/1`
cart carries the cells; a `starlab.tape/1` cart carries the acts; neither says what the world was MADE FOR: a
phone in a hand, one page inside Discord, the open twin on any CPU, the engine under WebGPU. An edition names
the lanes the maker claims, and for each lane what the world needs from it, the budget it must hold, the picture
it is drawn with, and the device it assumes. The record's witness then says, lane by lane, whether the claim
held on a named host, with the numbers, or was refused by name, or was never measured. A reader never fakes: a
lane that names a feature the lane lacks is refused by the witness with the twin's own words (the sim's law,
`world.rs`: "WHAT IS REFUSED, never faked … each named in the error, so a cart's record can say what its world
needs").

The edition is content, not manifest: it changes what the run IS for a visitor (the lane's render tier, its
budget), so the content digest covers it, as the tape's options are (`world-tape.md`: "these live in the content
… the content digest must cover them"). "A cartridge is a published data format plus a sealed record. It is never
code and never an engine" (`cart.md`): the WGSL a page carries, the parameter block, the module itself are the
PAGE's, never the cart's; an edition only names them.

## The container

A `starlab.world/1` or `starlab.tape/1` cart MAY list one more file in its content:

```
content/
  grid.png       the cells
  meta.lua       the world's sidecar
  tape.lua       (a tape's run)
  edition.lua    the edition (below), canonical Lua data
```

The world (or tape) reader reads the world unchanged, then the edition against it: the edition's `name` and the
lanes' `dims` must be the world's, and a lane's `model_mask` must be the save's when the save carries one. The
edition reads `meta.lua`'s `name`, `dims`, `frame` and `sim.model_mask` only, never the sidecars.

## edition.lua

```lua
-- starlab.edition/1 · basin_splash
return {
    format = 1,
    name = "basin_splash",                   -- the world's (meta.lua's)
    lanes = {
        twin = {         -- the open CPU twin: starlab-ref native, starlab-wasm in a page; the flat picture
            needs = { features = { "flux", "air", "soot", "warm_air" }, model_mask = 40, emitters = 2, dims = { 64, 64, 64 } },
            budget = { step_ms = 33, module_bytes = 600000, memory_mb = 64 },
            render = { tier = "flat" },
            device = {},
            touch = false,
        },
        engine = {       -- renderer 4 under WebGPU, CubeCL compiling in the page (starlab-web)
            needs = { features = { "flux", "air", "soot", "warm_air" }, model_mask = 40 },
            budget = { step_ms = 33, first_frame_ms = 8000, module_bytes = 20000000 },
            render = { tier = "r4", passes = 7, render_scale = 1, bypass = 0 },
            device = { webgpu = true, f16 = false, storage_buffers = 9 },
            touch = { hold_ms = 260, pinch = true },
        },
        activity = {     -- a Discord Activity: one self-contained page, the wasm twin inside it
            needs = { features = { "flux", "air", "soot", "warm_air" }, model_mask = 40, emitters = 2 },
            budget = { step_ms = 33, page_bytes = 4000000 },
            render = { tier = "flat" },
            device = {},
            touch = { hold_ms = 260, pinch = true },
        },
        phone = {        -- Safari on a phone: a secure context, the lab's touch rules, a lower render scale
            needs = { features = { "flux", "air", "soot", "warm_air" }, model_mask = 40 },
            budget = { step_ms = 33, first_frame_ms = 17000, memory_mb = 512 },
            render = { tier = "r4", passes = 3, render_scale = 0.45, bypass = 1280 },
            device = { webgpu = true, f16 = true, storage_buffers = 9, secure_context = true },
            touch = { hold_ms = 260, pinch = true },
        },
        wgsl = {         -- the table edition: the engine's WGSL recorded at build, a page that compiles nothing
            needs = { features = { "flux", "air", "soot", "warm_air" }, model_mask = 40 },
            budget = { step_ms = 33, first_frame_ms = 3000, module_bytes = 2000000 },
            render = { tier = "r4", passes = 3, render_scale = 1, bypass = 0 },
            device = { webgpu = true, f16 = true, storage_buffers = 9 },
            touch = { hold_ms = 260, pinch = true },
            compiled = { build = "0123456789ab", f16 = true, passes = 3, params = 840,
                         kernels = { "r4_main_kernel", "r4_water_pass", "step_prologue_kernel" },
                         table = "<sha256 of the WGSL table the page carries>" },
        },
    },
    recorder = { app = "starlab-console", engine_sha256 = "…", backend = "vulkan" },   -- optional, unchecked
}
```

- `format` is 1. `name` is the world's.
- `lanes` names at least one lane. **An edition that names no lane claims nothing** and is refused. The lanes
  are `twin`, `wgsl`, `engine`, `activity`, `phone`; `desktop`, `coop` and `blender` are reserved for a later
  catalog and refused; any other name is refused by name.
- A lane's keys are `needs`, `budget`, `render`, `device`, `touch`, and `compiled` on the `wgsl` lane only. A key
  the reader does not know is refused by name; it never skips one.
- `recorder` is free provenance, as the tape's: unchecked.

## The lanes

**twin.** The open reference simulation, word-exact with the engine: `starlab-ref` natively and `starlab-wasm`
in a page (the C ABI `sl_*`, no bindgen, ~0.5 MB). Not in it: the particle pool, actors, the heightfield, the
surface layers, FLIP, bedload, the console's tides, the CA spray, the flux jets; sixteen emitters. Its picture is
flat: the player's WebGL2 voxel view, one fixed light, the material palette, "Not renderer 4". The lane the
Activity and every phone without WebGPU get.

**engine.** Renderer 4 under WebGPU, CubeCL compiling the kernels inside the page (`starlab-web`). Needs
`navigator.gpu`; f16 where offered; at most nine storage arrays a kernel. The cost is the compiler in the page:
the first frame pays CubeCL's compile and the browser's own pipeline compile.

**wgsl.** The same engine with its kernels' WGSL recorded at build, per (build, f16), and fed back through
CubeCL's precompiled-source door, so the page compiles nothing of its own. Bit-identical to `engine` by
construction; the three-way row proves it per build. `compiled` names what the page carries.

**activity.** A Discord Activity: ONE self-contained page, every asset inlined, no host outside the app's mapping
(the proxy's content-security policy), the click guard, the storage keys inventoried, no OAuth scope. The wrapper
is `staros web activity`; the page's bytes are the lane's budget.

**phone.** Safari on a phone: WebGPU in a secure context only, a lower render scale, the lab's touch rules (hold to
arm, pinch to zoom), a GPU memory a few labs can exhaust.

## What a lane claims

- `needs`: `features`, a list of names from the catalog — the twin's refusal names made nouns — `flux`,
  `flux_mass`, `air`, `soot`, `warm_air`, `biomes`, `geo`, `climate`, `emitters`, `charge`, `consol`, `xfer`,
  `pool`, `heightfield`, `surf`, `bedload`, `flip`, `ca_spray`, `jets`, `moon`; `actors`, `columns`, `words` and
  `shards` are reserved for a later catalog (the tape's reserved ops, the record's P/Q/X strata). `model_mask` is
  an integer 0..1023 (the ten model bits, FLUX 1 … GRAN_RUN 512) and equals `meta.sim.model_mask` when the save
  carries one. `emitters` is what the world books (≥ 0; the native lane carries 16). `dims` are the world's.
  A lane may name a feature the lane lacks (`pool` on `twin`): the reader accepts the shape and the witness
  refuses it by name.
- `budget`: at least one of `step_ms`, `first_frame_ms`, `page_bytes`, `module_bytes`, `memory_mb`, each a
  positive number. **A lane with no budget claims nothing** and is refused. `step_ms = 33` is the house's live line
  (a world runs live under 33 ms a step on the reference, `carts.json`'s `live_ms`).
- `render`: `tier` is `flat` or `r4`. Under `r4`: `passes` 0..7 (renderer 4's pass gate: WATER 1, ICE 2, UW 4;
  7 is every pass), `render_scale` in (0, 1] (render param 81), `bypass` ≥ 0 (param 169's bits), and optionally
  `lens = { mode, band, lo, hi }` (param 168's lens; mode 6 is the map lens, mode 7 the game lens: the flat
  three-face look with edge lines) and `ortho = { yaw, pitch, tile_w }` (2026-10-30, the iso edition: the lane
  draws through renderer 4's orthographic camera at that pose, yaw and pitch in degrees (45 and 30 are the 2:1
  diamond; pitch in (0, 90]), `tile_w` the pixels across a cell's diagonal, an even integer 2..256, the view's
  half-height following from the pane's). Under `flat` those keys are refused.
- `device`: `webgpu`, `f16`, `secure_context` (booleans), `storage_buffers` (≥ 1, the arrays a kernel may bind).
  A fact absent assumes nothing.
- `touch`: `false`, or `{ hold_ms = n, pinch = bool }`.
- `compiled` (`wgsl` only): `build` (hex, 12 or more digits: the module build the WGSL was emitted by), `f16`,
  `passes`, `params` (840, the render block's length), `kernels` (the stable kernel names, at least one),
  `table` (optionally, the sha256 of the WGSL table the page carries).

Nothing in this version is removed by a later one.

## What the record witnesses

The cart's record (`record.json`, assay/2, kind `cart`) gains a payload `edition` with one entry per lane the
edition names, each with a `verdict`:

| verdict | meaning |
|---|---|
| `held` | every named budget under its number, every device fact present, nothing refused — on the named host |
| `over_budget` | a budget missed: `over = [{ budget, value, limit }]`, the numbers beside the claim |
| `refused` | the lane refused the world: `refused = [names]`, the tool's own words |
| `unmeasured` | no tool here for the lane; never a pass |

The witness entry `{ name = "edition", deterministic = true }` joins the record only when at least one lane was
measured; the cart's verdict (`conforms`, `malformed`, `diverged`) and `replayable` are untouched by a lane's
word. An edition whose lanes all read `unmeasured` has claimed and proved nothing, and the record says so lane by
lane.

## The reference

| lane | the tool | measures, against the budget | refuses |
|---|---|---|---|
| twin | `starlab-replay <content> --steps N --json` (a world), `starlab-replay play <content> --json` (a tape); the browser twin's `replay-wasm.mjs` / `tape-wasm.mjs` when the module is at hand | `ms_per_step` → `step_ms`; `wasm_bytes` → `module_bytes`; `memory_mb` | the twin's refusal list IS the witness; more than sixteen emitters |
| activity | `staros web activity --check <page>` and the page's bytes; the wasm twin's numbers | `page_bytes`, `step_ms` | a `--check` finding, by its line |
| engine | the lab's facts (`__starlabLab` / `facts()`), recorded to a facts file | `first_frame_ms`, `step_ms`, `wasm_bytes` → `module_bytes`; `device` against `adapter`, `shader_f16`, `max_storage_buffers_per_shader_stage` | `f16` claimed and absent; `webgpu` claimed and no adapter |
| phone | the web-phone report's facts | as engine, and `secure_context` | as engine |
| wgsl | the table lab's facts | as engine, and `compiled.build` against the runner's build | a build mismatch (both ids named); a kernel not in the table, by name |

## The console

THE EDITIONS (the starlab console, `' e`): one world, one frame, one pane per lane the edition names. An `r4`
lane's pane is renderer 4 through the frame's view table with the lane's lens; a `flat` lane's pane is the
twin's picture drawn from the same cells (the player's shader over the console's grid stream). Under each pane
the lane's word, its measured numbers, its refusals, its tier. Renderer 4's pass set, render scale and bypass
bits are the FRAME's, not a view's: a lane's tier is applied to the whole frame on a key, and the sheet
(`starbox editions-sheet`) shoots each lane's tier in turn on the same frame and camera and prints each pane's
FLIP against the engine pane — the difference number.

## Reserved

Lane names `desktop`, `coop`, `blender`; feature names `actors`, `columns`, `words`, `shards`. A reader refuses
them as reserved; it never skips them.

## What this is not

Not a build target, not a deploy, not a page: the edition names lanes, it does not make them. Not a licence or a
price. Not the tape's options (`sim_salt`, `model_mask`, `xfer_every`, `air_every` stay the tape's; an edition's
`model_mask` is the same number, claimed per lane, and must agree with the save's).

<details class="changes">
<summary>The work on this page: the checks that hold it</summary>

[[work: checks | rows=lint/web-reference]]

</details>

<nav class="pager"><a href="../../formats/world-tape/">← formats/world-tape</a><a href="../../">The reference</a><a href="../../formats/script/">formats/script →</a></nav>

*Generated by `tools/reference_pages.py` from `docs/formats/world-edition.md`; the twin `bfaad079a7ce` (434093 bytes). The words are a draft.*

</div>
