rig-c 0.0.0-stage → 2.20.4

package/src/assertions/model/constraints.ts

@@ -0,0 +1,233 @@
+/**
+ * The model side's supply of `ConstraintFacts` (issue #1025, step 4c of
+ * #380): the document's constraints in update order, the constraint
+ * timelines of its animations in the order the runtime builds them, and the
+ * slots its skins give a path.
+ *
+ * Every value is the one the runtime holds after its parse, through a
+ * function rigc already runs:
+ *
+ * - **A constraint's fields** are the core's records (`readModel` →
+ *   `readConstraintRecord`, `readPathRecord`, `readPhysicsRecord`,
+ *   `readSliderRecord`), which read a field the record leaves out at the
+ *   parser's value; a physics record's `massInverse` and `step` are the
+ *   reader's `1 / mass` and `1 / fps`. A transform constraint reads a mix
+ *   exactly where one of its `to` entries names that property — the core's
+ *   `properties`, by `TRANSFORM_MIXES`.
+ * - **A slider's animation** is the core's reading of it: its duration is
+ *   `CoreAnimationTimelines.duration` (the last key time, float32 — the
+ *   runtime's), and the timelines it carries are the bone and slot timelines
+ *   plus the count of every later group the reader counts.
+ * - **The timelines**: the animations in the file's order
+ *   (`fileAnimationOrder`, issue #1034: a `rigc-compiled/3` document's
+ *   `editorOrder`, else the emitter's own rule over its names); in each the
+ *   groups in the runtime's order (`../facts/constraints.ts`' ⭐), each
+ *   group's entries in the order the file keys them — the document's, an
+ *   integer-like constraint name first (`keyedOrder`) — and each entry's
+ *   timelines in the document's order, which the emitter writes unchanged. A key's time and value are the core's (float32), and a
+ *   Bézier segment's samples `bezierPolyline` over the numbers the document
+ *   states — the runtime's curve, as the core reproduces it.
+ * - **The reach of a physics timeline naming none** is asked of the core's
+ *   own `posedPhysics` rather than restated: the timeline is posed once with
+ *   a key the setup cannot hold (NaN), and the constraints it reached are the
+ *   ones whose pose field took it; a `reset` timeline's reach is the set
+ *   `posedPhysics` returns.
+ *
+ * ⚠️ One value is not the document's: `runtimeClass`, the runtime's class
+ * name for a kind, which A42's sentence names `update` on. The document has no
+ * field for it and rigc has no function returning it, so it is the table
+ * below; the selftest compares it with the class spine-core loaded on every
+ * call that reaches a constraint (`VF10`).
+ *
+ * Links nothing from the runtime.
+ */
+import { fileAnimationOrder, keyedOrder, type OrderedDocument } from '../../compile.ts';
+import { bezierPolyline, type CoreAnimationTimelines, type CoreKey } from '../../core/animation.ts';
+import { TRANSFORM_MIXES, TRANSFORM_PROPERTIES, type CoreConstraintRecord } from '../../core/constraints.ts';
+import { EVERY_GLOBAL_PHYSICS, posedPhysics, type CorePhysicsRecord, type PhysicsTimelineKind } from '../../core/constraints_physics.ts';
+import type { CompiledDocument } from '../../core/index.ts';
+import { physicsRuleFor } from '../../timelines.ts';
+import type { ConstraintEntry, ConstraintFacts, ConstraintKind, ConstraintTimeline } from '../facts/constraints.ts';
+import { isObj, type Json } from '../values.ts';
+import { fileOrderedEntries } from './skin_entries.ts';
+import type { ReadDocument } from './parse.ts';
+
+/** The runtime's class for each kind — the one value here that is not the document's (the header's ⚠️). */
+export const RUNTIME_CONSTRAINT_CLASS: Readonly<Record<ConstraintKind, string>> = {
+  ik: 'IkConstraint',
+  transform: 'TransformConstraint',
+  path: 'PathConstraint',
+  physics: 'PhysicsConstraint',
+  slider: 'Slider',
+};
+
+/** How many timelines the runtime builds for an animation the core read: every bone and slot timeline, and every later group's count. */
+export function timelineCount(timelines: CoreAnimationTimelines): number {
+  let n = 0;
+  for (const target of [...timelines.bones, ...timelines.slots]) n += target.timelines.length;
+  for (const [, count] of timelines.later) n += count;
+  return n;
+}
+
+/** Every value one channel of `keys` poses: each key's own, then the samples of the Bézier segment it opens. */
+export function channelValuesOf(keys: readonly CoreKey[], channel: number): number[] {
+  const out: number[] = [];
+  keys.forEach((a, i) => {
+    out.push(a.values[channel]);
+    const b = keys[i + 1];
+    if (b === undefined || !Array.isArray(a.curve)) return;
+    const c = a.curve.slice(channel * 4, channel * 4 + 4);
+    const inner = bezierPolyline(a.stated.time, a.stated.values[channel], c[0], c[1], c[2], c[3], b.stated.time, b.stated.values[channel]);
+    for (let p = 1; p < inner.length; p += 2) out.push(inner[p]);
+  });
+  return out;
+}
+
+/** The physics constraints a timeline naming none reaches, asked of `posedPhysics` (the header). */
+export function unnamedReach(records: readonly CorePhysicsRecord[], kind: PhysicsTimelineKind): Set<string> {
+  if (kind === 'reset') {
+    const keys: CoreKey[] = [{ time: 0, values: [], stated: { time: 0, values: [] }, curve: 'stepped' }];
+    return posedPhysics(records, [{ name: EVERY_GLOBAL_PHYSICS, kind, keys }], 0, -1, () => true).reset;
+  }
+  const keys: CoreKey[] = [{ time: 0, values: [Number.NaN], stated: { time: 0, values: [Number.NaN] }, curve: 'linear' }];
+  const posed = posedPhysics(records, [{ name: EVERY_GLOBAL_PHYSICS, kind, keys }], 0, -1, () => true).records;
+  const field = kind === 'mass' ? 'massInverse' : kind;
+  return new Set([...posed.values()].filter((r) => Number.isNaN(r[field])).map((r) => r.name));
+}
+
+function entryOf(doc: CompiledDocument, kind: ConstraintKind, name: string, record: CoreConstraintRecord): ConstraintEntry {
+  const base = { kind, name, runtimeClass: RUNTIME_CONSTRAINT_CLASS[kind] };
+  switch (record.kind) {
+    case 'physics':
+      return {
+        ...base,
+        physics: {
+          bone: record.bone,
+          // The length the core's step is handed (`bone(state, c.bone).length ?? 0` in `src/core/constraints.ts`): the parser's 0 where the document leaves it out.
+          boneLength: doc.bones.find((b) => b.name === record.bone)?.length ?? 0,
+          components: { x: record.x, y: record.y, rotate: record.rotate, scaleX: record.scaleX, shearX: record.shearX },
+          setup: { mix: record.mix, massInverse: record.massInverse, strength: record.strength, damping: record.damping },
+          step: record.step,
+        },
+      };
+    case 'path':
+      return { ...base, path: { bones: record.bones, slot: record.slot, setup: { mixRotate: record.mixRotate, mixX: record.mixX, mixY: record.mixY } } };
+    case 'slider': {
+      const anim = doc.animations.find((a) => a.name === record.animation);
+      return {
+        ...base,
+        slider: {
+          animation: anim === undefined ? null : { name: anim.name, timelines: timelineCount(anim.timelines), duration: anim.timelines.duration },
+          bone: record.bone,
+          loop: record.loop,
+          scale: record.scale,
+          mix: record.mix,
+        },
+      };
+    }
+    case 'ik': {
+      // The second bone's ancestors, parent first (issue #1205). The core's reader refuses a pair that is not a parent and its child, so on this side the first entry is always the first bone.
+      const secondAncestors: string[] = [];
+      if (record.bones.length === 2) {
+        for (let at = doc.bones.find((b) => b.name === record.bones[1])?.parent; at !== undefined; at = doc.bones.find((b) => b.name === at)?.parent) secondAncestors.push(at);
+      }
+      return { ...base, ik: { bones: record.bones, target: record.target, mix: record.mix, secondAncestors } };
+    }
+    case 'transform':
+      return {
+        ...base,
+        transform: {
+          bones: record.bones,
+          mixes: TRANSFORM_PROPERTIES.map((p) => (record.properties.some((from) => from.to.some((to) => to.property === p)) ? { field: TRANSFORM_MIXES[p], setup: record.mixes[p] } : null)),
+        },
+      };
+  }
+}
+
+/** One constraint timeline as the model side walks it: where it is, what it keys, and the core's keys for it. */
+export interface ModelConstraintTimelineSource {
+  animation: string;
+  kind: ConstraintKind;
+  word: string;
+  /** The constraint it names, or `EVERY_GLOBAL_PHYSICS`. */
+  name: string;
+  keys: readonly CoreKey[];
+}
+
+/** How the animations are put in the file's order: `fileAnimationOrder`. A parameter only so the selftest can show what another order would print (`VF11`). */
+export type AnimationFileOrder = (doc: OrderedDocument) => readonly string[];
+
+/**
+ * `entries` in the order the Spine file keys them by name (issue #1034): each
+ * constraint group of an animation is an object the emitter fills in the
+ * model's order, so the names are grouped as they first appear and put
+ * through `keyedOrder` — an integer-like name first — and every entry of one
+ * name keeps its place among them.
+ */
+function inKeyedOrder<T extends { name: string }>(entries: readonly T[]): T[] {
+  const names = entries.map((e) => e.name);
+  return keyedOrder(names.filter((n, i) => names.indexOf(n) === i)).flatMap((name) => entries.filter((e) => e.name === name));
+}
+
+/** Every constraint timeline of the document, in the order the runtime builds them (the header) — the walk `modelConstraintFacts` reads, and the selftest's measurement of each derivation. */
+export function modelConstraintTimelineSources(read: ReadDocument, animations: AnimationFileOrder = fileAnimationOrder): ModelConstraintTimelineSource[] {
+  const { doc } = read;
+  const jsonAnimations = Array.isArray(read.json.animations) ? read.json.animations.filter(isObj) : [];
+  const out: ModelConstraintTimelineSource[] = [];
+  for (const name of animations(doc)) {
+    const anim = doc.animations.find((a) => a.name === name);
+    if (anim === undefined) continue;
+    const c = anim.constraints;
+    for (const tl of inKeyedOrder(c.ik)) out.push({ animation: name, kind: 'ik', word: 'ik', name: tl.name, keys: tl.keys });
+    for (const tl of inKeyedOrder(c.transform)) out.push({ animation: name, kind: 'transform', word: 'transform', name: tl.name, keys: tl.keys });
+    for (const entry of inKeyedOrder(c.path)) {
+      for (const word of Object.keys(entry)) {
+        if (word === 'position' || word === 'spacing' || word === 'mix') out.push({ animation: name, kind: 'path', word, name: entry.name, keys: entry[word] ?? [] });
+      }
+    }
+    for (const tl of inKeyedOrder(c.physicsKeyed ?? [])) out.push({ animation: name, kind: 'physics', word: tl.kind, name: tl.name, keys: tl.keys });
+    // A slider entry's timelines in the order the document lists them, which `readSliderTimelines` keeps by name only.
+    const jsonSliders = ((): Json[] => {
+      const json = jsonAnimations.find((a) => a.name === name)?.constraints;
+      return isObj(json) && Array.isArray(json.slider) ? json.slider.filter(isObj) : [];
+    })();
+    // Paired with the document's own entry by index before the walk is put in the file's order.
+    const sliders = c.slider.map((entry, i) => ({ name: entry.name, entry, listed: Array.isArray(jsonSliders[i]?.timelines) ? (jsonSliders[i].timelines as unknown[]).filter(isObj).map((t) => t.name) : [] }));
+    for (const { entry, listed } of inKeyedOrder(sliders)) {
+      for (const word of listed) {
+        if (word === 'time' || word === 'mix') out.push({ animation: name, kind: 'slider', word, name: entry.name, keys: entry[word] ?? [] });
+      }
+    }
+  }
+  return out;
+}
+
+export function modelConstraintFacts(read: ReadDocument, animations: AnimationFileOrder = fileAnimationOrder): ConstraintFacts {
+  const { doc } = read;
+  const constraints: ConstraintEntry[] = doc.constraints.map((c) => {
+    if (c.record === undefined) throw new Error(`internal: ${c.kind} constraint "${c.name}" is one the reader returned without its record`);
+    return entryOf(doc, c.kind, c.name, c.record);
+  });
+  const indexOf = (kind: ConstraintKind, name: string): number => doc.constraints.findIndex((c) => c.kind === kind && c.name === name);
+  const physicsRecords = doc.constraints.flatMap((c) => (c.record?.kind === 'physics' ? [c.record] : []));
+  const timelines: ConstraintTimeline[] = modelConstraintTimelineSources(read, animations).map(({ animation, kind, word, name, keys }) => {
+    const constraint = name === EVERY_GLOBAL_PHYSICS && kind === 'physics' ? -1 : indexOf(kind, name);
+    const reach = constraint >= 0 ? [constraint] : [...unnamedReach(physicsRecords, word as PhysicsTimelineKind)].map((n) => indexOf('physics', n)).sort((a, b) => a - b);
+    const rule = kind === 'physics' ? physicsRuleFor(word) : undefined;
+    return {
+      animation,
+      kind,
+      word,
+      constraint,
+      reach,
+      frames: word === 'reset' ? [] : keys.map((k) => ({ time: k.time, value: k.values[0] })),
+      channelValues: (channel: number) => (word === 'reset' ? [] : channelValuesOf(keys, channel)),
+      ...(rule === undefined ? {} : { posed: (value: number) => rule.toPose(value) }),
+    };
+  });
+  const pathSlots: string[] = [];
+  for (const entry of fileOrderedEntries(read)) {
+    if (entry.record.kind === 'path' && !pathSlots.includes(entry.slot)) pathSlots.push(entry.slot);
+  }
+  return { animations: doc.animations.length, constraints, timelines, pathSlots };
+}

