spine-rigc 1.7.0 → 1.9.0

package/src/assertions/kinds.ts

@@ -0,0 +1,102 @@
+/**
+ * What kind of rule each assertion is, and which profile runs which kind
+ * (issue #1025, step 4c of #380).
+ *
+ * The table lives here rather than in `src/validate.ts` because two harnesses
+ * read it now: `validate()`'s `check`, which runs an assertion over what
+ * spine-core loaded, and the model side's (`./harness.ts`), which runs the
+ * same body over the model document and the core. A profile has to exclude
+ * the same rules on both sides, and two copies of the table is how one of
+ * them would come to exclude a rule the other runs. This module links nothing
+ * from the runtime, which is the condition for the model side to read it.
+ */
+
+/** The two rulebooks — `ValidateProfile` in `src/validate.ts`, where the choice between them is argued. */
+export type AssertionProfile = 'spine' | 'spine-html';
+
+/** The three kinds a rule can be; the table's own comment says what each means. */
+export type AssertionKind = 'validity' | 'renderer' | 'archetype';
+
+/**
+ * What kind of rule each assertion is. Every assertion has an entry, and
+ * `check()` throws on a name that has none — a new assertion must state its kind
+ * rather than defaulting into one, because the default would decide, silently,
+ * whether it runs on foreign data.
+ *
+ *   validity  — the file is wrong for any consumer. Runs under every profile.
+ *   renderer  — valid Spine that this project's renderer or frame budget refuses.
+ *   archetype — a structural rule about rigc's own formations, meaningless to a
+ *               skeleton rigc did not compile.
+ *
+ * Two assertions are MIXED and are marked `validity` here because their
+ * validity half must never stop running; their policy clauses are gated inside
+ * the assertion body against `profile`, and each such clause says so where it
+ * lives. They are A06 (size-vs-PNG and every region's rectangle inside the page
+ * it names are validity; pma / rotation / two regions over the same texels are
+ * policy — the rectangle moved across that line in issue #694, and the reason
+ * is stated where it now sits) and A20 (weight coherence is validity; requiring
+ * a mesh to be weighted at all is policy).
+ *
+ * A08 was the third until issue #574 retired its policy clause. It required a
+ * skin entry's placeholder to be spelled like the region it resolves to, under
+ * a renderer that resolves art by `path` and has never read a placeholder — so
+ * restating it as the renderer's own join made it a tautology over the validity
+ * half. The argument, with the renderer lines it is measured against, sits above
+ * `check('A08_…')`.
+ */
+export const ASSERTION_KIND: Readonly<Record<string, AssertionKind>> = {
+  A00_ROUNDTRIP_PARSE: 'validity',
+  A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS: 'validity',
+  A02_NO_BONE_TRANSFORM_KEY: 'validity',
+  A03_REGION_WIDTH_HEIGHT_FINITE: 'validity',
+  A04_MESH_TRIANGLES_AND_ENCODING: 'validity',
+  A05_CURVE_ARRAY_LENGTH: 'validity',
+  A06_ATLAS_PAGE_SIZE_MATCHES_PNG: 'validity', // mixed — see above
+  A07_ATLAS_TEXT_SHAPE: 'validity',
+  A08_REGION_NAMES_MATCH_ATTACHMENTS: 'validity', // no longer mixed — see above (#574)
+  A09_ANIMATION_DURATION_MATCHES_SPEC: 'validity',
+  A10_NO_NAN_AFTER_STEPPING: 'validity',
+  A11_NO_CLIPPING_ATTACHMENTS: 'renderer',
+  A12_NO_DARK_COLOR: 'renderer',
+  A13_MESH_BUDGET: 'renderer',
+  A14_NO_FULL_FRAME_MESH: 'renderer',
+  A15_IDLE_NO_MESH_BONE_KEYS: 'renderer',
+  A16_SKELETON_VERSION_4_3: 'validity',
+  A17_ATLAS_PAGE_FILES_EXIST: 'validity',
+  A18_DETERMINISTIC_EMIT: 'validity',
+  A19_OVERLAY_PNGS_HAVE_ALPHA: 'renderer',
+  A20_MESH_WEIGHTS_COHERENT: 'validity', // mixed — see above
+  A21_MESH_RIM_PINNED: 'archetype',
+  A22_MESH_UVS_IN_UNIT_RANGE: 'validity',
+  A23_PHYSICS_CONSTRAINT_EFFECTIVE: 'validity',
+  A24_AXIS_SPACE_STROKE: 'archetype',
+  A25_DETACHED_BONE_PARENTAGE: 'archetype',
+  A26_SLOT_DRAW_ORDER: 'archetype',
+  A27_REGION_NAME_MATCHES_PAGE_FILENAME: 'renderer',
+  A28_RIBBON_ROWS_SHARE_WEIGHTS: 'archetype',
+  A29_STROKE_WITHIN_CONTACT_DEPTH: 'archetype',
+  A30_STROKE_WITHIN_CAP_CONTAINMENT: 'archetype',
+  A31_DRAW_ORDER_OFFSETS_RESOLVE: 'validity',
+  A32_EVENT_KEYS_RESOLVE: 'validity',
+  A33_VERTEX_ATTACHMENT_GEOMETRY: 'validity',
+  A34_CONSTRAINT_TIMELINE_TARGETS: 'validity',
+  A35_DEFORM_KEYS_FIT_THE_ATTACHMENT: 'validity',
+  A36_PATH_CONSTRAINT_EFFECTIVE: 'validity',
+  A37_SLIDER_CONSTRAINT_EFFECTIVE: 'validity',
+  A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED: 'validity',
+  A39_DEFORM_KEEPS_TRIANGLE_WINDING: 'archetype',
+  A40_SLIDERS_COMPOSE_ON_A_SHARED_TARGET: 'validity',
+  A41_PHYSICS_SURVIVES_EDITOR_ROUND_TRIP: 'validity',
+  A42_DRIVEN_CONSTRAINTS_UPDATE_AFTER_THEIR_DRIVER: 'validity',
+  A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN: 'validity',
+  A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN: 'validity',
+  A45_SEPARABLE_COLOR_TIMELINES_OWN_THEIR_CHANNELS_AND_POSE_AS_WRITTEN: 'validity',
+  A46_SEQUENCE_ATTACHMENTS_SHOW_THE_FRAME_THE_FILE_STATES: 'validity',
+  A47_IK_CONSTRAINT_NOT_MUTED_THROUGHOUT: 'validity',
+  A48_TRANSFORM_CONSTRAINT_NOT_MUTED_THROUGHOUT: 'validity',
+};
+
+/** Whether `profile` runs a rule of `kind`: `spine` runs validity alone, `spine-html` every kind. */
+export function kindRunsUnder(kind: AssertionKind, profile: AssertionProfile): boolean {
+  return kind === 'validity' || profile === 'spine-html';
+}

