animader 0.0.0-stage → 0.1.1

package/src/piece.js

@@ -0,0 +1,222 @@
+// animader - the piece boundary's JS glue (road step 5).
+//
+// `PieceHost` drives the `anm_piece_*` exports of animader.wasm over one
+// instance, mirroring the log tier's zone convention byte for byte: the
+// host writes the document (and, for `golden`, the `(times ...)` text
+// after it) into `exports.anm_log_inPtr()`, calls the export, and reads
+// `anm_log_outLen()` bytes from `anm_log_outPtr()`. Memory views are
+// re-taken on every call (the pacer discipline: a view taken before a
+// grow would detach; these zones never grow, but the glue does not rely
+// on that).
+//
+// The aggregate a wasm host validates is the loader's own default
+// preload (the piece, world, session, machine and bridge manifests,
+// plus tempura's four-manifest bundle since the timeline landed,
+// embedded) plus whatever sibling manifests the host supplies through
+// `preload()`: pngine's for one with an authored program, any other
+// plugin's for a sidecar. A wasm boundary cannot read a checkout, so
+// the host is the one that resolves it; the seats are named
+// (`PIECE_PACER`, `PIECE_PNGINE`, `PIECE_OTHER`) for the placement
+// table's sake, and `PIECE_PACER` is a closed seat: pacer's manifest
+// is embedded inside tempura's bundle, so preloading it is refused by
+// the boundary rather than loaded as a second plugin named pacer.
+//
+// `golden(docText, timesText)` answers the piece corpus golden, the
+// SAME text `src/piece_runner.zig` renders natively: one rendering,
+// two executors, and native agreeing with wasm32 on one golden is the
+// determinism proof. `score(docText)` answers the piece's score text
+// alone, the same bytes that golden's `(score ...)` row hashes: the
+// identity lowering, the authored score, or the timeline's derived
+// export, whichever the aggregate carries. `scoreMap(docText)` answers
+// the spelling of time the piece carries and the map it came with: the
+// timeline spelling's derived score's position map (tempura's T1
+// `'TPMP'` record), the identity spelling's own state (named by the
+// identity table's row), or the authored-score spelling's own state
+// (its positions are its literal roots), never one bare null for both
+// no-timeline spellings. The two calls run the same load switch, so the
+// map's text spans index exactly the score bytes `score` returns. The
+// status convention is the entry's: a negative is a status, never data.
+
+export const PIECE_OTHER = 0;
+export const PIECE_PACER = 1;
+export const PIECE_PNGINE = 2;
+
+/** `anm_piece_score_map`'s two no-map states, mirrored from the entry.
+ * Distinct because the two no-timeline spellings are; a `'TPMP'` blob
+ * is never one byte. */
+export const PIECE_MAP_IDENTITY = 0;
+export const PIECE_MAP_AUTHORED = 1;
+
+/** The three spellings of time `scoreMap` names (05-model.md's three). */
+export const SPELLING_TIMELINE = "timeline";
+export const SPELLING_IDENTITY = "identity";
+export const SPELLING_AUTHORED = "authored";
+
+const IMPORTS = { env: { sjon_host_invoke_plugin: () => 0 } };
+
+const ERRORS = new Map([
+  [-1, "diagnosed load"],
+  [-2, "bad call"],
+  [-3, "out of memory"],
+  [-4, "output over its zone"],
+]);
+
+export class PieceHost {
+  /** @param {WebAssembly.Instance} instance one animader.wasm instance */
+  constructor(instance) {
+    this.instance = instance;
+    this.exports = instance.exports;
+  }
+
+  /** Instantiate from bytes or a module. */
+  static async instantiate(source) {
+    const result =
+      source instanceof WebAssembly.Module
+        ? await WebAssembly.instantiate(source, IMPORTS)
+        : (await WebAssembly.instantiate(source, IMPORTS)).instance;
+    return new PieceHost(result);
+  }
+
+  /** One manifest text into one seat; answers the stored count. */
+  preload(manifestText, kind = PIECE_OTHER) {
+    const bytes = typeof manifestText === "string"
+      ? new TextEncoder().encode(manifestText)
+      : manifestText;
+    const cap = this.exports.anm_log_inCap();
+    if (bytes.length > cap) throw new Error(`animader: manifest over the in zone (${bytes.length} > ${cap})`);
+    new Uint8Array(this.exports.memory.buffer, this.exports.anm_log_inPtr(), bytes.length).set(bytes);
+    const status = this.exports.anm_piece_preload(bytes.length, kind);
+    if (status < 0) throw new Error(`animader: anm_piece_preload failed: ${ERRORS.get(status) ?? status}`);
+    return status;
+  }
+
+  /** Drop every preloaded sibling manifest. */
+  reset() {
+    this.exports.anm_piece_reset();
+  }
+
+  /** The stored-manifest count. */
+  get extraCount() {
+    return this.exports.anm_piece_extraCount();
+  }
+
+  /**
+   * The piece corpus golden: the aggregate document and the
+   * `(times ...)` text in, the golden bytes out as a string.
+   */
+  golden(docText, timesText) {
+    const doc = new TextEncoder().encode(docText);
+    const times = new TextEncoder().encode(timesText);
+    const cap = this.exports.anm_log_inCap();
+    if (doc.length + times.length > cap) {
+      throw new Error(`animader: document plus times over the in zone (${doc.length + times.length} > ${cap})`);
+    }
+    const inZone = new Uint8Array(this.exports.memory.buffer, this.exports.anm_log_inPtr(), doc.length + times.length);
+    inZone.set(doc, 0);
+    inZone.set(times, doc.length);
+    const status = this.exports.anm_piece_golden(doc.length, times.length);
+    if (status < 0) throw new Error(`animader: anm_piece_golden failed: ${ERRORS.get(status) ?? status}`);
+    const out = new Uint8Array(this.exports.memory.buffer, this.exports.anm_log_outPtr(), status);
+    return new TextDecoder().decode(out);
+  }
+
+  /**
+   * The piece's score text: the identity lowering, the authored score
+   * (a file's bytes or the aggregate's own roots), or the timeline's
+   * derived export, whichever spelling of time the aggregate carries.
+   * The same load `golden` renders and the same switch its `(score ...)`
+   * row reads, so a host compiles exactly the bytes the corpus hashed.
+   */
+  score(docText) {
+    const doc = new TextEncoder().encode(docText);
+    const cap = this.exports.anm_log_inCap();
+    if (doc.length > cap) {
+      throw new Error(`animader: document over the in zone (${doc.length} > ${cap})`);
+    }
+    new Uint8Array(this.exports.memory.buffer, this.exports.anm_log_inPtr(), doc.length).set(doc);
+    const status = this.exports.anm_piece_score(doc.length);
+    if (status < 0) throw new Error(`animader: anm_piece_score failed: ${ERRORS.get(status) ?? status}`);
+    const out = new Uint8Array(this.exports.memory.buffer, this.exports.anm_log_outPtr(), status);
+    return new TextDecoder().decode(out);
+  }
+
+  /**
+   * The piece's spelling of time and the map it came with: a
+   * `{ spelling, map }` pair. `spelling` is `SPELLING_TIMELINE`,
+   * `SPELLING_IDENTITY` or `SPELLING_AUTHORED`. `map` is the decoded
+   * `'TPMP'` record (one entry per emitted position, `text` a byte span
+   * into the score `score()` answers for the same document, `doc` the
+   * document spans it came from) for the timeline spelling, and null for
+   * the two no-timeline spellings: the identity's positions are named by
+   * the identity table's own row, the authored score's by its own
+   * literal roots, and the distinct states say which. The two calls are
+   * deterministic over the same document and run the same load switch,
+   * so the map's text spans index exactly the score bytes `score()`
+   * returns.
+   *
+   * @returns {{ spelling: string, map: { entries: Array<{ text: [number, number], doc: Array<[number, number]> }> } | null }}
+   */
+  scoreMap(docText) {
+    const doc = new TextEncoder().encode(docText);
+    const cap = this.exports.anm_log_inCap();
+    if (doc.length > cap) {
+      throw new Error(`animader: document over the in zone (${doc.length} > ${cap})`);
+    }
+    new Uint8Array(this.exports.memory.buffer, this.exports.anm_log_inPtr(), doc.length).set(doc);
+    const status = this.exports.anm_piece_score_map(doc.length);
+    if (status === PIECE_MAP_IDENTITY) return { spelling: SPELLING_IDENTITY, map: null };
+    if (status === PIECE_MAP_AUTHORED) return { spelling: SPELLING_AUTHORED, map: null };
+    if (status < 0) throw new Error(`animader: anm_piece_score_map failed: ${ERRORS.get(status) ?? status}`);
+    const bytes = new Uint8Array(this.exports.memory.buffer, this.exports.anm_piece_mapPtr(), status).slice();
+    return { spelling: SPELLING_TIMELINE, map: decodeMap(bytes) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The 'TPMP' position map, tempura's T1 record
+// ---------------------------------------------------------------------------
+
+/** `"TPMP"` read little-endian. */
+export const MAP_MAGIC = 0x504d5054;
+export const MAP_VERSION = 1;
+
+const MAP_HEADER_LEN = 12;
+const MAP_RECORD_LEN = 12;
+const MAP_SPAN_LEN = 8;
+
+/**
+ * Decode a `'TPMP'` blob, what `anm_piece_score_map` wrote (tempura's
+ * `TprAbi.encodeMap`, the same record tempura's own `decodeMap` reads).
+ * One entry per emitted position, in emission order: `text` is a
+ * `[start, end]` byte span into the score text, `doc` an array of
+ * `[start, end]` byte spans into the document the derivation read, one
+ * per document node the position came from, several when the exporter's
+ * arithmetic merged sources. A malformed blob throws rather than
+ * answering a shorter map.
+ */
+export function decodeMap(bytes) {
+  if (bytes.length < MAP_HEADER_LEN) throw new Error("animader: map blob too short");
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const magic = dv.getUint32(0, true);
+  if (magic !== MAP_MAGIC) throw new Error(`animader: map magic ${magic.toString(16)}, not 'TPMP'`);
+  const version = dv.getUint32(4, true);
+  if (version !== MAP_VERSION) throw new Error(`animader: map version ${version}, not ${MAP_VERSION}`);
+  const count = dv.getUint32(8, true);
+  const entries = [];
+  let off = MAP_HEADER_LEN;
+  for (let i = 0; i < count; i++) {
+    if (off + MAP_RECORD_LEN > bytes.length) throw new Error("animader: map blob truncated at an entry");
+    const text = [dv.getUint32(off, true), dv.getUint32(off + 4, true)];
+    const docCount = dv.getUint32(off + 8, true);
+    off += MAP_RECORD_LEN;
+    if (off + docCount * MAP_SPAN_LEN > bytes.length) throw new Error("animader: map blob truncated at a document span");
+    const doc = [];
+    for (let j = 0; j < docCount; j++) {
+      doc.push([dv.getUint32(off, true), dv.getUint32(off + 4, true)]);
+      off += MAP_SPAN_LEN;
+    }
+    entries.push({ text, doc });
+  }
+  if (off !== bytes.length) throw new Error("animader: map blob carries trailing bytes");
+  return { entries };
+}

package/src/route.js

@@ -0,0 +1,116 @@
+// The bridge's JS routing (plan 03, phase 2): pacer's 'PACW' buffer in,
+// its entries split by registry in pacer's `npm/pacer/src/route.js`
+// shape, with registry 2 applied through pacer's `setControl` before
+// pacer evaluates (the frame-contract rule: a control pin outranks every
+// other write).
+//
+// The entries carry no names: the wire is ids only, so `targetId` is the
+// host's flat target join index and a consumer resolves names itself.
+// `laneValue` is pacer's `lane.js` shape: a scalar target hands a
+// number, a multi-lane target an array.
+//
+// Registry 2 is the pacer control-pin registry; registries 0 (pngine
+// uniforms) and 1 (audio params) are the host's to land.
+
+const MAGIC = 0x57434150; // 'PACW' read little-endian
+const VERSION = 1;
+const HEADER_LEN = 12;
+const ENTRY_LEN = 20;
+/** The registry a machine value rides to reach a pacer control pin. */
+export const CONTROL_REGISTRY = 2;
+
+/**
+ * Decode one 'PACW' buffer into write entries, in wire order:
+ * `{ targetId, registry, ncomp, value: Float32Array(4) }`. Throws on a
+ * corrupt buffer (bad magic or version, a length that is not exactly
+ * header plus count entries). Pacer's own decoders tolerate trailing
+ * bytes (`Writes.decode` checks the buffer is at least the encoded
+ * length; pacer's JS `#decodeWrites` reads `count` entries whatever the
+ * length); this module is stricter on purpose, because the bridge emits
+ * this buffer and a length mismatch is a bug worth failing loudly.
+ *
+ * @param {Uint8Array} bytes
+ * @returns {Array<{targetId: number, registry: number, ncomp: number, value: Float32Array}>}
+ */
+export function decodeWrites(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.byteLength < HEADER_LEN) {
+    throw new Error(
+      `animader: 'PACW' buffer is ${view.byteLength} bytes, short of the ${HEADER_LEN}-byte header`,
+    );
+  }
+  if (view.getUint32(0, true) !== MAGIC) {
+    throw new Error("animader: 'PACW' magic is missing");
+  }
+  if (view.getUint32(4, true) !== VERSION) {
+    throw new Error(`animader: 'PACW' version ${view.getUint32(4, true)} is not ${VERSION}`);
+  }
+  const count = view.getUint32(8, true);
+  if (HEADER_LEN + count * ENTRY_LEN !== view.byteLength) {
+    throw new Error("animader: 'PACW' length does not match its header (truncated or trailing bytes)");
+  }
+
+  const entries = [];
+  for (let i = 0; i < count; i++) {
+    const off = HEADER_LEN + i * ENTRY_LEN;
+    const value = new Float32Array(4);
+    for (let c = 0; c < 4; c++) value[c] = view.getFloat32(off + 4 + c * 4, true);
+    entries.push({
+      targetId: view.getUint16(off, true),
+      registry: view.getUint8(off + 2),
+      ncomp: view.getUint8(off + 3),
+      value,
+    });
+  }
+  return entries;
+}
+
+/**
+ * Group entries by registry index: `groups[registry]` is the entries in
+ * wire order, borrowing the same objects (pacer's `routeWrites` shape).
+ * An entry whose registry is at or above `registryCount` is dropped.
+ *
+ * @param {ReadonlyArray<{registry: number}>} entries
+ * @param {number} registryCount Number of registries (the length of `groups`).
+ * @returns {Array<Array<object>>}
+ */
+export function routeWrites(entries, registryCount) {
+  const groups = Array.from({ length: registryCount }, () => []);
+  for (const entry of entries) {
+    const group = groups[entry.registry];
+    if (group !== undefined) group.push(entry);
+  }
+  return groups;
+}
+
+/**
+ * One entry's value as a host wants it: a bare number for a scalar
+ * target, else a plain array of its live lanes (pacer's `laneValue`).
+ *
+ * @param {{ncomp: number, value: Float32Array}} entry
+ * @returns {number | number[]}
+ */
+export function laneValue(entry) {
+  return entry.ncomp === 1 ? entry.value[0] : Array.from(entry.value.subarray(0, entry.ncomp));
+}
+
+/**
+ * Apply every registry-2 entry through `setControl(targetId, value)`, in
+ * wire order. The frame contract calls this before `pacer.eval`, so a
+ * control pin is in the score's expression environment for the frame
+ * that produced it. Returns how many pieces were handed over; whether a
+ * host accepted one is `setControl`'s own return, the host's business.
+ *
+ * @param {ReadonlyArray<{targetId: number, registry: number, ncomp: number, value: Float32Array}>} entries
+ * @param {(id: number, value: number | number[]) => unknown} setControl
+ * @returns {number}
+ */
+export function applyControls(entries, setControl) {
+  let applied = 0;
+  for (const entry of entries) {
+    if (entry.registry !== CONTROL_REGISTRY) continue;
+    setControl(entry.targetId, laneValue(entry));
+    applied += 1;
+  }
+  return applied;
+}