package/src/assertions/model/declared.ts

@@ -0,0 +1,125 @@
+/**
+ * What the build declared, read off the document (issue #1054): the rig info
+ * the archetype and declaration rules read, and each animation's declared
+ * duration, which A09 holds the keys against.
+ *
+ * ⭐ **The document is the one source, on every spec it is read at.** A
+ * `rigc-compiled/3`, `/2` and `/1` document all carry the `rig` section
+ * (`CompileResult.rig` as `modelDocument` writes it) and every animation's
+ * `duration` (the motion spec's, which `readModel` reads as
+ * `CoreAnimationTimelines.declared` and refuses when it is not a finite
+ * number). Until this module the model side took both from its caller, as
+ * `validate()` does, and its verdict moved with what the caller handed it:
+ * measured over the 19 recipes with the document's own values left out, A09
+ * read SKIP on 38 of 38 cells, ten rules read their bare-directory SKIP, and
+ * A20 read FAIL on 7 cells where it reads PASS — without the rig every mesh is
+ * judged a generated ring (`meshKindOf`), so an authored mesh fails the
+ * generator policy. A value the document states is read from the document,
+ * and the same value given beside it is refused by name
+ * (`refuseDeclaredBeside`), as issue #1026 made the stage and `pma`
+ * (`./given.ts`).
+ *
+ * 🔒 **The rig section is read field by field, never cast.** A body reads a
+ * declaration only through `modelRigInfo`, which refuses by its path a field
+ * that is missing, of the wrong type or not one the writer writes — the
+ * model side's parse runs it (`./parse.ts`, `A00_MODEL_READ`), so a document
+ * whose declarations are malformed is refused where the reader refuses, and
+ * never judged against a guess.
+ *
+ * Links nothing from the runtime.
+ */
+import type { MeshKind } from '../../mesh.ts';
+import type { RigInfo } from '../../types.ts';
+import { isObj } from '../values.ts';
+import type { ReadDocument } from './parse.ts';
+
+/** A rig section the model side cannot read as rig info: every problem, each by its path, in one sentence. */
+export class DeclaredInputError extends Error {}
+
+/** The mesh kinds a rig's `meshKinds` may name: the generators' and `authored`. */
+const MESH_KINDS = ['ring', 'ribbon', 'contour', 'grid', 'segments', 'authored'] as const satisfies ReadonlyArray<MeshKind | 'authored'>;
+// Every kind the type names is in the list, or this line does not type-check.
+const MESH_KINDS_COMPLETE: Exclude<MeshKind | 'authored', (typeof MESH_KINDS)[number]> extends never ? true : false = true;
+void MESH_KINDS_COMPLETE;
+
+type Check = (value: unknown, at: string, problems: string[]) => void;
+const say = (problems: string[], at: string, value: unknown, what: string): void => void problems.push(`${at} is ${JSON.stringify(value) ?? 'absent'}, not ${what}`);
+const str: Check = (v, at, p) => (typeof v === 'string' ? undefined : say(p, at, v, 'a string'));
+const num: Check = (v, at, p) => (typeof v === 'number' && Number.isFinite(v) ? undefined : say(p, at, v, 'a finite number'));
+const nullable = (inner: Check): Check => (v, at, p) => (v === null ? undefined : inner(v, at, p));
+const list = (inner: Check, length?: number): Check => (v, at, p) => {
+  if (!Array.isArray(v) || (length !== undefined && v.length !== length)) return say(p, at, v, length === undefined ? 'a list' : `a list of ${length}`);
+  v.forEach((x, i) => inner(x, `${at}[${i}]`, p));
+};
+const record = (inner: Check): Check => (v, at, p) => {
+  if (!isObj(v)) return say(p, at, v, 'an object');
+  for (const [k, x] of Object.entries(v)) inner(x, `${at}.${k}`, p);
+};
+const oneOf = (words: readonly string[]): Check => (v, at, p) => (typeof v === 'string' && words.includes(v) ? undefined : say(p, at, v, `one of ${words.join(', ')}`));
+const shape = (fields: Readonly<Record<string, Check>>): Check => (v, at, p) => {
+  if (!isObj(v)) return say(p, at, v, 'an object');
+  for (const [k, check] of Object.entries(fields)) check(v[k], `${at}.${k}`, p);
+  for (const k of Object.keys(v)) if (!(k in fields)) p.push(`${at}.${k} is not a field the rig section has`);
+};
+
+/** The rig section's fields, as `RigInfo` declares them and the writer writes every one — each required, none defaulted. */
+const RIG_FIELDS: Readonly<Record<keyof RigInfo, Check>> = {
+  archetype: str,
+  axisBone: nullable(str),
+  axisSubtree: list(str),
+  detached: list(list(str, 2)),
+  slotOrder: nullable(list(str)),
+  meshKinds: record(oneOf(MESH_KINDS)),
+  meshDeclaredBones: record(list(str)),
+  meshSoftBones: record(str),
+  deformMayFold: list(str),
+  consumerDrivenMix: list(shape({ type: oneOf(['ik', 'transform']), constraint: str, why: str })),
+  idleDrivesMeshes: nullable(str),
+  basePlates: list(str),
+  meshSlotBudget: nullable(num),
+  meshTriangleBudget: nullable(num),
+  contactDepth: nullable(num),
+  capContainmentCeiling: nullable(num),
+  massBone: nullable(str),
+  inwardUnit: nullable(list(num, 2)),
+};
+
+/** Every problem with the document's `rig` section, each by its path — empty when it reads as rig info. */
+export function rigSectionProblems(json: Readonly<Record<string, unknown>>): string[] {
+  const problems: string[] = [];
+  shape(RIG_FIELDS)(json.rig, 'rig', problems);
+  return problems;
+}
+
+/** The rig info the document declares — its `rig` section, read field by field; a section that does not read is refused by its paths. */
+export function modelRigInfo(read: ReadDocument): RigInfo {
+  const problems = rigSectionProblems(read.json);
+  if (problems.length > 0) throw new DeclaredInputError(`the document's rig section does not read as rig info: ${problems.length} problem(s): ${problems.join('; ')}`);
+  return read.json.rig as RigInfo;
+}
+
+/**
+ * Each animation's declared duration, as the document states it and the core
+ * reads it (`CoreAnimationTimelines.declared`), keyed in the document's order —
+ * the motion spec's, the order `CompileResult.declaredDurations` is filled in.
+ */
+export function modelDeclaredDurations(read: ReadDocument): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const anim of read.doc.animations) out[anim.name] = anim.timelines.declared;
+  return out;
+}
+
+/** What a caller may not give beside a document, because every document states it. */
+export type DeclaredValue = 'rig' | 'declaredDurations';
+
+/** The sentence a value given beside the document is refused with. */
+export function declaredBesideRefusal(spec: string, what: DeclaredValue): string {
+  const given = what === 'rig' ? 'the rig info' : 'the declared durations';
+  const stated = what === 'rig' ? 'states it itself in its rig section' : "states each animation's duration itself";
+  return `the caller gave ${given} beside a ${spec} document, which ${stated} (issue #1054); a second source for one fact is refused rather than one of them silently read`;
+}
+
+/** A caller's value beside a document that states it, refused by name. */
+export function refuseDeclaredBeside(read: ReadDocument, input: { rig?: unknown; declaredDurations?: unknown }, what: DeclaredValue): void {
+  if (input[what] !== undefined) throw new Error(declaredBesideRefusal(read.doc.spec, what));
+}