package/src/assertions/mesh_kinds.ts

@@ -0,0 +1,56 @@
+/**
+ * What built a mesh, as the bodies that hold generator topology to its own
+ * rules ask it (issue #1025, step 4c of #380) — `A20`, `A21` and `A28`. Moved
+ * here from `validate()`'s closures unchanged but for what they read: a mesh
+ * entry of `./facts/mesh_attachments.ts` rather than a loaded attachment and
+ * the prelude's link map. Links nothing from the runtime.
+ */
+import type { RigInfo } from '../types.ts';
+import type { MeshEntry } from './facts/mesh_attachments.ts';
+
+/**
+ * What built this mesh. ring unless the rig says otherwise; absent rig info
+ * reads as ring (legacy).
+ *
+ * 🚨 `authored` is not a third topology, it is the ABSENCE of one rigc may
+ * assume. Geometry that came in through the rig spec was drawn by somebody
+ * with an editor, and its rim, its row pairing and its entry edge are
+ * whatever that person made them. The `||` fallback below used to hand such
+ * a mesh the string `ring`, and A21 then checked ring topology on a shape
+ * that was never a ring — 40 failures on correct data (issue #44).
+ *
+ * 🔗 A LINKED mesh borrows another attachment's geometry, so no generator
+ * topology is a claim about THIS attachment — and the ARTIFACT says which
+ * ones they are (the entry's `link`, read off the file's own `source` keys).
+ * It is read from there rather than off `meshKinds` for two reasons, and the
+ * second is the load-bearing one.
+ *
+ *   1. `meshKinds` is keyed by SLOT, and a link's slot is not its
+ *      geometry's: a link to a `ring` in another slot looked up the LINK's
+ *      slot, found nothing, and took the `|| 'ring'` fallback — issue #44's
+ *      own default, reached by a new route. Measured before this clause on
+ *      a correct rig (a ring on slot "sa", a link to it on slot "sb"):
+ *      **8 A21 failures**, `mesh "sb" rim vertex 0 is pinned to "a", not
+ *      the slot bone "b"`, one per hull vertex. The rim is pinned exactly
+ *      where the ring's own slot put it, which is the only place it could
+ *      be.
+ *   2. Writing the link into `meshKinds` instead would have overwritten
+ *      the source's kind wherever the two share a slot, which is the
+ *      commonest linked mesh there is — silencing A21 on the mesh rigc
+ *      DID build. A gate turned off by a feature is worse than a gate
+ *      that skips something it cannot measure.
+ */
+export function meshKindOf(mesh: MeshEntry, rig: RigInfo | undefined): RigInfo['meshKinds'][string] {
+  if (mesh.link !== null) return 'authored';
+  return rig?.meshKinds[mesh.slot] || 'ring';
+}
+
+/**
+ * Meshes whose topology is not rigc's to have an opinion about, by name and
+ * with the reason each one is on the list — the string several skips need.
+ */
+export function authoredMeshNames(list: readonly MeshEntry[], rig: RigInfo | undefined): string[] {
+  return list
+    .filter((m) => meshKindOf(m, rig) === 'authored')
+    .map((m) => (m.link === null ? `"${m.name}"` : `"${m.name}" (linked to "${m.link.source}")`));
+}

