The world tape (starlab.tape/1)

this page as plaintext

The format, 2026-10-29 (the replayable-worlds slice; the brand line’s engineering half, PRACTICES.md ruling 44). Commons: the reference implementation is the open twin’s command starlab-replay play (starburn/crates/starlab-replay, Apache-2.0 with the reference crate) and the cart reader in love-shared/cart/kinds.lua. 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. A starlab.world/1 cart carries the cells as they were saved, and its record’s replay witness says what the reference sim prints after N steps from there. Nothing in it says what a person DID: where they poured the water, when they struck the vent, which cells they painted. A tape carries that: the world as it stood when the recording began, every world-mutating act at the frame it landed, and the digest the recorder measured at chosen frames. Anyone with the open twin replays the acts from the saved world and holds every digest to the tape’s; the browser twin does the same in a page. A verified run is a tape cart whose sealed record carries an agreeing replay witness; “Verified with StarLab” follows that record, never the maker’s word (licenses/TRADEMARKS.md).

The tape is the smallest form of the sentence the platform is built on, replay is the API: a core is a pure function of a seed and a history (docs/working-engine-strategy-2026-10.md). The world record’s tape of actors (docs/formats/world-record.md, the Tape row; the world-record program’s L18) is the same idea one stratum deeper: the record at T0 plus the bodies’ intents plus D(T) per decision. This format is the cells’ tape, the one every copy of the twin can play today; the actor intents join it as ops when the record carries bodies (actor ops are reserved below).

The container

A starlab.tape/1 cart’s content/ is a starlab.world/1 content exactly as the console’s world save wrote it at the recording’s first frame (grid.png, meta.lua, and the sidecars the meta says were captured), plus one file:

content/
  grid.png       the cells at the first frame
  meta.lua       the world's sidecar (format, name, dims, frame, sim, …)
  tape.lua       the tape (below), canonical Lua data

The world part is read by the world kind’s reader unchanged; a world the reference refuses by name (a captured pool, a heightfield, surface layers) makes a tape the reference refuses by the same names, and the record says so.

tape.lua

-- starlab.tape/1 · basin_splash
return {
    format = 1,
    name = "basin_splash",          -- the world's name (meta.lua's)
    first_frame = 0,                -- the frame the world stands at (meta.lua's frame; 0 when it has none)
    steps = 120,                    -- the tape's length: the last frame is first_frame + steps
    options = { sim_salt = 0, model_mask = 40, xfer_every = 4, air_every = 4 },
    ops = {
        { at = 10, op = "box", x0 = 4, y0 = 2, z0 = 4, x1 = 11, y1 = 5, z1 = 11, mat = 2 },
        { at = 10, op = "sphere", x = 16, y = 8, z = 16, r = 3, mat = 1, temp = -1 },
        { at = 30, op = "cell", x = 7, y = 3, z = 7, mat = 3, temp = 200, state = -1 },
        { at = 40, op = "cells", xyz = { 2099205, 2099206 }, mat = { 1, 1 }, temp = { -1, -1 }, state = { -1, -1 } },
        { at = 50, op = "emitters", list = { { 16, 20, 16, 2, 6, 3, -1, -1, 32768, 60, 10, 0, 0 } } },
    },
    checkpoints = {
        { frame = 0, grid_hash = "2a6037e4e5e8297e" },
        { frame = 60, grid_hash = "aa823f64bad7d352" },
        { frame = 120, grid_hash = "c34b25a902770413" },
    },
    recorder = { app = "starlab-console", engine_sha256 = "…", backend = "vulkan" },
}

The clock

The world stands at frame f. In this order: (1) the checkpoint at f, if listed, is the digest of the world as it stands on arrival at f, before any op at f; (2) the ops at f apply, in list order; (3) one step takes the world to f + 1. So the checkpoint at first_frame is the saved world’s own digest, and the checkpoint at the last frame is the digest after the final step; no op may be listed at the last frame. A recorder measures a checkpoint at the top of the frame, before it applies that frame’s edits.

The ops

