@joystack/cli 0.0.0-stage → 0.1.43

package/lib/replay-export.mjs

@@ -0,0 +1,1379 @@
+// The recorded session, turned into a table.
+//
+// A recording stores what the player PRESSED — the world it started from, plus
+// every input stamped with the tick it arrived on. No position, no speed, no
+// score appears anywhere in it. So nothing can point a query at a recording:
+// everything worth asking about has to be re-derived by running the game
+// forward. That is what this does. It steps the session through the game's own
+// runtime and writes one row per (tick, entity), with every declared field as a
+// column — after which the questions are ordinary SQL, and asking a new one
+// costs nothing because the sim does not have to run again.
+//
+// Four tables come out on the tick axis, and a fifth describes the columns:
+//
+//   <stream>.state.parquet   one row per tick per entity, the wide sparse one
+//   <stream>.inputs.parquet  one row per wire send — already rows, no replay
+//   <stream>.perf.parquet    what each frame and second cost on the device
+//                            that played, when the session was measured
+//   <stream>.info.parquet    the session, its players and browsers, and the
+//                            tick ranges the other three cannot vouch for
+//   <stream>.fields.parquet  one row per state column and per channel: the
+//                            trait and source line behind it
+//
+// The state table is wide and mostly repeated (a real session measured 8.7% of
+// rows and 1.3% of cells changing between consecutive ticks). Delta-encoding it
+// was considered and rejected: Parquet's columnar compression already absorbs
+// the redundancy — 225 MB of JSONL becomes ~3 MB — and deltas would push
+// last-value-carried-forward semantics into every query anybody writes.
+import { mkdirSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ParquetWriter, fileWriter } from 'hyparquet-writer';
+import { readTrackLimits, readTrackSegments, readBuildStamp } from './replay-store.mjs';
+import { gameBuild } from './build-id.mjs';
+import { sourcePath } from './source-path.mjs';
+
+// The columns every state row carries, before any declared field. `def` is a
+// column rather than a prefix on every field name — which is what lets a query
+// say `WHERE def IN ('prop','saucer')` and read one `body_x`.
+export const STATE_KEYS = ['tick', 'id', 'def', 'owner'];
+const STATE_KEY_TYPES = { tick: 'DOUBLE', id: 'STRING', def: 'STRING', owner: 'STRING' };
+
+// The columns every input row carries.
+// `tick` is when a send ARRIVED. A predicting client stamps `targetTick` and the
+// room holds the send in its jitter buffer until exactly that tick, so for any
+// predicted input the tick it arrives at is not the tick its effect shows up at
+// in the state table. Without this column a join on `tick` mis-attributes every
+// one of them, silently.
+const INPUT_KEYS = ['tick', 'target_tick', 'conn', 'seq', 'entity', 'channel', 'payload'];
+const INPUT_KEY_TYPES = {
+  tick: 'DOUBLE', target_tick: 'DOUBLE', conn: 'STRING', seq: 'DOUBLE',
+  entity: 'STRING', channel: 'STRING', payload: 'JSON',
+};
+
+/**
+ * The logical column type a JS value implies.
+ *
+ * DOUBLE for every number, never INT: the engine has one numeric type (a JS
+ * double), and a column typed from whole-looking values is a column that throws
+ * a thousand rows later when a fraction arrives. JSON for anything that is not
+ * flat, and for anything that says nothing — a cell has to be a scalar, so a
+ * list or an object rides as text rather than being dropped.
+ */
+function typeOf(value) {
+  if (value === null || value === undefined) return 'JSON';
+  switch (typeof value) {
+    case 'number': return 'DOUBLE';
+    case 'boolean': return 'BOOLEAN';
+    case 'string': return 'STRING';
+    default: return 'JSON';
+  }
+}
+
+// Two declarations of one column name that disagree. One Parquet column cannot
+// be both a double and a string, and dropping it would lose both kinds' data
+// silently — so the column widens to the one type that holds anything.
+const merge = (a, b) => (a === b ? a : 'JSON');
+
+/**
+ * The state table's shape, read off the lowered bundle.
+ *
+ * Types come from what each field was DECLARED as, never from a sample of what
+ * rows happen to hold. That is the whole reason this reads the manifests rather
+ * than the world: a sample is a guess that is right until it is not, and the
+ * failure lands mid-write, after the replay has already run.
+ *
+ * @param {{ manifests: Array<{component: string, owns: object}> }} bundle
+ * @returns {{ columns: Array<{name: string, type: string}>, conflicts: string[] }}
+ */
+export function tableSchema(bundle) {
+  const declared = new Map();
+  const conflicts = new Set();
+  for (const manifest of bundle?.manifests ?? []) {
+    for (const [field, spec] of Object.entries(manifest.owns ?? {})) {
+      const type = typeOf(spec?.default);
+      if (!declared.has(field)) {
+        declared.set(field, type);
+        continue;
+      }
+      const merged = merge(declared.get(field), type);
+      if (merged !== declared.get(field) || merged !== type) conflicts.add(field);
+      declared.set(field, merged);
+    }
+  }
+  return {
+    columns: [
+      ...STATE_KEYS.map((name) => ({ name, type: STATE_KEY_TYPES[name] })),
+      // Sorted so the same game always exports the same column order, whatever
+      // order its definitions happened to be lowered in.
+      ...[...declared.keys()].sort().map((name) => ({ name, type: declared.get(name) })),
+    ],
+    conflicts: [...conflicts].sort(),
+  };
+}
+
+const FIELD_COLUMNS = [
+  ['row', 'STRING'], ['kind', 'STRING'], ['name', 'STRING'], ['trait', 'STRING'], ['instance', 'STRING'],
+  ['field', 'STRING'], ['type', 'STRING'], ['default', 'JSON'], ['source', 'STRING'], ['senders', 'JSON'],
+];
+
+/**
+ * What each state column and each channel is. One `field` row per (kind,
+ * column) and one `channel` row per (kind, channel), each naming the trait
+ * behind it, the name the kind gave that trait (a column's prefix), and the
+ * file and line it is declared on; a field row adds the field's own name, its
+ * declared type and its starting value.
+ *
+ * Names alone do not say this. `contact_asleep` is the `asleep` field of
+ * whatever trait the kind calls `contact`; a channel is named by the file its
+ * token is exported from, so `ground-contact_sleep` shares no prefix with the
+ * `contact_*` fields its handler changes. Only the lowered game knows which
+ * trait is behind each. A name the game lowered without an origin keeps its
+ * row, with the origin null.
+ *
+ * A channel row also says who sends on it (`senders`): each query declared to
+ * send on it, by kind, trait and line, and `{ from: 'client' }` when players'
+ * browsers may send on it too.
+ *
+ * A file inside the engine's package is named `@joystack/engine/shared/…`,
+ * the same in every install, rather than by where this one sits.
+ *
+ * @param {{ manifests: Array<{component: string, owns: object}>, fieldOrigins?: object, channelOrigins?: object,
+ *   channelSenders?: object }} bundle
+ * @param {{ dir?: string, sharedDir?: string }} [where] - the game folder, and
+ *   the engine's shared/ tree the game was lowered with
+ */
+export function fieldsTable(bundle, { dir = null, sharedDir = null } = {}) {
+  const originOf = (table, kind, name) => {
+    const byName = table?.[kind];
+    return byName && typeof byName === 'object' && Object.hasOwn(byName, name) ? byName[name] : null;
+  };
+  const sourceOf = (o) => {
+    const given = text(o?.file);
+    const file = sourcePath(given, { dir, sharedDir }) ?? given;
+    const line = Number.isSafeInteger(o?.line) && o.line > 0 ? o.line : null;
+    return file && line ? `${file}:${line}` : file;
+  };
+  const rows = [];
+  for (const manifest of bundle?.manifests ?? []) {
+    const kind = manifest.component;
+    for (const [column, spec] of Object.entries(manifest.owns ?? {})) {
+      const o = originOf(bundle?.fieldOrigins, kind, column);
+      rows.push({
+        row: 'field',
+        kind: text(kind),
+        name: text(column),
+        trait: text(o?.trait),
+        instance: text(o?.instance),
+        field: text(o?.field),
+        type: typeOf(spec?.default),
+        default: jsonCell(spec?.default ?? null),
+        source: sourceOf(o),
+        senders: null,
+      });
+    }
+  }
+  // Channels are listed from the manifests, so an engine that records no
+  // origins still gives every channel its row.
+  for (const manifest of bundle?.manifests ?? []) {
+    const kind = manifest.component;
+    const names = manifest.channels && typeof manifest.channels === 'object' ? Object.keys(manifest.channels) : [];
+    for (const name of names) {
+      const o = originOf(bundle?.channelOrigins, kind, name);
+      const known = o && typeof o === 'object' ? o : null;
+      // An engine that records no senders says nothing about them: null, not
+      // an empty list, which would claim nothing sends on the channel.
+      const recorded = bundle?.channelSenders && typeof bundle.channelSenders === 'object';
+      const declared = originOf(bundle?.channelSenders, kind, name);
+      const senders = (Array.isArray(declared) ? declared : [])
+        .filter((q) => q && typeof q === 'object')
+        .map((q) => ({ from: 'query', kind: text(q.kind), trait: text(q.trait), instance: text(q.instance), source: sourceOf(q) }));
+      if (manifest.channels[name]?.from === 'client') senders.push({ from: 'client' });
+      rows.push({
+        row: 'channel',
+        kind: text(kind),
+        name: text(name),
+        trait: text(known?.trait),
+        instance: text(known?.instance),
+        field: null,
+        type: null,
+        default: null,
+        source: sourceOf(known),
+        senders: recorded ? jsonCell(senders) : null,
+      });
+    }
+  }
+  const key = (r) => `${r.row === 'field' ? 0 : 1}\u0000${r.kind}\u0000${r.name}`;
+  rows.sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+  return { columns: FIELD_COLUMNS.map(([name, type]) => ({ name, type })), rows };
+}
+
+/**
+ * One cell, as its column's type — or null.
+ *
+ * A value that does not fit is null rather than coerced. Turning a string into
+ * 0, or a NaN into "some number", would put a value in the table that the
+ * session never held, and the whole point of this table is that a question
+ * asked of it gets the sim's real answer.
+ */
+export function coerce(value, type) {
+  if (value === null || value === undefined) return null;
+  switch (type) {
+    // Number.isFinite rejects NaN and ±Infinity: Parquet has no way to carry
+    // them as doubles that any reader agrees on.
+    case 'DOUBLE': return typeof value === 'number' && Number.isFinite(value) ? value : null;
+    case 'BOOLEAN': return typeof value === 'boolean' ? value : null;
+    case 'STRING': return typeof value === 'string' ? value : null;
+    // A value, not a string: the Parquet writer serializes a JSON column
+    // once, and serializing it here too stores a JSON string of the JSON,
+    // which every reader hands back as a string. See `jsonCell`.
+    case 'JSON': return jsonCell(value);
+    default: return null;
+  }
+}
+
+// Deeper than any value a game or a track has reason to hold, and far short of
+// the depth at which the Parquet writer's recursive walk overflows the stack.
+const JSON_MAX_DEPTH = 64;
+
+/**
+ * A JSON column's cell: a detached copy of the value as it is NOW, or null
+ * when JSON cannot carry it or it nests past `JSON_MAX_DEPTH`.
+ *
+ * A copy, because rows wait in a batch for several ticks before they are
+ * written, and a record field may hold a list or object a trait changes in
+ * place — a reference would be written with its later value on earlier rows.
+ * The depth is read off the serialized text, without recursion, so a value
+ * built to be deep cannot overflow this check either.
+ */
+// JSON escapes the C0 controls but writes U+0080–009F as they are, and U+009B
+// is a terminal's CSI. A cell read in DuckDB's csv or list mode reaches the
+// terminal byte for byte, so they are dropped from every string in a cell.
+const C1 = /[\u0080-\u009f]/g;
+const noC1 = (_, v) => (typeof v === 'string' ? v.replace(C1, '') : v);
+
+function jsonCell(value) {
+  let text;
+  try { text = JSON.stringify(value, noC1); } catch { return null; }
+  if (text === undefined) return null;
+  let depth = 0;
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (inString) {
+      if (c === 92) i++;                 // backslash: skip the escaped character
+      else if (c === 34) inString = false;
+    } else if (c === 34) inString = true;
+    else if (c === 91 || c === 123) { if (++depth > JSON_MAX_DEPTH) return null; }
+    else if (c === 93 || c === 125) depth--;
+  }
+  return JSON.parse(text);
+}
+
+/**
+ * One state row: the fixed keys, then every declared field this entity holds.
+ *
+ * A record key is `<kind>.<field>`; the kind is dropped because `def` already
+ * carries it. A key the schema does not know is skipped rather than added —
+ * Parquet needs its columns fixed before the first row is written, so a column
+ * discovered mid-session could not be honoured anyway.
+ */
+export function stateRow(entity, tick, columnIndex, tally) {
+  // The key columns go through `coerce` like every other cell. They used to be
+  // assigned straight through, so an id that was not a string reached the
+  // writer as one and threw a raw type error — after the entire replay had
+  // already been paid for.
+  const row = {
+    tick: coerce(tick, 'DOUBLE'),
+    id: coerce(entity.id, 'STRING'),
+    def: coerce(entity.def, 'STRING'),
+    owner: coerce(entity.owner, 'STRING'),
+  };
+  for (const [key, value] of Object.entries(entity.record ?? {})) {
+    const field = key.slice(key.indexOf('.') + 1);
+    const type = columnIndex.get(field);
+    if (!type) continue;
+    row[field] = coerce(value, type);
+    // NaN and ±Infinity are real values a world can hold (M2 carries them out
+    // of band through a keyframe for exactly that reason) and Parquet has no
+    // double that means them. Null is the right answer and a SILENT null is
+    // not: null already means "this kind has no such field", so a dropped NaN
+    // would be indistinguishable from an absent column.
+    if (tally && row[field] === null && type === 'DOUBLE' && typeof value === 'number') tally.undoubleable += 1;
+  }
+  return row;
+}
+
+/**
+ * The input table: one row per accepted wire send.
+ *
+ * No replay is needed — the recording already holds these as rows. A payload
+ * has no declared shape, so unlike the state table its columns are typed by
+ * reading EVERY event first. That is not the sampling rule 1 forbids: the whole
+ * list is in hand before a row is written, so this is an exact read of the data
+ * rather than a guess from its first few values.
+ *
+ * Each scalar payload key becomes `p_<key>`, and the whole payload also rides
+ * as JSON — so a question about a field that did not flatten is still one
+ * `json_extract` away rather than a re-export.
+ */
+// How many payload keys may become their own column.
+//
+// A recording is UNTRUSTED input. The segment endpoint takes what a room sends
+// and cannot demand an Origin (a multiplayer room posts from a worker that has
+// none), so anything that can reach the dev server can append events — and one
+// column per distinct key, uncapped, turns a 151 KB post into a multi-gigabyte
+// out-of-memory abort that names neither the export nor the recording.
+//
+// Capping loses nothing: the whole payload is on every row as JSON anyway, so a
+// question about a rare key is one `json_extract` away instead of a column. The
+// keys that survive are the ones that appear MOST OFTEN, because a key on every
+// event is the one worth a column and a key on one event is the one that is
+// not.
+const MAX_PAYLOAD_COLUMNS = 256;
+
+export function inputSchema(session) {
+  const sends = (session?.events ?? []).filter((e) => e?.k === 'w');
+  const payloadTypes = new Map();
+  const seen = new Map();
+  for (const send of sends) {
+    for (const [key, value] of Object.entries(send.payload ?? {})) {
+      const type = typeOf(value);
+      payloadTypes.set(key, payloadTypes.has(key) ? merge(payloadTypes.get(key), type) : type);
+      seen.set(key, (seen.get(key) ?? 0) + 1);
+    }
+  }
+  const ranked = [...seen.keys()].sort((a, b) => (seen.get(b) - seen.get(a)) || a.localeCompare(b));
+  // Sorted by name after ranking, so the same recording always exports the same
+  // column order.
+  const keys = ranked.slice(0, MAX_PAYLOAD_COLUMNS).sort();
+  const columns = [
+    ...INPUT_KEYS.map((name) => ({ name, type: INPUT_KEY_TYPES[name] })),
+    ...keys.map((k) => ({ name: `p_${k}`, type: payloadTypes.get(k) })),
+  ];
+  return { columns, keys, types: payloadTypes, sends, truncatedKeys: ranked.length - keys.length };
+}
+
+/** One input row: the fixed columns, then each flattened payload key. */
+export function inputRow(send, keys, types) {
+  const row = {
+    tick: coerce(send.t, 'DOUBLE'),
+    // Null, not a copy of `tick`: an input with no target tick was never
+    // held, and repeating arrival here would invent a fact.
+    target_tick: coerce(send.targetTick, 'DOUBLE'),
+    conn: coerce(send.connId, 'STRING'),
+    seq: coerce(send.seq, 'DOUBLE'),
+    entity: coerce(send.entityId, 'STRING'),
+    channel: coerce(send.channel, 'STRING'),
+    payload: coerce(send.payload ?? null, 'JSON'),
+  };
+  // Every column on every row, so a field an event did not carry reads as
+  // null rather than being absent — a Parquet column has one length.
+  for (const k of keys) row[`p_${k}`] = coerce(send.payload?.[k], types.get(k));
+  return row;
+}
+
+export function inputTable(session) {
+  const { columns, keys, types, sends, truncatedKeys } = inputSchema(session);
+  return { columns, rows: sends.map((send) => inputRow(send, keys, types)), truncatedKeys };
+}
+
+// The logical types above, as the Parquet schema elements the writer wants.
+// Every column is OPTIONAL because the table is deliberately SPARSE: a kind
+// that does not declare a field leaves it null on that row, and null is a
+// different answer from zero.
+const PARQUET_TYPE = {
+  DOUBLE: { type: 'DOUBLE' },
+  BOOLEAN: { type: 'BOOLEAN' },
+  STRING: { type: 'BYTE_ARRAY', converted_type: 'UTF8' },
+  JSON: { type: 'BYTE_ARRAY', converted_type: 'JSON' },
+};
+
+// ── the performance table (project note ofta45) ─────────────────────────────
+//
+// The third table: what the session COST, from the track the browser recorded
+// beside it. Unlike state, none of this is re-derived — it was measured on the
+// device that played, and no replay on another machine can reproduce it.
+//
+// One row per frame, one per finished second and one per long frame the
+// browser reported (below), told apart by `row`, in one table rather than
+// three: all are stamped with the ticks they cover, and a reader's question
+// ("what was alive while frames were slow") joins the tick axis once. On a
+// `long_frame` row, `at_ms` and `dt` are Chrome's start and duration for the
+// frame's main-thread work, and its ticks are those of the frame record it was
+// joined to. A `kind` row is one entity kind's share of a `second` row: the
+// same second's `at_ms` and ticks, the time that kind's entities spent
+// (`ms`, split into `tick_ms` and `present_ms`), how many trait calls that
+// took and how many of its entities spent any, and how many of that kind were
+// alive in the replayed world at the second's last tick. It is the second
+// row's `kinds` and `traits` JSON, as rows a query can group by. `conn` is
+// which browser measured it — in multiplayer each player
+// writes their own track, and averaging two devices together would describe
+// neither.
+const PERF_KEYS = [
+  'row', 'conn', 'seq', 'at_ms', 'tick_from', 'tick_to',
+  'dt', 'tick_ms', 'present_ms', 'render_ms', 'sim_ms', 'other_ms', 'wait_ms',
+  'window_ms', 'entities', 'calls', 'triangles', 'heap_delta_mb', 'dom', 'geometries', 'textures',
+  'spawned', 'despawned', 'programs', 'snapshot', 'channels', 'render', 'traits', 'kinds',
+  'blocking_ms', 'render_start', 'layout_start', 'scripts',
+  'kind', 'ms', 'trait_calls', 'entities_spent', 'alive', 'alive_max',
+];
+const PERF_KEY_TYPES = {
+  row: 'STRING', conn: 'STRING', seq: 'DOUBLE', at_ms: 'DOUBLE', tick_from: 'DOUBLE', tick_to: 'DOUBLE',
+  dt: 'DOUBLE', tick_ms: 'DOUBLE', present_ms: 'DOUBLE', render_ms: 'DOUBLE', sim_ms: 'DOUBLE',
+  other_ms: 'DOUBLE', wait_ms: 'DOUBLE', window_ms: 'DOUBLE', entities: 'DOUBLE',
+  calls: 'DOUBLE', triangles: 'DOUBLE',
+  heap_delta_mb: 'DOUBLE', dom: 'DOUBLE', geometries: 'DOUBLE', textures: 'DOUBLE',
+  spawned: 'JSON', despawned: 'JSON', programs: 'JSON', snapshot: 'JSON', channels: 'JSON',
+  render: 'JSON', traits: 'JSON', kinds: 'JSON',
+  blocking_ms: 'DOUBLE', render_start: 'DOUBLE', layout_start: 'DOUBLE', scripts: 'JSON',
+  kind: 'STRING', ms: 'DOUBLE', trait_calls: 'DOUBLE', entities_spent: 'DOUBLE', alive: 'DOUBLE', alive_max: 'DOUBLE',
+};
+
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+// Chrome writes 0 for the render and layout start of a long frame that
+// rendered nothing. A 0 in a time column reads as the page's first
+// millisecond, so it is exported as no value.
+const time = (v) => (num(v) > 0 ? v : null);
+// A JSON column's value, copied and depth-checked; see `jsonCell`.
+const json = (v) => (v === undefined || v === null ? null : jsonCell(v));
+
+function perfRow(kind, header, rec, joinedTicks = null) {
+  const ticks = joinedTicks ?? (Array.isArray(rec.ticks) && rec.ticks.length === 2 ? rec.ticks : [null, null]);
+  return {
+    row: kind,
+    conn: text(header.producer),
+    seq: num(header.seq),
+    at_ms: num(rec.at),
+    tick_from: num(ticks[0]),
+    tick_to: num(ticks[1]),
+    dt: num(rec.dt),
+    tick_ms: num(rec.tick),
+    present_ms: num(rec.present),
+    render_ms: num(rec.render),
+    sim_ms: num(rec.sim),
+    other_ms: num(rec.other),
+    wait_ms: num(rec.wait),
+    window_ms: num(rec.windowMs),
+    entities: num(rec.entities),
+    // What the frame asked the GPU for. The only columns that can explain a
+    // frame whose time is `wait` with every CPU phase small.
+    calls: num(rec.calls),
+    triangles: num(rec.triangles),
+    heap_delta_mb: num(rec.heapDeltaMB),
+    dom: num(rec.dom),
+    geometries: num(rec.geometries),
+    textures: num(rec.textures),
+    spawned: json(rec.spawned),
+    despawned: json(rec.despawned),
+    programs: json(rec.programs),
+    snapshot: json(rec.snapshot),
+    channels: json(rec.channels),
+    render: json(rec.render && typeof rec.render === 'object' ? rec.render : undefined),
+    traits: json(rec.traits),
+    kinds: json(rec.kinds),
+    blocking_ms: num(rec.blocking),
+    render_start: time(rec.renderStart),
+    layout_start: time(rec.styleAndLayoutStart),
+    scripts: kind === 'long_frame' ? json(Array.isArray(rec.scripts) ? rec.scripts : undefined) : null,
+  };
+}
+
+// ── long frames ─────────────────────────────────────────────────────────────
+//
+// Chrome's Long Animation Frames API reports, for each frame whose main-thread
+// work passed 50 ms, the scripts that ran in it. The browser delivers the
+// report after its frame, and it carries a time rather than a tick, so it is
+// stored beside the frame records (`longFrames` on a track segment) and joined
+// to them here, per browser, by time.
+//
+// The frame record a long frame belongs to is the one whose interval it
+// overlaps most. A frame record's interval runs from the previous
+// animation-frame timestamp to its own (`at - dt` to `at`), and its split is
+// the work that made that interval long. A long frame spans its first task to
+// the end of its paint (`at` to `at + duration`). Its `renderStart` is not a
+// usable key on its own: Chrome stamps an animation frame a few milliseconds
+// before the rendering it belongs to starts, so a long frame's render lands in
+// one interval or the next depending on how late the task before it ran.
+//
+// Frame intervals are taken as never overlapping — each begins no earlier than
+// the previous frame record's timestamp — which is true of a real track and
+// what keeps the scan below short on a posted one that is not.
+
+const finite = (v) => num(v) !== null;
+// A long frame overlaps two or three frame records; a scan this long only
+// happens on a track no browser wrote, and is cut rather than followed.
+const JOIN_SCAN = 64;
+
+/**
+ * Every long-frame record in a track, each with the frame record it describes.
+ * A long frame no frame record covers (the tab was hidden, measuring was off
+ * for the frame) is still listed, with `frame` null.
+ *
+ * @param {object[]} segments - track segments, any producer, any order
+ * @returns {{ conn: string|null, record: object, frame: object|null }[]}
+ */
+export function joinLongFrames(segments) {
+  const byConn = new Map();
+  const of = (conn) => {
+    if (!byConn.has(conn)) byConn.set(conn, { frames: [], longs: [] });
+    return byConn.get(conn);
+  };
+  for (const seg of segments ?? []) {
+    const conn = text(seg?.header?.producer);
+    const frames = Array.isArray(seg?.frames) ? seg.frames : [];
+    const longs = Array.isArray(seg?.longFrames) ? seg.longFrames : [];
+    if (!frames.length && !longs.length) continue;
+    const bucket = of(conn);
+    for (const f of frames) if (f && typeof f === 'object' && finite(f.at) && finite(f.dt) && f.dt > 0) bucket.frames.push(f);
+    for (const l of longs) if (l && typeof l === 'object' && finite(l.at)) bucket.longs.push(l);
+  }
+  const out = [];
+  for (const [conn, { frames, longs }] of byConn) {
+    frames.sort((x, y) => x.at - y.at);
+    const from = frames.map((f, i) => Math.max(f.at - f.dt, i ? frames[i - 1].at : -Infinity));
+    for (const record of longs) {
+      const start = record.at;
+      const end = start + (finite(record.duration) && record.duration > 0 ? record.duration : 0);
+      // The first frame record whose timestamp is past the long frame's start:
+      // the interval the long frame begins in, or the next one.
+      let lo = 0;
+      let hi = frames.length;
+      while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (frames[mid].at > start) hi = mid; else lo = mid + 1;
+      }
+      let best = null;
+      if (end === start) {
+        // No duration to overlap with: the interval its start falls in.
+        if (lo < frames.length && from[lo] <= start) best = frames[lo];
+      } else {
+        // That one and every one after it that begins before the long frame
+        // ends; on a tie the earlier frame keeps it.
+        let bestOverlap = 0;
+        for (let i = lo; i < frames.length && i < lo + JOIN_SCAN && from[i] < end; i++) {
+          const overlap = Math.min(end, frames[i].at) - Math.max(start, from[i]);
+          if (overlap > bestOverlap) { best = frames[i]; bestOverlap = overlap; }
+        }
+      }
+      out.push({ conn, record, frame: best });
+    }
+  }
+  return out;
+}
+
+// The most ticks one `second` record can span: a second at the fastest tick
+// rate a game runs, with room to spare. A longer claim is not a second.
+const MAX_SECOND_TICKS = 1000;
+
+// A second's ticks as a key: `second` records of different browsers can
+// cover the same ticks, and each gets the count for its own.
+const rangeKey = (from, to) => `${from}:${to}`;
+
+/**
+ * How many of each entity kind the replayed world held over each second the
+ * performance track records — the `kind` rows' `alive` and `alive_max`. Fed
+ * the world once per tick as the replay walks forward (`see`); holds only one
+ * running sum and maximum per second and kind.
+ *
+ * @param {object[]} segments - the track segments
+ * @returns {{ see(tick: number, entities: {def: string}[]): void,
+ *   stats(from: number, to: number): { ticks: number, sum: Map<string, number>, max: Map<string, number> } | null }}
+ */
+export function aliveCounter(segments) {
+  // The seconds each browser claims, by browser. A track is written by a
+  // browser, so its claims are checked before anything is counted over them:
+  // a span longer than any second's, or one overlapping the same browser's
+  // previous second, is dropped. What is left is at most one open second per
+  // browser at any tick, which is what keeps counting cheap.
+  const claimed = new Map();
+  for (const seg of segments ?? []) {
+    const producer = text(seg?.header?.producer) ?? '';
+    if (!claimed.has(producer)) claimed.set(producer, []);
+    for (const s of Array.isArray(seg?.seconds) ? seg.seconds : []) {
+      const from = Array.isArray(s?.ticks) ? num(s.ticks[0]) : null;
+      const to = Array.isArray(s?.ticks) ? num(s.ticks[1]) : null;
+      if (from === null || to === null || to < from || to - from > MAX_SECOND_TICKS) continue;
+      claimed.get(producer).push({ from, to });
+    }
+  }
+  const ranges = new Map();
+  for (const list of claimed.values()) {
+    list.sort((a, b) => a.from - b.from || a.to - b.to);
+    let lastTo = -Infinity;
+    for (const { from, to } of list) {
+      if (from <= lastTo) continue;
+      lastTo = to;
+      const key = rangeKey(from, to);
+      if (!ranges.has(key)) ranges.set(key, { from, to, ticks: 0, sum: new Map(), max: new Map() });
+    }
+  }
+  // Seconds in the order they start, walked alongside the replay: a tick only
+  // touches the seconds open at it.
+  const pending = [...ranges.values()].sort((a, b) => a.from - b.from);
+  let next = 0;
+  let open = [];
+  return {
+    see(tick, entities) {
+      while (next < pending.length && pending[next].from <= tick) open.push(pending[next++]);
+      open = open.filter((r) => r.to >= tick);
+      if (!open.length) return;
+      const here = new Map();
+      for (const e of entities) here.set(e.def, (here.get(e.def) ?? 0) + 1);
+      for (const r of open) {
+        r.ticks += 1;
+        // A kind missing from this tick counts 0 towards its mean: every kind
+        // seen in the second is divided by all of the second's ticks.
+        for (const [kind, n] of here) {
+          r.sum.set(kind, (r.sum.get(kind) ?? 0) + n);
+          r.max.set(kind, Math.max(r.max.get(kind) ?? 0, n));
+        }
+      }
+    },
+    stats(from, to) {
+      const r = ranges.get(rangeKey(from, to));
+      return r && r.ticks ? r : null;
+    },
+  };
+}
+
+// One `second` record's `kinds` and `traits`, as a row per kind. Every kind
+// the replayed world held during the second gets a row, whether or not it
+// spent anything, so a count by kind is complete.
+function kindRows(header, sec, alive) {
+  const ticks = Array.isArray(sec.ticks) && sec.ticks.length === 2 ? sec.ticks : [null, null];
+  const kinds = sec.kinds && typeof sec.kinds === 'object' && !Array.isArray(sec.kinds) ? sec.kinds : {};
+  const axes = new Map();
+  for (const t of Array.isArray(sec.traits) ? sec.traits : []) {
+    if (!t || typeof t !== 'object' || typeof t.comp !== 'string' || num(t.ms) === null) continue;
+    const a = axes.get(t.comp) ?? {};
+    if (t.axis === 'tick' || t.axis === 'present') a[t.axis] = (a[t.axis] ?? 0) + t.ms;
+    axes.set(t.comp, a);
+  }
+  // The world over the second's ticks, or null when the replay held none of
+  // them. Once counted, a kind with none is 0, not unknown.
+  const from = num(ticks[0]);
+  const to = num(ticks[1]);
+  const counted = from !== null && to !== null ? alive?.stats(from, to) ?? null : null;
+  const names = new Set([
+    ...Object.keys(kinds).filter((k) => kinds[k] && typeof kinds[k] === 'object'),
+    ...(counted?.max.keys() ?? []),
+  ]);
+  const rows = [];
+  for (const kind of [...names].sort()) {
+    const k = kinds[kind] && typeof kinds[kind] === 'object' ? kinds[kind] : {};
+    rows.push({
+      row: 'kind',
+      conn: text(header.producer),
+      seq: num(header.seq),
+      at_ms: num(sec.at),
+      tick_from: num(ticks[0]),
+      tick_to: num(ticks[1]),
+      kind: text(kind, 128),
+      ms: num(k.ms),
+      tick_ms: num(axes.get(kind)?.tick),
+      present_ms: num(axes.get(kind)?.present),
+      trait_calls: num(k.calls),
+      entities_spent: num(k.entities),
+      alive: counted ? Math.round(((counted.sum.get(kind) ?? 0) / counted.ticks) * 10) / 10 : null,
+      alive_max: counted ? (counted.max.get(kind) ?? 0) : null,
+    });
+  }
+  return rows;
+}
+
+/**
+ * The performance table for a session's track segments, or null when the
+ * session carries no track — a recording made with measuring switched off, or
+ * by an engine from before the track existed. Null rather than an empty table
+ * so the caller can say the cost was never recorded, which is a different
+ * answer from a session that cost nothing.
+ *
+ * @param {object[]} segments - the track segments, in producer then seq order
+ * @param {{ alive?: ReturnType<typeof aliveCounter> }} [opts] - how many of each
+ *   kind the replayed world held over each second
+ */
+export function perfTable(segments, { alive = null } = {}) {
+  if (!segments?.length) return null;
+  const rows = [];
+  for (const seg of segments) {
+    const header = seg?.header ?? {};
+    // Only records that ARE records: a track segment is whatever a browser
+    // posted, and `frames: {}` unguarded would fail the whole export over its
+    // optional third table.
+    const recs = (key) => (Array.isArray(seg?.[key]) ? seg[key] : []);
+    for (const f of recs('frames')) if (f && typeof f === 'object') rows.push(perfRow('frame', header, f));
+    for (const s of recs('seconds')) {
+      if (!s || typeof s !== 'object') continue;
+      rows.push(perfRow('second', header, s));
+      rows.push(...kindRows(header, s, alive));
+    }
+  }
+  for (const { conn, record, frame } of joinLongFrames(segments)) {
+    const ticks = Array.isArray(frame?.ticks) && frame.ticks.length === 2 ? frame.ticks : [null, null];
+    // Only a long frame's own fields: a record that also carries a frame's
+    // keys (`sim`, `traits`) does not get to fill those columns.
+    const own = {
+      at: record.at, dt: record.duration, blocking: record.blocking,
+      renderStart: record.renderStart, styleAndLayoutStart: record.styleAndLayoutStart, scripts: record.scripts,
+    };
+    rows.push(perfRow('long_frame', { producer: conn }, own, ticks));
+  }
+  if (!rows.length) return null;
+  return { columns: PERF_KEYS.map((name) => ({ name, type: PERF_KEY_TYPES[name] })), rows };
+}
+
+// ── the session info table ──────────────────────────────────────────────────
+//
+// The fourth table: what is true of the session as a whole, and of stretches
+// of it, that no row of the other three can say. Which machine each browser
+// measured on. Which ticks a browser measured nothing at all. Where the
+// replay stopped matching what was played, so the state rows there describe a
+// world nobody saw. None of it is a per-tick fact, and all of it changes what
+// a per-tick number means, so it is a table a query joins rather than a line
+// a reader has to remember.
+//
+// One table, told apart by `row`, like the performance table. Every row that
+// covers ticks carries `tick_from` and `tick_to`, both inclusive, so any row
+// kind joins another table the same way:
+//
+//   LEFT JOIN info d ON d.row = 'diverged' AND s.tick BETWEEN d.tick_from AND d.tick_to
+//
+// The row kinds:
+//   session          one row: the recording's span, tick rate, start time,
+//                    player count, and which engine and game code recorded it
+//                    against which replayed it
+//   player           one per stay in the room: `conn`, and the ticks between
+//                    joining and leaving
+//   browser          one per browser that wrote a performance track: `conn` and
+//                    the device it measured on
+//   unmeasured       a stretch of the recording none of that browser's frames
+//                    covered: the page was hidden, measuring was off, or its
+//                    segments never arrived
+//   track_cut        a browser's track stopped being stored at `tick_from`
+//                    because the session's track reached its size limit
+//   diverged         ticks where the replay's world is in doubt: after the last
+//                    checksum or keyframe that matched and up to the next one
+//   unsupported      an event the replay cannot reproduce (`what` says which);
+//                    the world from `tick_from` on is not the one played
+//   missing_segment  a recording segment that never reached storage; the
+//                    inputs just before `tick_from` are missing
+const INFO_COLUMNS = [
+  ['row', 'STRING'], ['conn', 'STRING'], ['tick_from', 'DOUBLE'], ['tick_to', 'DOUBLE'], ['what', 'STRING'],
+  ['stream', 'STRING'], ['started_at', 'STRING'], ['tick_rate', 'DOUBLE'], ['players', 'DOUBLE'],
+  ['checksums_verified', 'DOUBLE'],
+  ['recorded_engine', 'STRING'], ['replayed_engine', 'STRING'],
+  ['recorded_code', 'STRING'], ['replayed_code', 'STRING'], ['code_changed', 'BOOLEAN'],
+  ['recorded_build', 'STRING'], ['recorded_commit', 'STRING'], ['recorded_dirty', 'BOOLEAN'],
+  ['replayed_build', 'STRING'], ['build_changed', 'BOOLEAN'],
+  ['user_agent', 'STRING'], ['viewport_width', 'DOUBLE'], ['viewport_height', 'DOUBLE'],
+  ['screen_dpr', 'DOUBLE'], ['cores', 'DOUBLE'], ['touch', 'BOOLEAN'], ['long_frames', 'BOOLEAN'], ['automated', 'BOOLEAN'],
+  ['limit_bytes', 'DOUBLE'], ['detail', 'JSON'],
+];
+
+// Everything below is read off files anything that reaches the dev server can
+// write, so each value is kept only when it is the type its column says. Text
+// loses its control characters too: the table is read in a terminal, and
+// DuckDB's csv and list modes print a cell's bytes as they are, so an escape
+// sequence in a user agent would repaint the screen of whoever reads it.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/g;
+const text = (v, max = 512) => (typeof v === 'string' ? v.replace(CONTROL, '').slice(0, max) : null);
+const flag = (v) => (typeof v === 'boolean' ? v : null);
+const positiveNum = (v) => (num(v) !== null && v > 0 ? v : null);
+const whenOf = (ms) => {
+  if (num(ms) === null) return null;
+  const d = new Date(ms);
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+};
+const recordsOf = (seg, key) => (Array.isArray(seg?.[key]) ? seg[key] : []);
+const tickRangeOf = (f) => {
+  const t = f?.ticks;
+  return Array.isArray(t) && num(t[0]) !== null && num(t[1]) !== null ? [t[0], t[1]] : null;
+};
+
+// A frame's tick range is what the sim stepped during it, so a frame drawn
+// while the sim was between ticks leaves a tick or two uncovered in the
+// ordinary course of playing. Stretches shorter than this are not reported.
+const UNMEASURED_MIN_TICKS = 20;
+
+/**
+ * The stretches of the recording, per browser that wrote a track, that none
+ * of its frames covered, as inclusive tick ranges. Only browsers that wrote
+ * SOMETHING: a browser with no track has no row here, and its missing
+ * `browser` row is what says so. A browser whose player the recording saw
+ * come and go is only unmeasured while that player was in the room.
+ *
+ * @param {Map<string, [number, number][]>} [staysByConn] - each player's stays
+ */
+export function unmeasuredStretches(segments, firstTick, endTick, staysByConn = new Map(), minTicks = UNMEASURED_MIN_TICKS) {
+  const byConn = new Map();
+  for (const seg of segments ?? []) {
+    const conn = text(seg?.header?.producer);
+    const covered = byConn.get(conn) ?? [];
+    for (const f of recordsOf(seg, 'frames')) {
+      const range = tickRangeOf(f);
+      if (range) covered.push(range);
+    }
+    byConn.set(conn, covered);
+  }
+  const out = [];
+  const keep = (conn, from, to) => {
+    const windows = staysByConn.get(conn) ?? [[firstTick, endTick]];
+    for (const [a, b] of windows) {
+      const lo = Math.max(from, a);
+      const hi = Math.min(to, b);
+      if (hi - lo + 1 >= minTicks) out.push({ conn, from: lo, to: hi });
+    }
+  };
+  for (const [conn, ranges] of byConn) {
+    ranges.sort((a, b) => a[0] - b[0]);
+    // The last tick known measured; the stretch before the first frame starts
+    // at the session's first tick.
+    let cursor = firstTick - 1;
+    for (const [from, to] of ranges) {
+      if (from > cursor + 1) keep(conn, cursor + 1, from - 1);
+      cursor = Math.max(cursor, to);
+    }
+    if (endTick > cursor) keep(conn, cursor + 1, endTick);
+  }
+  return out;
+}
+
+/**
+ * Build the session info table.
+ *
+ * @param {object} o
+ * @param {string|null} o.stream
+ * @param {object} o.session - the stitched recording ({ header, events })
+ * @param {object} o.replayer - the replayer, AFTER it has run to the end
+ * @param {number} o.firstTick - the first tick the state table holds
+ * @param {number} o.endTick - the recording's last tick
+ * @param {object[]} o.segments - the performance track's segments
+ * @param {object|null} o.limits - what `readTrackLimits` returned
+ */
+export function infoTable({
+  stream, session, replayer, firstTick, endTick, segments = [], limits = null,
+  recordedEngine = null, runningEngine = null, recordedCode = null, runningCode = null, codeChanged = false,
+  recordedBuild = null, runningBuild = null, buildChanged = null,
+}) {
+  const rows = [];
+  const header = session?.header ?? {};
+  const span = (from, to) => ({ tick_from: num(from) ?? firstTick, tick_to: num(to) ?? endTick });
+
+  // Stays in the room. A participant in the header was there when recording
+  // began; after that, the recording's join and leave events say who came and
+  // went.
+  const stays = [];
+  const open = new Map();
+  const participants = header.participants && typeof header.participants === 'object' ? header.participants : {};
+  for (const [key, info] of Object.entries(participants)) {
+    const conn = text(key);
+    if (conn) open.set(conn, { conn, from: firstTick, info });
+  }
+  for (const e of Array.isArray(session?.events) ? session.events : []) {
+    const conn = text(e?.connId);
+    if (!conn) continue;
+    if (e.k === 'jn' && !open.has(conn)) open.set(conn, { conn, from: num(e.t) ?? firstTick, info: e.info });
+    else if (e.k === 'lv' && open.has(conn)) {
+      stays.push({ ...open.get(conn), to: num(e.t) ?? endTick });
+      open.delete(conn);
+    }
+  }
+  for (const stay of open.values()) stays.push({ ...stay, to: endTick });
+  stays.sort((a, b) => a.from - b.from);
+
+  rows.push({
+    row: 'session',
+    ...span(firstTick, endTick),
+    stream: text(stream),
+    started_at: whenOf(header.startedAt),
+    tick_rate: positiveNum(header.tickRate),
+    players: new Set(stays.map((s) => s.conn)).size,
+    checksums_verified: num(replayer?.checksumsVerified),
+    recorded_engine: recordedEngine,
+    replayed_engine: runningEngine,
+    recorded_code: recordedCode,
+    replayed_code: runningCode,
+    code_changed: codeChanged,
+    recorded_build: recordedBuild?.id ?? null,
+    recorded_commit: recordedBuild?.git?.commit ?? null,
+    recorded_dirty: recordedBuild?.git?.dirty ?? null,
+    replayed_build: runningBuild?.id ?? null,
+    build_changed: buildChanged,
+  });
+  for (const s of stays) rows.push({ row: 'player', conn: s.conn, ...span(s.from, s.to), detail: json(s.info ?? null) });
+
+  // The device block is stamped on every segment a browser wrote; the first
+  // one carrying it wins, so a segment written before the navigator was
+  // readable erases nothing.
+  const devices = new Map();
+  for (const seg of segments ?? []) {
+    const conn = text(seg?.header?.producer);
+    const device = seg?.header?.device && typeof seg.header.device === 'object' ? seg.header.device : null;
+    if (!devices.has(conn) || (!devices.get(conn) && device)) devices.set(conn, device);
+  }
+  for (const [conn, d] of devices) {
+    const viewport = d?.viewport && typeof d.viewport === 'object' ? d.viewport : {};
+    rows.push({
+      row: 'browser',
+      conn,
+      user_agent: text(d?.userAgent),
+      viewport_width: positiveNum(viewport.width),
+      viewport_height: positiveNum(viewport.height),
+      screen_dpr: positiveNum(d?.screenDpr),
+      cores: positiveNum(d?.cores),
+      touch: flag(d?.touch),
+      long_frames: flag(d?.longFrames),
+      automated: flag(d?.automated),
+    });
+  }
+  const staysByConn = new Map();
+  for (const st of stays) staysByConn.set(st.conn, [...(staysByConn.get(st.conn) ?? []), [st.from, st.to]]);
+  for (const g of unmeasuredStretches(segments, firstTick, endTick, staysByConn)) {
+    rows.push({ row: 'unmeasured', conn: g.conn, tick_from: g.from, tick_to: g.to });
+  }
+  for (const cut of limits?.cuts ?? []) {
+    rows.push({
+      row: 'track_cut', conn: text(cut.producer), what: text(cut.kind),
+      ...span(cut.fromTick, endTick), limit_bytes: positiveNum(limits.limitBytes),
+    });
+  }
+
+  // A divergence is found at a checksum, some ticks after whatever caused it.
+  // The ticks in doubt start after the last tick playback matched (`since`)
+  // and end at the next one it matched again (`until`). A state row at tick t
+  // is the world BEFORE tick t's events, so the end depends on what matched:
+  // a checksum that verifies at t vouches for row t, and the range ends at
+  // t - 1; a keyframe restore that changed the world at t (a re-anchor)
+  // leaves row t drifted, and the range ends at t. An engine whose replayer
+  // does not say `since` or `until` is read the conservative way: from the
+  // start of the session, up to the first re-anchor at or after the
+  // divergence. Divergences that come out with one range are one row.
+  const reanchorTicks = new Set((replayer?.reanchors ?? []).map((r) => num(r?.tick)).filter((t) => t !== null));
+  const byRange = new Map();
+  for (const d of replayer?.divergences ?? []) {
+    const found = num(d?.tick);
+    let from = 'since' in (d ?? {}) ? (num(d.since) === null ? firstTick : d.since + 1) : firstTick;
+    if (found !== null) from = Math.min(from, found);
+    let to;
+    if ('until' in (d ?? {})) {
+      const until = num(d.until);
+      to = until === null ? endTick : reanchorTicks.has(until) ? until : until - 1;
+    } else {
+      to = [...reanchorTicks].filter((t) => found !== null && t >= found).sort((a, b) => a - b)[0] ?? endTick;
+    }
+    to = Math.max(from, to);
+    const key = `${from}:${to}`;
+    const seen = byRange.get(key);
+    if (seen) {
+      seen.checks += num(d?.checks) ?? 1;
+      continue;
+    }
+    byRange.set(key, {
+      from, to, via: text(d?.via) ?? 'checksum',
+      found_at: found, checks: num(d?.checks) ?? 1, expected: d?.expected ?? null, got: d?.got ?? null,
+    });
+  }
+  for (const r of byRange.values()) {
+    rows.push({
+      row: 'diverged', what: r.via, tick_from: r.from, tick_to: r.to,
+      detail: json({ found_at: r.found_at, checks: r.checks, expected: r.expected, got: r.got }),
+    });
+  }
+  for (const u of replayer?.unsupported ?? []) {
+    const { tick, kind, ...rest } = u ?? {};
+    rows.push({ row: 'unsupported', what: text(kind), ...span(tick, endTick), detail: json(rest) });
+  }
+  // The inputs a missing segment held never reached the replay, so nothing
+  // from where it was on is the world played. A later checksum that verified
+  // would narrow this, and the recording keeps no list of those.
+  for (const g of replayer?.gaps ?? []) {
+    rows.push({
+      row: 'missing_segment', what: `seq ${num(g?.afterSeq) ?? '?'}→${num(g?.beforeSeq) ?? '?'}`,
+      ...span(g?.atTick, endTick),
+    });
+  }
+  return { columns: INFO_COLUMNS.map(([name, type]) => ({ name, type })), rows };
+}
+
+function schemaElements(columns) {
+  return [
+    { name: 'root', num_children: columns.length },
+    ...columns.map((c) => ({ name: c.name, repetition_type: 'OPTIONAL', ...PARQUET_TYPE[c.type] })),
+  ];
+}
+
+// A row-at-a-time front end over a columnar writer: rows go in, and every time
+// `rowsPerGroup` of them have arrived the batch is handed over as one row group
+// and dropped. Nothing accumulates across groups, which is the whole point —
+// materialising every column of every tick before writing is what made the
+// prototype cost 19 s and a gigabyte for a 27-second session.
+// A row group is held whole in memory before it is encoded, and its cost is
+// rows x COLUMNS — so a fixed row count means a 40-column game and a
+// 5,000-column one buffer two orders of magnitude apart. Budgeting cells keeps
+// the ceiling flat whatever the table's width. An explicit rowsPerGroup (a
+// test, a caller who knows) is obeyed as given.
+export const CELL_BUDGET = 8_000_000;
+export const DEFAULT_ROWS_PER_GROUP = 20_000;
+
+function groupFor(columns, requested) {
+  if (requested != null) return requested;
+  return Math.max(500, Math.min(DEFAULT_ROWS_PER_GROUP, Math.floor(CELL_BUDGET / Math.max(1, columns.length))));
+}
+
+// Written under a temporary name and moved into place only once the file is
+// complete. The writer streams straight to disk, so a throw partway through
+// would otherwise leave a truncated file sitting at the canonical name — every
+// later read of which fails with "not a parquet file", and the previous good
+// export of that session is already gone. A partial answer under the name of a
+// whole one is the worst of the three outcomes.
+function rowSink({ file, columns, rowsPerGroup }) {
+  const partial = `${file}.partial`;
+  const writer = fileWriter(partial);
+  const pq = new ParquetWriter({ writer, schema: schemaElements(columns) });
+  // Name → column position, so a row is placed by index rather than by looking
+  // each of the table's columns up on it. The table is WIDE and each row is
+  // narrow — 443 columns, ~49 of them set on any given entity — so reading
+  // every column name off every row costs a property lookup for the ~90% that
+  // are absent. Filling nulls and writing only what is there is the same table
+  // for about a third of the work.
+  const at = new Map(columns.map((c, i) => [c.name, i]));
+  let batch = columns.map(() => []);
+  let rows = 0;
+  const flush = () => {
+    if (!batch[0].length) return;
+    pq.write({
+      columnData: columns.map((c, i) => ({ name: c.name, data: batch[i] })),
+      // One group per batch: the batch IS the group, so the writer is never
+      // asked to hold more than what has already been handed to it.
+      rowGroupSize: batch[0].length,
+    });
+    batch = columns.map(() => []);
+  };
+  return {
+    push(row) {
+      const index = batch[0].length;
+      for (let i = 0; i < columns.length; i++) batch[i].push(null);
+      for (const name in row) {
+        const i = at.get(name);
+        if (i !== undefined && row[name] !== undefined) batch[i][index] = row[name];
+      }
+      rows += 1;
+      if (batch[0].length >= rowsPerGroup) flush();
+    },
+    finish() {
+      flush();
+      pq.finish();
+      renameSync(partial, file);
+      return rows;
+    },
+    // Called when the run did not get that far. Best-effort: a leftover
+    // `.partial` is untidy, an unreadable `.parquet` is a wrong answer.
+    abandon() {
+      try { rmSync(partial, { force: true }); } catch { /* nothing to clean up */ }
+    },
+  };
+}
+
+/** A streaming Parquet writer for a table of `columns`, sized as the export sizes its own. */
+export function rowSinkFor(file, columns, rowsPerGroup) {
+  return rowSink({ file, columns, rowsPerGroup: groupFor(columns, rowsPerGroup) });
+}
+
+/**
+ * Where the engine's headless replay door lives, in the engine THIS GAME is
+ * pinned to.
+ *
+ * Imported from the resolved bundle rather than by a relative path, for the
+ * same reason the recording's reassembler is: a game can sit on a new CLI and
+ * an older engine, and the honest answer to that is a sentence saying so — not
+ * a module-resolution stack trace that reads, to the person holding it, as "my
+ * recording is broken".
+ */
+export async function loadOpenReplay(sharedDir, forWhat = 'export') {
+  const at = join(sharedDir, 'framework', 'replay-open.mjs');
+  try {
+    return (await import(pathToFileURL(at).href)).openReplay;
+  } catch (e) {
+    throw new Error(
+      `this game's pinned engine cannot open a recording headlessly, so there is nothing to ${forWhat} — `
+      + `run \`joystack update\` and try again (${e?.message ?? e})`,
+    );
+  }
+}
+
+// A version or code fingerprint as a recording's header states it, or null
+// when the value is not one. A header is not first-party text (see
+// `exportSession`), so a value that is not a plain version-or-digest token is
+// treated as unknown — a state every reader already handles honestly — rather
+// than sanitized and printed. The charset covers semver including pre-release
+// labels (`0.2.0-riven`) and hex digests, and admits no control character,
+// escape or whitespace.
+//
+// `__PUBLISH_VERSION__` is the placeholder the release build substitutes. A
+// room served straight off a checkout never went through that build, so every
+// session recorded under `joystack dev` carries the token verbatim. Read as a
+// version it would print garbage, and would report a mismatch on every single
+// dev export — a warning that fires every time is one nobody reads by the
+// third time.
+const VERSION_TOKEN = /^[A-Za-z0-9._+-]{1,64}$/;
+export const knownHeaderToken = (v) =>
+  (typeof v === 'string' && VERSION_TOKEN.test(v) && v !== '__PUBLISH_VERSION__' ? v : null);
+
+/**
+ * Export one recorded session as Parquet tables: state, inputs,
+ * performance (when the session was measured), session info, and the fields
+ * table that says what the state columns and channels are.
+ *
+ * The state table is the expensive one and the reason this exists: a recording
+ * holds inputs, so the only way to know where anything WAS is to run the game
+ * forward again. Doing that once and writing the result down is what turns
+ * every later question into SQL instead of another replay.
+ *
+ * @param {object} opts
+ * @param {string} opts.dir - the game folder
+ * @param {string} [opts.stream] - which recording; defaults to the most recent
+ * @param {string} opts.outDir - where the .parquet files go
+ * @param {string} [opts.sharedDir] - the resolved engine bundle's shared/ tree
+ * @param {number} [opts.rowsPerGroup]
+ * @param {string} [opts.engineVersion] - the engine this export is running on,
+ *   compared against the one that recorded the session
+ * @param {(o: object) => Promise<object>} [opts.openReplayImpl] - seam for tests
+ * @param {(msg: string) => void} [opts.log]
+ */
+export async function exportSession({
+  dir, stream, outDir, sharedDir, rowsPerGroup, engineVersion, openReplayImpl, log = () => {},
+}) {
+  const openReplay = openReplayImpl ?? await loadOpenReplay(sharedDir);
+  // The engine's own warnings — a recording missing segments, a session tuned
+  // live mid-play — are written to this sink. Without it they go to the floor
+  // and the export looks clean while describing a world that is not the one
+  // that was played.
+  const opened = await openReplay({ dir, stream, log });
+  const { replayer, bundle, session } = opened;
+  const chosen = opened.stream ?? stream ?? null;
+
+  // Which engine wrote this recording, against the one about to replay it. The
+  // header has carried engineVersion since the first recording and nothing read
+  // it, so the only way a reader learned the two disagreed was a divergence —
+  // which does not fire if the change altered nothing the checksums cover.
+  //
+  // Reported before the replay runs, not after: the replay is the slow part and
+  // this answer is already known. An absent version is UNKNOWN, not different —
+  // every recording made before this shipped has none, and warning on those
+  // would fire on every old session still on disk.
+  // A recording's header is NOT first-party text. Segments reach the dev server
+  // over a lane that deliberately does not require an Origin (a multiplayer
+  // room's worker sends none), and the store validates only the four fields it
+  // routes on — format, seq, stream, events. Everything else is spread through
+  // the stitcher verbatim, so anything printed from a header is attacker-
+  // reachable by whoever can post a segment.
+  //
+  // Printing is what makes that matter. `ESC[2J ESC[H` clears the screen and
+  // repaints, and the line being repainted here is the one a creator — or the
+  // coding agent reading their terminal — uses to decide whether to trust the
+  // exported numbers. An export with no session named takes the newest
+  // recording, so a segment posted a moment ago is the default target.
+  //
+  // So: REJECT, don't sanitize — `knownHeaderToken` above.
+  // The build stamp the dev server wrote beside the recording (replay-store.mjs,
+  // "the build stamp"), and the build this folder holds now. Both are absent
+  // for a recording copied in without its stamp or made before stamps
+  // existed, and then nothing is claimed about whether the files changed.
+  const recordedBuild = chosen ? readBuildStamp(dir, chosen) : null;
+  let runningBuild = null;
+  try { runningBuild = gameBuild(dir, { git: false }); } catch { /* not a folder of game files */ }
+  const buildChanged = recordedBuild?.id && runningBuild?.id ? recordedBuild.id !== runningBuild.id : null;
+  // A room served by `joystack dev` carries a placeholder where a published one
+  // carries its engine version; the dev server's stamp names the engine it
+  // served.
+  const recordedEngine = knownHeaderToken(session?.header?.engineVersion) ?? recordedBuild?.engine ?? null;
+  const runningEngine = knownHeaderToken(engineVersion);
+  if (recordedEngine && runningEngine && recordedEngine !== runningEngine) {
+    log(`  ⚠ this session was recorded by engine ${recordedEngine} and is being replayed on `
+      + `${runningEngine}. A replay runs the code as it is now, so where the two engines `
+      + 'simulate differently the table holds a world nobody played.');
+  }
+  // And the same question for the game's own code, which is the half that
+  // actually moves. engineVersion changes once per release; a fingerprint
+  // changes the moment a tick does.
+  // Same provenance, same rule: this one comes off the header too.
+  const recordedCode = knownHeaderToken(session?.header?.codeFingerprint);
+  const runningCode = knownHeaderToken(bundle?.fingerprint);
+  const codeChanged = Boolean(recordedCode && runningCode && recordedCode !== runningCode);
+  if (codeChanged) {
+    log('  ⚠ this game has changed since the session was recorded (the simulation it lowers to '
+      + `is ${runningCode}; the recording was made by ${recordedCode}). The table below is what `
+      + 'your game does with those inputs TODAY, which is not what happened when you played.');
+  } else if (buildChanged) {
+    // The files moved while the simulation's shape did not: a number inside a
+    // tick, a helper's body. The shape check cannot see that; the build can.
+    log(`  ⚠ this game's files have changed since the session was recorded (build ${recordedBuild.id}, `
+      + `now ${runningBuild.id}), though not the shape of its simulation. The table below is what your `
+      + 'game does with those inputs TODAY, which may not be what happened when you played.');
+  }
+
+  const { columns, conflicts } = tableSchema(bundle);
+  if (conflicts.length) {
+    log(`note: ${conflicts.length} field name(s) are declared with different types by different entity kinds `
+      + `and ride as JSON text — ${conflicts.join(', ')}`);
+  }
+  const columnIndex = new Map(columns.map((c) => [c.name, c.type]));
+
+  mkdirSync(outDir, { recursive: true });
+  const stateFile = join(outDir, `${chosen ?? 'session'}.state.parquet`);
+  const inputFile = join(outDir, `${chosen ?? 'session'}.inputs.parquet`);
+
+  // Read before the replay: the seconds its `second` records cover are where
+  // the replay counts each kind alive, for the perf table's `kind` rows.
+  const segments = chosen ? readTrackSegments(dir, chosen) : [];
+  const alive = aliveCounter(segments);
+
+  const sink = rowSinkFor(stateFile, columns, rowsPerGroup);
+  const tally = { undoubleable: 0 };
+  let ticks = 0;
+  let firstTick = null;
+  let lastTick = null;
+  let rows;
+  try {
+  // The world BEFORE any step is a real tick of the session — it is the
+  // keyframe the replay entered at — so it is written before the loop, not
+  // skipped into it.
+    for (;;) {
+      const { tick, entities } = replayer.runtime.serializeEntities();
+      firstTick ??= tick;
+      lastTick = tick;
+      for (const entity of entities) sink.push(stateRow(entity, tick, columnIndex, tally));
+      alive.see(tick, entities);
+      ticks += 1;
+      if (replayer.atEnd) break;
+      replayer.step();
+    }
+    rows = sink.finish();
+  } catch (e) {
+    sink.abandon();
+    throw e;
+  }
+  // The new state table is in place, so a previous export's perf and info
+  // tables of this session no longer describe it. They go now rather than
+  // being overwritten later: the perf table is written only when there is a
+  // track, and a run that fails before the info table is written would leave
+  // the old one beside the new state. A run that fails before this point
+  // leaves the previous export whole.
+  for (const name of ['perf', 'info', 'fields']) rmSync(join(outDir, `${chosen ?? 'session'}.${name}.parquet`), { force: true });
+
+  // Streamed like the state table rather than materialised: the row count comes
+  // from a recording, and a recording is not this machine's to trust.
+  const inputs = inputSchema(session);
+  const inputSink = rowSinkFor(inputFile, inputs.columns, rowsPerGroup);
+  let inputRows;
+  try {
+    for (const send of inputs.sends) inputSink.push(inputRow(send, inputs.keys, inputs.types));
+    inputRows = inputSink.finish();
+  } catch (e) {
+    inputSink.abandon();
+    throw e;
+  }
+  // The third table: what the session cost on the device that played it
+  // (project note ofta45). Read straight off the track segments — nothing here
+  // is replayed, because cost is the one thing a replay cannot reproduce.
+  const perf = perfTable(segments, { alive });
+  let perfFile = null;
+  let perfRows = 0;
+  if (perf) {
+    perfFile = join(outDir, `${chosen ?? 'session'}.perf.parquet`);
+    const perfSink = rowSinkFor(perfFile, perf.columns, rowsPerGroup);
+    try {
+      for (const row of perf.rows) perfSink.push(row);
+      perfRows = perfSink.finish();
+    } catch (e) {
+      perfSink.abandon();
+      throw e;
+    }
+  }
+
+  // The fourth table, written last because two of its row kinds — where the
+  // replay diverged, what it could not reproduce — are only known once the
+  // replay has run to the end.
+  const info = infoTable({
+    stream: chosen, session, replayer,
+    firstTick: firstTick ?? 0,
+    endTick: num(session?.endTick) ?? lastTick ?? 0,
+    segments,
+    limits: chosen ? readTrackLimits(dir, chosen) : null,
+    recordedEngine, runningEngine, recordedCode, runningCode, codeChanged,
+    recordedBuild, runningBuild, buildChanged,
+  });
+  const infoFile = join(outDir, `${chosen ?? 'session'}.info.parquet`);
+  const infoSink = rowSinkFor(infoFile, info.columns, rowsPerGroup);
+  let infoRows;
+  try {
+    for (const row of info.rows) infoSink.push(row);
+    infoRows = infoSink.finish();
+  } catch (e) {
+    infoSink.abandon();
+    throw e;
+  }
+
+  // What each state column is. Read off the lowered game, like the state
+  // table's schema, so it describes the columns the state table actually has.
+  const fields = fieldsTable(bundle, { dir, sharedDir });
+  const fieldsFile = join(outDir, `${chosen ?? 'session'}.fields.parquet`);
+  const fieldsSink = rowSinkFor(fieldsFile, fields.columns, rowsPerGroup);
+  let fieldsRows;
+  try {
+    for (const row of fields.rows) fieldsSink.push(row);
+    fieldsRows = fieldsSink.finish();
+  } catch (e) {
+    fieldsSink.abandon();
+    throw e;
+  }
+
+  if (inputs.truncatedKeys) {
+    log(`note: ${inputs.truncatedKeys} rarely-used payload field(s) did not get their own column `
+      + `(the cap is ${MAX_PAYLOAD_COLUMNS}) — they are still in the \`payload\` JSON column on every row`);
+  }
+
+  return {
+    stream: chosen,
+    stateFile,
+    inputFile,
+    // Null when the session carries no performance track: measuring was off,
+    // or the recording predates the track. The caller says so rather than
+    // implying the session was free.
+    perfFile,
+    perfRows,
+    infoFile,
+    infoRows,
+    fieldsFile,
+    fieldsRows,
+    ticks,
+    rows,
+    columns: columns.length,
+    inputs: inputRows,
+    truncatedKeys: inputs.truncatedKeys,
+    // Three separate ways the table can describe a world that is not the one
+    // that was played, kept apart because they have different causes and
+    // different answers. The ticks each covers are in the info table.
+    divergences: replayer.divergences?.length ?? 0,
+    // One per `diverged` row: the ticks one drift covers, how it was found,
+    // and how many checksums failed inside it.
+    drifts: info.rows.filter((r) => r.row === 'diverged').map((r) => {
+      let checks;
+      const detail = r.detail && typeof r.detail === 'object' ? r.detail : null;
+      checks = Number.isSafeInteger(detail?.checks) ? detail.checks : null;
+      return { from: r.tick_from, to: r.tick_to, via: r.what, checks };
+    }),
+    gaps: replayer.gaps?.length ?? 0,
+    unsupported: replayer.unsupported?.length ?? 0,
+    recordedEngine,
+    runningEngine,
+    recordedCode,
+    runningCode,
+    codeChanged,
+    recordedBuild: recordedBuild?.id ?? null,
+    runningBuild: runningBuild?.id ?? null,
+    buildChanged,
+    undoubleable: tally.undoubleable,
+  };
+}