# Iteration 1, host half (core-host) Design.md section A, items 9 and 10 (host side), and the owner's "Acceptance: timeline" script support. Paths below are relative to `lib/sketchbook/` unless they start with `sketches/`. ## What changed **One `update` per frame** (src/host/Host.zig, timeline.zig). - A frame is the events up to and including a `tick`. `Host.update` cuts whatever it is given (`timeline.frames`) and calls the sketch once per frame; events after the last tick are never fed. - `Timeline.tick` (playback), `seekCount`, `seekTime` and `step` only ever stop between frames. `step N` now moves N *frames* (it used to move N input events, skipping ticks); `seek ` lands on the last frame whose tick is due. - `in.now`/`in.dt` in `update` come from the frame's tick: `now` is the tick's time, `dt` is `Event.tickDt()` (the tick's f32 seconds, rounded to ns). Live uses the same path, so live and replay give the same bits (E4). While recording, the frame is captured *before* `update`, and capture rewrites the times to recorded ones, so live update sees exactly the bytes a replay will (consequence: `in.now` in `update` restarts near 0 when recording starts; nothing in the game or the ports reads it there). - Input reset (E2): any snapshot restore (`play`, `seek`, `step`, console `load`, `record`) sets `Timeline.restored`; `Host.runLine` then clears `mouse_*`, `buttons`, `keys`. On `record`, the input held before the reset is prepended to the first frame as events: a `mouse_move` (if the pointer is not at 0,0), a `mouse_down` per held button, a `key_down` per held key. The recording format is unchanged; a sketch sees those events once, when recording starts. - `abi.Event.tick(time, dt)` / `tickDt()`; the web host uses them too (src/sketch/web.zig `frame`), so `in.dt` agrees on both hosts. **Inspection** (src/layout.zig, memory.zig, fields.zig, script.zig, Console.zig, probe.zig, overlay.zig, web.zig). - `layout.flatten` makes arrays and byte-sized-lane vectors into element leaves with `[]` in the path, one leaf per element *field*, not per element: `boids.buffer[].pos[]` with `dims = {(64, 24), (2, 4)}` (count, stride, outermost first; `abi.Field.rank/dims`). Each array also stays as a whole leaf (kind `array`) for migration. Decision: indices are resolved at lookup (`abi.layout.match/resolve`, `Layout.find`), not stored. Storing every element would put e.g. the game's `tracker.songs` (8 songs x 16 patterns x 16 rows x 4 notes x 2 fields = 16k leaves) into a 64 KiB header and slow every lookup; strided leaves cost one row per field of the element type. - Syntax is the Zig one: `pos[0]`, `boids.buffer[3].pos[1]`, `grid[2][1]`. `get`/`set`/`expect`/`await`/`sk_field`/`sk_tag` all accept it. Vectors of bool or odd-width ints stay one opaque leaf. - `memory.compare` (behind `Bank.compare`, console `diff`, `expect-snapshot`) compares leaf by leaf, element by element, so padding never differs (E3). `diff` names the first differing leaf. - `expect F V ~T` / `await F V ~T`: numeric comparison within T. The field is looked up again every frame, so it works across a `load`. **Migration** (memory.zig). - Element-wise: for every new leaf with an old leaf of the same pattern path, the index tuples both have (min count per dimension) are copied: bytes when the element type hash is equal, enums by tag name otherwise. Shrink drops the tail, growth keeps the new defaults, scalar arrays keep their common prefix, `[2]f32` <-> `@Vector(2, f32)` carry over lane by lane. An array whose whole type is unchanged is copied in one piece and its element leaves skipped. - `List` clamp: agreed with draw-layer that `sk.List` accessors clamp `len` to the capacity; migration keeps `len` as it was. - File format: `SKETCH02` (StoredField grows to 40 bytes with `rank` and a `dims` offset into the string table). `SKETCH01` files are read: their arrays are whole leaves, which migrate whenever the array type is unchanged (so `tracker.songs` survives). An unchanged layout on a v1 file just rewrites the header. Any other file is refused with `NotAStateFile` / `CorruptStateFile`, untouched (E11). The store's layout header follows the same scheme (`SKSTORE2`, reads `SKSTORE1`); a `.store` that is not a store is refused unless `--fresh`. - Checked by hand on a copy of `drat-meout.state` with today's game: "kept 72 fields, reset 4" (4 fields added since the file was written), songs byte-identical, probe prints `tracker.songs[].bpm [8] ... 156 168`. **Recording stamp** (timeline.zig, Host.zig, Console.zig). `Host.build` is a hash of the library file (or `/proc/self/exe` when linked), recomputed on each load; `record` stores it in `Recording.reserved` (old recordings read as 0, unknown, no warning); `play` (and a seek/step that starts playback) logs "Warning: recorded by another build of the sketch; the replay may differ." A hash of the file, so a draw-only edit also warns: it is a warning. **Harness** (root.zig, Host.zig, build.zig). - Scripted `--fresh` runs work on `.` (+ `.inputs`, `.store`), renamed to the given `--state` at exit. Two `zig build e2e` at once share the Run step's output path, which caused "store is open in another process". Verified: two concurrent noc `e2e` builds pass. - Segfault: `Host.init` registered the renderer's `errdefer` before the GPU device's, so on an error (store busy) the device was destroyed first and `SDL_DestroyRenderer` used it. Swapped; the store-busy path now exits with `StoreInUse`. - `LeakedSdlMemory` under parallel e2e: not ours. Every leak trace is `VULKAN_INTERNAL_AllocateMemory` (SDL 3.4.18, SDL_gpu_vulkan.c ~1866): when `vkAllocateMemory` fails it frees `freeRegions` and the allocation but not `usedRegions` and `memoryLock`, then falls back to another memory type and carries on. With 12+ headless Vulkan devices, some heap runs out and the fallback path runs. Fix: build.zig compiles that file from a copy with the two frees added (`fixSdlVulkanAllocationLeak`, via draw-layer's `tools/reload_edit.zig`). Before: 3 of 3 parallel noc runs failed; after: 6 of 6 passed (incl. two concurrent builds, 24 processes). Worth sending upstream. **Script commands** (script.zig): `expect-snapshot N` (prints up to 5 differing leaves with both values), `expect-log`/`expect-no-log TEXT`, `expect-same-screenshot A B [MAX [X Y W H]]`, `expect-different-screenshot A B [X Y W H]`, `expect-pixel FILE X Y R G B A [TOL]` (the last three also for draw-layer's reload checks). ## Timeline template `sketches/noc/test/accel_to_mouse.timeline.script`, wired into noc's `e2e` through the `timelines` list in `sketches/noc/build.zig`. It records pointer input, then checks play-to-end, pause, seek end, seek middle and play on, step from the start and back and forth, replay after a live move (each `expect-snapshot 2`), and play-end vs seek-end screenshots. With `Host.update` temporarily switched back to one call per batch it fails (`position[0]: live 327.02, snapshot 2 340.14`); with the fix it passes. ## Tests - layout.zig: element leaves and dims; vector lanes and nested array elements resolve by index, out-of-range and malformed paths do not. - fields.zig: get/set/match through indexed paths (lanes, struct elements, enums). - memory.zig: element-wise migration (field added to an element, enum per element by name, shrink, regrow, scalar prefix, `[2]f32` to `@Vector`, `[2][3]` to `[3][2]`); `[8]Song` gaining a field keeps every song; unchanged arrays copy whole; leaf-wise compare ignores every padding byte and names `list[1].d`; a non-state file (short and long) is refused and left byte-identical; `test/fixtures/drat-meout-v1.state-fixture` (a copy of the game's file) reopens with every byte, gets a v2 header, then migrates to a changed layout keeping every other leaf. - timeline.zig: playback at 1 ms steps never yields a partial frame; seek-time between input and tick, seek end, step back/forward land on frame boundaries; a cut-off trailing frame is never fed; the stamp is stored; live and recorded ticks give the same dt (E4 values). - test/replay.script (new `zig build test` step, sketch test/replay.zig): button held before `record` (seeded), shift held mid-recording, clicks, pointer chasing; `expect` with indices and `~`; then play to end, pause, seek end, seek start + step 1000, step -7/+7, seek 200 + play on, `diff`, and replay after a live move and press, each `expect-snapshot 2`. The sum of `in.dt` is in State, so live dt == replayed dt is checked too. - test/reload.script: recording made by v1 plays without the warning; after `load {v2}` the same recording warns; `expect streak 7 ~0.5` right after the load. - Passing: `zig build test` (lib/sketchbook), the game's `zig build test e2e`, `sketches/noc` and `sketches/shaders` `zig build e2e` (parallel, several times). No noc script needed new expected values. ## Deferred / notes - Migration does not clamp a `List`'s `len` (the host does not know which field is a count); `get boids.len` can read more than the capacity after a shrink. A `pub const sketchbook_list = true` marker would let it; not needed while accessors clamp. - v1 files: an array whose element type changed resets (v1 headers do not describe elements). After the first write everything is element-wise. - Seeded record-start events are visible to the sketch (a held button arrives as a `mouse_down` on the first recorded frame). - Fields no event carries (`width`, `window_*`, `console`, `frame`) still reach `update` and do not replay; documented in the README, not narrowed. - The memory overlay lists arrays as wholes (``), not elements. - The build stamp hashes the whole file; a narrower identity (State layout + `update`'s code) would avoid warnings on draw-only edits.