spine-rigc 1.9.1 → 1.9.3

package/src/assertions/facts/mesh_attachments.ts

@@ -1,8 +1,16 @@
 /**
- * The mesh attachments, as the bodies that read their geometry and their
- * weights see them (issue #1025, step 4c of #380) — the census's F07 (vertex
- * data), F08 (mesh geometry) and F10 (the linked-mesh join), for A04, A20,
- * A21, A28 and the mesh half of A23.
+ * The mesh attachments, as every body that reads a mesh sees them (issue
+ * #1025, step 4c of #380) — the census's F03, F05, F07 (vertex data), F08
+ * (mesh geometry) and F10 (the linked-mesh join), for A04, A13, A14, A15, A20,
+ * A21, A22, A28 and the mesh half of A23.
+ *
+ * ⭐ **One family** (issue #1054). Cut 4c-1 stated the meshes for A13, A14,
+ * A15 and A22 as a family of their own (`SkinMeshFacts`) and cut 4c-2 stated
+ * them again here; the two walked the same entries in the same order and
+ * agreed on every field they shared, and two families of one fact are two
+ * places for a supplier to disagree with itself. The size the budget and
+ * canvas rules read joined this one, and the bones a mesh's weights name are
+ * derived from `weights` (`weightBonesOf`) rather than stated beside them.
  *
  * ⭐ **The order is the file's**, as `./skin_entries.ts` states it: every
  * skin in the file's order, and within a skin the entries slot by slot in the
@@ -56,6 +64,9 @@ export interface MeshEntry {
   readonly regionUVs: readonly number[];
   /** `hullLength`: two numbers per hull vertex. */
   readonly hullLength: number;
+  /** Its `width` and `height` — a link's are its source's, which the runtime's `setSourceMesh` writes over the link's own. */
+  readonly width: number;
+  readonly height: number;
   /** Per vertex its influences, in order — or `null` for an unweighted mesh. */
   readonly weights: ReadonlyArray<readonly MeshBinding[]> | null;
   /** The kept clauses' findings about this mesh's vertex run (`A04`'s encoding rules), in order; never on the model side. */
@@ -69,3 +80,21 @@ export interface MeshFacts {
   /** Every mesh attachment of every skin, in the file's walk order. */
   readonly meshes: readonly MeshEntry[];
 }
+
+/**
+ * Every bone a mesh's weights name, in the weight run's order (repeats kept),
+ * by name — empty for an unweighted mesh. A binding whose index the roster
+ * does not hold names nothing here: that index is the encoding's fault, which
+ * `A20`'s kept clause names (`MeshBinding.encoding`), and no bone drives the
+ * mesh through it.
+ */
+export function weightBonesOf(facts: Pick<MeshFacts, 'bones'>, mesh: Pick<MeshEntry, 'weights'>): string[] {
+  const names: string[] = [];
+  for (const vertex of mesh.weights ?? []) {
+    for (const binding of vertex) {
+      const name = facts.bones[binding.bone];
+      if (name !== undefined) names.push(name);
+    }
+  }
+  return names;
+}

package/src/assertions/facts/slider_composition.ts