package/src/assertions/model/animated_bones.ts

@@ -0,0 +1,30 @@
+/**
+ * The model side's supply of `AnimatedBoneFacts` (issue #1025, step 4c of
+ * #380): an animation's bone timelines as the document lists them.
+ *
+ * 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.
+ *
+ * Links nothing from the runtime.
+ */
+import type { AnimatedBoneFacts } from '../facts/animated_bones.ts';
+import { isObj } from '../values.ts';
+import type { ReadDocument } from './parse.ts';
+
+export function modelAnimatedBones(read: ReadDocument): AnimatedBoneFacts {
+  const animations = Array.isArray(read.json.animations) ? read.json.animations.filter(isObj) : [];
+  return {
+    bonesKeyedBy: (name) => {
+      const animation = animations.find((a) => a.name === name);
+      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));
+    },
+  };
+}

package/src/assertions/model/atlas_pages.ts

@@ -0,0 +1,15 @@
+/**
+ * The model side's supply of `AtlasPageFacts` (issue #1025, step 4c of #380):
+ * the document's `pages` section, which `build` spells from the atlas text it
+ * writes (`pagesOfAtlas` in `src/model.ts`), so the page names are the ones
+ * the written atlas names, in its order and trimmed as the parser trims them.
+ * A `rigc-compiled/1` document states no pages, and reads as no atlas.
+ *
+ * Links nothing from the runtime.
+ */
+import type { AtlasPageFacts } from '../facts/atlas_pages.ts';
+import type { ReadDocument } from './parse.ts';
+
+export function modelAtlasPages(read: ReadDocument): AtlasPageFacts {
+  return { atlas: read.doc.pages === null ? null : { pages: read.doc.pages.map((page) => ({ name: page.name })) } };
+}

package/src/assertions/model/atlas_regions.ts

