animader 0.0.0-stage → 0.1.0

package/src/session.js

@@ -0,0 +1,480 @@
+// animader/session - the composed frame contract's JS glue (plan 03,
+// phase 4).
+//
+// `Session` holds one machine and one bridge over a shared
+// `animader.wasm` instance, the host's sinks, an optional score shaped
+// like pacer's public `setControl`/`eval` pair, and the registered
+// consumers. `step(events, now)` executes the frame contract's order:
+//
+//     derived  = union c.derive(events)         ; (input-write ...) records, in memory only
+//     writes_c = union c.eval(now)              ; before the machine steps
+//     m        = machine.step(merge(events, derived), now)
+//     writes_m = bridge.encode(m.outputs)
+//     apply registry 2 of writes_c, writes_m    ; setControl, BEFORE the score
+//     writes_p = score.eval(now)                ; its :expr tracks read the pins
+//     apply registry 0/1 of writes_c            ; raw input first
+//     apply registry 0/1 of writes_m            ; then the machine
+//     apply registry 0/1 of writes_p            ; then the score: later wins
+//     c.emit(writes_c + writes_m + writes_p, now)
+//     host.handle(m.emits)                      ; the machine's emits, last
+//
+// One rule orders it: the more authored a source is, the later it lands.
+// The score and the consumers are the host's, so the sinks are callbacks
+// (`host.setControl`/`setUniform`/`setParam`/`handle`); a recording fake in
+// the tests, a real pngine/audio/pacer host in production.
+//
+// The machine document and the bridge document are separate because the
+// bridge boundary validates against `schema/bridge.sjon` alone: `machine`
+// is the aggregate document, `bridge` its `(output ...)`/`(route ...)`
+// subset in the machine's declaration order.
+//
+// A consumer is `{ derive(records), eval(now), emit(writes, now) }`, all
+// optional; `derive` returns `(input-write ...)` records stamped with the
+// causing record's `:at` (never appended to the log, never re-stamped) and
+// `eval` returns its own 'PACW'. `emit` receives the merged frame's
+// entries in order. Consumers are the JS glue's business because a sibling
+// runtime is its own wasm.
+//
+// The host's `handle(emits)` step is the contract's last: the boundary
+// carries each stepping call's emitted events out as the 'ANME' blob
+// (`anm_machine_emits`, read after every `machine.step`, `setInput` and
+// `fireTrigger`), and this glue concatenates the frame's calls into the
+// one list the native single-step `Machine.step` would have returned,
+// handing it to the host after every consumer's `emit`.
+//
+// The score's `eval` receives the frame's `now` in session microseconds;
+// a pacer-backed score adapter converts to its own seconds (divide by
+// 1e6), because pacer's clock is f64 seconds while this runtime's is i64
+// microseconds.
+
+import { Machine, decodeMeta } from "./machine.js";
+import { decodeWrites, laneValue } from "./route.js";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+const IMPORTS = { env: { sjon_host_invoke_plugin: () => 0 } };
+
+// 'ANEV' (src/Abi.zig): the blob the log parses to.
+const ANEV_MAGIC = 0x56454e41;
+const ANEV_VERSION = 1;
+const ANEV_HEADER_LEN = 20;
+const ANEV_RECORD_LEN = 32;
+const MAX_EVENTS = 1 << 20;
+const NO_STR = 0xffff;
+
+/** Kind ordinals, append-only on the wire (`EventLog.Kind`). */
+const KIND_NAMES = [
+  "resize",
+  "down",
+  "move",
+  "up",
+  "wheel",
+  "key",
+  "custom",
+  "input-write",
+  "mark",
+  "adjust",
+  "reset",
+  "cancel",
+  "derived",
+];
+
+const PACT_MAGIC = 0x54434150;
+const BRIDGE_HANDLE = 1;
+
+const CONTROL_REGISTRY = 2;
+const UNIFORM_REGISTRY = 0;
+const PARAM_REGISTRY = 1;
+
+/** A boundary failure, a diagnosed document or a malformed blob. */
+export class SessionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SessionError";
+  }
+}
+
+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) || value < 0) {
+    throw new SessionError(`animader: ${what} must be a safe, non-negative integer (microseconds), got ${value}`);
+  }
+  return value;
+}
+
+/**
+ * The 'ANEV' decoder this glue needs for `derive`: the same record shape
+ * `Log.decode` answers. Kept local so the module has no import cycle with
+ * `index.js`; the session test pins the same blob through `Log.decode`.
+ *
+ * @param {Uint8Array} bytes
+ * @returns {{ records: Array<object>, strings: string[] }}
+ */
+function decodeEvents(bytes) {
+  if (bytes.byteLength < ANEV_HEADER_LEN) {
+    throw new SessionError(`animader: 'ANEV' blob is ${bytes.byteLength} bytes, under the header`);
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.getUint32(0, true) !== ANEV_MAGIC) throw new SessionError("animader: 'ANEV' magic is missing");
+  if (view.getUint32(4, true) !== ANEV_VERSION) {
+    throw new SessionError(`animader: 'ANEV' version ${view.getUint32(4, true)} is not ${ANEV_VERSION}`);
+  }
+  const count = view.getUint32(8, true);
+  const strtabLen = view.getUint32(12, true);
+  if (count > MAX_EVENTS) throw new SessionError(`animader: 'ANEV' count ${count} over the ceiling`);
+  if (ANEV_HEADER_LEN + count * ANEV_RECORD_LEN + strtabLen !== bytes.byteLength) {
+    throw new SessionError("animader: 'ANEV' length does not match its header");
+  }
+
+  const strings = [];
+  const strtabOff = ANEV_HEADER_LEN + count * ANEV_RECORD_LEN;
+  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 records = [];
+  for (let i = 0; i < count; i++) {
+    const o = ANEV_HEADER_LEN + i * ANEV_RECORD_LEN;
+    const kind = KIND_NAMES[view.getUint8(o + 8)];
+    if (kind === undefined) throw new SessionError(`animader: 'ANEV' record kind ${view.getUint8(o + 8)} is not a Kind`);
+    const at = view.getBigInt64(o, true);
+    if (at < 0n || at > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new SessionError(`animader: 'ANEV' record :at ${at} is outside the writer's domain`);
+    }
+    const strRaw = view.getUint16(o + 18, true);
+    records.push({
+      at: Number(at),
+      kind,
+      ptr: view.getUint8(o + 9),
+      buttons: view.getUint8(o + 10),
+      mods: view.getUint8(o + 11),
+      x: view.getUint16(o + 12, true),
+      y: view.getUint16(o + 14, true),
+      p: view.getUint16(o + 16, true),
+      str: strRaw === NO_STR ? null : (strings[strRaw] ?? null),
+      v: [view.getInt32(o + 20, true), view.getInt32(o + 24, true), view.getInt32(o + 28, true)],
+    });
+  }
+  return { records, strings };
+}
+
+/** pacer's 'PACT' blob for the host join, `{name, ncomp, registry}`. */
+export function encodeTargets(targets) {
+  const names = targets.map((t) => encoder.encode(t.name));
+  let len = 8;
+  for (const n of names) len += 4 + n.length;
+  const blob = new Uint8Array(len);
+  const dv = new DataView(blob.buffer);
+  dv.setUint32(0, PACT_MAGIC, true);
+  dv.setUint32(4, targets.length, true);
+  let pos = 8;
+  targets.forEach((t, i) => {
+    blob[pos] = t.ncomp;
+    blob[pos + 1] = t.registry;
+    dv.setUint16(pos + 2, names[i].length, true);
+    pos += 4;
+    blob.set(names[i], pos);
+    pos += names[i].length;
+  });
+  return blob;
+}
+
+/**
+ * An 'ANEV' blob holding records [start, end) of `blob`, keeping the full
+ * string table so every record's index stays valid (the machine corpus
+ * test's slice, the exact-time seam for derived records).
+ */
+function sliceBlob(blob, start, end) {
+  const view = new DataView(blob.buffer, blob.byteOffset, blob.byteLength);
+  const count = view.getUint32(8, true);
+  const strtabLen = view.getUint32(12, true);
+  const strtabOff = ANEV_HEADER_LEN + count * ANEV_RECORD_LEN;
+  const out = new Uint8Array(ANEV_HEADER_LEN + (end - start) * ANEV_RECORD_LEN + strtabLen);
+  out.set(blob.subarray(0, ANEV_HEADER_LEN), 0);
+  new DataView(out.buffer).setUint32(8, end - start, true);
+  out.set(blob.subarray(ANEV_HEADER_LEN + start * ANEV_RECORD_LEN, ANEV_HEADER_LEN + end * ANEV_RECORD_LEN), ANEV_HEADER_LEN);
+  out.set(blob.subarray(strtabOff, strtabOff + strtabLen), ANEV_HEADER_LEN + (end - start) * ANEV_RECORD_LEN);
+  return out;
+}
+
+/**
+ * Apply every registry-2 entry through `host.setControl`, in wire order.
+ * The third argument is the emitter (`machine`, `score` or `consumer`),
+ * the frame contract's "more authored lands later" tag.
+ */
+function applyControls(entries, host, source) {
+  if (typeof host.setControl !== "function") return;
+  for (const entry of entries) {
+    if (entry.registry !== CONTROL_REGISTRY) continue;
+    host.setControl(entry.targetId, laneValue(entry), source);
+  }
+}
+
+/** Apply registries 0 and 1 through `host.setUniform`/`host.setParam`. */
+function applyValues(entries, host, source) {
+  for (const entry of entries) {
+    if (entry.registry === UNIFORM_REGISTRY) {
+      if (typeof host.setUniform === "function") host.setUniform(entry.targetId, laneValue(entry), source);
+    } else if (entry.registry === PARAM_REGISTRY) {
+      if (typeof host.setParam === "function") host.setParam(entry.targetId, laneValue(entry), source);
+    }
+  }
+}
+
+/** The composed session over one artifact instance. */
+export class Session {
+  #e;
+  #machine;
+  #bridgeHandle = 0;
+  #host;
+  #score;
+  #consumers = [];
+  #inputKinds = new Map();
+
+  /**
+   * Instantiate the artifact synchronously (node, tests).
+   * @param {BufferSource} bytes
+   * @param {object} opts see the constructor
+   * @returns {Session}
+   */
+  static loadSync(bytes, opts) {
+    return new Session(new WebAssembly.Instance(new WebAssembly.Module(bytes), IMPORTS), opts);
+  }
+
+  /**
+   * Instantiate the artifact from bytes or a compiled module (browser).
+   * @param {BufferSource | WebAssembly.Module} source
+   * @param {object} opts see the constructor
+   * @returns {Promise<Session>}
+   */
+  static async load(source, opts) {
+    const instance =
+      source instanceof WebAssembly.Module
+        ? await WebAssembly.instantiate(source, IMPORTS)
+        : (await WebAssembly.instantiate(source, IMPORTS)).instance;
+    return new Session(instance, opts);
+  }
+
+  /**
+   * @param {WebAssembly.Instance} instance one animader.wasm instance,
+   *   shared by the machine and the bridge (one of each per instance, the
+   *   module-global caches).
+   * @param {object} opts
+   * @param {string} opts.machine the machine document (the machine + bridge
+   *   aggregate)
+   * @param {string} opts.bridge the `(output ...)`/`(route ...)` subset,
+   *   in the machine's declaration order (the bridge boundary validates
+   *   against the bridge manifest alone)
+   * @param {Array<{name: string, ncomp: number, registry: number}>} opts.targets
+   *   the host join in target_id order
+   * @param {number} [opts.registryCount] the host's registry count
+   * @param {object} [opts.host] `{ setControl, setUniform, setParam }`
+   * @param {object | null} [opts.score] pacer's pair: `setControl(id, value)`
+   *   and `eval(now)` returning 'PACW'
+   * @param {Array<object>} [opts.consumers]
+   */
+  constructor(instance, opts = {}) {
+    const { machine, bridge, targets, registryCount = 0, host = {}, score = null, consumers = [] } = opts;
+    if (typeof machine !== "string" || typeof bridge !== "string") {
+      throw new SessionError("animader: session needs the machine and bridge documents");
+    }
+    if (!Array.isArray(targets) || targets.length === 0) {
+      throw new SessionError("animader: session needs the host's target join");
+    }
+    this.#e = instance.exports;
+    this.#host = host;
+    this.#score = score;
+    this.#machine = new Machine(instance, machine);
+    this.#inputKinds = new Map(decodeMeta(this.#machine.meta()).inputs.map((i) => [i.name, i.kind]));
+    this.#loadBridge(bridge, targets, registryCount);
+    for (const consumer of consumers) this.registerConsumer(consumer);
+  }
+
+  /** Register one consumer, in call order. @param {object} consumer @returns {Session} */
+  registerConsumer(consumer) {
+    if (consumer === null || typeof consumer !== "object") {
+      throw new SessionError("animader: a consumer must be an object");
+    }
+    this.#consumers.push(consumer);
+    return this;
+  }
+
+  /** The loaded machine, for a host that needs its meta or snapshot. */
+  get machine() {
+    return this.#machine;
+  }
+
+  /**
+   * One frame: the frame's drained records as an 'ANEV' blob (or null for
+   * an empty batch) and the frame's `now` in session microseconds.
+   * @param {Uint8Array | ArrayBuffer | null} events
+   * @param {number} now
+   * @returns {Session}
+   */
+  step(events, now) {
+    const at = micros(now, "now");
+    const bytes = events === null || events === undefined ? null : toBytes(events);
+    const records = bytes === null ? [] : decodeEvents(bytes).records;
+
+    // 1. The consumers' derived records, in registration order, then the
+    // stable merge by :at (consumer order on ties).
+    const derived = [];
+    for (const consumer of this.#consumers) {
+      if (typeof consumer.derive !== "function") continue;
+      for (const record of consumer.derive(records)) {
+        if (record.kind !== "input-write") {
+          throw new SessionError(
+            `animader: a consumer's derived record must be an (input-write ...) record, got ${record.kind}`,
+          );
+        }
+        if (!Number.isSafeInteger(record.at) || record.at < 0 || record.at > at) {
+          throw new SessionError(`animader: a derived record's :at ${record.at} is outside 0..now`);
+        }
+        derived.push(record);
+      }
+    }
+    const ordered = derived
+      .map((record, i) => [record, i])
+      .sort((a, b) => a[0].at - b[0].at || a[1] - b[1])
+      .map(([record]) => record);
+
+    // 2. The consumers' own writes, before the machine steps.
+    const consumerWrites = this.#consumers.map((consumer) => {
+      if (typeof consumer.eval !== "function") return [];
+      const blob = consumer.eval(at);
+      return blob === null || blob === undefined ? [] : decodeWrites(toBytes(blob));
+    });
+
+    // 3. The machine: the log's records and the derived ones, merged by :at
+    // (the log first on ties), applied at their exact times. The frame's
+    // emits are the concatenation of every stepping call the exact-time
+    // seam makes, in order.
+    const machineEmits = this.#stepMachine(bytes, records, ordered, at);
+
+    // 4. The machine's values as pacer's 'PACW'.
+    const machineWrites = this.#encodeMachine();
+
+    // 5. Registry 2: consumers, then the machine, before the score. The
+    // score owns the pins (pacer's `setControl`); a scoreless host may
+    // still take them through its own `setControl`.
+    for (const writes of consumerWrites) this.#applyControls(writes, "consumer");
+    this.#applyControls(machineWrites, "machine");
+
+    // 6. The score, whose :expr tracks read the pins just landed.
+    let scoreWrites = [];
+    if (this.#score !== null && typeof this.#score.eval === "function") {
+      const blob = this.#score.eval(at);
+      if (blob !== null && blob !== undefined) scoreWrites = decodeWrites(toBytes(blob));
+    }
+
+    // 7. Registries 0/1: consumers, then the machine, then the score.
+    for (const writes of consumerWrites) applyValues(writes, this.#host, "consumer");
+    applyValues(machineWrites, this.#host, "machine");
+    applyValues(scoreWrites, this.#host, "score");
+
+    // 8. Each consumer reads the merged frame.
+    const merged = [...consumerWrites.flat(), ...machineWrites, ...scoreWrites];
+    for (const consumer of this.#consumers) {
+      if (typeof consumer.emit === "function") consumer.emit(merged.slice(), at);
+    }
+
+    // 9. The contract's last step: the machine's emitted events go to the
+    // host, never to a log.
+    if (typeof this.#host.handle === "function") this.#host.handle(machineEmits);
+    return this;
+  }
+
+  /** Registry-2 entries: the score's pins, or the host's control sink. */
+  #applyControls(entries, source) {
+    const score = this.#score;
+    const sink = score !== null && typeof score.setControl === "function" ? score : this.#host;
+    applyControls(entries, sink, source);
+  }
+
+  #loadBridge(text, targets, registryCount) {    const e = this.#e;
+    const pact = encodeTargets(targets);
+    const doc = encoder.encode(text);
+    if (pact.length + doc.length > e.anm_log_inCap()) {
+      throw new SessionError("animader: the bridge inputs do not fit the module's input zone");
+    }
+    new Uint8Array(e.memory.buffer, e.anm_log_inPtr(), pact.length).set(pact);
+    new Uint8Array(e.memory.buffer, e.anm_log_inPtr() + pact.length, doc.length).set(doc);
+    const status = e.anm_bridge_load(pact.length, doc.length, registryCount);
+    if (status !== BRIDGE_HANDLE) {
+      throw new SessionError(
+        `animader: the bridge join failed (status ${status}); check the documents and the target join`,
+      );
+    }
+    this.#bridgeHandle = status;
+  }
+
+  #encodeMachine() {
+    const e = this.#e;
+    const outputs = this.#machine.outputs();
+    const len = outputs.length * 16;
+    if (len > e.anm_log_inCap()) throw new SessionError("animader: the machine's values do not fit the input zone");
+    const view = new DataView(e.memory.buffer, e.anm_log_inPtr(), len);
+    for (const output of outputs) {
+      const off = output.index * 16;
+      for (let lane = 0; lane < 4; lane++) view.setFloat32(off + lane * 4, output.value[lane], true);
+    }
+    const status = e.anm_bridge_encode(this.#bridgeHandle, len);
+    if (status < 0) {
+      throw new SessionError(
+        `animader: the bridge encode failed (status ${status}); the bridge document must list the machine's outputs in order`,
+      );
+    }
+    return decodeWrites(new Uint8Array(e.memory.buffer, e.anm_log_outPtr(), status).slice());
+  }
+
+  /**
+   * The machine's exact-time walk over the frame's records and derived
+   * inputs, returning every stepping call's emits concatenated in order:
+   * the one list a native single-step `Machine.step` would have returned.
+   */
+  #stepMachine(bytes, records, derived, at) {
+    const emits = [];
+    if (derived.length === 0) {
+      this.#machine.step(bytes, at);
+      emits.push(...this.#machine.emits());
+      return emits;
+    }
+    let cursor = 0;
+    for (const record of derived) {
+      let end = cursor;
+      while (end < records.length && records[end].at <= record.at) end += 1;
+      this.#machine.step(end > cursor ? sliceBlob(bytes, cursor, end) : null, record.at);
+      emits.push(...this.#machine.emits());
+      this.#applyInput(record);
+      emits.push(...this.#machine.emits());
+      cursor = end;
+    }
+    this.#machine.step(cursor < records.length ? sliceBlob(bytes, cursor, records.length) : null, at);
+    emits.push(...this.#machine.emits());
+    return emits;
+  }
+
+  #applyInput(record) {
+    const kind = this.#inputKinds.get(record.name);
+    if (kind === "trigger") {
+      this.#machine.fireTrigger(record.name);
+    } else {
+      const lane0 = Array.isArray(record.v) || (record.v && typeof record.v.length === "number") ? record.v[0] ?? 0 : 0;
+      this.#machine.setInput(record.name, lane0 | 0);
+    }
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.