@@ -0,0 +1,78 @@
+/**
+ * The sliders and the timelines their animations key, as A40 reads them
+ * (issue #1025, cut 4c-5 of step 4c of #380) — the census's F01–F04, F12,
+ * F15, F18, F19 and R3.
+ *
+ * ⭐ **The order is the runtime's.** The sliders in the `constraints` array's
+ * order, which is the update order and the order A40 calls "earlier" and
+ * "later" in; each animation's timelines in the order the runtime builds
+ * them — the slot timelines, the bone timelines, then ik, transform, path,
+ * physics, slider, the attachments' deform and sequence, the draw order and
+ * the events, each group's targets in the order the file keys them [measured:
+ * an animation keying `events`, `drawOrder`, `attachments`, `slider`,
+ * `physics`, `path`, `transform`, `ik`, `slots`, `bones` in that key order
+ * loads them slots, bones, ik, transform, path, physics, slider, deform,
+ * sequence, draw order, events]; each timeline's properties in the order it
+ * registers them. A40 groups the timelines by property in that order and
+ * prints one line per property shared, so the order is a fact both suppliers
+ * state, not a sort either applies.
+ *
+ * 🔑 **A property is named by an id both suppliers spell the same way**: the
+ * property's name, then the index of the bone, slot or constraint it
+ * addresses in the skeleton's order (`-1` for a physics timeline naming no
+ * constraint), then — for a deform or sequence timeline — the attachment it
+ * is keyed on as `skin/slot/placeholder`. The runtime spells the last as an
+ * object's serial number, which is the runtime's and not the rig's, so its
+ * supplier maps each attachment object to the address it is filed under; a
+ * physics `reset` and the draw-order and event timelines carry no index at
+ * all (measured: a named `reset` reads `physicsConstraintReset` alone).
+ *
+ * 🔸 **What applying a timeline additively does is a question, not a value.**
+ * It is posed — twice, with `add`, from two start states, under every skin —
+ * so a body asks for it (`behaviour`), and only for the timelines it needs:
+ * the validator answers with the runtime's probe, the model side with the
+ * core's (`src/core/additive.ts`), and the selftest puts every question a
+ * body asks to both.
+ *
+ * Links nothing from the runtime.
+ */
+
+/** What applying a timeline twice with `add` does (`src/core/additive.ts`' header). */
+export type AddBehaviour = 'accumulates' | 'overwrites' | 'inert';
+
+/** One property a timeline registers: the id it is shared by, the property's name, and the target and property as A40's sentence names them. */
+export interface SliderTimelineProperty {
+  readonly id: string;
+  readonly property: string;
+  readonly names: string;
+}
+
+/** One timeline of a slider's animation. */
+export interface SliderTimelineFact {
+  /** The runtime class it loads as — the word A40's sentence names `apply` on. */
+  readonly runtimeClass: string;
+  readonly properties: readonly SliderTimelineProperty[];
+}
+
+/** One slider constraint. */
+export interface SliderFact {
+  readonly name: string;
+  /** Its position in the skeleton's `constraints` array. */
+  readonly index: number;
+  /** Its setup `mix`. */
+  readonly mix: number;
+  readonly additive: boolean;
+  readonly skinRequired: boolean;
+  /** The skins whose `slider` list names it, in the skeleton's skin order. */
+  readonly skins: readonly string[];
+  /** The animation it applies, with its timelines in the runtime's order — or `null` where it applies none. */
+  readonly animation: { readonly name: string; readonly timelines: readonly SliderTimelineFact[] } | null;
+}
+
+/** What A40 reads beside the constraint facts. */
+export interface SliderCompositionFacts {
+  /** Every slider, in the `constraints` array's order. */
+  readonly sliders: readonly SliderFact[];
+  /** What the `timeline`-th timeline of `animation` does when it is applied twice with `add` — posed. */
+  behaviour(animation: string, timeline: number): AddBehaviour;
+}

package/src/assertions/facts/stepped_poses.ts

@@ -0,0 +1,74 @@
+/**
+ * The stepped poses (issue #1025, cut 4c-5a of step 4c of #380) — the census's
+ * F01, F18, R4 (the posed `inherit`) and R5 as A10 reads them: the skeleton's
+ * setup pose with every physics state reset, every animation walked on a
+ * LOOPING track from that pose in equal steps, and a bone's inheritance mode
+ * posed at one time on a fresh, non-looping track.
+ *
+ * ⭐ **A pose is handed over whole, non-finite values in place.** A10's
+ * subject is the first number of a pose that is not finite, so a supplier
+ * that refused such a pose, or wrote it as something else, would answer a
+ * different question. The runtime's supplier reads what spine-core posed; the
+ * model side's is the core's looping walk (`src/core/walk.ts`), which returns
+ * the value rather than refusing it.
+ *
+ * 🔸 **The inheritance mode is `null` where the pose holds a mode**, and the
+ * value it holds, as `String` spells it, where it holds none — the one bone
+ * reading that can be wrong with every number finite (#733): the runtime's
+ * lookup leaves a spelling it does not resolve as no mode at all.
+ *
+ * The bone timelines A10 walks for its `inherit` keys are `BoneTimelineFacts`
+ * (`./bone_timelines.ts`), the family A24, A29 and A30 read.
+ *
+ * Links nothing from the runtime: `validate()` supplies it from spine-core
+ * (`spineSteppedPoses`), the model side from the document and the core
+ * (`../model/stepped_poses.ts`).
+ */
+import type { PosedVertices, WorldTransform } from '../../nonfinite.ts';
+
+/** One bone of a pose: its world transform as computed, and its inheritance mode — `null` for a mode, else the value held. */
+export interface SteppedBone extends WorldTransform {
+  readonly inherit: string | null;
+}
+
+/** One slot of a pose: its light colour and its dark colour (`null` for a slot holding none), as computed. */
+export interface SteppedSlot {
+  readonly name: string;
+  readonly colour: readonly [number, number, number, number];
+  readonly dark: readonly [number, number, number] | null;
+}
+
+/** One pose: every bone in skeleton order, every region and mesh shown in draw order, every slot in setup order. */
+export interface SteppedFrame {
+  readonly bones: readonly SteppedBone[];
+  readonly drawn: readonly PosedVertices[];
+  readonly slots: readonly SteppedSlot[];
+}
+
+/** What A10 reads. */
+export interface SteppedPoseFacts {
+  /** The skeleton's bone count. */
+  readonly boneCount: number;
+  /** The animations, in the file's order, each with the runtime's duration (the last key of every timeline, as float32). */
+  readonly steppedAnimations: ReadonlyArray<{ readonly name: string; readonly duration: number }>;
+  /** Whether the skeleton holds an animation of this name. */
+  hasAnimation(name: string): boolean;
+  /** Whether the skeleton holds a bone of this name. */
+  hasBone(name: string): boolean;
+  /**
+   * The bone's inheritance mode with the animation applied at `time` on a
+   * fresh, non-looping track from the setup pose, every physics state reset
+   * before it — `null` where the pose holds a mode, else that value spelled by
+   * `String`, and `undefined` for a bone the skeleton does not have.
+   */
+  posedInherit(animation: string, bone: string, time: number): string | null | undefined;
+  /** How the file spells a bone's setup `inherit`: `JSON.stringify` of the stated value (`"undefined"` for none). */
+  statedInherit(bone: string): string;
+  /** The setup pose, every physics state reset, before any animation is set. */
+  setup(): SteppedFrame;
+  /**
+   * The animation set on a LOOPING track over that setup pose, then `frames`
+   * steps of `step` each — the poses after steps 1 to `frames`, in order.
+   */
+  walk(animation: string, step: number, frames: number): SteppedFrame[];
+}