package/src/assertions/model/deform_survey.ts

@@ -0,0 +1,24 @@
+/**
+ * The model side's supply of `DeformSurveyFacts` (issue #1025, cut 4c-3 of
+ * step 4c of #380): the survey off the model document alone —
+ * `surveyOfModel` (`src/deformsurvey.ts`), the document's structure read by
+ * `modelStructure` (`src/deformstructure.ts`) and every pose taken by the
+ * core's poser. It is the survey `explain` takes of a build that carries a
+ * model document (`surveyOfBuild`'s model path) and the one
+ * `tools/survey_hashes.ts` holds byte for byte to spine-core's on every corpus
+ * row; called, not restated.
+ *
+ * A pose the core refuses — a construct it leaves out, a value it computes as
+ * no number — is a `CoreInputError` naming why, and it reaches A39 as the
+ * refusal: the line the harness prints for a body that threw, the core's
+ * sentence in it. A survey that is not the runtime's is never handed on.
+ *
+ * Links nothing from the runtime.
+ */
+import { surveyOfModel } from '../../deformsurvey.ts';
+import type { DeformSurveyFacts } from '../facts/deform_survey.ts';
+import type { ReadDocument } from './parse.ts';
+
+export function modelDeformSurvey(read: ReadDocument): DeformSurveyFacts {
+  return { survey: (exempt) => surveyOfModel(read.doc, exempt) };
+}

