<!-- 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 tape (`starlab.tape/1`)

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

*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

```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" },
}
```

- `format` is 1. `name` is the world's name and must equal `meta.lua`'s. `first_frame` must equal the frame the
  world stands at when opened (`meta.lua`'s `frame`, 0 when absent). `steps` is a non-negative integer.
- `options` is what the save does not carry and the replay must repeat, as integers: `sim_salt`, `model_mask`
  (the engine's model bits), `xfer_every`, `air_every`. An absent key is the reference's default. For a tape these
  live in the content, not in `cart.toml`'s `[replay]`: they change what the run IS, and the content digest must
  cover them. (`cart.toml`'s `[replay]` may mirror them for a world cart's tooling; the tape's are authoritative.)
- `ops` is the list of world-mutating acts in the order they are applied. Each has `at`, an integer frame with
  `first_frame ≤ at < first_frame + steps`, and `op`, one of the names below. The list is sorted by `at`; two ops at
  one frame apply in list order.
- `checkpoints` lists at least one `{ frame, grid_hash }`, frames strictly increasing within
  `[first_frame, first_frame + steps]`, each `grid_hash` sixteen lowercase hex digits (the engine's `grid_hash`,
  the digest `starlab_sim_grid_hash` prints and the twin's `grid_hash()` reproduces). **The last frame's checkpoint
  is required**: a tape with no digest at its end claims nothing.
- `recorder` is optional provenance, free-form strings the reference does not check and the record carries: which
  app recorded, the engine it ran (`engine_sha256`), its backend. It answers the determinism program's open
  question (c), "tapes carry no provenance".

### 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 | z<<20` (the engine's packing); a cell named twice keeps the last word | `edit_cells` (per cell, in order) |
| `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.

```lua
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):

- **`source`** on every op: who wrote (`"humanoid:<id>"`, `"character:bite"`, `"serpent:graze"`,
  `"kinect_life:joint"`, `"verb:<action>"`; `"untagged"` for a caller that has not said). The design's source
  attribution. A reader that plays the tape ignores it; a reader that audits one groups by it.
- **`via = "edit_box"`** on a `box` the console wrote on the device (`edit_box`) rather than through the host
  (`spawn_box_state`): the console's replay calls the writer that made it. The two write the same words.
- **`temp` and `state`** are the bytes the engine was handed (0 to 255), left out for the material's default.
- **`breaks`**, a top-level list `{ at, kind, source }`: writes the format cannot carry that happened under the
  recording (`write_box`, `load_linear`, `restore`, `record_load`, `clear`, `blast`, `emitters`). A tape with a
  break is not replayable and says so: the console refuses to replay it, and so should any reader.
- **`recorder`**: `{ app = "starlab-console", door = 1, every, trailing? }`. `trailing` counts writes made after the
  last step: by the clock above they are in no tape, and the tape is cut back to the last frame whose arrival
  digest was measured.

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

<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="../../starscript/">← starscript</a><a href="../../">The reference</a><a href="../../formats/world-edition/">formats/world-edition →</a></nav>

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

</div>