package/src/assertions/model/animated_bones.ts

@@ -5,13 +5,21 @@
  * The document writes each animation's `bones` as a list in the model's map
  * order, and the emitter writes the Spine file's `bones` group from that same
  * map, entry for entry, leaving the group out when it is empty
- * (`emitAnimation`'s `if (animation.bones.size)`) — so the list's order is the
- * file's, an empty list is a file with no `bones` group, and an animation the
- * document does not hold is one the file does not key. The first animation of
- * a name answers, as the file's object would hold only one.
+ * (`emitAnimation`'s `if (animation.bones.size)`) — so an empty list is a file
+ * with no `bones` group, and an animation the document does not hold is one the
+ * file does not key. The first animation of a name answers, as the file's
+ * object would hold only one.
+ *
+ * 🔢 **The order is `keyedOrder` over the list's, not the list's** (issue
+ * #1039). The group is an object keyed by bone name, so the file lists an
+ * array-index name (`5`, `10`) first whatever order the emitter filled it in —
+ * measured on a walk whose tracks key `-a, 5, 2b, 10, …`: the document lists
+ * that, the file and spine-core `5, 10, -a, 2b, …`, and A15 prints one line per
+ * keyed bone in the file's order.
  *
  * Links nothing from the runtime.
  */
+import { keyedOrder } from '../../compile.ts';
 import type { AnimatedBoneFacts } from '../facts/animated_bones.ts';
 import { isObj } from '../values.ts';
 import type { ReadDocument } from './parse.ts';
@@ -24,7 +32,7 @@ export function modelAnimatedBones(read: ReadDocument): AnimatedBoneFacts {
       if (animation === undefined) return undefined;
       const bones = Array.isArray(animation.bones) ? animation.bones.filter(isObj) : [];
       if (bones.length === 0) return null;
-      return bones.map((bone) => String(bone.name));
+      return keyedOrder(bones.map((bone) => String(bone.name)));
     },
   };
 }

package/src/assertions/model/bone_timelines.ts

@@ -6,9 +6,11 @@
  * `./slot_colour.ts`), over the `bones` group: the animations put in the
  * file's order by `editorAnimationOrder` (`src/compile.ts`, the function the
  * emitter is handed), each animation's bones and their timelines laid out as
- * the file lays them (`animations.<name>.bones.<bone>.<timeline> = keys`, in
- * the document's order, which is the order `emitAnimation` writes the model's
- * map in), and the whole handed to the emitter's own `withoutParserDefaults`
+ * the file lays them (`animations.<name>.bones.<bone>.<timeline> = keys`,
+ * filled in the document's order, which is the order `emitAnimation` writes
+ * the model's map in — and read back out of that object, so an array-index
+ * bone name comes first as it does in the file: issue #1039 measured this
+ * reader already walking the file's order), and the whole handed to the emitter's own `withoutParserDefaults`
  * and `inEditorKeyOrder` (`src/keyorder.ts`) — so a key field the emitter
  * leaves out at the parser's default (`time: 0`, a translate key's `y: 0`) is
  * left out here too, and a body printing a key's `time` prints what it prints

package/src/assertions/model/constraint_targets.ts