package/src/assertions/model/event_keys.ts

@@ -0,0 +1,45 @@
+/**
+ * The model side's supply of `EventKeyFacts` (issue #1025, cut 4c-4 of #380):
+ * every event key of the document, with the declaration it fires.
+ *
+ * - **The order is the file's.** The animations by `editorAnimationOrder`
+ *   (`src/compile.ts`, the function the emitter is handed), and an animation's
+ *   keys in the document's order, which is the order `emitAnimation` writes
+ *   the model's list in; an animation with no event key writes no `events`
+ *   group, so it carries no event timeline here either.
+ * - **The moved clause's inputs.** Which of `volume` and `balance` the key
+ *   states — the document's key carries the fields the file's does, and the
+ *   parser-default pass leaves an event key's audio fields alone (its row is
+ *   `time` only) — and whether the declaration names an audio path, the
+ *   `audio` the document's `events` section states for that name.
+ * - **No `kept` finding, ever.** The four clauses that stay with the round
+ *   trip are states `readModel` refuses (`readEventKeys`), so on a document
+ *   this side has read none of them can hold.
+ *
+ * Links nothing from the runtime.
+ */
+import { editorAnimationOrder } from '../../compile.ts';
+import type { EventKeyEntry, EventKeyFacts } from '../facts/event_keys.ts';
+import { isObj, type Json } from '../values.ts';
+import type { ReadDocument } from './parse.ts';
+
+const list = (v: unknown): Json[] => (Array.isArray(v) ? v.filter(isObj) : []);
+
+export function modelEventKeys(read: ReadDocument): EventKeyFacts {
+  const audio = new Map<string, boolean>();
+  for (const def of list(read.json.events)) if (typeof def.name === 'string') audio.set(def.name, typeof def.audio === 'string');
+  const byName = new Map<string, Json>();
+  for (const anim of list(read.json.animations)) if (typeof anim.name === 'string') byName.set(anim.name, anim);
+  const keys: EventKeyEntry[] = [];
+  let timelines = 0;
+  for (const animation of editorAnimationOrder([...byName.keys()])) {
+    const events = list((byName.get(animation) as Json).events);
+    if (events.length === 0) continue;
+    timelines++;
+    events.forEach((key, index) => {
+      const name = String(key.name);
+      keys.push({ animation, index, kept: [], stopped: false, name, sets: { volume: key.volume !== undefined, balance: key.balance !== undefined }, audio: audio.get(name) ?? false });
+    });
+  }
+  return { parsed: true, animations: true, timelines, keys };
+}