@@ -0,0 +1,76 @@
+/**
+ * The model side's supply of `AtlasRegionFacts` (issue #1025, step 4c of
+ * #380): the document's `pages` section — which `build` spells from the atlas
+ * text it writes (`pagesOfAtlas` in `src/model.ts`, the reader `PKR01` holds
+ * field for field to spine-core's `TextureAtlas`) — with each page's `pma` as
+ * a `rigc-compiled/3` document states it (issue #1026), or, for a `/2`
+ * document, which does not, as the caller gives it.
+ *
+ * - The pages and their regions in the document's order, which is the atlas
+ *   file's; each region carries the page it sits on.
+ * - `findRegion` is the core's lookup, called: `documentPageLookup`
+ *   (`src/core/uvs.ts`), the first region of exactly that spelling with pages
+ *   in order — the runtime's `findRegion`, measured there.
+ * - A `rigc-compiled/1` document states no pages, and reads as no atlas.
+ *
+ * ⚠️ On a `/2` document `pma` is the one value here the document does not
+ * hold. A caller that gives none, or gives a list that is not one value per
+ * page, is refused by name rather than read as `false`: a page's claim the
+ * caller did not state is not a claim of straight alpha. On a `/3` document a
+ * caller that gives one anyway is refused too (`refuseGivenBeside`): the
+ * document is the statement, and a second source for the same fact is how a
+ * verdict comes to read one value while the document says another.
+ *
+ * Links nothing from the runtime.
+ */
+import { documentPageLookup } from '../../core/uvs.ts';
+import type { ModelPageRegion } from '../../model.ts';
+import type { AtlasRegionEntry, AtlasRegionFacts, AtlasRegionPage } from '../facts/atlas_regions.ts';
+import type { ReadDocument } from './parse.ts';
+import { refuseGivenBeside, type ModelGiven } from './given.ts';
+
+export function modelAtlasRegions(read: ReadDocument, given: ModelGiven | undefined): AtlasRegionFacts {
+  refuseGivenBeside(read, given);
+  const pages = read.doc.pages;
+  if (pages === null) return { atlas: null };
+  // A rigc-compiled/3 document states each page's pma (issue #1026); `readModel` requires it on every /3 page.
+  const pma = read.doc.stated !== null ? pages.map((page) => page.pma) : given?.pma;
+  if (pma === undefined || pma.length !== pages.length || pma.some((v) => typeof v !== 'boolean')) {
+    throw new Error(`the caller gave ${pma === undefined ? 'no' : pma.length} page pma value(s) for the document's ${pages.length} page(s); a ${read.doc.spec} document does not state pma, so the model side cannot read a page without it`);
+  }
+  const outPages: AtlasRegionPage[] = [];
+  const regions: AtlasRegionEntry[] = [];
+  const byRecord = new Map<ModelPageRegion, AtlasRegionEntry>();
+  pages.forEach((page, i) => {
+    const at: AtlasRegionPage = { name: page.name, width: page.width, height: page.height, pma: pma[i] === true };
+    outPages.push(at);
+    for (const region of page.regions) {
+      const entry: AtlasRegionEntry = {
+        name: region.name,
+        page: at,
+        x: region.x,
+        y: region.y,
+        width: region.width,
+        height: region.height,
+        degrees: region.degrees,
+        offsetX: region.offsetX,
+        offsetY: region.offsetY,
+        originalWidth: region.originalWidth,
+        originalHeight: region.originalHeight,
+      };
+      regions.push(entry);
+      byRecord.set(region, entry);
+    }
+  });
+  const lookup = documentPageLookup(pages);
+  return {
+    atlas: {
+      pages: outPages,
+      regions,
+      findRegion: (name) => {
+        const found = lookup(name);
+        return found === null ? null : (byRecord.get(found.region) ?? null);
+      },
+    },
+  };
+}

package/src/assertions/model/constraints.ts

@@ -0,0 +1,207 @@
+/**
+ * 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
+ *   (`editorAnimationOrder`, the function the emitter is handed); in each the
+ *   groups in the runtime's order (`../facts/constraints.ts`' ⭐) and each
+ *   group's entries and 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 { editorAnimationOrder } 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,
+          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':
+      return { ...base, ik: { bones: record.bones, target: record.target, mix: record.mix } };
+    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[];
+}
+
+/** 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): ModelConstraintTimelineSource[] {
+  const { doc } = read;
+  const jsonAnimations = Array.isArray(read.json.animations) ? read.json.animations.filter(isObj) : [];
+  const out: ModelConstraintTimelineSource[] = [];
+  for (const name of editorAnimationOrder(doc.animations.map((a) => a.name))) {
+    const anim = doc.animations.find((a) => a.name === name);
+    if (anim === undefined) continue;
+    const c = anim.constraints;
+    for (const tl of c.ik) out.push({ animation: name, kind: 'ik', word: 'ik', name: tl.name, keys: tl.keys });
+    for (const tl of c.transform) out.push({ animation: name, kind: 'transform', word: 'transform', name: tl.name, keys: tl.keys });
+    for (const entry of 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 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) : [];
+    })();
+    c.slider.forEach((entry, i) => {
+      const listed = Array.isArray(jsonSliders[i]?.timelines) ? (jsonSliders[i].timelines as unknown[]).filter(isObj).map((t) => t.name) : [];
+      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): 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).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/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[];
+}