The world edition (starlab.edition/1)

this page as plaintext

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

-- 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
}

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

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).

The work on this page: the checks that hold it
  • FAILlint/web-reference 12 Nov on tower

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