animader 0.0.0-stage → 0.1.1

package/src/machine.js

@@ -0,0 +1,712 @@
+// animader/machine - the Machine class over the machine boundary (plan 02,
+// phase 6).
+//
+// This file mirrors src/wasm_entry.zig's machine section byte for byte.
+// The host writes a document into the shared input zone, calls
+// `anm_machine_load` once, then drives the cached machine:
+//
+//   - `anm_machine_step(events_len, now)` takes an 'ANEV' blob (the log
+//     records a session parses to) and writes the outputs wire;
+//   - `anm_machine_snapshot()` / `anm_machine_restore(blob_len)` move the
+//     `'ANMS'` snapshot;
+//   - `anm_machine_setInput(name, lane0)` and `anm_machine_fireTrigger`
+//     apply one `(input-write ...)` record at the snapshot's current time;
+//   - `anm_machine_meta()` writes the `'ANMM'` listing;
+//   - `anm_machine_diag()` writes the last load's `'ANMD'` diagnostics;
+//   - `anm_machine_emits()` writes the last stepping call's `'ANME'`
+//     emitted events, the frame contract's `host.handle` step;
+//   - `anm_machine_eject(doc_len, verb_index)` is the phase-5 export.
+//
+// Return convention, mirrored from the entry header: a call answers a byte
+// length (>= 0) or a negative status, never data:
+//
+//   -1  diagnostics; the load is kept so `diag()` answers its blob
+//   -2  bad call (over a zone cap, a malformed blob, no clean machine)
+//   -3  out of memory
+//   -4  output over its zone
+//   -5  a component over its cap
+//   -6  a well-formed snapshot from a different machine
+//
+// The outputs wire (`anm_machine_step`):
+//
+//   [count u32]
+//   count x { index u16, arity u8, pad u8 = 0, lanes [4]f64 LE }
+//
+// The snapshot is `'ANMS'`: 28-byte header (magic, version, machine_hash
+// u64, time i64, input_count u16, layer_count u16), then per input a value
+// f64 and an armed byte with 7 pad bytes, then per layer a state u16, a
+// blend_from u16, 4 pad bytes and three i64 clocks, then two u64 counters.
+// The meta is `'ANMM'`: a 32-byte header of six u32 counts (inputs, hit
+// areas, outputs, layers, states, transitions) and the records in that
+// order, each followed by its name bytes. The diagnostics blob is `'ANMD'`:
+// magic, version, count, then per record a source byte, a severity byte, a
+// code u16, two u32 span ends, a message length u32 and the message.
+//
+// The emits blob is `'ANME'` (src/Emits.zig), the `'ANEV'` envelope's own
+// shape: a 20-byte header (magic, version, count, strtab_len, the last
+// four bytes zero pad), then per emit a 10-byte record (`at` i64
+// microseconds, `name` u16 index), then the string table of NUL-separated
+// names in first-occurrence order. An emit carries no value.
+//
+// Memory views are re-taken from `exports.memory.buffer` on every call
+// (the pacer discipline): a view taken before a grow would detach.
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+const MAGIC_ANMS = 0x534d4e41; // 'ANMS' read little-endian
+const SNAPSHOT_VERSION = 1;
+const SNAPSHOT_HEADER_LEN = 28;
+const INPUT_STATE_LEN = 16;
+const LAYER_STATE_LEN = 32;
+const SNAPSHOT_TAIL_LEN = 16;
+const MAX_INPUTS = 256;
+const MAX_LAYERS = 32;
+const NO_INDEX = 0xffff;
+
+const MAGIC_ANMD = 0x444d4e41; // 'ANMD' read little-endian
+const DIAGS_VERSION = 1;
+const DIAGS_HEADER_LEN = 12;
+const DIAG_RECORD_LEN = 16;
+
+const MAGIC_ANMM = 0x4d4d4e41; // 'ANMM' read little-endian
+const META_VERSION = 1;
+const META_HEADER_LEN = 32;
+const INPUT_REC_LEN = 24;
+const HIT_AREA_REC_LEN = 40;
+const OUTPUT_REC_LEN = 4;
+const LAYER_REC_LEN = 16;
+const STATE_REC_LEN = 24;
+const TRANSITION_REC_LEN = 24;
+
+const MAGIC_ANME = 0x454d4e41; // 'ANME' read little-endian
+const EMITS_VERSION = 1;
+const EMITS_HEADER_LEN = 20;
+const EMIT_RECORD_LEN = 10;
+
+const OUTPUTS_HEADER_LEN = 4;
+const OUTPUTS_ENTRY_LEN = 36;
+
+const STATUS_DIAGNOSTICS = -1;
+const STATUS_BAD_CALL = -2;
+const STATUS_OOM = -3;
+const STATUS_OUTPUT_TOO_SMALL = -4;
+const STATUS_COMPONENT_TOO_LARGE = -5;
+const STATUS_SNAPSHOT_MISMATCH = -6;
+
+/** The machine diagnostic ordinals (`Machine.Code`), append-only. */
+export const MACHINE_CODES = {
+  state_duplicate: 0,
+  transition_cross_layer: 1,
+  output_multiply_owned: 2,
+  output_undefined_in_state: 3,
+  output_arity_mismatch: 4,
+  when_references_time: 5,
+  transition_cycle: 6,
+  expr_invalid: 7,
+  verb_invalid: 8,
+  input_cap_exceeded: 9,
+  layer_cap_exceeded: 10,
+  state_cap_exceeded: 11,
+  transition_cap_exceeded: 12,
+  snapshot_mismatch: 13,
+};
+
+/** The status semantics, so a caller does not have to know the integers. */
+export const STATUS = {
+  DIAGNOSTICS: STATUS_DIAGNOSTICS,
+  BAD_CALL: STATUS_BAD_CALL,
+  OOM: STATUS_OOM,
+  OUTPUT_TOO_SMALL: STATUS_OUTPUT_TOO_SMALL,
+  COMPONENT_TOO_LARGE: STATUS_COMPONENT_TOO_LARGE,
+  SNAPSHOT_MISMATCH: STATUS_SNAPSHOT_MISMATCH,
+};
+
+const describeStatus = (status) => {
+  switch (status) {
+    case STATUS_DIAGNOSTICS:
+      return "the document has diagnostics";
+    case STATUS_BAD_CALL:
+      return "bad call";
+    case STATUS_OOM:
+      return "out of memory";
+    case STATUS_OUTPUT_TOO_SMALL:
+      return "the output would not fit its zone";
+    case STATUS_COMPONENT_TOO_LARGE:
+      return "a component is over its cap";
+    case STATUS_SNAPSHOT_MISMATCH:
+      return "the snapshot belongs to a different machine";
+    default:
+      return `unknown status ${status}`;
+  }
+};
+
+/** A boundary failure, a diagnosed document, or a malformed blob. */
+export class MachineError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ status?: number | null, code?: number | null, diagnostics?: Array<object> | null }} [details]
+   *   `status` is the boundary's negative return (null for a JS-side
+   *   defect); `code` is the first machine diagnostic code for a refused
+   *   restore; `diagnostics` is the decoded `'ANMD'` list for a diagnosed
+   *   load.
+   */
+  constructor(message, { status = null, code = null, diagnostics = null } = {}) {
+    super(message);
+    this.name = "MachineError";
+    this.status = status;
+    this.code = code;
+    this.diagnostics = diagnostics;
+  }
+}
+
+function toBytes(blob) {
+  if (blob instanceof Uint8Array) return blob;
+  if (blob instanceof ArrayBuffer) return new Uint8Array(blob);
+  if (ArrayBuffer.isView(blob)) return new Uint8Array(blob.buffer, blob.byteOffset, blob.byteLength);
+  throw new TypeError("animader: expected an ArrayBuffer or a typed array");
+}
+
+function micros(value, what) {
+  if (!Number.isSafeInteger(value)) {
+    throw new MachineError(`animader: ${what} must be a safe integer (microseconds), got ${value}`, {
+      status: STATUS_BAD_CALL,
+    });
+  }
+  return value;
+}
+
+function viewOf(bytes) {
+  return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+function nameAt(bytes, off, len) {
+  return decoder.decode(bytes.subarray(off, off + len));
+}
+
+/** One `'ANMS'` blob decoded field by field; throws on any defect. */
+export function decodeSnapshot(blob) {
+  const bytes = toBytes(blob);
+  if (bytes.byteLength < SNAPSHOT_HEADER_LEN) {
+    throw new MachineError(`animader: 'ANMS' blob is ${bytes.byteLength} bytes, under the header`);
+  }
+  const view = viewOf(bytes);
+  if (view.getUint32(0, true) !== MAGIC_ANMS) throw new MachineError("animader: 'ANMS' magic is missing");
+  if (view.getUint32(4, true) !== SNAPSHOT_VERSION) {
+    throw new MachineError(`animader: 'ANMS' version ${view.getUint32(4, true)} is not ${SNAPSHOT_VERSION}`);
+  }
+  const machineHash = view.getBigUint64(8, true);
+  const time = Number(view.getBigInt64(16, true));
+  const inputCount = view.getUint16(24, true);
+  const layerCount = view.getUint16(26, true);
+  if (inputCount > MAX_INPUTS) throw new MachineError(`animader: 'ANMS' input count ${inputCount} over the cap`);
+  if (layerCount > MAX_LAYERS) throw new MachineError(`animader: 'ANMS' layer count ${layerCount} over the cap`);
+  const need =
+    SNAPSHOT_HEADER_LEN + inputCount * INPUT_STATE_LEN + layerCount * LAYER_STATE_LEN + SNAPSHOT_TAIL_LEN;
+  if (bytes.byteLength !== need) {
+    throw new MachineError("animader: 'ANMS' length does not match its header");
+  }
+
+  const inputs = [];
+  let off = SNAPSHOT_HEADER_LEN;
+  for (let i = 0; i < inputCount; i++, off += INPUT_STATE_LEN) {
+    inputs.push({
+      value: view.getBigUint64(off, true),
+      armed: view.getUint8(off + 8) !== 0,
+    });
+  }
+  const layers = [];
+  for (let i = 0; i < layerCount; i++, off += LAYER_STATE_LEN) {
+    layers.push({
+      state: view.getUint16(off, true),
+      blendFrom: view.getUint16(off + 2, true),
+      enteredAt: Number(view.getBigInt64(off + 8, true)),
+      blendStart: Number(view.getBigInt64(off + 16, true)),
+      fromEnteredAt: Number(view.getBigInt64(off + 24, true)),
+    });
+  }
+  return {
+    machineHash,
+    time,
+    inputCount,
+    layerCount,
+    inputs,
+    layers,
+    chainCapHits: Number(view.getBigUint64(off, true)),
+    unknownInputHits: Number(view.getBigUint64(off + 8, true)),
+  };
+}
+
+/** The `anm_machine_step` outputs wire, decoded; throws on any defect. */
+export function decodeOutputs(blob) {
+  const bytes = toBytes(blob);
+  if (bytes.byteLength < OUTPUTS_HEADER_LEN) {
+    throw new MachineError(`animader: outputs wire is ${bytes.byteLength} bytes, under the header`);
+  }
+  const view = viewOf(bytes);
+  const count = view.getUint32(0, true);
+  if (bytes.byteLength !== OUTPUTS_HEADER_LEN + count * OUTPUTS_ENTRY_LEN) {
+    throw new MachineError("animader: outputs wire length does not match its header");
+  }
+  const out = [];
+  for (let i = 0; i < count; i++) {
+    const off = OUTPUTS_HEADER_LEN + i * OUTPUTS_ENTRY_LEN;
+    const bits = [];
+    const value = [];
+    for (let lane = 0; lane < 4; lane++) {
+      const b = view.getBigUint64(off + 4 + lane * 8, true);
+      bits.push(b);
+      value.push(view.getFloat64(off + 4 + lane * 8, true));
+    }
+    out.push({ index: view.getUint16(off, true), arity: view.getUint8(off + 2), value, bits });
+  }
+  return out;
+}
+
+/** The `'ANMM'` listing decoded; throws on any defect. */
+export function decodeMeta(blob) {
+  const bytes = toBytes(blob);
+  if (bytes.byteLength < META_HEADER_LEN) {
+    throw new MachineError(`animader: 'ANMM' blob is ${bytes.byteLength} bytes, under the header`);
+  }
+  const view = viewOf(bytes);
+  if (view.getUint32(0, true) !== MAGIC_ANMM) throw new MachineError("animader: 'ANMM' magic is missing");
+  if (view.getUint32(4, true) !== META_VERSION) {
+    throw new MachineError(`animader: 'ANMM' version ${view.getUint32(4, true)} is not ${META_VERSION}`);
+  }
+  const counts = {
+    inputs: view.getUint32(8, true),
+    hitAreas: view.getUint32(12, true),
+    outputs: view.getUint32(16, true),
+    layers: view.getUint32(20, true),
+    states: view.getUint32(24, true),
+    transitions: view.getUint32(28, true),
+  };
+  let off = META_HEADER_LEN;
+  const take = (len, what) => {
+    if (off + len > bytes.byteLength) throw new MachineError(`animader: 'ANMM' ${what} runs past the blob`);
+    const start = off;
+    off += len;
+    return start;
+  };
+  const nameOf = (recOff, nameLen) => nameAt(bytes, recOff, nameLen);
+
+  const inputs = [];
+  for (let i = 0; i < counts.inputs; i++) {
+    const rec = take(INPUT_REC_LEN, "input record");
+    const nameLen = view.getUint16(rec, true);
+    inputs.push({
+      name: nameOf(take(nameLen, "input name"), nameLen),
+      kind: ["number", "bool", "trigger"][view.getUint8(rec + 2)],
+      valueSpan: { start: view.getUint32(rec + 4, true), end: view.getUint32(rec + 8, true) },
+      defaultBits: view.getBigUint64(rec + 16, true),
+    });
+  }
+  const hitAreas = [];
+  for (let i = 0; i < counts.hitAreas; i++) {
+    const rec = take(HIT_AREA_REC_LEN, "hit-area record");
+    const nameLen = view.getUint16(rec, true);
+    hitAreas.push({
+      name: nameOf(take(nameLen, "hit-area name"), nameLen),
+      rect: [0, 1, 2, 3].map((lane) => view.getFloat64(rec + 8 + lane * 8, true)),
+    });
+  }
+  const outputs = [];
+  for (let i = 0; i < counts.outputs; i++) {
+    const rec = take(OUTPUT_REC_LEN, "output record");
+    const nameLen = view.getUint16(rec, true);
+    outputs.push({ name: nameOf(take(nameLen, "output name"), nameLen), arity: view.getUint8(rec + 2) });
+  }
+  const layers = [];
+  for (let i = 0; i < counts.layers; i++) {
+    const rec = take(LAYER_REC_LEN, "layer record");
+    const nameLen = view.getUint16(rec, true);
+    layers.push({
+      name: nameOf(take(nameLen, "layer name"), nameLen),
+      entry: view.getUint16(rec + 4, true),
+      span: { start: view.getUint32(rec + 8, true), end: view.getUint32(rec + 12, true) },
+    });
+  }
+  const states = [];
+  for (let i = 0; i < counts.states; i++) {
+    const rec = take(STATE_REC_LEN, "state record");
+    const nameLen = view.getUint16(rec, true);
+    states.push({
+      name: nameOf(take(nameLen, "state name"), nameLen),
+      layer: view.getUint16(rec + 2, true),
+      origin: view.getUint8(rec + 4),
+      span: { start: view.getUint32(rec + 8, true), end: view.getUint32(rec + 12, true) },
+      verbSpan: { start: view.getUint32(rec + 16, true), end: view.getUint32(rec + 20, true) },
+    });
+  }
+  const transitions = [];
+  for (let i = 0; i < counts.transitions; i++) {
+    const rec = take(TRANSITION_REC_LEN, "transition record");
+    transitions.push({
+      from: view.getUint16(rec, true),
+      layer: view.getUint16(rec + 2, true),
+      to: view.getUint16(rec + 4, true),
+      origin: view.getUint8(rec + 6),
+      span: { start: view.getUint32(rec + 8, true), end: view.getUint32(rec + 12, true) },
+      verbSpan: { start: view.getUint32(rec + 16, true), end: view.getUint32(rec + 20, true) },
+    });
+  }
+  if (off !== bytes.byteLength) throw new MachineError("animader: 'ANMM' has trailing bytes");
+  return { counts, inputs, hitAreas, outputs, layers, states, transitions };
+}
+
+/** The `'ANMD'` diagnostics decoded; throws on any defect. */
+export function decodeDiags(blob) {
+  const bytes = toBytes(blob);
+  if (bytes.byteLength < DIAGS_HEADER_LEN) {
+    throw new MachineError(`animader: 'ANMD' blob is ${bytes.byteLength} bytes, under the header`);
+  }
+  const view = viewOf(bytes);
+  if (view.getUint32(0, true) !== MAGIC_ANMD) throw new MachineError("animader: 'ANMD' magic is missing");
+  if (view.getUint32(4, true) !== DIAGS_VERSION) {
+    throw new MachineError(`animader: 'ANMD' version ${view.getUint32(4, true)} is not ${DIAGS_VERSION}`);
+  }
+  const count = view.getUint32(8, true);
+  const diagnostics = [];
+  let off = DIAGS_HEADER_LEN;
+  for (let i = 0; i < count; i++) {
+    if (off + DIAG_RECORD_LEN > bytes.byteLength) throw new MachineError("animader: 'ANMD' record runs past the blob");
+    const msgLen = view.getUint32(off + 12, true);
+    if (off + DIAG_RECORD_LEN + msgLen > bytes.byteLength) {
+      throw new MachineError("animader: 'ANMD' message runs past the blob");
+    }
+    diagnostics.push({
+      source: view.getUint8(off),
+      severity: view.getUint8(off + 1),
+      code: view.getUint16(off + 2, true),
+      span: { start: view.getUint32(off + 4, true), end: view.getUint32(off + 8, true) },
+      message: nameAt(bytes, off + DIAG_RECORD_LEN, msgLen),
+    });
+    off += DIAG_RECORD_LEN + msgLen;
+  }
+  return { count, diagnostics };
+}
+
+/**
+ * The `'ANME'` emitted-events blob decoded, `anm_machine_emits()`'s wire
+ * (src/Emits.zig): `{ count, emits }` with each emit `{ name, at }`, the
+ * name borrowed from the machine's table and `at` the entry instant in
+ * microseconds. Throws on any defect.
+ * @param {BufferSource} blob
+ * @returns {{ count: number, emits: Array<{ name: string, at: number }> }}
+ */
+export function decodeEmits(blob) {
+  const bytes = toBytes(blob);
+  if (bytes.byteLength < EMITS_HEADER_LEN) {
+    throw new MachineError(`animader: 'ANME' blob is ${bytes.byteLength} bytes, under the header`);
+  }
+  const view = viewOf(bytes);
+  if (view.getUint32(0, true) !== MAGIC_ANME) throw new MachineError("animader: 'ANME' magic is missing");
+  if (view.getUint32(4, true) !== EMITS_VERSION) {
+    throw new MachineError(`animader: 'ANME' version ${view.getUint32(4, true)} is not ${EMITS_VERSION}`);
+  }
+  const count = view.getUint32(8, true);
+  const strtabLen = view.getUint32(12, true);
+  const strtabOff = EMITS_HEADER_LEN + count * EMIT_RECORD_LEN;
+  if (strtabOff + strtabLen !== bytes.byteLength) {
+    throw new MachineError("animader: 'ANME' length does not match its header");
+  }
+
+  const strings = [];
+  let pos = strtabOff;
+  while (pos < bytes.byteLength) {
+    const end = bytes.indexOf(0, pos);
+    if (end === -1) {
+      strings.push(decoder.decode(bytes.subarray(pos)));
+      break;
+    }
+    strings.push(decoder.decode(bytes.subarray(pos, end)));
+    pos = end + 1;
+  }
+
+  const emits = [];
+  for (let i = 0; i < count; i++) {
+    const off = EMITS_HEADER_LEN + i * EMIT_RECORD_LEN;
+    const raw = view.getUint16(off + 8, true);
+    if (raw >= strings.length) {
+      throw new MachineError(`animader: 'ANME' record name index ${raw} has no table entry`);
+    }
+    emits.push({ name: strings[raw], at: Number(view.getBigInt64(off, true)) });
+  }
+  return { count, emits };
+}
+
+const IMPORTS = { env: { sjon_host_invoke_plugin: () => 0 } };
+
+/** The loaded machine boundary and the JS-side blob decoders. */
+export class Machine {
+  #e;
+  #doc;
+  #meta;
+  #outputsWire = null;
+  #emits = [];
+
+  /**
+   * Instantiate the artifact synchronously (node, tests) and load a
+   * document. `bytes` is the built animader.wasm, e.g. from
+   * `readFileSync`. Throws `MachineError` on a diagnosed document.
+   * @param {BufferSource} bytes
+   * @param {string} text
+   * @returns {Machine}
+   */
+  static loadSync(bytes, text) {
+    return new Machine(new WebAssembly.Instance(new WebAssembly.Module(bytes), IMPORTS), text);
+  }
+
+  /**
+   * Instantiate the artifact from bytes or a compiled module (browser) and
+   * load a document.
+   * @param {BufferSource | WebAssembly.Module} source
+   * @param {string} text
+   * @returns {Promise<Machine>}
+   */
+  static async load(source, text) {
+    const instance =
+      source instanceof WebAssembly.Module
+        ? await WebAssembly.instantiate(source, IMPORTS)
+        : (await WebAssembly.instantiate(source, IMPORTS)).instance;
+    return new Machine(instance, text);
+  }
+
+  /** @param {WebAssembly.Instance} instance @param {string} text */
+  constructor(instance, text) {
+    this.#e = instance.exports;
+    if (typeof this.#e.animader_abiVersion !== "function" || this.#e.animader_abiVersion() !== 1) {
+      throw new MachineError("animader: unsupported or missing ABI version 1");
+    }
+    for (const name of [
+      "anm_log_inPtr",
+      "anm_log_outPtr",
+      "anm_log_outLen",
+      "anm_machine_load",
+      "anm_machine_step",
+      "anm_machine_snapshot",
+      "anm_machine_restore",
+      "anm_machine_setInput",
+      "anm_machine_fireTrigger",
+      "anm_machine_meta",
+      "anm_machine_diag",
+      "anm_machine_emits",
+      "anm_machine_eject",
+      "memory",
+    ]) {
+      if (this.#e[name] === undefined) throw new MachineError(`animader: missing export ${name}`);
+    }
+    this.#doc = text;
+    this.#load(text);
+  }
+
+  /** The boundary ABI version (1). */
+  get abiVersion() {
+    return this.#e.animader_abiVersion();
+  }
+
+  #writeInput(bytes) {
+    const e = this.#e;
+    new Uint8Array(e.memory.buffer, e.anm_log_inPtr(), bytes.byteLength).set(bytes);
+  }
+
+  #output(len) {
+    return new Uint8Array(this.#e.memory.buffer, this.#e.anm_log_outPtr(), len).slice();
+  }
+
+  #check(status, what) {
+    if (status < 0) {
+      throw new MachineError(`animader: ${what}: ${describeStatus(status)} (status ${status})`, { status });
+    }
+    return status;
+  }
+
+  #load(text) {
+    const bytes = encoder.encode(text);
+    this.#writeInput(bytes);
+    const status = this.#e.anm_machine_load(bytes.byteLength);
+    if (status === STATUS_DIAGNOSTICS) {
+      const blob = this.#output(this.#e.anm_machine_diag());
+      const diagnostics = decodeDiags(blob).diagnostics;
+      throw new MachineError(
+        `animader: the machine document has diagnostics (${diagnostics.length} record(s))`,
+        { status, diagnostics },
+      );
+    }
+    this.#check(status, "load");
+    this.#meta = decodeMeta(this.#output(this.#e.anm_machine_meta()));
+  }
+
+  /**
+   * Apply an 'ANEV' events blob (or null for an empty batch) and advance
+   * to `now` (session microseconds). The outputs at `now` are cached for
+   * `outputs()` and the emitted events for `emits()`.
+   * @param {Uint8Array | ArrayBuffer | null} events
+   * @param {number} now
+   * @returns {Machine}
+   */
+  step(events, now) {
+    const at = micros(now, "now");
+    let bytes = null;
+    if (events !== null && events !== undefined) {
+      bytes = toBytes(events);
+      this.#writeInput(bytes);
+    }
+    // A failed step leaves no emits (the boundary's own rule), so the
+    // cache is cleared before the call, never after a throw.
+    this.#emits = [];
+    const status = this.#e.anm_machine_step(bytes === null ? 0 : bytes.byteLength, BigInt(at));
+    this.#check(status, "step");
+    this.#outputsWire = this.#output(status);
+    this.#syncEmits();
+    return this;
+  }
+
+  /**
+   * The last stepping call's emitted events, in order: `{ name, at }` per
+   * `(emit ...)` of every state the call entered, `at` the entry instant
+   * in microseconds (not necessarily the step's `now`). A clean load
+   * reports the empty list until a step runs.
+   * @returns {Array<{ name: string, at: number }>}
+   */
+  emits() {
+    return this.#emits.slice();
+  }
+
+  /**
+   * The outputs evaluated at the last `step`'s time, in declaration order:
+   * `{ name, index, arity, value: [4 numbers] }`. Throws when no step has
+   * run.
+   * @returns {Array<{ name: string, index: number, arity: number, value: number[] }>}
+   */
+  outputs() {
+    if (this.#outputsWire === null) {
+      throw new MachineError("animader: outputs are evaluated by step; call step first", {
+        status: STATUS_BAD_CALL,
+      });
+    }
+    return decodeOutputs(this.#outputsWire).map((o) => {
+      const decl = this.#meta.outputs[o.index];
+      return { name: decl === undefined ? null : decl.name, index: o.index, arity: o.arity, value: o.value };
+    });
+  }
+
+  /** The raw outputs wire of the last `step`, or null before one. */
+  outputsWire() {
+    return this.#outputsWire === null ? null : this.#outputsWire.slice();
+  }
+
+  /**
+   * The current `'ANMS'` snapshot.
+   * @returns {Uint8Array}
+   */
+  snapshot() {
+    const status = this.#e.anm_machine_snapshot();
+    this.#check(status, "snapshot");
+    return this.#output(status);
+  }
+
+  /**
+   * Replace the cached snapshot from an `'ANMS'` blob. A well-formed blob
+   * from a different machine throws with status -6 and the
+   * `snapshot_mismatch` code.
+   * @param {Uint8Array} blob
+   * @returns {Machine}
+   */
+  restore(blob) {
+    const bytes = toBytes(blob);
+    this.#writeInput(bytes);
+    const status = this.#e.anm_machine_restore(bytes.byteLength);
+    if (status === STATUS_SNAPSHOT_MISMATCH) {
+      throw new MachineError("animader: the snapshot belongs to a different machine (status -6)", {
+        status,
+        code: MACHINE_CODES.snapshot_mismatch,
+      });
+    }
+    this.#check(status, "restore");
+    return this;
+  }
+
+  /**
+   * Apply one `(input-write ...)` record for `name` at the snapshot's current
+   * time, exactly as `step` would. `value` is lane 0 (i32): a number
+   * input takes it, a bool takes truthiness, a trigger is armed.
+   * @param {string} name
+   * @param {number} [value]
+   * @returns {Machine}
+   */
+  setInput(name, value = 1) {
+    return this.#input(name, value, "setInput");
+  }
+
+  /**
+   * Arm the named input for the current instant: `setInput(name, 1)` with
+   * the trigger's own name.
+   * @param {string} name
+   * @returns {Machine}
+   */
+  fireTrigger(name) {
+    return this.#input(name, 1, "fireTrigger");
+  }
+
+  #input(name, value, what) {
+    if (!Number.isInteger(value) || value < -2147483648 || value > 2147483647) {
+      throw new MachineError(`animader: ${what} value must be an i32, got ${value}`, {
+        status: STATUS_BAD_CALL,
+      });
+    }
+    const bytes = encoder.encode(name);
+    this.#writeInput(bytes);
+    this.#emits = [];
+    const status =
+      what === "setInput"
+        ? this.#e.anm_machine_setInput(bytes.byteLength, value)
+        : this.#e.anm_machine_fireTrigger(bytes.byteLength);
+    this.#check(status, what);
+    this.#syncEmits();
+    return this;
+  }
+
+  /** Read and decode the boundary's current 'ANME' blob. */
+  #syncEmits() {
+    const status = this.#e.anm_machine_emits();
+    this.#check(status, "emits");
+    this.#emits = decodeEmits(this.#output(status)).emits;
+  }
+
+  /**
+   * The loaded machine's `'ANMM'` listing.
+   * @returns {Uint8Array}
+   */
+  meta() {
+    const status = this.#e.anm_machine_meta();
+    this.#check(status, "meta");
+    return this.#output(status);
+  }
+
+  /**
+   * The last load's `'ANMD'` diagnostics: a zero-count blob for a clean
+   * document.
+   * @returns {Uint8Array}
+   */
+  diag() {
+    const status = this.#e.anm_machine_diag();
+    this.#check(status, "diag");
+    return this.#output(status);
+  }
+
+  /**
+   * The document with the verb at `verbIndex` replaced by its emitted
+   * core forms, the verb kept above them as a comment.
+   * @param {number} verbIndex
+   * @returns {string}
+   */
+  eject(verbIndex) {
+    const bytes = encoder.encode(this.#doc);
+    this.#writeInput(bytes);
+    const status = this.#e.anm_machine_eject(bytes.byteLength, verbIndex);
+    this.#check(status, "eject");
+    return decoder.decode(this.#output(status));
+  }
+}