spine-rigc 0.26.0 → 0.28.0

package/docs/INGEST.md

@@ -237,7 +237,9 @@ Spine runtime plays it, whatever rigc's own rasteriser or validator thinks.
 `diff` takes two compiled skeletons and reports 49 measures in eight groups, plus two
 blocks that report and gate nothing: the `(reported)` measures beside `attachments`
 and `animations`, and the `skeleton` header block at the top, which measures the stage
-(issue #578). Both sides may be foreign; the interesting pairing during ingest is
+(issue #578). A ninth group of six joins them when something has paired the two sides'
+animations — `--as <candidate>=<reference>`, or one animation each side, which pairs by
+position (§1.3.1). Both sides may be foreign; the interesting pairing during ingest is
 **your transcription against the export it came from**:
 
 ```bash
@@ -326,6 +328,44 @@ attachment types and bone-binding shapes by draw-order position. That is how you
 *"the same rig with a different vocabulary"* from *"a different rig"*, and §4.2 is the
 recipe built on it.
 
+#### 1.3.1 Animations differ by name too — `--as`
+
+`bones` and `slots` are matched name-agnostically by their own shape. Animations have
+none: the candidate's `take01` and the reference's `arcs` are the same shot only
+because somebody says they are. Two things say it —
+
+```bash
+rigc diff work/t6/skeleton.json examples/6-arcs/export/6-arcs-pro.json --as take01=arcs
+```
+
+— and, with no flag, **one animation each side**, which pairs by position because there
+is exactly one reading of which shot is which. `--as` is repeatable, one pair each, and
+the candidate's name goes on the left, as it does in `bonedist`'s correspondence file.
+
+With the pairing in hand the `animations` section reports two figures like the other
+two sections, the second over the paired shots — `duration`, `timeline_kinds`,
+`key_counts`, `curve_kinds`, `draw_order`, `deform` — and the heading says which pairing
+it used:
+
+```
+  animations            mean 0.222  over 9 measures
+      1.000  count                        1/1         how many animations
+      0.000  names                        0/2         the animation names
+      …
+  animations (name-agnostic) mean 1.000  over 6 measures  — the same two skeletons compared with names thrown away, paired by position: take01=arcs, the one animation each side carries
+```
+
+Read that pair exactly as you read `bones`'s: **1.000 beside `names` 0.000** says the
+shot is right and its name is yours. ⛔ `names` never moves into the second block, and
+with two shots on each side and no `--as`, the block is **absent** rather than paired by
+declaration order — a candidate that declares its two shots the other way round would
+then read 0.000 across it and the report would be calling a guess a measurement.
+
+⚠️ An `--as` naming an animation a side does not have is **refused** with what that side
+does have, and so is one that pairs the same animation twice. Neither is dropped
+quietly: a typo that measured less than you asked for is a report about a pairing you
+did not state.
+
 ### 1.4 `check` — the instrument that does see coordinates
 
 ```bash
@@ -476,6 +516,19 @@ a default the source left to the format and the rebuild writes out). A blocker e
 non-zero and still writes both files. **Every code it can print has a row at the end
 of this section**, with its gutter, its effect on the exit code and what to do.
 
+⛔ **And it reads one generation.** Spine data is locked to the generation that
+exported it, and a mismatch is silent rather than loud: 4.3 takes constraints from the
+top-level `constraints` array alone, so a 4.0–4.2 file's `ik`/`transform`/`path`/
+`physics` arrays load as nothing at all — 1,302 shipped skeletons parsed on a 4.3
+runtime and loaded 0 of 8,672 constraints
+([#706](https://github.com/firejune/rigc/issues/706) row 1). So `ingest` reads
+`skeleton.spine` before it reads a field of the file, and a file from another
+generation is a blocker naming that generation and counting, **on that file**, what a
+4.3 reader loses by it. Reading such a file with *that generation's own* defaults is a
+different job — #706's item 2, a per-generation table extracted by machine from each
+runtime's `SkeletonJson` — and it is not in this tool, which is why the finding points
+at the policy rather than implying the file was read.
+
 **Two values are not in a skeleton**, so `ingest` asks rather than guesses:
 
 - **the stage** (`skeleton.width`/`height`) — `--stage x,y,w,h` is how you supply one
@@ -540,6 +593,7 @@ is the one failure a comparison of two sets cannot show you.
 | --- | --- | --- | --- | --- |
 | `ANIMATION_GROUP` | `BLOCK` | 1 | the animation carries a group the motion spec has no home for. The detail names the ten it does carry. `drawOrderFolder` is the group to know about: the runtime reads it and builds a timeline from it, and no export in this corpus carries one | transcribe that group by hand (§2), or accept that the rebuild does not carry it |
 | `ATTACHMENT_<TYPE>` | `BLOCK` | 1 | an attachment of a type rigc does not emit; the code is composed from the type, so on the one type left it reads `ATTACHMENT_POINT`. rigc emits region, mesh, linkedmesh, boundingbox, clipping and path — `linkedmesh` since [#691](https://github.com/firejune/rigc/issues/691), and `point` is the remaining deferred type | the rebuild will not have that attachment at all. `docs/SPEC_COVERAGE.md` part 1-6 says what a deferred type would carry |
+| `ATTACHMENT_LINK_GEOMETRY` | `LOSS` | 0 | a **linked mesh** that also states `uvs`, `triangles`, `vertices`, `hull` or `edges`. The parser returns from the `source` branch before `readVertices` (`SkeletonJson.ts:582-586`), so those keys are read by nothing at all and the attachment draws the geometry its `source` names; the rig spec has no home for them either, because `build` refuses geometry on a link by name. The detail lists the keys and the source. Until [#710](https://github.com/firejune/rigc/issues/710) the rebuild dropped them with no line at all, so an `ingest` that normalised somebody's file said nothing about it | nothing. The rebuild is the mesh the runtime was already drawing — and if those keys were the geometry you meant, take `source` off and author it as a mesh of its own. `A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN` is the same fact at the gate |
 | `ATTACHMENT_NAME` | `LOSS` | 0 | the attachment states a `name` and only **one** skin fills the placeholder, so rigc writes none — it composes `<skin>/<placeholder>` exactly where a placeholder is contested | nothing, unless something downstream looks that attachment up by the name the source gave it |
 | `ATTACHMENT_SEQUENCE` | `BLOCK` | 1 | the attachment carries a `sequence` block — a numbered image series — which the rig spec cannot say | the rebuild draws the single region the attachment names; the frames have to be driven some other way |
 | `ATTACHMENT_TIMELINE` | `BLOCK` | 1 | an attachment timeline other than `deform`, which is the only one the motion spec carries | transcribe it, or accept that the rebuild does not play it |
@@ -549,9 +603,11 @@ is the one failure a comparison of two sets cannot show you.
 | `CONSTRAINT_KEY_RESTATED` | `LOSS` | 0 | an `ik` or `transform` track whose keys do not all state the same fields. The motion spec takes one field set per track, so a field **any** key states is written on **every** key at the value the parser would have read there | nothing. Same values, larger file — the rebuild plays what the source plays |
 | `CONSTRAINT_TYPE` | `BLOCK` | 1 | a constraint whose `type` is none rigc knows, so the whole constraint is dropped rather than approximated | the rebuild has no such constraint; check the spelling before assuming the type is unsupported |
 | `DURATION` | `JUDGE` | 0 | skeleton JSON has no duration field at all. The largest key time is used, which is what a runtime plays to — and wrong for an animation that holds its last pose past its last key | if you know the real number, edit `duration` in the motion spec. It costs nothing: the declared duration is checked against the compiled keys |
+| `GENERATION_UNKNOWN` | `BLOCK` | 1 | `skeleton.spine` names no generation rigc knows, or the header states none at all. A version is read as its LEADING `major.minor` token — a down-export writes `4.0-from-4.1.24`, which is 4.0 data from a 4.1 editor — and it is never rounded to the nearest generation: a catalog that rounded handed 19 skeletons labelled `3.8.99` a 4.2 runtime and every one posed as NaN ([#706](https://github.com/firejune/rigc/issues/706) row 7) | check the string against the file you were handed. A real generation rigc does not list belongs on #706 item 1, with the string beside it |
+| `GENERATION_UNSUPPORTED` | `BLOCK` | 1 | the file is Spine data from another generation and this reader reads 4.3. The detail names the generation, the string it was read from, and what a 4.3 reader loses on **this** file: constraints parked in the top-level `ik` / `transform` / `path` / `physics` / `slider` arrays 4.3 folded into `constraints` and this reader never opens (row 1), bones carrying 4.2's `transform` where 4.3 spells `inherit` (row 6), and physics constraints omitting `inertia` / `damping`, whose default is not the same number in 4.2 as in 4.3 (row 4) | re-export the file as 4.3 from an editor of its own generation, or transcribe it by hand (§2). Reading it with **that generation's** defaults is #706 item 2 and is not in this tool |
 | `HEADER_BOOKKEEPING` | `LOSS` | 0 | a header field the editor writes and the rig spec has no home for — `hash`, `audio`. Dropped, and nothing reads it back | nothing. It is one of the three differences §2.3 measures on every editor export |
 | `HEADER_ORIGIN` | `LOSS` | 0 | the source declares an extent and omits `x`/`y`. Inside a declared extent an omitted origin **is** 0, so the spec states it — and the rebuild then spells two fields the source did not | nothing. Same box, different bytes — which is why byte identity is not the claim for an export that takes this branch |
-| `HEADER_REDERIVED` | `LOSS` | 0 | `skeleton.spine`: the rebuild writes the version of the runtime rigc links. The line says whether that is the same string the source states | nothing — but read the line: a 4.2 export rebuilds as 4.3 in that one field |
+| `HEADER_REDERIVED` | `LOSS` | 0 | `skeleton.spine`: the rebuild writes the version of the runtime rigc links. The line says whether that is the same string the source states | nothing — but read the line: a 4.2 export rebuilds as 4.3 in that one field, and a source from another generation raises `GENERATION_UNSUPPORTED` beside it, which is the blocker about the DATA rather than about the string |
 | `IK_KEY_FIELD` | `BLOCK` | 1 | a key field on an `ik` timeline that is not part of its shape | check the spelling; an unknown field is dropped from the rebuilt track |
 | `NO_STAGE` | `BLOCK` `JUDGE` | 1 | the skeleton declares no stage. It is a blocker with no `--stage`, and a **judgement** — exit 0 — when `--stage x,y,w,h` supplies one, because nothing measured the box you gave it | supply the box from the project the file came from. It cannot be derived: posing the rig gives the animated extent, which is a different number |
 | `PATH_LENGTHS` | `LOSS` | 0 | the source states a path attachment's `lengths` and rigc re-measures it as `PathConstraint` does | nothing. Dropping it is the correct reading: the field is the runtime's own four-sample forward difference, not an arc length |

package/docs/SPEC_COVERAGE.md

@@ -736,6 +736,7 @@ This is the split Part 4(c) needs. **Spine-validity** = the file is wrong for an
 | `A11_NO_CLIPPING_ATTACHMENTS` | **renderer-profile** | clipping attachments — "the renderer skips them silently" |
 | `A12_NO_DARK_COLOR` | **renderer-profile** | slot `dark`, `rgba2`/`rgb2` timelines — "parsed, then ignored". ⚠️ rigc **emits** the first two; a renderer that drops a construct is what a profile is for, not a reason not to emit it |
 | `A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN` | validity | a slot `dark` the parser drops or reads as NaN, an `rgba2` timeline on a slot with no dark colour to pose, or a key whose posed light/dark is not what it states |
+| `A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN` | validity | a linked mesh, in either spelling, that also states `uvs`, `triangles`, `vertices`, `hull` or `edges` — keys the `source` branch returns before reading, so the file says one mesh and every runtime draws its source's |
 | `A13_MESH_BUDGET` | **renderer-profile** | >4 mesh slots, >80 triangles per mesh |
 | `A14_NO_FULL_FRAME_MESH` | **renderer-profile** | a mesh spanning the whole stage |
 | `A19_OVERLAY_PNGS_HAVE_ALPHA` | **renderer-profile** | an overlay page that can never be transparent — no alpha channel and no `tRNS` chunk |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {

package/src/diff.ts

@@ -46,6 +46,34 @@
  *    wrong; name-agnostic low alone is impossible, since a wrong shape cannot
  *    have right names.
  *
+ *    ⭐ `animations` carries the same second comparison, and it arrived last
+ *    because it needs something the other two do not: a PAIRING. A bone is
+ *    paired with a bone by its depth and its child count, which the file
+ *    states; two animations have no such shape to be matched on, so the
+ *    candidate's `take01` and the reference's `arcs` are the same shot only
+ *    because somebody says they are. Until that was said, every animation
+ *    measure was keyed on the name — and a candidate that followed a brief
+ *    withholding it read `count` 1/1 and **0.000 on all eight measures below**,
+ *    on a shot with the same duration, the same timeline families and the same
+ *    key counts (issue #720). That is the *gate that cannot be passed* shape on
+ *    the measuring instrument rather than on the gate.
+ *
+ *    Two things say it, and nothing else does. `--as <candidate>=<reference>`
+ *    pairs them outright; failing that, **one animation each side** pairs by
+ *    position, because there is exactly one reading of which shot is which and
+ *    no name is consulted to reach it. Anything else — two against two, three
+ *    against one — has several readings, so the block is ABSENT rather than
+ *    guessed at, which is what `DiffSection.nameAgnostic` means by *"should say
+ *    so by having none"*. ⚠️ Guessing there is the failure this file is built
+ *    against: pairing two-against-two by position would score a candidate whose
+ *    two shots are declared in the other order 0.000 across the block and call
+ *    it a measurement.
+ *
+ *    🔒 `names` stays in the name-matched block alone, and that is the whole
+ *    point of the split rather than an oversight: the pair is read as *agnostic
+ *    1.000 with `names` 0.000*, which says the shot is right and its name is the
+ *    author's own.
+ *
  * 4. **A measure that cannot gate is not in the mean.** `section.reported`
  *    carries the measures `docs/GATE.md`'s *What never gates* calls
  *    unobservable by construction — *"could any reading of the frames have
@@ -121,6 +149,18 @@ export interface DiffAgnostic {
   /** Unweighted mean of the measures below. NOT a quality score either. */
   ratio: number;
   measures: DiffMeasure[];
+  /**
+   * How the two sides were put against each other, for a block that had to
+   * choose — `animations` alone today. Absent where the correspondence is the
+   * elements themselves and there was nothing to decide.
+   *
+   * ⚠️ It is data rather than a caption. A block whose figures depend on a
+   * pairing, printed without the pairing beside it, is a measurement of
+   * something the reader cannot name — and the two pairings say different
+   * things: `--as` is the caller's claim, position is this file's reading of a
+   * one-against-one roster.
+   */
+  pairedBy?: string;
 }
 
 /**
@@ -279,12 +319,21 @@ function sectionOf(
   measures: DiffMeasure[],
   nameAgnostic?: DiffMeasure[],
   reported?: DiffMeasure[],
+  pairedBy?: string,
 ): DiffSection {
   return {
     name,
     ratio: meanRatio(measures),
     measures,
-    ...(nameAgnostic === undefined ? {} : { nameAgnostic: { ratio: meanRatio(nameAgnostic), measures: nameAgnostic } }),
+    ...(nameAgnostic === undefined
+      ? {}
+      : {
+          nameAgnostic: {
+            ratio: meanRatio(nameAgnostic),
+            measures: nameAgnostic,
+            ...(pairedBy === undefined ? {} : { pairedBy }),
+          },
+        }),
     ...(reported === undefined ? {} : { reported: { measures: reported } }),
   };
 }
@@ -905,11 +954,154 @@ function keyingTotals(f: AnimationFacts): KeyingTotals {
   return { keys: sum(f.keys), timelines: sum(f.kinds), seconds: sum(f.duration) };
 }
 
-function diffAnimations(c: Json, r: Json): DiffSection {
+/** One animation on each side, said to be the same shot. */
+export interface DiffAnimationPair {
+  candidate: string;
+  reference: string;
+}
+
+/**
+ * What a caller may tell `diffSkeletons` that neither file can say itself.
+ *
+ * Only the animation pairing today, and it is an INPUT in the sense
+ * `bonedist`'s correspondence file is one: two skeletons cannot derive which of
+ * their shots are the same shot, so a value worked out here would be a guess
+ * reported as a measurement.
+ */
+export interface DiffOptions {
+  /** `--as <candidate>=<reference>`, in the order the caller stated them. */
+  animationPairs?: readonly DiffAnimationPair[];
+}
+
+/**
+ * The pairing used for `animations.agnostic.*`, or `null` when there is none.
+ *
+ * ⚠️ A stated pair naming an animation a side does not have is DROPPED and said
+ * so in `pairedBy`, rather than silently making the block narrower. `cmdDiff`
+ * refuses one by name before this is reached, so through the CLI the branch is
+ * unreachable; it exists because this module is exported and a caller of the
+ * API can state one.
+ */
+function pairAnimations(
+  a: AnimationFacts,
+  b: AnimationFacts,
+  stated: readonly DiffAnimationPair[],
+): { pairs: DiffAnimationPair[]; pairedBy: string } | null {
+  const spell = (p: DiffAnimationPair): string => `${p.candidate}=${p.reference}`;
+  if (stated.length > 0) {
+    const usable = stated.filter((p) => a.duration.has(p.candidate) && b.duration.has(p.reference));
+    if (usable.length === 0) return null;
+    const dropped = stated.filter((p) => !usable.includes(p));
+    return {
+      pairs: [...usable],
+      pairedBy:
+        `paired by --as: ${usable.map(spell).join(', ')}` +
+        (dropped.length === 0 ? '' : `; ${dropped.map(spell).join(', ')} named an animation a side does not have and was dropped`),
+    };
+  }
+  if (a.names.length === 1 && b.names.length === 1) {
+    const pair = { candidate: a.names[0], reference: b.names[0] };
+    return { pairs: [pair], pairedBy: `paired by position: ${spell(pair)}, the one animation each side carries` };
+  }
+  return null;
+}
+
+/**
+ * `f` restricted to the animations `label` names, with each one's name replaced
+ * by the label — `#0` for the first pair, `#1` for the second.
+ *
+ * That substitution is the whole of what makes the block name-agnostic: the
+ * measures below are the name-matched ones run again over facts whose keys are
+ * positions in the pairing. Everything else about them — the tolerance, the
+ * denominators, the histogram — is unchanged, which is what lets the two blocks
+ * be read against each other.
+ */
+function underLabels(f: AnimationFacts, label: ReadonlyMap<string, string>): AnimationFacts {
+  const keyed = <T>(m: Map<string, T>): Map<string, T> => {
+    const out = new Map<string, T>();
+    for (const [anim, v] of m) {
+      const to = label.get(anim);
+      if (to !== undefined) out.set(to, v);
+    }
+    return out;
+  };
+  // `kinds`, `keys` and `curves` are keyed `<anim>|<rest>`, so only the head is
+  // relabelled and the tail — the timeline's kind, the curve's shape — is what
+  // the histogram then intersects on.
+  const prefixed = (m: Map<string, number>): Map<string, number> => {
+    const out = new Map<string, number>();
+    for (const [k, v] of m) {
+      const bar = k.indexOf('|');
+      const to = label.get(k.slice(0, bar));
+      if (to === undefined) continue;
+      const id = `${to}${k.slice(bar)}`;
+      out.set(id, (out.get(id) ?? 0) + v);
+    }
+    return out;
+  };
+  return {
+    names: [...label.values()],
+    duration: keyed(f.duration),
+    kinds: prefixed(f.kinds),
+    keys: prefixed(f.keys),
+    curves: prefixed(f.curves),
+    events: keyed(f.events),
+    hasDrawOrder: keyed(f.hasDrawOrder),
+    hasDeform: keyed(f.hasDeform),
+  };
+}
+
+/**
+ * The six measures of `animations.agnostic.*`.
+ *
+ * ⛔ `names` is not among them, by construction — a block that threw the names
+ * away cannot then compare them. ⛔ Neither is `count`, which `bones` and
+ * `slots` do carry, and the difference is what the block is OVER: those two
+ * compare whole rosters, so their agnostic half has the same subject as their
+ * name-matched half and restates the count for a reader with one block open.
+ * This one is over the PAIRS. A `count` in it would either restate the roster
+ * figure — a different subject under the same heading — or count the pairs,
+ * which measures the flag rather than the two rigs. The roster figure is
+ * `animations.count`, and it is already name-free.
+ */
+function agnosticAnimationMeasures(a: AnimationFacts, b: AnimationFacts, pairs: readonly DiffAnimationPair[]): DiffMeasure[] {
+  const slot = (i: number): string => `#${i}`;
+  const ca = underLabels(a, new Map(pairs.map((p, i) => [p.candidate, slot(i)])));
+  const rb = underLabels(b, new Map(pairs.map((p, i) => [p.reference, slot(i)])));
+  return [
+    agreement(
+      'animations.agnostic.duration',
+      'each paired animation runs as long (last key time, within one frame)',
+      ca.duration,
+      rb.duration,
+      (x, y) => Math.abs(x - y) <= FRAME,
+    ),
+    histogram('animations.agnostic.timeline_kinds', 'the same timelines exist in the paired animations', ca.kinds, rb.kinds),
+    histogram('animations.agnostic.key_counts', 'those timelines carry as many keys', ca.keys, rb.keys),
+    histogram('animations.agnostic.curve_kinds', 'as many linear / stepped / bezier keys', ca.curves, rb.curves),
+    agreement(
+      'animations.agnostic.draw_order',
+      'a draw-order timeline is present or absent alike',
+      ca.hasDrawOrder,
+      rb.hasDrawOrder,
+      (x, y) => x === y,
+    ),
+    agreement(
+      'animations.agnostic.deform',
+      'a deform timeline is present or absent alike',
+      ca.hasDeform,
+      rb.hasDeform,
+      (x, y) => x === y,
+    ),
+  ];
+}
+
+function diffAnimations(c: Json, r: Json, pairsStated: readonly DiffAnimationPair[]): DiffSection {
   const a = animationFacts(c);
   const b = animationFacts(r);
   const at = keyingTotals(a);
   const bt = keyingTotals(b);
+  const paired = pairAnimations(a, b, pairsStated);
   const perSecond = (t: KeyingTotals): number => (t.seconds === 0 ? 0 : t.keys / t.seconds);
   const perTimeline = (t: KeyingTotals): number => (t.timelines === 0 ? 0 : t.keys / t.timelines);
   return sectionOf('animations', [
@@ -929,7 +1121,14 @@ function diffAnimations(c: Json, r: Json): DiffSection {
     agreement('animations.draw_order', 'a draw-order timeline is present or absent alike', a.hasDrawOrder, b.hasDrawOrder, (x, y) => x === y),
     agreement('animations.deform', 'a deform timeline is present or absent alike', a.hasDeform, b.hasDeform, (x, y) => x === y),
   ],
-  undefined,
+  // ── the same two skeletons' shots, paired rather than named (issue #720) ──
+  //
+  // Absent unless something pairs them — see `pairAnimations` and the header's
+  // point 3. `undefined` and not `[]`: a block with no measures in it prints a
+  // vacuous `mean 1.000 over 0 measures`, which is the false green this whole
+  // file is built to refuse, and `movedAgnosticMeasures` cannot tell it from a
+  // block that agreed about everything.
+  paired === null ? undefined : agnosticAnimationMeasures(a, b, paired.pairs),
   // ── reported (issue #20) ────────────────────────────────────────────────
   //
   // 🔍 What #20 asked and what was actually wrong. The issue proposed making key
@@ -981,7 +1180,8 @@ function diffAnimations(c: Json, r: Json): DiffSection {
         `(${at.timelines} vs ${bt.timelines}), compared as min/max at ${RATE_PLACES} decimal places. Read beside ` +
         '`key_density`: this one alone moving means the same keying spread over a different number of timelines.',
     ),
-  ]);
+  ],
+  paired?.pairedBy);
 }
 
 function eventFacts(root: Json): Map<string, string> {
@@ -1168,11 +1368,19 @@ function orientation(root: Json): Record<string, number> {
   };
 }
 
-export function diffSkeletons(candidate: unknown, reference: unknown): DiffReport {
+export function diffSkeletons(candidate: unknown, reference: unknown, options?: DiffOptions): DiffReport {
   const c = isObj(candidate) ? candidate : {};
   const r = isObj(reference) ? reference : {};
+  const animationPairs = options?.animationPairs ?? [];
   return {
-    sections: [diffBones(c, r), diffSlots(c, r), diffAttachments(c, r), diffConstraints(c, r), diffAnimations(c, r), diffEvents(c, r)],
+    sections: [
+      diffBones(c, r),
+      diffSlots(c, r),
+      diffAttachments(c, r),
+      diffConstraints(c, r),
+      diffAnimations(c, r, animationPairs),
+      diffEvents(c, r),
+    ],
     header: diffHeader(c, r),
     candidate: orientation(c),
     reference: orientation(r),
@@ -1466,8 +1674,18 @@ export function diffLines(report: DiffReport, labels: { candidate: string; refer
   );
   lines.push(...measureLines(report.header.measures, 'skeleton.'.length));
   lines.push('');
-  // Wide enough for `<longest section> (name-agnostic)`, so that a section's two
-  // headings line their figures up under each other and read as a pair.
+  // Wide enough for `bones (name-agnostic)` and `animations (reported)`, both
+  // exactly 21, so that most of a section's headings line their figures up
+  // under each other and read as a pair.
+  //
+  // ⚠️ Two headings are longer and push their own figure right instead:
+  // `attachments (reported)`, which has done so since that block existed, and
+  // `animations (name-agnostic)` (issue #720). Widening the column is the
+  // obvious repair and it is the wrong one — it moves every heading line of
+  // every report, and those lines are quoted verbatim in `docs/LADDER.md` and
+  // in the landed run records under `bench/runs/`, which are sealed. A
+  // cosmetic alignment is not worth a byte change in every transcript already
+  // written, and the overflow is visible rather than silent.
   const head = (label: string, ratio: number, n: number): string =>
     `  ${label.padEnd(21)} mean ${fmt(ratio)}  over ${n} measures`;
   for (const section of report.sections) {
@@ -1478,7 +1696,9 @@ export function diffLines(report: DiffReport, labels: { candidate: string; refer
       lines.push('');
       lines.push(
         `${head(`${section.name} (name-agnostic)`, agnostic.ratio, agnostic.measures.length)}` +
-          '  — the same two skeletons compared with names thrown away',
+          '  — the same two skeletons compared with names thrown away' +
+          // The pairing is part of the figure, not decoration: see `DiffAgnostic.pairedBy`.
+          (agnostic.pairedBy === undefined ? '' : `, ${agnostic.pairedBy}`),
       );
       lines.push(...measureLines(agnostic.measures, section.name.length + '.agnostic.'.length));
     }
@@ -1506,6 +1726,12 @@ export function diffLines(report: DiffReport, labels: { candidate: string; refer
   lines.push('  comparisons, not two halves of one: name-agnostic 1.000 beside a low');
   lines.push('  name-matched figure means the shape is right and the vocabulary differs.');
   lines.push('');
+  lines.push('  `animations` carries the same pair, and only once something has PAIRED the two');
+  lines.push('  sides\' shots: `--as <candidate>=<reference>`, or one animation each side, which');
+  lines.push('  pairs by position. With neither there is no reading of which shot is which, so');
+  lines.push('  the block is absent rather than guessed — and its absence beside `names` 0.000');
+  lines.push('  is the report saying the candidate named its shots itself and nothing said how.');
+  lines.push('');
   lines.push('  `skeleton` is the file\'s own header block and reports two measures for the stage.');
   lines.push('  It has no mean for the reason a `(reported)` block never does, and it never');
   lines.push('  gates for two: no reading of the frames recovers a setup-pose bounding box, and');

package/src/generation.ts

@@ -0,0 +1,138 @@
+/**
+ * Which Spine data generation a skeleton's own version string names.
+ *
+ * ## Why this is one function and not a regex per caller
+ *
+ * Spine data is locked to the generation that exported it, and a mismatch fails
+ * **silently**: 4.3 takes constraints from the top-level `constraints` array
+ * alone, so a 4.0–4.2 file parses clean with none of them — measured across
+ * 1,302 shipped skeletons that loaded 0 of 8,672 constraints
+ * ([#706](https://github.com/firejune/rigc/issues/706) row 1). rigc is where
+ * that knowledge lives for the tools around it (#706 *Ownership*), and living
+ * in one place means one reader of `skeleton.spine`:
+ * `A16_SKELETON_VERSION_4_3` asks this function for its verdict, and `ingest`
+ * asks it before it reads a field of the file.
+ *
+ * ## What is here, and what is deliberately not
+ *
+ * This is #706's item **1**, and nothing else. Item **2** — the per-generation
+ * table of key renames, array shapes and `getValue(map, key, default)` defaults,
+ * extracted by machine from each runtime branch's `SkeletonJson` — is not here,
+ * and neither is item **4**'s conversion utility. So this module reads a string
+ * and names a generation. It does not read a file, apply another generation's
+ * defaults, or convert anything, and a caller that meets data from another
+ * generation has to say so out loud rather than read it anyway.
+ *
+ * ## The grammar, and the two rules in it
+ *
+ * A version string is `MAJOR.MINOR`, an optional chain of `-from-MAJOR.MINOR`,
+ * then an optional `.PATCH` and an optional `-SUFFIX` after that. The shipped
+ * strings #706 lists are `3.8.99`, `4.0.33`, `4.0-from-4.1.24`,
+ * `4.0-from-4.1-from-4.2.29`, `4.1-from-4.2.33`, `4.2.09-beta`, `4.2.43`,
+ * `4.3.26` and `4.3.75-beta`.
+ *
+ * 1. **The leading token is the generation.** `4.0-from-4.1.24` is 4.0 data
+ *    written by a 4.1 editor — a *down-export* — and all 418 such-or-plain 4.0
+ *    files and 101 4.1 files in #706's corpus load and render on the 4.0 / 4.1
+ *    runtimes with 0 failures. Reading the trailing token would hand them the
+ *    wrong runtime, which is row 7's defect with extra steps.
+ * 2. **Every token has to be a generation this module knows, and the chain has
+ *    to ascend.** A down-export comes *from* a newer editor, so `4.0-from-4.1`
+ *    is a down-export and `4.3-from-4.2` is not a version string this reader
+ *    can account for. Both rules answer `null`, which is rule 3.
+ * 3. **Unknown is `null`, never the nearest.** A catalog builder gave 19
+ *    skeletons labelled `3.8.99` the nearest runtime it had; they loaded, and
+ *    posed 238 of 248 bones as NaN (#706 row 7). `null` is what a caller has to
+ *    act on, and it is why this returns a union rather than a number to compare.
+ *
+ * ⭐ Rules 2 and 3 together are also what keeps `A16`'s accepted set **exactly**
+ * what its own regex accepted before this module existed: 4.3 is the highest
+ * generation here, nothing can ascend above it, so no `-from-` string is ever
+ * read as 4.3 and `A16` still accepts `4.3`, `4.3.<patch>` and
+ * `4.3.<patch>-<suffix>` and those alone. The cost is stated rather than hidden:
+ * a future editor down-exporting as `4.3-from-4.4.1` reads as `null` here and is
+ * refused by name until that generation is added — which is #706 policy 1's own
+ * answer ("an unknown generation gets no runtime") rather than a gap in this one.
+ *
+ * ## Purity
+ *
+ * No clock, no randomness, no filesystem, no network, no `spine-core`. It reads
+ * strings and small plain objects and nothing else.
+ */
+
+/** A generation of Spine data — the `MAJOR.MINOR` pair a runtime is locked to. */
+export type SpineGeneration = '3.8' | '4.0' | '4.1' | '4.2' | '4.3';
+
+/**
+ * Every generation this module knows, oldest first.
+ *
+ * The order is load-bearing twice: a down-export chain has to ascend through it,
+ * and a caller listing "the generations rigc knows" reads it here rather than
+ * typing five strings next to a sixth.
+ */
+export const SPINE_GENERATIONS: readonly SpineGeneration[] = ['3.8', '4.0', '4.1', '4.2', '4.3'];
+
+/**
+ * `MAJOR.MINOR`, then the `-from-` chain, then the patch and its suffix.
+ *
+ * Anchored at both ends on purpose: `4.30` and `4.3.1.2` are not version strings
+ * and a partial match would read them as 4.3. The suffix shape is the one the
+ * editor writes for a pre-release (`4.3.75-beta`, which every one of the twelve
+ * official example exports declares) and is the same one `A16`'s own regex
+ * carried, character for character, before this module took it over.
+ */
+const VERSION_STRING = /^(\d+\.\d+)((?:-from-\d+\.\d+)*)(?:\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.+-]*)?)?$/;
+
+/**
+ * The generation a `skeleton.spine` string names, or `null` for one this module
+ * cannot account for.
+ *
+ * `null` is never the nearest generation and never a guess — see rule 3 above.
+ */
+export function spineGeneration(version: string): SpineGeneration | null {
+  const match = VERSION_STRING.exec(version);
+  if (match === null) return null;
+  const chain = match[2] === '' ? [] : match[2].split('-from-').slice(1);
+  const known = SPINE_GENERATIONS as readonly string[];
+  const steps = [match[1], ...chain].map((token) => known.indexOf(token));
+  if (steps.some((at) => at < 0)) return null;
+  for (let i = 1; i < steps.length; i++) if (steps[i] <= steps[i - 1]) return null;
+  return SPINE_GENERATIONS[steps[0]];
+}
+
+/**
+ * The constraint kinds a skeleton can carry as a **top-level array**, which 4.3
+ * folded into one `constraints` array with a `type` on each entry.
+ *
+ * 4.3 reads `constraints` and nothing else, so an array under any of these names
+ * loads without an error and the constraints in it are simply not there — #706
+ * row 1, and what `A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS` refuses in emitted
+ * data. `slider` never had a top-level form (sliders are 4.3's own), and it is
+ * on this list for the same reason as the other four: a constraint parked
+ * outside `constraints` vanishes whatever its kind, and a list with a hole in it
+ * is a rule with a hole in it.
+ */
+export const TOPLEVEL_CONSTRAINT_ARRAYS: readonly string[] = ['ik', 'transform', 'path', 'physics', 'slider'];
+
+/**
+ * The bone key 4.2 spelled `transform` and 4.3 spells `inherit`.
+ *
+ * The old key does not throw and does not warn — it is an unknown field, so the
+ * bone falls back to Normal inheritance (#706 row 6, and
+ * `A02_NO_BONE_TRANSFORM_KEY`).
+ */
+export const LEGACY_BONE_INHERIT_KEY = 'transform';
+
+/**
+ * The physics-constraint fields whose **omitted default** is not the same number
+ * in 4.2 as in 4.3.
+ *
+ * JSON omits a field equal to the parser's default, so the same file means two
+ * different constraints under two readers: `inertia` and `damping` both default
+ * to 1 in 4.2's `SkeletonJson` and to 0.5 and 0.85 in 4.3's (#706 row 4, which
+ * also counts 111 shipped constraints omitting `inertia`). The numbers are not
+ * repeated here deliberately — a hand-copied table is what #706 policy 3 exists
+ * to refuse, and item 2's generated table is where they belong. What a caller
+ * needs from this list is which fields to *count*, and that is what it is.
+ */
+export const PHYSICS_FIELDS_WHOSE_DEFAULT_MOVED: readonly string[] = ['inertia', 'damping'];