animader-cli 0.0.0-stage → 0.1.1

package/lib/score.mjs

@@ -0,0 +1,434 @@
+// The demo's portable score/run composition (M1 slice 2). One load walks
+// the real stages a show needs before it can be READY: the piece boundary
+// derives the score from the document's inline roots (`PieceHost.score`,
+// never a second reader), the target join is the compiled program's own
+// reflection (`buildJoin` by import, so a target the program does not
+// declare is refused by the compile instead of drifting with a hand
+// list), pacer compiles the derived bytes against exactly that one
+// visual registry, and the compiled metadata is audited so automation
+// the hosted buses cannot take is refused — never silently dropped.
+//
+// Every producer is an injected port (`factories.instantiatePieceHost` /
+// `factories.loadPacer`, shaped like `PieceHost.instantiate` and
+// `Pacer.load`), so this module carries no `node:` import, no process
+// state and no DOM, and the same decisions run in a page, a headless
+// test or a future host. Failures are `ShowError`s: a stable `code`, the
+// `stage` that failed, the `document` name and the producer's own
+// `diagnostics`, so a caller reports causes instead of guessing them.
+//
+// Ownership: stage order, the single-registry join policy, the
+// never-drop audit, the structured error shape. WASM bytes, reflection
+// and IO belong to the host adapters.
+
+import { buildJoin } from '../hello/join.js';
+
+/** The stages `loadShow` walks, in order. */
+export const SHOW_STAGES = Object.freeze([
+  'piece_host',
+  'derive_score',
+  'reflect',
+  'compile',
+  'audit',
+]);
+
+/**
+ * One structured show failure. `code` names the decision, `stage` the
+ * step that failed, `document` the piece document's name and
+ * `diagnostics` the producer's own answer (pacer 'PACD' records for a
+ * refused compile; show audit records for unhosted automation).
+ */
+export class ShowError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   * @param {{stage?: string, document?: string, diagnostics?: Array<object>, cause?: unknown}} [detail]
+   */
+  constructor(code, message, { stage = '', document = '', diagnostics = [], cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'ShowError';
+    this.code = code;
+    this.stage = stage;
+    this.document = document;
+    this.diagnostics = diagnostics;
+  }
+}
+
+/** The one failure shape for a missing or malformed port. */
+function portError(loader, what) {
+  return new TypeError(`${loader} needs ${what}`);
+}
+
+/** `name`, or a sentence for a target the score declared but never named for the host. */
+function named(name) {
+  return name === null || name === undefined ? 'an unnamed declared target' : `'${name}'`;
+}
+
+/** The diagnostics' own messages, for the error text. */
+function messagesOf(diagnostics) {
+  const messages = (Array.isArray(diagnostics) ? diagnostics : [])
+    .filter((entry) => entry && typeof entry.message === 'string')
+    .map((entry) => entry.message);
+  return messages.length > 0 ? messages.join('; ') : 'no diagnostics were answered';
+}
+
+/**
+ * The reflection stage shared by both score spellings: validate the
+ * compiled program's own table, join exactly the targets it can carry,
+ * then refuse an empty target list before any compile runs.
+ */
+export function reflectedJoin(reflection, name) {
+  // The join is the reflection's own target list, in its table order; an
+  // empty one means the program declares nothing a score can address. A
+  // malformed field is a named reflection failure, never a guessed target.
+  for (const [fieldName, field] of Object.entries(reflection)) {
+    if (!field || typeof field !== 'object' || typeof field.type !== 'string' || field.type === '') {
+      throw new ShowError(
+        'bad_reflection',
+        `${name}'s reflected field '${fieldName}' has no WGSL type, so the score join cannot be built`,
+        { stage: 'reflect', document: name },
+      );
+    }
+    if (field.elemCount !== undefined && !Number.isInteger(field.elemCount)) {
+      throw new ShowError(
+        'bad_reflection',
+        `${name}'s reflected field '${fieldName}' has a non-integer elemCount (${String(field.elemCount)})`,
+        { stage: 'reflect', document: name },
+      );
+    }
+  }
+  let join;
+  try {
+    join = buildJoin(reflection);
+  } catch (cause) {
+    throw new ShowError(
+      'bad_reflection',
+      `${name}'s reflected fields could not be joined: ${cause?.message ?? cause}`,
+      { stage: 'reflect', document: name, cause },
+    );
+  }
+  if (join.length === 0) {
+    throw new ShowError(
+      'no_score_targets',
+      `the compiled program reflects no score targets for ${name}, so there is no registry to join`,
+      { stage: 'reflect', document: name },
+    );
+  }
+  return join;
+}
+
+/**
+ * The compile and audit stages shared by both score spellings. The score
+ * bytes are already final here: `loadShow` derived them, `loadDerivedShow`
+ * received them from the export. Returns exactly the public load result.
+ */
+async function compileShow({ name, score, reflection, pacerWasm, factories }) {
+  const join = reflectedJoin(reflection, name);
+
+  let driver;
+  try {
+    // Keep the receiver the old load handed to its port: callers may pass a
+    // method rather than a bare function, and the compile stage must not
+    // change its `this`.
+    driver = await factories.loadPacer(pacerWasm, score, { registries: [join] });
+  } catch (cause) {
+    throw new ShowError(
+      'pacer_load_failed',
+      `the score compile failed for ${name}: ${cause?.message ?? cause}`,
+      { stage: 'compile', document: name, cause },
+    );
+  }
+  if (!driver.ok) {
+    throw new ShowError(
+      'score_refused',
+      `${name}'s derived score was refused by the compile: ${messagesOf(driver.diagnostics)}`,
+      { stage: 'compile', document: name, diagnostics: Array.isArray(driver.diagnostics) ? driver.diagnostics : [] },
+    );
+  }
+
+  // The metadata is the driver's own public answer ('PACM' through the
+  // `meta` getter), read once here — never reconstructed or guessed.
+  const meta = driver.meta;
+  if (meta === null || meta === undefined) {
+    throw new ShowError(
+      'metadata_unavailable',
+      `the compiled driver answered no metadata for ${name}`,
+      { stage: 'audit', document: name },
+    );
+  }
+
+  auditMeta(name, meta);
+
+  return { documentName: name, score, join, driver, meta };
+}
+
+/**
+ * The never-drop audit shared by both score spellings. This show hosts one
+ * registry (the visual bus), so a track or control the metadata places on
+ * any other bus — or a declared-only target with no host name, which a
+ * by-name fold cannot key — would be dropped by the route pair's own rules.
+ * Refuse it with the metadata's own names; a compile's unknown-target
+ * diagnostics have already refused everything addressable before this point.
+ */
+function auditMeta(name, meta) {
+  const buses = 1;
+  const audit = [];
+  for (const track of meta.tracks ?? []) {
+    if (track.name === null || track.name === undefined || track.registry >= buses) {
+      audit.push({
+        source: 'show',
+        severity: 'error',
+        code: 0,
+        start: track.span?.start ?? 0,
+        end: track.span?.end ?? 0,
+        message: `track ${named(track.name)} automates registry ${track.registry}, which this show does not host`,
+      });
+    }
+  }
+  for (const control of meta.controls ?? []) {
+    if (control.registry >= buses) {
+      audit.push({
+        source: 'show',
+        severity: 'error',
+        code: 0,
+        start: control.valueSpan?.start ?? 0,
+        end: control.valueSpan?.end ?? 0,
+        message: `control ${named(control.name ?? control.id)} pins registry ${control.registry}, which this show does not host`,
+      });
+    }
+  }
+  if (audit.length > 0) {
+    throw new ShowError(
+      'unsupported_automation',
+      `${name} automates targets outside the ${buses} hosted registrie${buses === 1 ? '' : 's'} (${messagesOf(audit)}); automation is never dropped`,
+      { stage: 'audit', document: name, diagnostics: audit },
+    );
+  }
+}
+
+/**
+ * Compose one show's score run from injected producers.
+ *
+ * @param {object} options
+ * @param {{name: string, text: string}} options.document
+ *   the piece document (the inline-roots aggregate) and its name, kept
+ *   by every failure.
+ * @param {object} options.dep
+ * @param {WebAssembly.Module|BufferSource} options.dep.pieceWasm animader.wasm.
+ * @param {WebAssembly.Module|BufferSource} options.dep.pacerWasm pacer.wasm.
+ * @param {Object<string, {type: string, elemCount: number}>} options.dep.reflection
+ *   the compiled program's reflected fields, as its own public
+ *   reflection reports them (`getUniforms`'s parsed answer).
+ * @param {object} options.factories
+ * @param {(wasm: WebAssembly.Module|BufferSource) => Promise<{score(text: string): string}>} options.factories.instantiatePieceHost
+ * @param {(wasm: WebAssembly.Module|BufferSource, score: string, options: {registries: Array<Array<{name: string, ncomp: number}>>}) => Promise<{ok: boolean, diagnostics: Array<object>, meta: object}>} options.factories.loadPacer
+ * @returns {Promise<{documentName: string, score: string, join: Array<{name: string, ncomp: number}>, driver: object, meta: object}>}
+ *   the derived score, the reflected join, the compiled driver and the
+ *   driver's own public metadata. A failed load throws before any of
+ *   this is handed out, so nothing half-loaded escapes to be reused.
+ */
+export async function loadShow({ document, dep, factories }) {
+  if (!document
+    || typeof document.name !== 'string'
+    || document.name === ''
+    || typeof document.text !== 'string'
+    || document.text === '') {
+    throw portError('loadShow', 'document.name and a non-empty document.text (the inline-roots aggregate)');
+  }
+  if (!factories || typeof factories.instantiatePieceHost !== 'function' || typeof factories.loadPacer !== 'function') {
+    throw portError('loadShow', 'factories.instantiatePieceHost and factories.loadPacer (the PieceHost.instantiate and Pacer.load shapes)');
+  }
+  if (!dep || dep.pieceWasm === undefined || dep.pieceWasm === null
+    || dep.pacerWasm === undefined || dep.pacerWasm === null
+    || typeof dep.reflection !== 'object' || dep.reflection === null) {
+    throw portError('loadShow', 'dep.pieceWasm, dep.pacerWasm and dep.reflection (the compiled program\'s reflected fields)');
+  }
+
+  const name = document.name;
+
+  let host;
+  try {
+    host = await factories.instantiatePieceHost(dep.pieceWasm);
+  } catch (cause) {
+    throw new ShowError(
+      'piece_host_failed',
+      `the piece boundary could not be instantiated for ${name}: ${cause?.message ?? cause}`,
+      { stage: 'piece_host', document: name, cause },
+    );
+  }
+
+  let score;
+  try {
+    score = host.score(document.text);
+  } catch (cause) {
+    throw new ShowError(
+      'derive_failed',
+      `the piece boundary refused ${name}: ${cause?.message ?? cause}`,
+      { stage: 'derive_score', document: name, cause },
+    );
+  }
+  if (typeof score !== 'string' || score === '') {
+    throw new ShowError(
+      'empty_score',
+      `the piece boundary answered an empty score for ${name}`,
+      { stage: 'derive_score', document: name },
+    );
+  }
+
+  return compileShow({
+    name,
+    score,
+    reflection: dep.reflection,
+    pacerWasm: dep.pacerWasm,
+    factories,
+  });
+}
+
+/**
+ * Compose the same show run from a score already derived at export time.
+ * The release page has no PieceHost and no compiler: the bytes it compiles
+ * are the export's actual `PieceHost.score` answer, and the reflection is
+ * the prepared program's own live `getUniforms` table (or, in Node export
+ * verification, the same table parsed from the baked payload).
+ *
+ * @param {object} options
+ * @param {{name: string, text: string}} options.document
+ *   the derived score document and the name every failure keeps.
+ * @param {object} options.dep
+ * @param {WebAssembly.Module|BufferSource} options.dep.pacerWasm pacer.wasm.
+ * @param {Object<string, {type: string, elemCount: number}>} options.dep.reflection
+ *   the compiled program's reflected fields.
+ * @param {object} options.factories
+ * @param {(wasm: WebAssembly.Module|BufferSource, score: string, options: {registries: Array<Array<{name: string, ncomp: number}>>}) => Promise<{ok: boolean, diagnostics: Array<object>, meta: object}>} options.factories.loadPacer
+ * @returns {Promise<{documentName: string, score: string, join: Array<{name: string, ncomp: number}>, driver: object, meta: object}>}
+ *   the same shape `loadShow` answers, so the page's player wiring is
+ *   identical on both spellings.
+ */
+export async function loadDerivedShow({ document, dep, factories }) {
+  if (!document
+    || typeof document.name !== 'string'
+    || document.name === ''
+    || typeof document.text !== 'string'
+    || document.text === '') {
+    throw portError('loadDerivedShow', 'document.name and a non-empty document.text (the prederived score)');
+  }
+  if (!factories || typeof factories.loadPacer !== 'function') {
+    throw portError('loadDerivedShow', 'factories.loadPacer (the Pacer.load shape)');
+  }
+  if (!dep
+    || dep.pacerWasm === undefined || dep.pacerWasm === null
+    || typeof dep.reflection !== 'object' || dep.reflection === null) {
+    throw portError('loadDerivedShow', 'dep.pacerWasm and dep.reflection (the compiled program\'s reflected fields)');
+  }
+
+  const name = document.name;
+  return compileShow({
+    name,
+    score: document.text,
+    reflection: dep.reflection,
+    pacerWasm: dep.pacerWasm,
+    factories,
+  });
+}
+
+/** The packed container's four-byte magic, as bytes 'P' 'A' 'C' 'B'. */
+const PACB_MAGIC = [0x50, 0x41, 0x43, 0x42];
+
+/** A non-copying Uint8Array view of a Uint8Array/BufferSource, or null. */
+function packedView(value) {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  return null;
+}
+
+/**
+ * Compose the release show from a packed 'PACB' score. There is no source
+ * text and no compiler here: the export's real `pacer pack` answer is
+ * loaded by the playback-only runtime against the prepared program's
+ * reflected join. The join, metadata and never-drop audit are the same
+ * decisions the text paths make, so the page wiring stays identical.
+ *
+ * @param {object} options
+ * @param {{name: string, bytes: Uint8Array|ArrayBuffer}} options.document
+ *   the packed score and the name every failure keeps.
+ * @param {object} options.dep
+ * @param {WebAssembly.Module|BufferSource} options.dep.pacerRtWasm
+ *   pacer-rt.wasm.
+ * @param {Object<string, {type: string, elemCount: number}>} options.dep.reflection
+ *   the compiled program's reflected fields.
+ * @param {object} options.factories
+ * @param {(wasm: WebAssembly.Module|BufferSource, pacb: Uint8Array|ArrayBuffer, options: {registries: Array<Array<{name: string, ncomp: number}>>}) => Promise<{ok: boolean, status: number, reason: number, meta: object}>} options.factories.loadPacerRt
+ *   the `PacerRt.load` shape.
+ * @returns {Promise<{documentName: string, score: Uint8Array, scoreBytes: number, join: Array<{name: string, ncomp: number}>, driver: object, meta: object}>}
+ *   the packed bytes, the reflected join, the playback driver and the
+ *   driver's own public metadata.
+ */
+export async function loadPackedShow({ document, dep, factories }) {
+  const name = document && typeof document.name === 'string' && document.name !== ''
+    ? document.name
+    : 'score.pacb';
+  const bytes = packedView(document?.bytes);
+  const magicOk = bytes !== null
+    && bytes.byteLength >= PACB_MAGIC.length
+    && PACB_MAGIC.every((byte, index) => bytes[index] === byte);
+  if (!magicOk) {
+    throw new ShowError(
+      'bad_packed_document',
+      `${name} is not a 'PACB' packed score (a non-empty Uint8Array starting with the four-byte 'PACB' magic is required)`,
+      { stage: 'load', document: name },
+    );
+  }
+  if (!factories || typeof factories.loadPacerRt !== 'function') {
+    throw portError('loadPackedShow', 'factories.loadPacerRt (the PacerRt.load shape)');
+  }
+  if (!dep
+    || dep.pacerRtWasm === undefined || dep.pacerRtWasm === null
+    || typeof dep.reflection !== 'object' || dep.reflection === null) {
+    throw portError('loadPackedShow', 'dep.pacerRtWasm and dep.reflection (the compiled program\'s reflected fields)');
+  }
+
+  const join = reflectedJoin(dep.reflection, name);
+
+  let driver;
+  try {
+    driver = await factories.loadPacerRt(dep.pacerRtWasm, bytes, { registries: [join] });
+  } catch (cause) {
+    throw new ShowError(
+      'pacer_load_failed',
+      `the packed score could not be loaded for ${name}: ${cause?.message ?? cause}`,
+      { stage: 'compile', document: name, cause },
+    );
+  }
+  if (!driver.ok) {
+    const status = Number.isInteger(driver.status) ? driver.status : -1;
+    const reason = Number.isInteger(driver.reason) ? driver.reason : -1;
+    throw new ShowError(
+      'score_refused',
+      `${name}'s packed score was refused by the playback runtime (status ${status}, reason ${reason})`,
+      {
+        stage: 'compile',
+        document: name,
+        diagnostics: Array.isArray(driver.diagnostics) ? driver.diagnostics : [],
+      },
+    );
+  }
+
+  const meta = driver.meta;
+  if (meta === null || meta === undefined) {
+    throw new ShowError(
+      'metadata_unavailable',
+      `the packed driver answered no metadata for ${name}`,
+      { stage: 'audit', document: name },
+    );
+  }
+
+  auditMeta(name, meta);
+
+  return {
+    documentName: name,
+    score: bytes,
+    scoreBytes: bytes.byteLength,
+    join,
+    driver,
+    meta,
+  };
+}