@@ -0,0 +1,82 @@
+/**
+ * The model side's supply of `ConstraintTargetFacts` (issue #1025, cut 4c-5
+ * of step 4c of #380): the document's constraints and every animation's
+ * constraint groups, laid out as the Spine file lays them.
+ *
+ * - **The constraints**: the document's, in its order — which the emitter
+ *   writes the `constraints` array in — each its name and its kind, the word
+ *   the file spells its `type` with.
+ * - **The animations**: in the file's order (`fileAnimationOrder`, issue
+ *   #1034); in each the five groups in A34's fixed order, a group only where
+ *   the document holds an entry for it (`emitAnimation` writes a group only
+ *   when the model holds something for it); each group's entries in the order
+ *   the file keys them — an object the emitter fills in the document's order,
+ *   so its names land as `keyedOrder` lands them, built here as that object;
+ *   the timeline naming no physics constraint under the empty name the
+ *   emitter spells it with, where the document spells it `*`
+ *   (`EVERY_GLOBAL_PHYSICS`); each entry's timelines in the document's order,
+ *   which the emitter writes unchanged (a name-keyed map no key-order pass
+ *   touches, `src/keyorder.ts`). A document the reader accepted states every
+ *   key array as a non-empty list, a named group's entry as named timelines,
+ *   and only constraints of the kind its group names, so the clauses that
+ *   refuse those shapes have nothing to fire on here.
+ * - **The reach** of a physics timeline naming none: the core's own reading,
+ *   `unnamedReach` (`./constraints.ts`, which poses the timeline through
+ *   `posedPhysics` and reads which records took the key), over the document's
+ *   physics records in its order. The reader refuses a physics timeline name
+ *   it does not know, so every name asked of it is one the core poses.
+ *
+ * Links nothing from the runtime.
+ */
+import { fileAnimationOrder } from '../../compile.ts';
+import { EVERY_GLOBAL_PHYSICS, PHYSICS_TIMELINE_KINDS, type CorePhysicsRecord } from '../../core/constraints_physics.ts';
+import type { ConstraintTargetFacts, TargetAnimation, TargetEntry, TargetKeyArray } from '../facts/constraint_targets.ts';
+import { isObj, type Json } from '../values.ts';
+import { unnamedReach } from './constraints.ts';
+import type { ReadDocument } from './parse.ts';
+
+const list = (v: unknown): Json[] => (Array.isArray(v) ? v.filter(isObj) : []);
+const keyArray = (timeline: string, keys: unknown): TargetKeyArray => ({ timeline, keys: Array.isArray(keys) ? { count: keys.length } : { spelled: `${JSON.stringify(keys)}` } });
+
+/** One group's entries as the file keys them: an object filled in the document's order, read back in its key order. */
+function fileEntries(group: 'ik' | 'transform' | 'path' | 'physics' | 'slider', entries: readonly Json[]): TargetEntry[] {
+  const keyed: Record<string, TargetEntry> = {};
+  for (const entry of entries) {
+    if (typeof entry.name !== 'string') continue;
+    const name = group === 'physics' && entry.name === EVERY_GLOBAL_PHYSICS ? '' : entry.name;
+    keyed[name] =
+      group === 'ik' || group === 'transform'
+        ? { name, bare: null, keyArrays: [keyArray('', entry.keys)] }
+        : { name, bare: null, keyArrays: list(entry.timelines).flatMap((t) => (typeof t.name === 'string' ? [keyArray(t.name, t.keys)] : [])) };
+  }
+  return Object.values(keyed);
+}
+
+export function modelConstraintTargets(read: ReadDocument): ConstraintTargetFacts {
+  const { doc } = read;
+  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 animations: TargetAnimation[] = [];
+  for (const name of fileAnimationOrder(doc)) {
+    const anim = byName.get(name);
+    if (anim === undefined) continue;
+    const groups: TargetAnimation['groups'][number][] = [];
+    const constraints = isObj(anim.constraints) ? anim.constraints : {};
+    for (const group of ['ik', 'transform', 'path', 'physics', 'slider'] as const) {
+      const entries = list(constraints[group]);
+      if (entries.length > 0) groups.push({ group, entries: fileEntries(group, entries) });
+    }
+    animations.push({ name, groups });
+  }
+  const records = doc.constraints.flatMap((c): CorePhysicsRecord[] => (c.record?.kind === 'physics' ? [c.record] : []));
+  return {
+    constraints: doc.constraints.map((c) => ({ name: c.name, type: c.kind, spelled: c.name })),
+    groupsByAnimation: animations,
+    reach: (timeline) => {
+      const kind = PHYSICS_TIMELINE_KINDS.find((k) => k === timeline);
+      if (kind === undefined) return null;
+      const reached = unnamedReach(records, kind);
+      return { resets: kind === 'reset', reached: records.filter((r) => reached.has(r.name)).map((r) => r.name) };
+    },
+  };
+}

package/src/assertions/model/declared.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 bool: Check = (v, at, p) => (typeof v === 'boolean' ? undefined : say(p, at, v, 'true or false'));
+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),
+  editorRoundTrip: bool,
+  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));
+}