The parameters are the engine’s own (starlab_sim_spawn_*, starlab_sim_edit_cells, starlab_sim_set_emitters in starlab_sim.h); the twin applies each through the same word the engine writes (encode_cell_state, grid_fill_box, grid_fill_sphere, Emitter::from_words). temp and state are i32 with a negative meaning the material’s default; absent means −1. Corners are inclusive, in order; a box or sphere is clamped to the grid; a cell outside the grid writes nothing.

op fields the engine’s call
box x0 y0 z0 x1 y1 z1 mat [temp] [state] spawn_box_state (the console’s spawn_box, edit_box)
sphere x y z r mat [temp] spawn_sphere
cell x y z mat [temp] [state] spawn_cell_state
cells xyz = {…}, mat = {…}, [temp = {…}], [state = {…}]: parallel integer arrays of one length; xyz packed `x y<<10
emitters list = { {13 integers}, … }: each record the FFI’s EMITTER_WORDS (x, y, z, r·scatter, h, mat, temp, state, rate, period, burst, phase, heat); an empty list clears set_emitters (replaces the set)

actor_add and actor_intent are the creature strand (below; readable since 2026-10-30, the reference handing a tape that carries them to starlab-char’s reader). Reserved, not yet readable: actor_remove (the world record’s bodies, L18), words (a dense box of arbitrary words, write_box), columns (edit_columns). A reader refuses an op it does not know by name; it never skips one.

The reference

starlab-replay play <content dir> [--json]            exit 0 agrees · 1 diverged · 2 refused
starlab-replay play <content dir> --mint [--every K]  writes the checkpoints the twin measures

play opens the world with the tape’s options, refuses by name anything it cannot replay (the world’s refusals; an unknown op; a frame mismatch; a missing hash), then walks the clock: at each listed frame it holds the twin’s grid_hash() to the tape’s and stops at the first that differs, naming the frame, the expected digest and the one it found. --mint keeps the listed frames (or every K frames from the first, plus the last) and rewrites tape.lua with the digests the twin measured; it is how a tape is made without a console, and how the reference countersigns one made with one. The browser twin plays the same tape through its C ABI (sl_op_box, sl_op_sphere, sl_op_cell, sl_op_emitters; starburn/scripts/tape-wasm.mjs in node), and the fleet row holds native and wasm to the same verdict on the same tape. The worlds page’s player plays it too (mountTape in starburn/crates/starlab-wasm/web/starlab-player.js; a tape cart at /play/<record sha>), held to tape-wasm.mjs’s verdict word for word by starburn/crates/starlab-wasm/web/tape.test.mjs (2026-10-30).

The record

A tape cart’s record.json is the cart record (docs/formats/cart.md, “The record”) with its replay witness run by play: the payload’s replay carries verdict (agrees or diverged), the checkpoints held, the first and last digests, the frame reached and the host; a diverged tape’s record has the verdict diverged (the cart is well-formed and its claim is false, which the record says). A world the reference refuses leaves the record replayable = false with the reasons (the refusal was recorded as a deterministic witness before this date; it is not one).

The creature strand (2026-10-29; the reference plays it since 2026-10-30)

The sim-RL design’s D3 (docs/working-sim-rl-design-2026-10.md), drafted by the crate that reads it (starburn/crates/starlab-char, starlab-char replay) on 2026-10-29. Since 2026-10-30 the reference starlab-replay play knows the two ops: a tape that carries them is handed to its reader, the program starlab-char replay (STARLAB_CHAR_BIN, or starlab-char beside the reference’s binary), whose verdict and exit code the reference relays: the same twin, the same grid_hash digests, actor_hash beside them. Without the reader the tape is refused by name, saying where the reader was looked for; --mint on such a tape is refused (a creature tape is minted by starlab-char episode --tape). A program and not a crate dependency: the creature’s contract and senses live with the creature, and the reference keeps the open twin as its one dependency, so the engine’s export (releases/starlab-engine.manifest) stays a closed set. A reader of another kind still refuses the ops by name.

The reserved actor_add and actor_intent ops carry a creature’s run over the cells’ tape: what it was when the recording began, and what it DECIDED at each decision frame. Everything else (the kinematic substeps, the drives, the consumption of a sensed cell, death) the reader re-derives from the world and the contract, so a tape of intents is a tape of the run, not a transcript of it.

op fields meaning
actor_add id x z energy eat_commit held_sun contract, at first_frame only, ONE PER ACTOR (id 1 the creature, 2.. the herd’s mates in index order) the actor as it stood: its position and energy (floats, exact as canonical numbers), its eat commitment, the day phase it last held, and the contract version its senses and drives follow (CONTRACT_VERSION, starlab-char’s contract.rs; a reader of another contract refuses by name)
actor_intent id action, at a decision frame, one per LIVING actor the decoded action (0 stay · 1 +x · 2 −x · 3 +z · 4 −z) the actor holds for the next DECISION_PERIOD (8) frames; the creature’s (id 1) is required at every decision frame, a mate’s missing reads 0 (rest)

The clock keeps its order: at a decision frame f, the checkpoint at f (the world AND the creature on arrival), then the ops at f (the intent), then eight steps to f + 8 with the held intent, the drives at the rates sensed at f, and the consumption at the boundary. An intent at a frame that is not a decision frame (first_frame + 8k) is refused; a decision frame without an intent is refused (“no intent at frame f”); a creature that died ends the tape (its steps end where the window broke).

A checkpoint may carry actor_hash beside grid_hash: sixteen hex digits, the actors’ state digest on arrival at the frame (FNV-1a 64 over the creature’s words, then each mate’s in index order: position and energy by their bits, the held drives and the held move, the commitment, alive; then the decision count). A reader that knows the strand holds both; a reader that does not reads only grid_hash (it ignores a key it does not know, as recorder’s keys are ignored).

recorder gains brain (which row decided: random, scripted, policy), contract, contract_hash, seed, level (compact, sampled, herd, burn), actors, and not_in_twin (the stages of the console’s frame the twin does not carry: the particle pool, the heightfield), so the record says what the run’s physics was.

ops = {
    { at = 0, op = "actor_add", id = 1, x = 14.3, z = 10.2, energy = 1, eat_commit = 0, held_sun = 0, contract = 3 },
    { at = 0, op = "actor_intent", id = 1, action = 1 },
    { at = 8, op = "actor_intent", id = 1, action = 1 },
    …
},
checkpoints = {
    { frame = 0, grid_hash = "…", actor_hash = "…" },
    { frame = 32, grid_hash = "…", actor_hash = "…" },
    …
},

Not drafted: more than one creature per tape (the fields allow it; the reader takes one), actor_remove, the world record’s bodies (L18: the same clock one stratum deeper, docs/formats/world-record.md).

The console’s recorder: the matter door (2026-11-10)

The console writes tape.lua itself since the bodies program’s phase B1 (docs/design-bodies-2026-11.md §5; starlab/console/elements/world_tape.lua, the verb tape). It is not the session tape below: that one records the VERBS that came through the remote door, and this one hears the sim’s cell writers, whoever called them (a creature’s bite, a body’s hand, the Kinect scene, a paint dab, a verb). What it adds to the shape above, all of it additive (the reader passes over a key it does not name):

The origin. Beside tape.lua the console keeps state0.slws, the crate’s own save of the first frame (docs/formats/world-record.md: every stratum, exact), and replays from that, in the console, on the native lane. That is what makes its replay exact whatever the scene arms. It is NOT yet this kind’s content: the world cart (grid.png + meta.lua, options) that the open twin plays is the export still owed, and most console scenes arm what the twin refuses. emitters is not written yet either (a break).

The gate (starlab/console/tools/door_check.py): a real Kinect take played into a scene with a body writing sand from its hands, a box, a sphere and a cell from verbs; the replay meets every checkpoint; the same run with one writer made to bypass the door diverges; a run with no writes agrees; a scene load under a recording is refused.

What this is not

Not a recording of frames (starlab.replay/1 is: cells every K steps, scrubbed, never stepped); not the console’s session tape (starlab/console/tools/tape.py, starbox verbs replayed on a live console, native lane only: its export to this kind is the console’s half of the slice); not the writing-session tape (docs/formats/tape.md, staros.steps/1); not the environment episode (envsvc.py: actions and a digest per ply over a served core). Each of those is a replay; this is the one a stranger plays on the open twin.

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-tape.md; the twin bfaad079a7ce (434093 bytes). The words are a draft.