@joystack/cli 0.0.0-stage → 0.1.43

package/lib/replay-store.mjs

@@ -0,0 +1,719 @@
+// The dev recording store — where a session you just played is kept.
+//
+// In dev the room server, the game folder and the person who played are all on
+// one machine, so a recording has no reason to make a round trip: the room
+// posts each closed segment to the dev server (see sessionIngestUrlFor in
+// shared/ui/room/session-ingest.js) and it lands here, under the game's
+// `.joystack/replays/<stream>/`. Watching a session back is then just reading
+// files that are already on disk — which is what makes `?replay=<id>` a URL
+// you paste rather than a fetch with credentials behind it.
+//
+// A PUBLISHED game is the other case entirely: its room is a Worker, the only
+// durable place is the platform, and segments go to /sessions/ingest (R2 +
+// D1). Nothing here is involved in that lane.
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, existsSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { BUILD_ID_RE } from './build-id.mjs';
+import { canonicalFormat, stateDir } from './legacy-names.mjs';
+
+// The stream id is minted room-side from a timestamp and a counter, and it is
+// interpolated into a filesystem path — so its charset is pinned here rather
+// than trusted. Anything with a separator, a dot segment, or nothing in it is
+// refused outright instead of being sanitized into something plausible.
+const STREAM_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+// Where a dev room posts its closed segments. The engine derives the same path
+// in shared/ui/room/session-ingest.js (DEV_SEGMENT_PATH there) — the two ends
+// of one wire, kept spelled out in both so neither can drift silently.
+export const DEV_SEGMENT_PATH = '/__joystack/segments';
+
+// Where the dev page asks what recordings exist, deletes one, or pins one
+// against the prune — the read half of the same lane. Spelled out in the
+// engine's Sessions tool too (shared/ui/sessions/sessions.js), for the same
+// reason as above: two ends of one wire, neither able to drift silently.
+export const DEV_REPLAYS_PATH = '/__joystack/replays';
+
+export function replaysRoot(projectDir) {
+  return join(stateDir(projectDir), 'replays');
+}
+
+export function streamDir(projectDir, stream) {
+  if (!STREAM_RE.test(stream ?? '')) throw new Error(`invalid stream id: ${JSON.stringify(stream)}`);
+  return join(replaysRoot(projectDir), stream);
+}
+
+/**
+ * Persist one closed segment. The address is (stream, seq), the same pair the
+ * production index uses, so a room's bounded retry rewrites the same file
+ * rather than appending a duplicate.
+ * @param {string} projectDir - the game folder
+ * @param {{ slug?: string, room?: string, segment: object }} body - the room's POST body
+ * @param {{ maxTrackBytes?: number, stamp?: () => object }} [opts] - the per-session
+ *   track limit (tests), and the build stamp (see `stampBuild`)
+ * @returns {{ stored: true, stream: string, seq: number }}
+ */
+export function writeSegment(projectDir, body, opts = {}) {
+  const segment = body?.segment;
+  const header = segment?.header;
+  if (!header || typeof header !== 'object') throw new Error('not a segment: no header');
+  const format = canonicalFormat(header.format);
+  if (format === TRACK_SEGMENT_FORMAT) return writeTrackSegment(projectDir, segment, opts);
+  if (format !== 'joystack-replay-seg/1') {
+    throw new Error(`not a segment: format ${JSON.stringify(header.format)}`);
+  }
+  // Bounded above as well as below: `seq` names the file, and while no number's
+  // string form can contain a separator, an unbounded one lets a sender pick
+  // arbitrary names in the stream directory (`1e21`, `9007199254740992`) that
+  // the reader's lexical sort then misorders. A stream that reaches a million
+  // segments is a bug, not a session.
+  //
+  // The bound is EXCLUSIVE because the filename is six digits: an accepted
+  // 1000000 would write `1000000.json`, which SEGMENT_FILE_RE never matches, so
+  // the store would answer `stored: true` (stopping the room's retries) to a
+  // segment no reader can see and no retention cap can ever sweep.
+  if (!Number.isInteger(header.seq) || header.seq < 0 || header.seq >= 1e6) {
+    throw new Error('not a segment: bad seq');
+  }
+  if (!Array.isArray(segment.events)) throw new Error('not a segment: no events');
+  const dir = streamDir(projectDir, header.stream);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, segmentFileName(header.seq)), JSON.stringify(segment));
+  updateIndex(dir, segment);
+  if (opts.stamp) stampBuild(dir, opts.stamp);
+  return { stored: true, stream: header.stream, seq: header.seq };
+}
+
+// ── the per-stream index ────────────────────────────────────────────────────
+//
+// The Sessions panel asks each recording when it was played, how long it ran
+// and how many inputs it carries. Every one of those lives in the segments, so
+// answering from the segments costs the whole recording — a five-minute session
+// is megabytes, and the panel asks about twenty of them at once, on a phone.
+// So each segment write also folds its own contribution into a small file
+// beside the segments, and reading a stream's headline facts is then one small
+// read instead of a full parse.
+//
+// The counts are held PER SEQ rather than as a running total because a segment
+// can legitimately arrive twice: a room's flush retries are idempotent by
+// (stream, seq) and rewrite the same file, so a running total would count that
+// segment's inputs again every time the network hiccuped.
+//
+// Keyed as an OBJECT rather than indexed into an array, because `seq` comes off
+// the wire from an endpoint nothing authenticates. An array indexed at seq
+// 999999 serialises 999999 holes as `null` — so a 160-byte POST would write
+// megabytes here, none of it visible to the retention caps, and every later
+// listing would reduce over a million elements inside the dev server's one
+// thread. An object costs one entry per segment that actually exists.
+//
+// The index is derived, never authoritative: it is rebuilt from the segments
+// whenever it is missing or was written by an older shape, so deleting it is a
+// safe thing for anyone to do and an older recording gains one on first read.
+const INDEX_FILE = 'index.json';
+const INDEX_VERSION = 2;
+
+// Segments are the six-digit files; everything else in the directory (this
+// index, the keep marker) is bookkeeping and is not a segment.
+const SEGMENT_FILE_RE = /^\d{6}\.json$/;
+
+// A TRACK segment (project note ofta45) is the cost half of a session: the
+// same stream, written by a different producer — in multiplayer, by each
+// player's browser rather than by the room. It lands FLAT in the stream's
+// directory rather than in a subfolder, so every byte of it is visible to the
+// retention caps and one `rm -rf` of the directory still takes the whole
+// session with it.
+//
+// `<kind>.<producer>.<seq>.json`, with `.` as the separator precisely because
+// neither field may contain one: the name parses back into its three parts
+// with no ambiguity, and no value either field can hold reaches another
+// directory.
+const TRACK_SEGMENT_FORMAT = 'joystack-track-seg/1';
+const TRACK_KIND_RE = /^[a-z0-9][a-z0-9-]{0,15}$/;
+// Long enough for a whole connection id (a UUID is 36 characters): the
+// producer is what joins a browser's frames to the recording's own record of
+// that player, so a name cut short of the id joins nothing.
+const TRACK_PRODUCER_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const TRACK_FILE_RE = /^([a-z0-9][a-z0-9-]{0,15})\.([a-z0-9][a-z0-9-]{0,63})\.(\d{6})\.json$/;
+
+function segmentFileName(seq) {
+  // Zero-padded so a directory listing is already in stream order — the same
+  // reason the R2 key is padded.
+  return `${String(seq).padStart(6, '0')}.json`;
+}
+
+/**
+ * Persist one closed TRACK segment — the cost half of a session, written by
+ * the browser that measured it. The address is (stream, kind, producer, seq),
+ * so a browser's bounded retry rewrites the same file, and two players in one
+ * room never collide.
+ *
+ * A track is additive: the recording is complete without it, and a reader that
+ * finds none says so rather than failing. So nothing here touches the
+ * recording's index — a track segment is not a recording segment, and counting
+ * it as one would misreport how much of the session is on disk.
+ */
+// What one session's cost track may take up, and what one segment of it may
+// be. A real track runs about 1 MB a minute, so the per-session ceiling is
+// several hours of play: long enough that no session a person plays reaches
+// it. It exists because the endpoint that accepts a track segment is the dev
+// server's, open to anything that can reach it (a second player's browser is
+// the intended case), and the bytes land in a folder the retention sweep
+// measures: without a ceiling, one sender could push a session past the
+// folder's byte cap (MAX_RECORDING_BYTES, several times this) and make the
+// sweep delete OTHER sessions to get back under it.
+export const MAX_TRACK_BYTES_PER_STREAM = 512 * 1024 * 1024;
+export const MAX_TRACK_SEGMENT_BYTES = 2 * 1024 * 1024;
+
+// What the track already occupies in this stream's folder.
+function trackBytes(dir) {
+  let bytes = 0;
+  let names;
+  try { names = readdirSync(dir); } catch { return 0; }
+  for (const name of names) {
+    if (!TRACK_FILE_RE.test(name)) continue;
+    try { bytes += statSync(join(dir, name)).size; } catch { /* vanished mid-scan */ }
+  }
+  return bytes;
+}
+
+function writeTrackSegment(projectDir, segment, { maxTrackBytes = MAX_TRACK_BYTES_PER_STREAM } = {}) {
+  const h = segment.header;
+  if (!TRACK_KIND_RE.test(h.kind ?? '')) throw new Error(`not a track segment: bad kind ${JSON.stringify(h.kind)}`);
+  if (!TRACK_PRODUCER_RE.test(h.producer ?? '')) {
+    throw new Error(`not a track segment: bad producer ${JSON.stringify(h.producer)}`);
+  }
+  // Same bound and same reason as a recording segment's seq: the number names
+  // the file, and an unbounded one lets a sender pick names no reader matches.
+  if (!Number.isInteger(h.seq) || h.seq < 0 || h.seq >= 1e6) throw new Error('not a track segment: bad seq');
+  const dir = streamDir(projectDir, h.stream);
+  const body = JSON.stringify(segment);
+  const name = trackFileName(h.kind, h.producer, h.seq);
+  // Refused rather than thrown: a track is additive, so a browser that has
+  // written more than its share is told no and the session carries on. The
+  // ceilings are decided above; what matters here is that neither one is a
+  // reason to fail a POST that also carried a recording.
+  if (body.length > MAX_TRACK_SEGMENT_BYTES) {
+    return { stored: false, reason: 'too-large', stream: h.stream, seq: h.seq, kind: h.kind, producer: h.producer };
+  }
+  mkdirSync(dir, { recursive: true });
+  // The file being rewritten is a retry of a segment already counted, so its
+  // current size comes off the total rather than counting twice.
+  let already = trackBytes(dir);
+  try { already -= statSync(join(dir, name)).size; } catch { /* first write of this seq */ }
+  if (already + body.length > maxTrackBytes) {
+    noteTrackCut(dir, h, maxTrackBytes);
+    return { stored: false, reason: 'budget', stream: h.stream, seq: h.seq, kind: h.kind, producer: h.producer };
+  }
+  writeFileSync(join(dir, name), body);
+  return { stored: true, stream: h.stream, seq: h.seq, kind: h.kind, producer: h.producer };
+}
+
+// Where the per-session limit cut each browser's track, kept beside the
+// segments. A refused stretch is one nobody will ever read, and without this a
+// reader reports it exactly as it reports measuring switched off — a false
+// reason. One entry per (kind, producer), holding the earliest tick refused:
+// segments can arrive out of order (a beacon, a retried post), and the cut is
+// where refusing began. At most MAX_TRACK_CUTS entries, because the producer
+// name is the sender's to choose and a stream already over its limit must not
+// grow a second file without bound.
+const TRACK_LIMIT_FILE = 'track-limit.json';
+const MAX_TRACK_CUTS = 16;
+
+function noteTrackCut(dir, header, limitBytes) {
+  const fromTick = Number.isFinite(header.startTick) ? header.startTick : null;
+  const file = join(dir, TRACK_LIMIT_FILE);
+  let record = null;
+  try { record = JSON.parse(readFileSync(file, 'utf8')); } catch { /* the first cut */ }
+  const cuts = Array.isArray(record?.cuts) ? record.cuts : [];
+  const at = cuts.find((c) => c?.kind === header.kind && c?.producer === header.producer);
+  if (at) {
+    if (fromTick === null || (at.fromTick !== null && at.fromTick <= fromTick)) return;
+    at.fromTick = fromTick;
+  } else {
+    if (cuts.length >= MAX_TRACK_CUTS) return;
+    cuts.push({ kind: header.kind, producer: header.producer, fromTick });
+  }
+  try {
+    writeFileSync(file, JSON.stringify({ limitBytes, cuts }));
+  } catch {
+    // The note is for the reader; failing to write it costs the explanation,
+    // never the refusal it explains.
+  }
+}
+
+/**
+ * Where the per-session limit cut this stream's track, or null when it never
+ * did.
+ * @returns {{ limitBytes: number, cuts: { kind: string, producer: string, fromTick: number|null }[] }|null}
+ */
+export function readTrackLimits(projectDir, stream) {
+  let record;
+  try {
+    record = JSON.parse(readFileSync(join(streamDir(projectDir, stream), TRACK_LIMIT_FILE), 'utf8'));
+  } catch {
+    return null;
+  }
+  const cuts = (Array.isArray(record?.cuts) ? record.cuts : [])
+    .filter((c) => c && typeof c === 'object' && typeof c.producer === 'string' && typeof c.kind === 'string')
+    .map((c) => ({ kind: c.kind, producer: c.producer, fromTick: Number.isFinite(c.fromTick) ? c.fromTick : null }));
+  if (!cuts.length) return null;
+  return { limitBytes: Number.isFinite(record.limitBytes) ? record.limitBytes : null, cuts };
+}
+
+function trackFileName(kind, producer, seq) {
+  return `${kind}.${producer}.${String(seq).padStart(6, '0')}.json`;
+}
+
+/**
+ * Every track segment of one kind in a stream, in producer then seq order.
+ *
+ * Empty when the session carries no track: a recording made with measuring
+ * switched off, or by an engine from before tracks existed. That is a
+ * different answer from "no such recording", and the caller reports it as a
+ * session whose cost was not recorded.
+ *
+ * @param {string} projectDir - the game folder
+ * @param {string} stream - the recording's stream id
+ * @param {string} [kind] - which track, 'perf' by default
+ */
+export function readTrackSegments(projectDir, stream, kind = 'perf') {
+  const dir = streamDir(projectDir, stream);
+  let names;
+  try { names = readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const name of names.sort()) {
+    const m = TRACK_FILE_RE.exec(name);
+    if (!m || m[1] !== kind) continue;
+    try {
+      out.push(JSON.parse(readFileSync(join(dir, name), 'utf8')));
+    } catch {
+      // A half-written file — the dev server was killed mid-POST. The same
+      // tolerance the recording's own rebuild has: one lost segment, not a
+      // lost session.
+    }
+  }
+  return out;
+}
+
+/** Which kinds of track a stream carries, sorted. */
+function trackKinds(names) {
+  const kinds = new Set();
+  for (const name of names) {
+    const m = TRACK_FILE_RE.exec(name);
+    if (m) kinds.add(m[1]);
+  }
+  return [...kinds].sort();
+}
+
+function countInputs(segment) {
+  // A recorded INPUT is a `w` — an accepted wire send, the player doing
+  // something. Spawns, roster changes and checksums are the world's own
+  // bookkeeping and are not things anybody did.
+  return (segment?.events ?? []).reduce((n, e) => n + (e?.k === 'w' ? 1 : 0), 0);
+}
+
+function foldSegment(index, segment) {
+  const h = segment.header;
+  const seq = h.seq;
+  // Anchored on the SEQ alone. `startedAt` is null in a runtime with no Date
+  // (recorder.js writes it conditionally), and keying on "we have no stamp yet"
+  // would make every later segment re-anchor — so `startTick` would track the
+  // last segment written and the duration would collapse to one segment's span,
+  // or go negative.
+  if (seq < (index.firstSeq ?? Infinity)) {
+    index.firstSeq = seq;
+    index.startedAt = h.startedAt ?? null;
+    index.startTick = h.startTick ?? 0;
+  }
+  if (h.tickRate) index.tickRate = h.tickRate;
+  // Whether this stream can be ENTERED. A replay starts at a keyframe, so a
+  // stream that has not cut one yet is on disk and not yet watchable — a
+  // not-yet, not a corruption, and a different answer from "no such recording".
+  if (h.keyframe) index.hasKeyframe = true;
+  const end = segment.endTick ?? h.startTick ?? 0;
+  index.endTick = Math.max(index.endTick ?? -Infinity, end);
+  index.inputsBySeq[String(seq)] = countInputs(segment);
+  return index;
+}
+
+function emptyIndex(stream) {
+  return { v: INDEX_VERSION, stream, startedAt: null, firstSeq: null, startTick: 0, endTick: null,
+    tickRate: null, hasKeyframe: false, inputsBySeq: {} };
+}
+
+// Read every segment in a stream and fold them into a fresh index. The slow
+// path, taken once per stream: on the first write, and on the first read of a
+// recording made before this file existed.
+function rebuildIndex(dir, stream) {
+  const index = emptyIndex(stream);
+  for (const name of readdirSync(dir).sort()) {
+    if (!SEGMENT_FILE_RE.test(name)) continue;
+    try {
+      const seg = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+      if (canonicalFormat(seg?.header?.format) === 'joystack-replay-seg/1') foldSegment(index, seg);
+    } catch {
+      // A half-written file (the dev server was killed mid-POST) must not cost
+      // the rest of the session — the same tolerance stitching has.
+    }
+  }
+  return index;
+}
+
+function readIndex(dir) {
+  try {
+    const index = JSON.parse(readFileSync(join(dir, INDEX_FILE), 'utf8'));
+    if (index?.v === INDEX_VERSION && index.inputsBySeq && typeof index.inputsBySeq === 'object'
+      && !Array.isArray(index.inputsBySeq)) return index;
+  } catch {
+    // Missing, half-written, or an older shape — all one case: rebuild.
+  }
+  return null;
+}
+
+function writeIndex(dir, index) {
+  try {
+    writeFileSync(join(dir, INDEX_FILE), JSON.stringify(index));
+  } catch {
+    // The index is a cache. A game folder that has gone read-only must not
+    // turn a recorded session into a failed POST.
+  }
+}
+
+function updateIndex(dir, segment) {
+  // Absent means rebuild rather than start over: an index deleted mid-stream
+  // would otherwise silently lose every segment written before it went.
+  const existing = readIndex(dir);
+  writeIndex(dir, existing ? foldSegment(existing, segment) : rebuildIndex(dir, segment.header.stream));
+}
+
+// ── the read side ───────────────────────────────────────────────────────────
+
+// Presence is the whole marker: a recording under triage must survive the
+// prune, and the flag lives in its own FILE rather than in the index because
+// the index is rewritten on every segment write — a keep toggled while that
+// stream is still recording would lose the race. Deleting the directory still
+// takes the marker with it.
+const KEEP_FILE = 'keep';
+
+// ── the build stamp ─────────────────────────────────────────────────────────
+//
+// Which code recorded the session: the game's build id (build-id.mjs), the
+// commit its files came from and whether they differed from it, and the engine
+// version the dev server was serving. A recording's own header cannot say
+// this. The page and the room know neither the game's files nor its git, and
+// a room served straight off `joystack dev` carries a placeholder where a
+// published build carries its engine version.
+//
+// Taken once per session, when its first recording segment lands — which is
+// within seconds of the page loading the code it records. Never taken for a
+// track segment: a browser's cost track is not the recording, and a stream
+// holding only tracks has no code to vouch for. A stamp that fails (no git, a
+// file vanished mid-walk) is simply absent: the recording it describes is
+// worth more than the description.
+const BUILD_FILE = 'build.json';
+
+// Sessions this process has already tried to stamp. A stamp that failed is
+// not tried again on every later segment of the same session.
+const stampTried = new Set();
+
+function stampBuild(dir, take) {
+  const file = join(dir, BUILD_FILE);
+  if (stampTried.has(file) || existsSync(file)) return;
+  stampTried.add(file);
+  try {
+    writeFileSync(file, JSON.stringify({ ...take(), stampedAt: Date.now() }));
+  } catch {
+    // See above: the recording is stored either way.
+  }
+}
+
+const COMMIT_RE = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+const ENGINE_RE = /^[0-9A-Za-z][0-9A-Za-z.+-]{0,63}$/;
+
+/**
+ * A session's build stamp, or null when it has none. The file sits in a folder
+ * anyone can copy a recording into, so each field is kept only when it is the
+ * shape it claims and is otherwise null — never sanitized into something that
+ * looks right.
+ *
+ * @returns {{ id: string|null, files: number|null, git: { commit: string, dirty: boolean|null }|null,
+ *   engine: string|null, stampedAt: number|null } | null}
+ */
+export function readBuildStamp(projectDir, stream) {
+  let raw;
+  try { raw = JSON.parse(readFileSync(join(streamDir(projectDir, stream), BUILD_FILE), 'utf8')); } catch { return null; }
+  if (!raw || typeof raw !== 'object') return null;
+  const is = (v, re) => typeof v === 'string' && re.test(v);
+  const git = raw.git && typeof raw.git === 'object' && is(raw.git.commit, COMMIT_RE)
+    ? { commit: raw.git.commit, dirty: typeof raw.git.dirty === 'boolean' ? raw.git.dirty : null }
+    : null;
+  return {
+    id: is(raw.id, BUILD_ID_RE) ? raw.id : null,
+    files: Number.isSafeInteger(raw.files) && raw.files >= 0 ? raw.files : null,
+    git,
+    engine: typeof raw.engine === 'string' && ENGINE_RE.test(raw.engine) ? raw.engine : null,
+    stampedAt: Number.isFinite(raw.stampedAt) ? raw.stampedAt : null,
+  };
+}
+
+/**
+ * Every recording this game has on disk, newest first.
+ *
+ * Each entry carries what the Sessions panel shows: when it was played, how
+ * long it ran, how many inputs it holds, what it weighs, and whether it is
+ * pinned against the prune. Cost is one small read and a stat per file — never
+ * a parse of the recordings themselves (see the index above).
+ *
+ * @param {string} projectDir - the game folder
+ * @returns {Array<{ stream: string, startedAt: number|null, durationMs: number|null,
+ *   inputs: number, segments: number, bytes: number, kept: boolean }>}
+ */
+export function listRecordings(projectDir) {
+  const root = replaysRoot(projectDir);
+  if (!existsSync(root)) return [];
+  const out = [];
+  for (const stream of readdirSync(root)) {
+    // Only names this store could have minted. A creator copying a teammate's
+    // recording in calls the directory whatever they like, and listing one made
+    // `deleteRecording` throw on a name `streamDir` refuses — inside a prune
+    // that runs before `joystack dev` binds a port, so the whole stack failed to
+    // start over a directory name. The two functions agree on the charset here.
+    if (!STREAM_RE.test(stream)) continue;
+    const dir = join(root, stream);
+    let names;
+    try {
+      if (!statSync(dir).isDirectory()) continue;
+      names = readdirSync(dir);
+    } catch {
+      continue;
+    }
+    const segments = names.filter((n) => SEGMENT_FILE_RE.test(n));
+    const tracks = trackKinds(names);
+    // A folder with neither is not this store's.
+    if (!segments.length && !tracks.length) continue;
+    // A folder holding ONLY tracks is listed too, with nothing to watch. It is
+    // either a session whose recording never landed or bytes somebody posted
+    // at a stream id no recording ever used — and both are the store's to
+    // account for: the retention caps bound a folder, and anything left out of
+    // the inventory is something the prune can never reclaim however much of
+    // it there is. A track is written by a browser over the same open dev
+    // endpoint the recording uses, so "however much" is not hypothetical.
+    let index = segments.length ? readIndex(dir) : (readIndex(dir) ?? emptyIndex(stream));
+    if (!index) {
+      index = rebuildIndex(dir, stream);
+      writeIndex(dir, index);
+    }
+    // Every file, not only the segments: the caps exist to bound a folder, and
+    // anything left out of the measurement is something the prune can never
+    // reclaim however much of it there is.
+    let bytes = 0;
+    for (const name of names) {
+      try { bytes += statSync(join(dir, name)).size; } catch { /* the file vanished mid-scan */ }
+    }
+    const ticks = index.endTick == null ? null : index.endTick - (index.startTick ?? 0);
+    out.push({
+      stream,
+      startedAt: index.startedAt ?? null,
+      // The tick span, which is the axis a performance track joins on.
+      startTick: index.startTick ?? 0,
+      endTick: index.endTick ?? null,
+      durationMs: ticks != null && index.tickRate ? (ticks / index.tickRate) * 1000 : null,
+      tickRate: index.tickRate ?? null,
+      inputs: Object.values(index.inputsBySeq).reduce((n, v) => n + (v ?? 0), 0),
+      segments: segments.length,
+      bytes,
+      // A replay enters at a keyframe. A stream a few seconds old has not cut
+      // one yet, so it is on disk and not yet watchable.
+      watchable: index.hasKeyframe === true,
+      // Which cost tracks were recorded alongside it, if any (project note
+      // ofta45). Empty is the ordinary answer for a session played with
+      // measuring switched off.
+      tracks,
+      // Which code recorded it, when the dev server that stored it said so.
+      build: readBuildStamp(projectDir, stream),
+      kept: existsSync(join(dir, KEEP_FILE)),
+    });
+  }
+  // Newest first, by the wall clock the room stamped rather than by mtime: a
+  // copied folder keeps its play order, and the list reads the way the person
+  // remembers playing. Streams with no stamp sort last rather than first.
+  return out.sort((a, b) => (b.startedAt ?? -Infinity) - (a.startedAt ?? -Infinity));
+}
+
+/**
+ * The most recent recording that can actually be WATCHED, or null.
+ *
+ * Newest-that-is-watchable rather than newest: a stream cuts its first keyframe
+ * a few seconds in, so the very newest recording is routinely not enterable
+ * yet — and `?replay=last` resolving to it would answer "no recording ... it is
+ * recorded on the machine that played it" while a perfectly watchable session
+ * sits right behind it, on the machine asking.
+ */
+export function latestRecording(projectDir) {
+  return listRecordings(projectDir).find((r) => r.watchable)?.stream ?? null;
+}
+
+/**
+ * Delete one recording, whole. Returns false when there was nothing there —
+ * deleting a session twice is not an error, it is the second tap.
+ */
+export function deleteRecording(projectDir, stream) {
+  const dir = streamDir(projectDir, stream);
+  if (!existsSync(dir)) return false;
+  rmSync(dir, { recursive: true, force: true });
+  return true;
+}
+
+/**
+ * Pin a recording against the prune, or unpin it. Returns false when there is
+ * no such recording.
+ */
+export function setKept(projectDir, stream, kept) {
+  const dir = streamDir(projectDir, stream);
+  if (!existsSync(dir)) return false;
+  const marker = join(dir, KEEP_FILE);
+  if (kept) writeFileSync(marker, '');
+  else rmSync(marker, { force: true });
+  return true;
+}
+
+// What a game's recordings may take up before the oldest start going. Two caps
+// because either one alone has a case it cannot see: a game with big worlds
+// hits the byte cap after a handful of sessions, and a small game would sit at
+// a few megabytes while accumulating hundreds of directories.
+export const MAX_RECORDINGS = 20;
+// A real session writes about 2.7 MB a minute of recording and 1 MB of track,
+// so the byte cap holds well over ten hours of play; for most games the count
+// is the cap that bites.
+export const MAX_RECORDING_BYTES = 3 * 1024 * 1024 * 1024;
+
+/**
+ * Bring a game's recordings back under the caps, oldest first.
+ *
+ * Pinned recordings are never swept, and they still COUNT against the caps —
+ * pinning is "do not delete this", not "do not charge me for it". Pin
+ * everything and the caps simply stop having anything to take, which is the
+ * honest outcome: the alternative silently deletes an unpinned session the
+ * creator only just made.
+ *
+ * @param {string} projectDir - the game folder
+ * @param {{ maxCount?: number, maxBytes?: number }} [caps]
+ * @returns {{ removed: string[], bytes: number, count: number, caps: { maxCount: number, maxBytes: number } }}
+ *   what went, what is left, and the caps that decided it
+ */
+export function pruneRecordings(projectDir, { maxCount = MAX_RECORDINGS, maxBytes = MAX_RECORDING_BYTES } = {}) {
+  // Oldest first: the sweep order is the reverse of the reading order.
+  const all = listRecordings(projectDir).reverse();
+  let count = all.length;
+  let bytes = all.reduce((n, r) => n + r.bytes, 0);
+  const removed = [];
+  for (const rec of all) {
+    if (count <= maxCount && bytes <= maxBytes) break;
+    if (rec.kept) continue;
+    // A delete that fails for its own reason (a permission, a file held open)
+    // costs that one recording, never the startup this runs inside.
+    try {
+      if (!deleteRecording(projectDir, rec.stream)) continue;
+    } catch {
+      continue;
+    }
+    removed.push(rec.stream);
+    count -= 1;
+    bytes -= rec.bytes;
+  }
+  return { removed, bytes, count, caps: { maxCount, maxBytes } };
+}
+
+/**
+ * Read a whole stream back as the single playable recording the replay
+ * transport consumes, or null when there is nothing enterable there.
+ *
+ * Stitching goes through the ENGINE's `stitchSegments` rather than a copy: it
+ * is the same reassembler the recorder's own export() uses, which is what
+ * keeps "segments are just a slicing of the recording" true by construction.
+ * It is imported from the resolved engine bundle, so a recording is always
+ * read back by the engine that wrote it — from `entity/stitch.js`, which is
+ * the reassembler alone, rather than through the recorder and its runtime
+ * dependencies.
+ *
+ * @param {string} projectDir - the game folder
+ * @param {string} stream
+ * @param {string} sharedDir - the engine bundle's shared/ tree
+ * @returns {Promise<string|null>} the recording as JSON text
+ */
+export async function stitchStream(projectDir, stream, sharedDir) {
+  const dir = streamDir(projectDir, stream);
+  if (!existsSync(dir)) return null;
+  const segments = [];
+  for (const name of readdirSync(dir).sort()) {
+    if (!SEGMENT_FILE_RE.test(name)) continue;
+    try {
+      const seg = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+      if (canonicalFormat(seg?.header?.format) === 'joystack-replay-seg/1') segments.push(seg);
+    } catch {
+      // A half-written file (the dev server was killed mid-POST) must not
+      // cost the rest of the session.
+    }
+  }
+  if (!segments.length) return null;
+  // The stitcher belongs to the ENGINE, and the engine a game is pinned to may
+  // predate recordings entirely — a creator on a new CLI and an old engine can
+  // record perfectly well (the room is the new engine's; the segments are on
+  // disk) and then find nothing to read them with. Said plainly here, because
+  // the alternative is a module-resolution error surfacing to that creator as
+  // "no recording", with the files sitting in front of them.
+  const stitcher = join(sharedDir, 'ui', 'room', 'entity', 'stitch.js');
+  if (!existsSync(stitcher)) {
+    throw new Error(
+      "this game's pinned engine predates session recordings, so it cannot read one back — "
+      + 'run `joystack update` to watch this session',
+    );
+  }
+  const { stitchSegments } = await import(pathToFileURL(stitcher).href);
+  try {
+    return JSON.stringify(stitchSegments(segments));
+  } catch {
+    // The only way stitching refuses a contiguous range is "no keyframe
+    // segment in it" — a stream whose first cadence keyframe has not been cut
+    // yet. That is a not-yet, not a corruption.
+    return null;
+  }
+}
+
+// A byte cap as a person reads it: whole gigabytes when it is one, else MB.
+const GB = 1024 * 1024 * 1024;
+const sizeLabel = (bytes) => (bytes >= GB && bytes % GB === 0
+  ? `${bytes / GB} GB`
+  : `${Math.round(bytes / 1024 / 1024)} MB`);
+
+/**
+ * The prune `joystack dev` runs on the way up, and the line it prints.
+ *
+ * On start rather than on write: a sweep mid-session could delete the
+ * recording of the session the creator is in the middle of watching back, and
+ * the moment a stack starts is the one moment nobody is reading anything.
+ * Silent deletion is not an option either — a creator who goes looking for
+ * Tuesday's session deserves to have been told it went, so the line names the
+ * count and the caps that took it.
+ */
+export function pruneOnStart({ projectDir, log = () => {}, caps } = {}) {
+  // This runs before `joystack dev` has bound a port. Housekeeping over old
+  // recordings is never a reason for the stack not to start, so whatever the
+  // disk does here costs the sweep and nothing else.
+  let result;
+  try {
+    result = pruneRecordings(projectDir, caps);
+  } catch (e) {
+    log(`→ replays     could not sweep old recordings: ${e?.message ?? e}`);
+    return { removed: [], bytes: 0, count: 0, caps: { maxCount: MAX_RECORDINGS, maxBytes: MAX_RECORDING_BYTES } };
+  }
+  if (result.removed.length) {
+    // The caps the sweep ACTUALLY applied, not the module defaults: a line that
+    // names limits a caller overrode would be telling the creator their session
+    // went for a reason that was not the reason.
+    log(`→ replays     swept ${result.removed.length} old recording(s) — keeping the newest `
+      + `${result.caps.maxCount} and up to ${sizeLabel(result.caps.maxBytes)} `
+      + "(pin one in the toolbox's Sessions tool to keep it)");
+  }
+  return result;
+}