package/src/assertions/model/given.ts

@@ -0,0 +1,45 @@
+/**
+ * What the model side is given beside the document (issue #1025, step 4c of
+ * #380): the two values the census found the document does not hold, which a
+ * moved assertion reads — the stage (A14, A19) and each atlas page's `pma`
+ * (A06). Both entered the document with issue #1026 (`rigc-compiled/3`):
+ * a `/3` document is read for them and this input is for a `/2` or `/1`
+ * document alone — given beside a `/3` document it is refused by name
+ * (`refuseGivenBeside`) rather than ignored, because a value the caller states
+ * beside the document's own is a second source for one fact, and a silent
+ * winner between two sources is how a verdict comes to pass for the wrong
+ * reason.
+ *
+ * ⛔ **The model side never reads them off a Spine file itself.** A verdict that
+ * read `skeleton.json` would be a second reading of the encoding, which is the
+ * round trip's subject; so whoever calls the model side states them, from what
+ * it holds. The selftest's supplier check and `tools/verdict_gate.ts` hold the
+ * build they gate, and read both off it with one function
+ * (`modelGivenOfBuild` in that tool): the stage the skeleton header the build
+ * wrote states, and each page's `pma` as rigc's own atlas reader
+ * (`parseAtlasText`) reads the atlas the build wrote.
+ *
+ * Links nothing from the runtime.
+ */
+
+import type { ReadDocument } from './parse.ts';
+
+/**
+ * A caller's `given` beside a document that states both values itself
+ * (`rigc-compiled/3`, issue #1026), refused by name: the caller is to give
+ * them for a `/2` or `/1` document only (`modelGivenOf` in
+ * `tools/verdict_gate.ts` gives them exactly then).
+ */
+export function refuseGivenBeside(read: ReadDocument, given: ModelGiven | undefined): void {
+  if (given !== undefined && read.doc.stated !== null) {
+    throw new Error(`the caller gave the stage and the pages' pma beside a ${read.doc.spec} document, which states both itself (issue #1026); a second source for one fact is refused rather than one of them silently read`);
+  }
+}
+
+/** The stage and the pages' `pma`, as the caller states them. */
+export interface ModelGiven {
+  /** The stage the skeleton states — each extent where it states one — or `null` where it states none. */
+  readonly stage: { readonly width?: number; readonly height?: number } | null;
+  /** Each page's `pma`, in the atlas's page order: one value per page of the document's `pages`. */
+  readonly pma: readonly boolean[];
+}