rig-c 0.0.0-stage → 2.20.4

package/src/diff.ts

@@ -0,0 +1,2252 @@
+/**
+ * rigc diff — structural comparison of two skeletons, section by section.
+ *
+ * The benchmark ladder needs a yardstick, and a yardstick that reports one
+ * number is not one. A single "87% match" cannot distinguish a rig with the
+ * right skeleton and the wrong timing from a rig with the right timing and the
+ * wrong skeleton, and those are opposite diagnoses. So this reports a ratio per
+ * MEASURE, grouped into sections, and refuses to combine them: the section
+ * ratios are means of their own measures and are labelled as such, and there is
+ * no report-wide score at all.
+ *
+ * Three properties the measures are built to have:
+ *
+ * 1. **`diff X X` is 1.000 everywhere.** Every measure is a comparison of two
+ *    derived quantities, never a judgement, so a file against itself has
+ *    nothing to differ on. The CLI has a `--self-check` for exactly this, and
+ *    the selftest runs it: a comparison tool that cannot recognise identity is
+ *    reporting noise, and noise looks like a small honest gap.
+ * 2. **A difference moves as few measures as possible.** Reordering slots must
+ *    not disturb the slot-to-bone binding figure, so bindings are compared by
+ *    name and order is a separate measure. This is what makes the report
+ *    diagnostic rather than merely quantitative.
+ * 3. **Name-agnostic figures sit beside name-matched ones.** A candidate that
+ *    builds the right tree with its own names scores zero on `parent_by_name`
+ *    and full marks on `depth_histogram` / `degree_sequence`. Reporting only
+ *    the first would call a correct rig a total failure; reporting only the
+ *    second would call any 14-bone tree a match. Both, separately, or neither
+ *    is honest.
+ *
+ *    ⭐ That held at the MEASURE level and not at the SECTION level, which is
+ *    where a reader actually looks (issue #21). `bones` rolled eight measures
+ *    into one mean, five of them gated on the same one-name-in-common
+ *    condition — the naming figure counted five times, not five findings — so
+ *    a rig with a structurally identical tree and its own vocabulary read
+ *    `bones=0.567` and a reader who did not open the table under it read "the
+ *    skeleton is wrong" when the skeleton was right. So `bones` and `slots`
+ *    now carry a SECOND, independent comparison in `nameAgnostic`: the same
+ *    two skeletons compared with names thrown away entirely.
+ *
+ *    The two are not a partition of one mean. They are two comparisons of one
+ *    section, with their own measure sets, and neither is a subset of the
+ *    other — `section.ratio` is unchanged, to the digit, from what it has
+ *    always been, so every `bench.json` already on disk stays comparable.
+ *    Read them as a pair: name-agnostic 1.000 with name-matched low says the
+ *    shape is right and the vocabulary differs; both low says the rig is
+ *    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
+ *    decided it?"*, and for these the answer is no whatever the frames are.
+ *    They are printed beside the section, with their conventions, and they have
+ *    **no mean at all**: an average of "does this mesh declare edges" and "how
+ *    many keys per second" is a number with no referent, and a section mean is
+ *    the one figure a stored ladder row quotes. Same discipline as point 3 and
+ *    the same reason — `section.ratio` does not move when a reported measure is
+ *    added, so every `bench.json` already on disk stays comparable — with one
+ *    addition of its own: *reports, never gates* becomes a property of where the
+ *    measure sits rather than of a sentence somebody has to remember.
+ *
+ * Pure JSON reading — no spine-core, no filesystem. Validity is `validate.ts`'s
+ * job and this file assumes nothing about it. In particular the name-agnostic
+ * measures resolve nothing through the atlas: see `attachments.region_size`.
+ * The per-frame pose comparison that DOES need spine-core is a separate
+ * instrument — [`bonedist.ts`](bonedist.ts), the ladder's stage 3.
+ */
+import { constraintAt } from './rig.ts';
+import { walkTimelines } from './timelines.ts';
+// Type only, and erased: the values themselves are read by `skeletonValues` in
+// `src/validate.ts`, which is one of the three modules CLAUDE.md allows to link
+// spine-core. This file stays what its header says it is — see
+// `diffSkeletonValues` for why the reading and the comparing are split there.
+import type { SkeletonValue } from './validate.ts';
+
+type Json = Record<string, unknown>;
+
+function isObj(v: unknown): v is Json {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function arr(v: unknown): unknown[] {
+  return Array.isArray(v) ? v : [];
+}
+
+function objs(v: unknown): Json[] {
+  return arr(v).filter(isObj);
+}
+
+function str(v: unknown): string | null {
+  return typeof v === 'string' ? v : null;
+}
+
+function num(v: unknown): number | null {
+  return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
+/** One comparable quantity. `total` 0 means neither side had anything to compare. */
+export interface DiffMeasure {
+  /** Stable dotted id, e.g. `bones.parent_by_name`. Tests name these. */
+  id: string;
+  matched: number;
+  total: number;
+  ratio: number;
+  /** What the measure is, in one line, for the human table. */
+  what: string;
+  /** Set when the measure is vacuous or otherwise needs a caveat. */
+  note?: string;
+}
+
+/**
+ * A second comparison of one section, made without consulting a name anywhere.
+ *
+ * Its `ratio` is an unweighted mean of its OWN measures and is not comparable,
+ * term for term, with the section's — the two sets overlap but neither contains
+ * the other. `count` / `depth_histogram` / `degree_sequence` appear in both,
+ * once under their section id and once under `<section>.agnostic.*`, so that
+ * each report reads on its own without the other open beside it.
+ */
+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;
+}
+
+/**
+ * Measures that are **reported and never gate**, with no mean over them.
+ *
+ * `docs/GATE.md`'s *What never gates* seals off "anything unobservable by
+ * construction", and its test is *could any reading of the frames have decided
+ * it?* — mesh `edges` draw no pixel at all, and two keyings of one curve render
+ * the same frames at every rate. Those measures still belong in the report:
+ * `bench` is a structural comparison against the reference export and a feature
+ * the reference declares that a candidate drops is a finding, whether or not a
+ * clause may read it.
+ *
+ * ⚠️ No `ratio` field, deliberately, and not for lack of arithmetic. The
+ * measures here have unlike units — a presence share, a keys-per-second
+ * agreement — so their mean would be a number with no referent, and the one
+ * number a stored ladder row quotes per section is `DiffSection.ratio`. Keeping
+ * these out of it is what lets a measure be added without moving a figure
+ * somebody has already recorded.
+ */
+export interface DiffReported {
+  measures: DiffMeasure[];
+}
+
+export interface DiffSection {
+  name: string;
+  /** Unweighted mean of this section's measures. NOT a quality score. */
+  ratio: number;
+  measures: DiffMeasure[];
+  /**
+   * The same section compared with names thrown away — `bones` and `slots`
+   * only, because they are the two sections whose measures are dominated by
+   * name-keyed ones (#21). Absent elsewhere rather than empty: a section with
+   * no name-agnostic comparison defined should say so by having none.
+   */
+  nameAgnostic?: DiffAgnostic;
+  /**
+   * Measures reported beside this section and folded into nothing. Absent
+   * rather than empty, for the same reason `nameAgnostic` is.
+   */
+  reported?: DiffReported;
+}
+
+export interface DiffReport {
+  sections: DiffSection[];
+  /**
+   * The `skeleton` block itself — measured, and reported beside the sections
+   * rather than inside one (issue #578).
+   *
+   * ⭐ It is a `DiffReported` and not a seventh `DiffSection`, and the reason is
+   * the one thing a section must have: a `ratio`. A section's mean is the figure
+   * a stored `bench.json` row quotes, and these measures cannot be in one —
+   * `docs/GATE.md`'s *What never gates* covers them twice over, so a `skeleton`
+   * section would carry either a vacuous `mean 1.000 over 0 measures` (the false
+   * green this file exists to refuse) or a nullable `ratio` every reader of every
+   * other section would then have to handle. `DiffReported` already models
+   * exactly "measures with no mean over them", which is what the header is.
+   *
+   * ⚠️ Not optional, deliberately: a block that may be absent is a block that can
+   * silently stop being emitted, and `movedReportedMeasures` over an absent one
+   * is the empty list — indistinguishable from one that is all 1.000. The
+   * selftest asserts its COUNT for the same reason it does for the others.
+   */
+  header: DiffReported;
+  /** Raw counts either side, for orientation. Never combined into anything. */
+  candidate: Record<string, number>;
+  reference: Record<string, number>;
+}
+
+// ---------------------------------------------------------------------------
+// measure primitives
+// ---------------------------------------------------------------------------
+
+const FRAME = 1 / 60;
+
+function ratioOf(matched: number, total: number): number {
+  return total === 0 ? 1 : matched / total;
+}
+
+function measure(id: string, what: string, matched: number, total: number, note?: string): DiffMeasure {
+  return {
+    id,
+    what,
+    matched,
+    total,
+    ratio: ratioOf(matched, total),
+    ...(total === 0 ? { note: note ?? 'neither side has any' } : note ? { note } : {}),
+  };
+}
+
+/** |A ∩ B| over |A ∪ B| — the set measure. */
+function jaccard(id: string, what: string, a: Set<string>, b: Set<string>): DiffMeasure {
+  let shared = 0;
+  for (const x of a) if (b.has(x)) shared++;
+  return measure(id, what, shared, a.size + b.size - shared);
+}
+
+/**
+ * Histogram intersection: sum of the per-bucket minima over the larger total.
+ * Used for every name-agnostic comparison, because it degrades smoothly — one
+ * bone in the wrong bucket costs one bone, not the whole measure.
+ */
+function histogram(id: string, what: string, a: Map<string, number>, b: Map<string, number>): DiffMeasure {
+  let shared = 0;
+  for (const [k, v] of a) shared += Math.min(v, b.get(k) ?? 0);
+  const sum = (m: Map<string, number>) => [...m.values()].reduce((x, y) => x + y, 0);
+  return measure(id, what, shared, Math.max(sum(a), sum(b)));
+}
+
+/** Longest common subsequence length — order agreement that survives an insert. */
+function lcs(a: string[], b: string[]): number {
+  const rows: number[][] = Array.from({ length: a.length + 1 }, () => new Array<number>(b.length + 1).fill(0));
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      rows[i][j] = a[i - 1] === b[j - 1] ? rows[i - 1][j - 1] + 1 : Math.max(rows[i - 1][j], rows[i][j - 1]);
+    }
+  }
+  return rows[a.length][b.length];
+}
+
+function counted(values: Iterable<string>): Map<string, number> {
+  const out = new Map<string, number>();
+  for (const v of values) out.set(v, (out.get(v) ?? 0) + 1);
+  return out;
+}
+
+/**
+ * Agreement over the names both sides have, scored against the larger roster.
+ *
+ * ⚠️ The denominator is deliberately `max(candidate, reference)` rather than the
+ * shared count. Scoring only the shared names would let a candidate with two of
+ * twenty bones report 1.000 for "parents agree", which is the shape of a
+ * measurement that flatters whatever is missing.
+ */
+function agreement<T>(
+  id: string,
+  what: string,
+  a: Map<string, T>,
+  b: Map<string, T>,
+  same: (x: T, y: T) => boolean,
+): DiffMeasure {
+  let agree = 0;
+  for (const [k, v] of a) {
+    const other = b.get(k);
+    if (other !== undefined && same(v, other)) agree++;
+  }
+  return measure(id, what, agree, Math.max(a.size, b.size));
+}
+
+function meanRatio(measures: DiffMeasure[]): number {
+  return measures.length === 0 ? 1 : measures.reduce((s, m) => s + m.ratio, 0) / measures.length;
+}
+
+function sectionOf(
+  name: string,
+  measures: DiffMeasure[],
+  nameAgnostic?: DiffMeasure[],
+  reported?: DiffMeasure[],
+  pairedBy?: string,
+): DiffSection {
+  return {
+    name,
+    ratio: meanRatio(measures),
+    measures,
+    ...(nameAgnostic === undefined
+      ? {}
+      : {
+          nameAgnostic: {
+            ratio: meanRatio(nameAgnostic),
+            measures: nameAgnostic,
+            ...(pairedBy === undefined ? {} : { pairedBy }),
+          },
+        }),
+    ...(reported === undefined ? {} : { reported: { measures: reported } }),
+  };
+}
+
+/**
+ * How many decimal places a reported RATE is compared at.
+ *
+ * The counts column prints `matched`/`total` verbatim, so a rate measured to
+ * full float precision would print seventeen digits of it. Rounding here rather
+ * than at print time keeps `ratio === matched / total` true in the data — a
+ * printed figure that is not the compared quantity is the same defect as a
+ * measure nobody asserts on, one layer down.
+ */
+const RATE_PLACES = 3;
+
+function atPlaces(n: number): number {
+  const scale = 10 ** RATE_PLACES;
+  return Math.round(n * scale) / scale;
+}
+
+/**
+ * Two rates compared as `min / max`, so that identity reads 1.000 and either
+ * direction of disagreement reads below it.
+ *
+ * ⚠️ The direction is the whole point of the measure and a ratio cannot carry
+ * it, so `note` states both rates and which side is the bigger one. A histogram
+ * intersection over the same quantity reads 421/1339 whether the candidate has
+ * a third of the reference's keys or three times them — that ambiguity is what
+ * [issue #20](https://github.com/firejune/rigc/issues/20) turned on, and a
+ * figure that repeated it would be the second copy of the same defect.
+ */
+function rateAgreement(id: string, what: string, unit: string, a: number, b: number, convention: string): DiffMeasure {
+  const candidate = atPlaces(a);
+  const reference = atPlaces(b);
+  const lo = Math.min(candidate, reference);
+  const hi = Math.max(candidate, reference);
+  const direction =
+    hi === 0
+      ? 'neither side has any'
+      : candidate === reference
+        ? 'the two agree'
+        : reference === 0
+          ? 'the reference has none'
+          : candidate === 0
+            ? 'the candidate has none'
+            : `candidate carries ${(candidate / reference).toFixed(2)}x — ${candidate > reference ? 'OVER' : 'UNDER'}-keyed`;
+  return {
+    id,
+    what,
+    matched: lo,
+    total: hi,
+    ratio: ratioOf(lo, hi),
+    note: `candidate ${candidate} vs reference ${reference} ${unit}; ${direction}. ${convention}`,
+  };
+}
+
+/**
+ * Order agreement over a sequence of SHAPES rather than names — the
+ * name-agnostic half of an `order` measure.
+ *
+ * LCS over the signatures, against the larger roster, exactly as the
+ * name-matched `order` measures do it, so the two read on the same scale. Two
+ * elements with the same signature are interchangeable here and swapping them
+ * is correctly invisible: name-agnostically they ARE the same element. The
+ * name-matched `order` measure is what catches that swap.
+ */
+function orderShape(id: string, what: string, a: string[], b: string[]): DiffMeasure {
+  return measure(id, what, lcs(a, b), Math.max(a.length, b.length));
+}
+
+// ---------------------------------------------------------------------------
+// per-section extraction
+// ---------------------------------------------------------------------------
+
+interface BoneFacts {
+  order: string[];
+  parent: Map<string, string | null>;
+  hasLength: Map<string, boolean>;
+  hasInherit: Map<string, boolean>;
+  depths: Map<string, number>;
+  children: Map<string, number>;
+}
+
+function boneFacts(root: Json): BoneFacts {
+  const bones = objs(root.bones);
+  const order: string[] = [];
+  const parent = new Map<string, string | null>();
+  const hasLength = new Map<string, boolean>();
+  const hasInherit = new Map<string, boolean>();
+  const children = new Map<string, number>();
+  for (const b of bones) {
+    const name = str(b.name);
+    if (name === null) continue;
+    order.push(name);
+    parent.set(name, str(b.parent));
+    hasLength.set(name, 'length' in b);
+    hasInherit.set(name, 'inherit' in b);
+    children.set(name, children.get(name) ?? 0);
+  }
+  for (const [, p] of parent) {
+    if (p !== null) children.set(p, (children.get(p) ?? 0) + 1);
+  }
+  // Depth by walking to the root. A parent declared after its child is invalid
+  // Spine, so the walk terminates on any file the parser would accept; the
+  // `seen` guard is there so a malformed candidate cannot hang the comparison.
+  const depths = new Map<string, number>();
+  for (const name of order) {
+    let depth = 0;
+    const seen = new Set<string>([name]);
+    for (let at = parent.get(name) ?? null; at !== null; at = parent.get(at) ?? null) {
+      depth++;
+      if (seen.has(at)) break;
+      seen.add(at);
+    }
+    depths.set(name, depth);
+  }
+  return { order, parent, hasLength, hasInherit, depths, children };
+}
+
+/**
+ * The shape of a bone nothing declares — a slot bound to a name no bone
+ * carries. A real answer rather than a gap: it says "this hangs off nothing".
+ */
+const UNDECLARED = '?';
+
+/**
+ * A bone's place in the tree, written without its name: how far it sits from a
+ * root, and how many children hang off it. `d1c3` is "one hop down, three
+ * children".
+ *
+ * Nothing else in a bone's declaration is name-free AND structural. `x`, `y`,
+ * `rotation`, `scale` are the setup pose, which this section does not compare
+ * on either side of the split; `length` and `inherit` are compared by name
+ * above and have no name-free counterpart, because there is no way to say
+ * WHICH bone is missing its length without naming one.
+ */
+function boneShape(facts: BoneFacts, name: string): string {
+  if (!facts.parent.has(name)) return UNDECLARED;
+  return `d${facts.depths.get(name) ?? 0}c${facts.children.get(name) ?? 0}`;
+}
+
+function boneShapes(facts: BoneFacts): string[] {
+  return facts.order.map((n) => boneShape(facts, n));
+}
+
+function diffBones(c: Json, r: Json): DiffSection {
+  const a = boneFacts(c);
+  const b = boneFacts(r);
+  const shared = a.order.filter((n) => b.parent.has(n));
+  const max = Math.max(a.order.length, b.order.length);
+  const aShapes = boneShapes(a);
+  const bShapes = boneShapes(b);
+  return sectionOf(
+    'bones',
+    [
+      measure('bones.count', 'how many bones', Math.min(a.order.length, b.order.length), max),
+      jaccard('bones.names', 'the bone names themselves', new Set(a.order), new Set(b.order)),
+      agreement('bones.parent_by_name', 'each bone hangs off the same parent', a.parent, b.parent, (x, y) => x === y),
+      measure(
+        'bones.order',
+        'the bones are declared in the same order',
+        lcs(shared, b.order.filter((n) => a.parent.has(n))),
+        max,
+      ),
+      agreement('bones.length_present', 'a setup `length` is present or absent alike', a.hasLength, b.hasLength, (x, y) => x === y),
+      agreement('bones.inherit_present', 'a setup `inherit` is present or absent alike', a.hasInherit, b.hasInherit, (x, y) => x === y),
+      histogram(
+        'bones.depth_histogram',
+        'NAME-AGNOSTIC: as many bones at each depth',
+        counted([...a.depths.values()].map(String)),
+        counted([...b.depths.values()].map(String)),
+      ),
+      histogram(
+        'bones.degree_sequence',
+        'NAME-AGNOSTIC: as many bones with each child count',
+        counted([...a.children.values()].map(String)),
+        counted([...b.children.values()].map(String)),
+      ),
+    ],
+    // The tree compared as a tree — no name is consulted anywhere below.
+    [
+      measure('bones.agnostic.count', 'how many bones', Math.min(a.order.length, b.order.length), max),
+      histogram(
+        'bones.agnostic.depth_histogram',
+        'as many bones at each depth',
+        counted([...a.depths.values()].map(String)),
+        counted([...b.depths.values()].map(String)),
+      ),
+      histogram(
+        'bones.agnostic.degree_sequence',
+        'as many bones with each child count',
+        counted([...a.children.values()].map(String)),
+        counted([...b.children.values()].map(String)),
+      ),
+      // Strictly stronger than the two above it, and it earns its place for
+      // that reason: two trees can hold the same depths and the same child
+      // counts while pairing them up differently — a deep leaf and a shallow
+      // fork against a shallow leaf and a deep fork. This asks for the pair.
+      histogram(
+        'bones.agnostic.shape_histogram',
+        'as many bones of each depth-and-child-count shape (`d1c3` = one hop down, three children)',
+        counted(aShapes),
+        counted(bShapes),
+      ),
+      orderShape(
+        'bones.agnostic.order_shape',
+        'the bones are declared in the same order of shapes',
+        aShapes,
+        bShapes,
+      ),
+    ],
+  );
+}
+
+interface SlotFacts {
+  order: string[];
+  bone: Map<string, string | null>;
+  attachment: Map<string, string | null>;
+  blend: Map<string, string>;
+  hasColor: Map<string, boolean>;
+  /**
+   * `<slot>` -> the TYPE of what it shows in setup: `region`, `mesh`, and so
+   * on; `none` when the slot shows nothing; `absent` when it names an
+   * attachment no skin carries. The type is name-free — it is *what kind of
+   * thing is drawn here*, which survives every rename — while the attachment's
+   * own name is compared by `slots.attachment` above.
+   */
+  setupType: Map<string, string>;
+}
+
+/** `<slot>/<attachment>` -> type, over every skin. */
+function attachmentTypes(root: Json): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const skin of objs(root.skins)) {
+    if (!isObj(skin.attachments)) continue;
+    for (const [slotName, slotMap] of Object.entries(skin.attachments)) {
+      if (!isObj(slotMap)) continue;
+      for (const [attName, att] of Object.entries(slotMap)) {
+        if (!isObj(att)) continue;
+        // First skin wins. Every skeleton on the ladder has exactly one skin
+        // (`default`), and a per-skin type comparison would need a skin
+        // correspondence, which is a naming question by another route.
+        if (!out.has(`${slotName}/${attName}`)) out.set(`${slotName}/${attName}`, str(att.type) ?? 'region');
+      }
+    }
+  }
+  return out;
+}
+
+function slotFacts(root: Json): SlotFacts {
+  const order: string[] = [];
+  const bone = new Map<string, string | null>();
+  const attachment = new Map<string, string | null>();
+  const blend = new Map<string, string>();
+  const hasColor = new Map<string, boolean>();
+  const setupType = new Map<string, string>();
+  const types = attachmentTypes(root);
+  for (const s of objs(root.slots)) {
+    const name = str(s.name);
+    if (name === null) continue;
+    const setup = str(s.attachment);
+    order.push(name);
+    bone.set(name, str(s.bone));
+    attachment.set(name, setup);
+    blend.set(name, str(s.blend) ?? 'normal');
+    hasColor.set(name, 'color' in s);
+    setupType.set(name, setup === null ? 'none' : (types.get(`${name}/${setup}`) ?? 'absent'));
+  }
+  return { order, bone, attachment, blend, hasColor, setupType };
+}
+
+/** What a slot is, written without a name: what it draws, on what shape of bone. */
+function slotShapes(facts: SlotFacts, bones: BoneFacts): string[] {
+  return facts.order.map((n) => `${facts.setupType.get(n) ?? 'none'}@${boneShape(bones, facts.bone.get(n) ?? '')}`);
+}
+
+function diffSlots(c: Json, r: Json): DiffSection {
+  const a = slotFacts(c);
+  const b = slotFacts(r);
+  const ab = boneFacts(c);
+  const bb = boneFacts(r);
+  const max = Math.max(a.order.length, b.order.length);
+  const aShapes = slotShapes(a, ab);
+  const bShapes = slotShapes(b, bb);
+  const byPosition = (f: SlotFacts): Map<string, number> =>
+    counted(f.order.map((n, i) => `${i}:${f.setupType.get(n) ?? 'none'}`));
+  const boundTo = (f: SlotFacts, bones: BoneFacts): Map<string, number> =>
+    counted(f.order.map((n) => boneShape(bones, f.bone.get(n) ?? '')));
+  return sectionOf(
+    'slots',
+    [
+      measure('slots.count', 'how many slots', Math.min(a.order.length, b.order.length), max),
+      jaccard('slots.names', 'the slot names themselves', new Set(a.order), new Set(b.order)),
+      measure(
+        'slots.order',
+        'the slots array IS the draw order, so its order is data',
+        lcs(
+          a.order.filter((n) => b.bone.has(n)),
+          b.order.filter((n) => a.bone.has(n)),
+        ),
+        max,
+      ),
+      agreement('slots.bone', 'each slot is bound to the same bone', a.bone, b.bone, (x, y) => x === y),
+      agreement('slots.attachment', 'each slot shows the same setup attachment', a.attachment, b.attachment, (x, y) => x === y),
+      agreement('slots.blend', 'each slot uses the same blend mode', a.blend, b.blend, (x, y) => x === y),
+      agreement('slots.color_present', 'a tint is present or absent alike', a.hasColor, b.hasColor, (x, y) => x === y),
+    ],
+    [
+      measure('slots.agnostic.count', 'how many slots', Math.min(a.order.length, b.order.length), max),
+      // Positional on purpose, and paired with the LCS measure below for the
+      // same reason `slots.order` is paired with `slots.names`: this one says
+      // "position 3 draws a mesh on both sides", the LCS one degrades smoothly
+      // when a slot is inserted rather than counting every later slot wrong.
+      histogram(
+        'slots.agnostic.attachment_types_by_position',
+        'the same kind of attachment sits at each position in the draw order',
+        byPosition(a),
+        byPosition(b),
+      ),
+      histogram(
+        'slots.agnostic.bone_binding_shape',
+        'as many slots hang off a bone of each shape (`?` = no such bone is declared)',
+        boundTo(a, ab),
+        boundTo(b, bb),
+      ),
+      orderShape(
+        'slots.agnostic.order_shape',
+        'the draw order is the same order of `<attachment type>@<bone shape>`',
+        aShapes,
+        bShapes,
+      ),
+    ],
+  );
+}
+
+interface AttachmentFact {
+  type: string;
+  /** uv pairs, i.e. the real vertex count of a mesh. */
+  vertices: number | null;
+  triangles: number | null;
+  weighted: boolean | null;
+  hull: number | null;
+  /**
+   * Whether the mesh DECLARES an `edges` key at all — see
+   * `attachments.mesh_edges` for why that is the granularity and not the list.
+   */
+  edgesPresent: boolean | null;
+  /** `<width>x<height>` as stated, or `unstated` — see `attachments.region_size`. */
+  size: string;
+  /**
+   * The name the runtime gives the attachment: its stated `name`, else its
+   * placeholder key (`getValue(map, "name", placeholder)`, `SkeletonJson.js:526`)
+   * — see `attachments.runtime_name`.
+   */
+  runtimeName: string;
+  /**
+   * Every name the attachment resolves, as `<field>:<name>` and sorted — see
+   * `attachmentRefTokens` for which fields and why.
+   */
+  refs: string;
+  /** The same tokens as a list, for the note that spells a disagreement out. */
+  refList: string[];
+}
+
+/**
+ * The names an attachment resolves (issue #1085): the atlas region a region or
+ * a mesh draws, a clipping polygon's end slot, and the mesh a linked mesh takes
+ * its geometry from — with the skin and slot it is found under, where stated.
+ *
+ * ⭐ The region is read as the runtime resolves it, `path`, else the stated
+ * `name`, else the placeholder (SPEC_COVERAGE §1.5's three-level indirection),
+ * for the reason `runtime_name` reads its name that way: a file that spells the
+ * path out and one that leaves it to the parser name the same region, and a
+ * measure that called those different would score every export against every
+ * writer that states its paths. Every other field is a token only when the file
+ * states it — absent is no token, never a default, as in `constraints.refs`.
+ *
+ * Measured on public builds through spine-core: a region's `path` moved to the
+ * other eye of `spineboy-pro` changes 94 of its 99 sampled draws, its clipping
+ * polygon's `end` moved six slots on changes the clipping of 9, and a linked
+ * mesh on `gallery/nod` taking `ear_r` instead of `ear_l` as its source changes
+ * all 18 of its sampled poses. `diff` compared none of the three, and two of them occur in
+ * none of the twelve editor exports (a stated `path` and a linked mesh).
+ */
+function attachmentRefTokens(type: string, key: string, att: Json): string[] {
+  const out: string[] = [];
+  if (type === 'region' || type === 'mesh' || type === 'linkedmesh') out.push(`path:${str(att.path) ?? str(att.name) ?? key}`);
+  for (const field of ['end', 'source', 'skin', 'slot'] as const) {
+    const s = str(att[field]);
+    if (s !== null) out.push(`${field}:${s}`);
+  }
+  return out.sort();
+}
+
+function attachmentFacts(root: Json): { skins: Set<string>; byKey: Map<string, AttachmentFact> } {
+  const skins = new Set<string>();
+  const byKey = new Map<string, AttachmentFact>();
+  for (const skin of objs(root.skins)) {
+    const skinName = str(skin.name) ?? 'default';
+    skins.add(skinName);
+    if (!isObj(skin.attachments)) continue;
+    for (const [slotName, slotMap] of Object.entries(skin.attachments)) {
+      if (!isObj(slotMap)) continue;
+      for (const [attName, att] of Object.entries(slotMap)) {
+        if (!isObj(att)) continue;
+        const type = str(att.type) ?? 'region';
+        const uvs = arr(att.uvs);
+        const verticesRun = arr(att.vertices);
+        const vertexCount = uvs.length > 0 ? uvs.length / 2 : num(att.vertexCount);
+        // Weighted versus unweighted carries no marker: the run is longer than
+        // 2 numbers per vertex exactly when it holds bone/weight triples.
+        const weighted =
+          vertexCount === null || verticesRun.length === 0 ? null : verticesRun.length !== vertexCount * 2;
+        byKey.set(`${skinName}/${slotName}/${attName}`, {
+          type,
+          vertices: type === 'mesh' ? vertexCount : null,
+          triangles: type === 'mesh' ? arr(att.triangles).length / 3 : null,
+          weighted: type === 'mesh' ? weighted : null,
+          hull: type === 'mesh' ? num(att.hull) : null,
+          // `'edges' in att` rather than a length test, so a mesh that declares
+          // `"edges": []` reads as DECLARED. That is a different statement from
+          // omitting the key — the parser stores it as a different thing — and
+          // `bench/count_features.ts`'s `mesh_hasEdges` survey counts presence
+          // the same way, so the corpus census and this measure agree on what
+          // "has edges" means.
+          edgesPresent: type === 'mesh' ? 'edges' in att : null,
+          size: num(att.width) !== null && num(att.height) !== null ? `${num(att.width)}x${num(att.height)}` : 'unstated',
+          runtimeName: str(att.name) ?? attName,
+          refs: attachmentRefTokens(type, attName, att).join(' '),
+          refList: attachmentRefTokens(type, attName, att),
+        });
+      }
+    }
+  }
+  return { skins, byKey };
+}
+
+function diffAttachments(c: Json, r: Json): DiffSection {
+  const a = attachmentFacts(c);
+  const b = attachmentFacts(r);
+  const meshes = (m: Map<string, AttachmentFact>) => new Map([...m].filter(([, f]) => f.type === 'mesh'));
+  const regions = (m: Map<string, AttachmentFact>) => new Map([...m].filter(([, f]) => f.type === 'region'));
+  const am = meshes(a.byKey);
+  const bm = meshes(b.byKey);
+  const ar = regions(a.byKey);
+  const br = regions(b.byKey);
+  return sectionOf('attachments', [
+    jaccard('attachments.skins', 'the skin names', a.skins, b.skins),
+    measure(
+      'attachments.count',
+      'how many attachments',
+      Math.min(a.byKey.size, b.byKey.size),
+      Math.max(a.byKey.size, b.byKey.size),
+    ),
+    jaccard('attachments.names', 'skin/slot/attachment keys', new Set(a.byKey.keys()), new Set(b.byKey.keys())),
+    histogram(
+      'attachments.type_counts',
+      'as many of each attachment type',
+      counted([...a.byKey.values()].map((f) => f.type)),
+      counted([...b.byKey.values()].map((f) => f.type)),
+    ),
+    agreement('attachments.mesh_vertices', 'each mesh has the same vertex count', am, bm, (x, y) => x.vertices === y.vertices),
+    agreement('attachments.mesh_triangles', 'each mesh has the same triangle count', am, bm, (x, y) => x.triangles === y.triangles),
+    agreement('attachments.mesh_weighted', 'each mesh is weighted, or is not, alike', am, bm, (x, y) => x.weighted === y.weighted),
+    agreement('attachments.mesh_hull', 'each mesh declares the same hull length', am, bm, (x, y) => x.hull === y.hull),
+    // Replaces `attachments.region_size_present` (issue #28), which asked
+    // whether each region STATED a size and read near zero on every honest run.
+    //
+    // The issue's diagnosis was that Spine's exporter omits `width`/`height`
+    // when they match the atlas region, so a rigc rig — which always states
+    // them (AUTHORING R1/R5) — could never agree. That is not what the corpus
+    // says: all twelve reference exports state a size on every one of their
+    // regions, and no region omits either field — so there is nothing for an
+    // atlas lookup to resolve and the `--atlas` plumbing the issue proposed
+    // would be dead code against every rung on the ladder.
+    //
+    // ⛔ No count on that claim, deliberately, and this was the fourth copy of
+    // the one issue #490 struck off `docs/LADDER.md`: nothing derives the
+    // figure — not the plainest reading, every `region` attachment under
+    // `skins` in the twelve `export/*.json` skeletons, and not counting by
+    // skin, by slot, by attachment name, by atlas path or by atlas region. The
+    // claim carries the argument without one, because it is universal and a
+    // single counterexample refutes it: after `bun run fetch-examples`, read
+    // the region attachments of those twelve files and check that each states
+    // both `width` and `height`.
+    //
+    // What the measure actually reported was the naming gap, a third time. It
+    // was keyed by `skin/slot/attachment`, so it could never exceed the name
+    // overlap: rung 1 read `0/8` where `attachments.names` read `0/16`, and
+    // `3/5` where three names matched. That is #21's defect in this section.
+    //
+    // So it is name-agnostic and numeric instead: do the two rigs agree about
+    // how big their regions are? A rig that states a size a differently-named
+    // rig also states now agrees, which is what a structural diff is for.
+    histogram(
+      'attachments.region_size',
+      'NAME-AGNOSTIC: as many regions of each stated size (`unstated` is its own size)',
+      counted([...ar.values()].map((f) => f.size)),
+      counted([...br.values()].map((f) => f.size)),
+    ),
+    wiringAgreement(
+      'attachments.refs',
+      'each attachment resolves the same region, clipping end and linked-mesh source',
+      a.byKey,
+      b.byKey,
+      (key) => `attachment ${JSON.stringify(key)}`,
+      '`attachments.names`',
+    ),
+    wiringAgreement(
+      'attachments.skin_members',
+      'each skin activates the same skin-required bones and constraints',
+      skinMembers(c),
+      skinMembers(r),
+      (skin) => `skin ${JSON.stringify(skin)}`,
+      '`attachments.skins`',
+    ),
+  ],
+  undefined,
+  // ── reported (issue #46) ────────────────────────────────────────────────
+  //
+  // `docs/LADDER.md` gates rung 6 on three features — transform constraints,
+  // weighted meshes from authored geometry, and mesh `edges` — and this section
+  // measured nine things, none of which read the third. A candidate that
+  // dropped one of the rung's own gating features scored a clean 1.000 for the
+  // meshes it kept, which is the shape of a measurement that flatters whatever
+  // is missing.
+  //
+  // ⭐ Present-vs-absent, and not the list. `edges` constrains triangulation in
+  // the editor and has no runtime effect whatever — it draws no pixel — so two
+  // candidates can carry different-but-equivalent lists and mean the same rig,
+  // and index equality would score a correct rig below 1.000. `edges.length`
+  // has the same defect in weaker form: `6-arcs`' `tail` declares 116 entries
+  // and a mesh triangulated differently declares a different number while
+  // being just as right. Present-vs-absent is the only distinction that is
+  // unambiguous, and it is exactly the one that was invisible.
+  //
+  // 🚫 Reported rather than in the mean, and on principle rather than for
+  // compatibility: `edges` is unobservable by construction under GATE.md's own
+  // test — no reading of the frames could decide it, because no reading of the
+  // frames can see it.
+  [
+    agreement(
+      'attachments.mesh_edges',
+      'each mesh declares an edge list, or declares none, alike',
+      am,
+      bm,
+      (x, y) => x.edgesPresent === y.edgesPresent,
+    ),
+    // ── issue #796 ───────────────────────────────────────────────────────────
+    //
+    // The name the RUNTIME gives each attachment — `name` if stated, else the
+    // placeholder key — agreed per skin/slot/placeholder. Every measure above is
+    // keyed by the placeholder, so a rebuild that renamed every attachment while
+    // keeping every key read 1.000 across this whole section: that is what a
+    // rebuild did on two production rigs (a stated name respelled as `path`, and
+    // `<skin>/<placeholder>` composed over a name the file never stated), and it
+    // took a pose oracle comparing `slot.attachment.name` to see it.
+    //
+    // 🚫 Reported rather than in the mean, by the same test as `mesh_edges`: a
+    // name draws no pixel, so no reading of the frames could decide it. It is
+    // still a value a consumer reads — `slot.attachment.name` — which is why it
+    // is measured at all.
+    //
+    // ⚠️ Over the keys BOTH sides hold, not over the larger roster, and that is
+    // the one departure from `agreement` here. A key one side lacks is already
+    // `attachments.names` and `attachments.count`; scored again here it would
+    // move this measure on every rename of a key and every dropped attachment,
+    // and "the same key answers to another name" — the only thing nothing else
+    // reads — would be one term among many. The denominator this reports is the
+    // number of keys compared, so a report over few shared keys says so.
+    runtimeNames(a.byKey, b.byKey),
+  ]);
+}
+
+/**
+ * What each skin activates (issue #1085): the `bones` and the per-kind
+ * constraint lists a skin declares, as `<list>:<name>` tokens, sorted — a skin's
+ * MEMBERSHIP, which is what decides whether a bone or constraint marked
+ * `skin: true` is active under it.
+ *
+ * Measured on public builds through spine-core: a `gallery/look` bone made
+ * skin-required and left out of the skin's `bones` moves every one of its 27
+ * sampled poses, and `gallery/walk`'s `leg_b_ik` left out of the skin's `ik`
+ * moves all 9. None of the twelve editor exports declares a membership list, so
+ * every one of them reads `1/1` per skin here — two empty lists agree — which is
+ * the comparison being made rather than an absence of one.
+ */
+function skinMembers(root: Json): Map<string, { refs: string; refList: string[] }> {
+  const out = new Map<string, { refs: string; refList: string[] }>();
+  for (const skin of objs(root.skins)) {
+    const name = str(skin.name) ?? 'default';
+    const refList: string[] = [];
+    for (const list of ['bones', 'ik', 'transform', 'path', 'physics', 'slider'] as const) {
+      for (const member of arr(skin[list])) {
+        const s = str(member);
+        if (s !== null) refList.push(`${list}:${s}`);
+      }
+    }
+    refList.sort();
+    out.set(name, { refs: refList.join(' '), refList });
+  }
+  return out;
+}
+
+/**
+ * `agreement` over the larger roster on a `refs` string, with the note
+ * `constraints.refs` writes: each entry both sides hold whose names differ,
+ * field by field and candidate first, then a count of the entries one side holds
+ * alone, which `elsewhere` is the measure that names.
+ */
+function wiringAgreement<T extends { refs: string; refList: string[] }>(
+  id: string,
+  what: string,
+  a: Map<string, T>,
+  b: Map<string, T>,
+  label: (key: string) => string,
+  elsewhere: string,
+): DiffMeasure {
+  const base = agreement(id, what, a, b, (x, y) => x.refs === y.refs);
+  const missed = base.total - base.matched;
+  if (missed === 0) return base;
+  const differ: string[] = [];
+  for (const [key, fact] of a) {
+    const other = b.get(key);
+    if (other !== undefined && other.refs !== fact.refs) differ.push(refsDisagreement(label(key), fact, other));
+  }
+  const oneSided = missed - differ.length;
+  const spelled = differ.slice(0, REFS_SPELLED_OUT);
+  const note =
+    (differ.length === 0 ? '' : `${differ.length} differ: ${spelled.join('; ')}`) +
+    (differ.length > spelled.length ? `; …and ${differ.length - spelled.length} more` : '') +
+    (oneSided === 0 ? '' : `${differ.length === 0 ? '' : '; '}${oneSided} on one side only, which ${elsewhere} names`);
+  return { ...base, note };
+}
+
+/**
+ * `attachments.runtime_name`: of the skin/slot/placeholder keys both sides
+ * hold, how many answer to the same runtime name — see the note at its call.
+ */
+function runtimeNames(a: Map<string, AttachmentFact>, b: Map<string, AttachmentFact>): DiffMeasure {
+  let shared = 0;
+  let agree = 0;
+  const differ: string[] = [];
+  for (const [key, fact] of a) {
+    const other = b.get(key);
+    if (other === undefined) continue;
+    shared++;
+    if (fact.runtimeName === other.runtimeName) agree++;
+    else if (differ.length < 3) differ.push(`${key} "${fact.runtimeName}" vs "${other.runtimeName}"`);
+  }
+  const missed = shared - agree;
+  return measure(
+    'attachments.runtime_name',
+    'each attachment both sides hold answers to the same name at runtime (`name` if stated, else its placeholder)',
+    agree,
+    shared,
+    shared === 0
+      ? 'no skin/slot/placeholder key is on both sides, so no name was compared'
+      : missed === 0
+        ? undefined
+        : `${missed} renamed: ${differ.join('; ')}${missed > differ.length ? `; …and ${missed - differ.length} more` : ''}`,
+  );
+}
+
+interface ConstraintFact {
+  type: string;
+  /**
+   * Every name the constraint resolves, as `<field>:<name>` and sorted — its
+   * wiring: the bones and slots it reads and writes, a slider's animation, and
+   * the properties a slider or a transform maps (`property:rotate`,
+   * `property:x>y`). See `constraintFacts` for which fields and why.
+   */
+  refs: string;
+  /** The same tokens as a list, for the note that spells a disagreement out. */
+  refList: string[];
+}
+
+/**
+ * Every constraint, keyed the way the format resolves one: by KIND and name.
+ *
+ * ⚠️ Keyed by the name alone, a skeleton that carries `leg` as an ik constraint
+ * and as a transform one — valid Spine, and what `findConstraint(name, type)`
+ * exists to tell apart — lost one of the pair out of all five measures below
+ * (issue #692). It was invisible rather than wrong: both sides collapse the same
+ * way, so the report read 1.000 while its own header line counted one constraint
+ * more than `constraints.count` did, measured at 14/14 against 13/13 on the
+ * export that made the card.
+ *
+ * ⭐ **What the wiring is** (issue #1078): every field of a 4.3 constraint whose
+ * value is a NAME the parser resolves — `SPEC_COVERAGE.md` §1.4, field by field.
+ * `bones`, `bone`, `target`, `source` and `slot` name a bone or a slot; a
+ * slider's `animation` names an animation; a slider's `property` and the
+ * `from`/`to` keys of a transform's `properties` name the property read and the
+ * property written, from a closed set the parser throws outside of. Every other
+ * field is a number, a flag or a mode — a value, which this file does not compare
+ * on either side of any split; the value walk (`diffSkeletonValues`) does.
+ *
+ * 🔍 Until #1078 the list stopped at the five bone and slot fields, so an editor
+ * import that repointed both sliders of a probe (`yaw -> "5"` came back as
+ * `yaw -> "-a"`, issue #1040) read 1.000 on every constraint measure. The two
+ * property fields were blinder still: measured on `gallery/look` and `6-arcs-pro`,
+ * a slider moved from `rotate` to `x` and a transform remapped from `x>x` to
+ * `x>y` moved no measure here and no value in the value walk either (its skip
+ * list named `properties`), so nothing in the tree compared them at all. Since
+ * issue #1084 the walk reads both, by class (`property/kind`, `properties/FromX/to/ToY`).
+ *
+ * ⚠️ Absent is no token, never a default: a transform with no `properties` maps
+ * nothing, and two sides that both omit a field agree about it. And the tokens
+ * are a set, so the order a file writes `properties` in — an object, re-keyed by
+ * any writer — is not a difference.
+ */
+function constraintFacts(root: Json): Map<string, ConstraintFact> {
+  const out = new Map<string, ConstraintFact>();
+  for (const con of objs(root.constraints)) {
+    const name = str(con.name);
+    if (name === null) continue;
+    const at = constraintAt(str(con.type) ?? '(none)', name);
+    const refs = new Set<string>();
+    for (const b of arr(con.bones)) {
+      const s = str(b);
+      if (s !== null) refs.add(`bone:${s}`);
+    }
+    for (const key of ['bone', 'target', 'source', 'slot', 'animation', 'property'] as const) {
+      const s = str(con[key]);
+      if (s !== null) refs.add(`${key}:${s}`);
+    }
+    if (isObj(con.properties)) {
+      for (const [from, entry] of Object.entries(con.properties)) {
+        const to = isObj(entry) && isObj(entry.to) ? Object.keys(entry.to) : [];
+        // A `from` with no `to` maps nothing at runtime, but it is still a
+        // statement the file makes, so it is a token of its own rather than
+        // silently equal to the key being absent.
+        if (to.length === 0) refs.add(`property:${from}>`);
+        for (const t of to) refs.add(`property:${from}>${t}`);
+      }
+    }
+    const refList = [...refs].sort();
+    out.set(at, { type: str(con.type) ?? '(none)', refs: refList.join(' '), refList });
+  }
+  return out;
+}
+
+/** How many disagreeing constraints `constraints.refs`' note spells out before it counts the rest. */
+const REFS_SPELLED_OUT = 3;
+
+/**
+ * One constraint's disagreement, by field: `slider constraint "yaw": animation
+ * "5" vs "-a"` — the candidate's names for each field that differs, then the
+ * reference's, `none` where a side has none.
+ */
+function refsDisagreement(at: string, a: { refList: string[] }, b: { refList: string[] }): string {
+  const byField = (f: { refList: string[] }): Map<string, string[]> => {
+    const m = new Map<string, string[]>();
+    for (const token of f.refList) {
+      const colon = token.indexOf(':');
+      const field = token.slice(0, colon);
+      m.set(field, [...(m.get(field) ?? []), token.slice(colon + 1)]);
+    }
+    return m;
+  };
+  const af = byField(a);
+  const bf = byField(b);
+  const fields = [...new Set([...af.keys(), ...bf.keys()])].sort();
+  const spell = (names: string[] | undefined): string =>
+    names === undefined ? 'none' : names.map((n) => JSON.stringify(n)).join(', ');
+  const parts = fields
+    .filter((f) => (af.get(f) ?? []).join(' ') !== (bf.get(f) ?? []).join(' '))
+    .map((f) => `${f} ${spell(af.get(f))} vs ${spell(bf.get(f))}`);
+  return `${at}: ${parts.join(', ')}`;
+}
+
+/**
+ * `constraints.refs`: `agreement` over the constraints, unchanged in what it
+ * counts, with a note naming each disagreement and both sides' names — the
+ * figure alone says that some constraint is wired differently, and a reader
+ * acting on it needs to know which one and to what (issue #1078).
+ *
+ * The note's two counts partition the misses: a constraint both sides hold whose
+ * wiring differs is spelled out, and one only one side holds is counted, since
+ * `constraints.names` is the measure that names it.
+ */
+function constraintRefs(a: Map<string, ConstraintFact>, b: Map<string, ConstraintFact>): DiffMeasure {
+  const base = agreement(
+    'constraints.refs',
+    'each constraint names the same bones, slots, animation and properties',
+    a,
+    b,
+    (x, y) => x.refs === y.refs,
+  );
+  const differ: string[] = [];
+  for (const [at, fact] of a) {
+    const other = b.get(at);
+    if (other !== undefined && other.refs !== fact.refs) differ.push(refsDisagreement(at, fact, other));
+  }
+  const missed = base.total - base.matched;
+  if (missed === 0) return base;
+  const oneSided = missed - differ.length;
+  const spelled = differ.slice(0, REFS_SPELLED_OUT);
+  const note =
+    (differ.length === 0 ? '' : `${differ.length} wired differently: ${spelled.join('; ')}`) +
+    (differ.length > spelled.length ? `; …and ${differ.length - spelled.length} more` : '') +
+    (oneSided === 0
+      ? ''
+      : `${differ.length === 0 ? '' : '; '}${oneSided} on one side only, which \`constraints.names\` names`);
+  return { ...base, note };
+}
+
+/**
+ * The constraints in the order the file declares them, by kind and name — the
+ * key `constraintFacts` uses, so that `leg` as an ik and as a transform are two
+ * entries here as well.
+ *
+ * 🔍 **Why the order is data** (issue #1085). 4.3 folds every constraint into one
+ * array and applies them in its order, so two files with the same constraints
+ * wired the same way can pose differently. Measured by reversing the array and
+ * posing both through spine-core: `spineboy-pro` moves 98 of its 99 sampled
+ * poses, `6-arcs-pro` 8 of 9 and `sack-pro` 8 of 36 (33 of 36 with physics
+ * stepped); swapping `aim-torso-ik` and `aim-torso-transform` alone moves the 9
+ * samples of `aim`. Before this nothing in the tree compared it — the value walk
+ * keys constraints by name, so it is blind to the order by construction.
+ *
+ * ⚠️ Not every swap poses differently, and the measure does not pretend to know
+ * which do: `gallery/look`'s two sliders and `gallery/walk`'s two legs drive
+ * disjoint bones and read the same pose either way. A reordering is reported as
+ * what the file states, the way `bones.order` reports one.
+ */
+function constraintOrder(root: Json): string[] {
+  const out: string[] = [];
+  for (const con of objs(root.constraints)) {
+    const name = str(con.name);
+    if (name !== null) out.push(constraintAt(str(con.type) ?? '(none)', name));
+  }
+  return out;
+}
+
+function diffConstraints(c: Json, r: Json): DiffSection {
+  const a = constraintFacts(c);
+  const b = constraintFacts(r);
+  const ao = constraintOrder(c);
+  const bo = constraintOrder(r);
+  const shared = ao.filter((n) => b.has(n));
+  const sharedOther = bo.filter((n) => a.has(n));
+  const inOrder = lcs(shared, sharedOther);
+  const max = Math.max(a.size, b.size);
+  return sectionOf('constraints', [
+    measure('constraints.count', 'how many constraints', Math.min(a.size, b.size), Math.max(a.size, b.size)),
+    jaccard('constraints.names', 'the constraint names', new Set(a.keys()), new Set(b.keys())),
+    histogram(
+      'constraints.type_counts',
+      'as many of each constraint type',
+      counted([...a.values()].map((f) => f.type)),
+      counted([...b.values()].map((f) => f.type)),
+    ),
+    agreement('constraints.type_by_name', 'each constraint is the same type', a, b, (x, y) => x.type === y.type),
+    constraintRefs(a, b),
+    measure(
+      'constraints.order',
+      'the constraints are declared, and so applied, in the same order',
+      inOrder,
+      max,
+      [
+        ...(inOrder === shared.length ? [] : [outOfOrder(shared, sharedOther)]),
+        ...(shared.length === max ? [] : [`${max - shared.length} of the larger roster not on both sides, which \`constraints.names\` names`]),
+      ].join('; ') || undefined,
+    ),
+  ]);
+}
+
+/**
+ * `constraints.order`'s note when the shared constraints are not in one order:
+ * both sides' order of them, candidate first, spelled out to a limit.
+ */
+function outOfOrder(a: string[], b: string[]): string {
+  const spell = (list: string[]): string =>
+    list.slice(0, ORDER_SPELLED_OUT).join(', ') + (list.length > ORDER_SPELLED_OUT ? `, …and ${list.length - ORDER_SPELLED_OUT} more` : '');
+  return `${a.length - lcs(a, b)} out of order: candidate ${spell(a)}; reference ${spell(b)}`;
+}
+
+/** How many constraints `constraints.order`'s note lists per side before it counts the rest. */
+const ORDER_SPELLED_OUT = 6;
+
+interface AnimationFacts {
+  names: string[];
+  /** `<anim>` -> last key time. Skeleton JSON has no duration field. */
+  duration: Map<string, number>;
+  /** `<anim>|<path>` -> 1, one entry per timeline that exists. */
+  kinds: Map<string, number>;
+  /** `<anim>|<kind>` -> number of keys. */
+  keys: Map<string, number>;
+  /** `<anim>|linear|stepped|bezier` -> number of keys with that curve. */
+  curves: Map<string, number>;
+  events: Map<string, number>;
+  hasDrawOrder: Map<string, boolean>;
+  hasDeform: Map<string, boolean>;
+}
+
+function animationFacts(root: Json): AnimationFacts {
+  const facts: AnimationFacts = {
+    names: [],
+    duration: new Map(),
+    kinds: new Map(),
+    keys: new Map(),
+    curves: new Map(),
+    events: new Map(),
+    hasDrawOrder: new Map(),
+    hasDeform: new Map(),
+  };
+  if (!isObj(root.animations)) return facts;
+  for (const name of Object.keys(root.animations)) {
+    facts.names.push(name);
+    facts.duration.set(name, 0);
+    facts.events.set(name, 0);
+    facts.hasDrawOrder.set(name, false);
+    facts.hasDeform.set(name, false);
+  }
+  const bump = (m: Map<string, number>, k: string, by = 1) => m.set(k, (m.get(k) ?? 0) + by);
+  walkTimelines(root, (path, kind, name, keys) => {
+    const anim = path.slice(0, path.indexOf('.'));
+    // The path carries the target's name (bone `face`, constraint `probe_ik`),
+    // which is compared under bones/constraints already. Here only the SHAPE
+    // matters, so the target is dropped and the kind kept.
+    bump(facts.kinds, `${anim}|${kind}.${name}`);
+    bump(facts.keys, `${anim}|${kind}.${name}`, keys.length);
+    if (kind === 'drawOrder' || kind === 'drawOrderFolder') facts.hasDrawOrder.set(anim, true);
+    if (kind === 'attachment' && name === 'deform') facts.hasDeform.set(anim, true);
+    if (kind === 'event') facts.events.set(anim, (facts.events.get(anim) ?? 0) + keys.length);
+    for (const key of keys) {
+      if (!isObj(key)) continue;
+      const time = num(key.time) ?? 0;
+      if (time > (facts.duration.get(anim) ?? 0)) facts.duration.set(anim, time);
+      const curve = key.curve;
+      const shape = curve === undefined ? 'linear' : curve === 'stepped' ? 'stepped' : Array.isArray(curve) ? 'bezier' : 'other';
+      bump(facts.curves, `${anim}|${shape}`);
+    }
+  });
+  return facts;
+}
+
+/**
+ * The names the animations resolve, as two multisets of tokens (issue #1085).
+ *
+ * `animationFacts` keeps each timeline's kind and drops its target on purpose —
+ * a candidate's own vocabulary would otherwise be counted against it a second
+ * time inside `timeline_kinds` (#21) — and reads no key's contents beyond its
+ * time and curve. So until this, a bone timeline moved onto another bone, an
+ * attachment key naming another attachment, a draw-order key naming another slot
+ * and an event key firing another event each moved no measure in this file, and
+ * every one of them poses or draws differently: measured on public builds
+ * through spine-core, a retargeted bone timeline moves 7 of `gallery/look`'s 27
+ * sampled poses, two slots' attachment keys swapped move 9 of `spineboy-pro`'s
+ * 99, a draw-order offset moved to the next slot moves 9 of `spineboy-ess`'s 72
+ * and an event key renamed to a second event moves the event block of one sample.
+ *
+ * - `targets`: one token per timeline, `<animation>|<group>|<target>` — the
+ *   bone, slot or constraint it keys, a deform's or sequence's
+ *   `skin/slot/attachment`, and each slot a draw-order folder holds. The
+ *   timeline's own kind is left out on purpose: it is `timeline_kinds`'
+ *   subject, and a rotate keyed as a scale on the same bone moves that measure
+ *   and must not move this one too.
+ * - `keyed`: one token per name a KEY carries, with its position in the
+ *   timeline — an attachment key's attachment (`(none)` for a key that clears
+ *   the slot), each draw-order offset's slot, an event key's event.
+ *
+ * Both are names, so both are name-matched, and a candidate with its own names
+ * reads low here exactly as it does on `names` — the name-agnostic block is
+ * where that rig is read. ⚠️ No key VALUE is read: a key's time, an offset's
+ * distance and an event's payload are the value walk's.
+ */
+interface AnimationRefs {
+  targets: Map<string, number>;
+  keyed: Map<string, number>;
+}
+
+/** The physics group's empty name, which applies a timeline to every physics constraint. */
+const EVERY_PHYSICS_CONSTRAINT = '(every physics constraint)';
+
+function animationRefs(root: Json): AnimationRefs {
+  const targets = new Map<string, number>();
+  const keyed = new Map<string, number>();
+  const bump = (m: Map<string, number>, k: string): void => {
+    m.set(k, (m.get(k) ?? 0) + 1);
+  };
+  if (!isObj(root.animations)) return { targets, keyed };
+  for (const [anim, body] of Object.entries(root.animations)) {
+    if (!isObj(body)) continue;
+    for (const group of ['bones', 'slots', 'path', 'physics', 'slider'] as const) {
+      const held = body[group];
+      if (!isObj(held)) continue;
+      for (const [target, timelines] of Object.entries(held)) {
+        if (!isObj(timelines)) continue;
+        const named = group === 'physics' && target === '' ? EVERY_PHYSICS_CONSTRAINT : target;
+        for (const [timeline, keys] of Object.entries(timelines)) {
+          if (!Array.isArray(keys)) continue;
+          bump(targets, `${anim}|${group}|${named}`);
+          if (group === 'slots' && timeline === 'attachment') {
+            keys.forEach((key, i) => {
+              if (isObj(key)) bump(keyed, `${anim}|attachment key ${i}|${target}: ${str(key.name) ?? '(none)'}`);
+            });
+          }
+        }
+      }
+    }
+    for (const group of ['ik', 'transform'] as const) {
+      const held = body[group];
+      if (!isObj(held)) continue;
+      for (const [target, keys] of Object.entries(held)) if (Array.isArray(keys)) bump(targets, `${anim}|${group}|${target}`);
+    }
+    if (isObj(body.attachments)) {
+      for (const [skin, bySlot] of Object.entries(body.attachments)) {
+        if (!isObj(bySlot)) continue;
+        for (const [slot, byAttachment] of Object.entries(bySlot)) {
+          if (!isObj(byAttachment)) continue;
+          for (const [attachment, timelines] of Object.entries(byAttachment)) {
+            if (!isObj(timelines)) continue;
+            for (const keys of Object.values(timelines)) {
+              if (Array.isArray(keys)) bump(targets, `${anim}|attachments|${skin}/${slot}/${attachment}`);
+            }
+          }
+        }
+      }
+    }
+    const offsets = (label: string, keys: unknown): void => {
+      arr(keys).forEach((key, i) => {
+        if (!isObj(key)) return;
+        for (const offset of objs(key.offsets)) bump(keyed, `${anim}|${label} key ${i}|${str(offset.slot) ?? '(none)'}`);
+      });
+    };
+    offsets('drawOrder', body.drawOrder);
+    objs(body.drawOrderFolder).forEach((folder, f) => {
+      for (const slot of arr(folder.slots)) bump(targets, `${anim}|drawOrderFolder ${f}|${str(slot) ?? '(none)'}`);
+      offsets(`drawOrderFolder ${f}`, folder.keys);
+    });
+    arr(body.events).forEach((key, i) => {
+      if (isObj(key)) bump(keyed, `${anim}|event key ${i}|${str(key.name) ?? '(none)'}`);
+    });
+  }
+  return { targets, keyed };
+}
+
+/** How many tokens a names histogram's note spells out per side before it counts the rest. */
+const TOKENS_SPELLED_OUT = 3;
+
+/**
+ * `histogram`, with a note naming what each side holds that the other does not —
+ * the figure alone says some name moved, and a reader acting on it needs which.
+ */
+function namesHistogram(id: string, what: string, a: Map<string, number>, b: Map<string, number>): DiffMeasure {
+  const base = histogram(id, what, a, b);
+  if (base.matched === base.total) return base;
+  // A token one side holds more often than the other, with how many more — a
+  // bone keyed by three timelines on one side and one on the other is `×2`.
+  const only = (x: Map<string, number>, y: Map<string, number>): string[] => {
+    const out: string[] = [];
+    for (const [k, v] of x) {
+      const extra = v - (y.get(k) ?? 0);
+      if (extra > 0) out.push(`${JSON.stringify(k)}${extra > 1 ? ` ×${extra}` : ''}`);
+    }
+    return out;
+  };
+  const spell = (side: string, list: string[]): string =>
+    list.length === 0
+      ? ''
+      : `${side} only: ${list.slice(0, TOKENS_SPELLED_OUT).join(', ')}` +
+        (list.length > TOKENS_SPELLED_OUT ? `, …and ${list.length - TOKENS_SPELLED_OUT} more` : '');
+  const parts = [spell('candidate', only(a, b)), spell('reference', only(b, a))].filter((p) => p !== '');
+  return { ...base, note: `${base.total - base.matched} differ — ${parts.join('; ')}` };
+}
+
+/**
+ * What a side's keying costs, in the two shapes that separate the two ways a
+ * key total can differ: more timelines, or more keys inside a timeline.
+ *
+ * Every number here is already collected by `animationFacts` — this only sums
+ * it. `seconds` is the sum of each animation's last key time, which is what
+ * `animations.duration` compares, because skeleton JSON carries no duration
+ * field of its own.
+ */
+interface KeyingTotals {
+  keys: number;
+  timelines: number;
+  seconds: number;
+}
+
+function keyingTotals(f: AnimationFacts): KeyingTotals {
+  const sum = (m: Map<string, number>): number => [...m.values()].reduce((x, y) => x + y, 0);
+  return { keys: sum(f.keys), timelines: sum(f.kinds), seconds: sum(f.duration) };
+}
+
+/** 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 refsA = animationRefs(c);
+  const refsB = animationRefs(r);
+  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', [
+    measure('animations.count', 'how many animations', Math.min(a.names.length, b.names.length), Math.max(a.names.length, b.names.length)),
+    jaccard('animations.names', 'the animation names', new Set(a.names), new Set(b.names)),
+    agreement(
+      'animations.duration',
+      'each animation runs as long (last key time, within one frame)',
+      a.duration,
+      b.duration,
+      (x, y) => Math.abs(x - y) <= FRAME,
+    ),
+    histogram('animations.timeline_kinds', 'the same timelines exist', a.kinds, b.kinds),
+    histogram('animations.key_counts', 'those timelines carry as many keys', a.keys, b.keys),
+    histogram('animations.curve_kinds', 'as many linear / stepped / bezier keys', a.curves, b.curves),
+    histogram('animations.event_keys', 'as many event firings', a.events, b.events),
+    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),
+    namesHistogram(
+      'animations.targets',
+      'each timeline keys the same bone, slot, constraint or attachment',
+      refsA.targets,
+      refsB.targets,
+    ),
+    namesHistogram(
+      'animations.keyed_names',
+      'each key names the same attachment, draw-order slot or event',
+      refsA.keyed,
+      refsB.keyed,
+    ),
+  ],
+  // ── 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
+  // density OBSERVABLE — 24/30 fps reference renders, or a hint in the brief —
+  // and both routes were measured before either was built (the figures are in
+  // [BENCHMARK.md](../docs/BENCHMARK.md), *Key density*). Neither works, and the
+  // reason is the same one twice: **the two keyings render the same pictures.**
+  // A candidate that lays extra keys along the curve the reference already
+  // describes poses identically at every instant, so a higher sampling rate
+  // samples the same curve more often and sees the same thing — the frames'
+  // rate is not the ceiling, the pixels are. And a hint in the brief does not
+  // make density observable; it makes it TOLD, which turns a scored measure into
+  // an input and would be a reference-side value of a scored row landing in an
+  // allowed-reading surface — the exact text LADDER.md's honesty rule seals.
+  //
+  // ⭐ So what the issue found is a REPORTING defect, and it is here.
+  // `animations.key_counts` is a histogram intersection over
+  // `max(candidate, reference)`, so **it cannot say which side is the bigger
+  // one**: rung 4 read 421/1339 for a candidate carrying three times the
+  // reference's keys, and that figure is indistinguishable from one carrying a
+  // third of them. The author read it as a gap and left it, correctly, because
+  // nothing in the report said "over-keyed". These two measures say so, with
+  // their conventions, in the direction the ratio drops.
+  //
+  // Two figures and not one, because a key total can differ two ways and the
+  // repairs are opposite: `key_density` moves when the shot is keyed harder,
+  // `keys_per_timeline` when each timeline is, and a candidate with the
+  // reference's density spread over twice the timelines shows up on the second
+  // alone. 🚫 Neither gates — GATE.md's *What never gates* names key density
+  // outright, and gate v2.3 (#153) settled that a clause does not read a figure
+  // the authoring loop cannot see.
+  [
+    rateAgreement(
+      'animations.key_density',
+      'how hard the shot is keyed, as keys per second',
+      'keys/s',
+      perSecond(at),
+      perSecond(bt),
+      `Convention: every key of every timeline (${at.keys} vs ${bt.keys}) over the summed last-key time of ` +
+        `every animation (${atPlaces(at.seconds)}s vs ${atPlaces(bt.seconds)}s), compared as min/max at ${RATE_PLACES} decimal places.`,
+    ),
+    rateAgreement(
+      'animations.keys_per_timeline',
+      'how hard each timeline is keyed, as keys per timeline',
+      'keys/timeline',
+      perTimeline(at),
+      perTimeline(bt),
+      `Convention: every key of every timeline (${at.keys} vs ${bt.keys}) over the number of timelines that exist ` +
+        `(${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> {
+  const out = new Map<string, string>();
+  if (!isObj(root.events)) return out;
+  for (const [name, def] of Object.entries(root.events)) {
+    const d = isObj(def) ? def : {};
+    // The typed payload, in the parser's own defaults (`:469-484`), so that a
+    // field written explicitly at its default reads the same as one omitted.
+    out.set(
+      name,
+      JSON.stringify({
+        int: num(d.int) ?? 0,
+        float: num(d.float) ?? 0,
+        string: str(d.string) ?? '',
+        audio: str(d.audio) ?? '',
+        volume: num(d.volume) ?? 1,
+        balance: num(d.balance) ?? 0,
+      }),
+    );
+  }
+  return out;
+}
+
+function diffEvents(c: Json, r: Json): DiffSection {
+  const a = eventFacts(c);
+  const b = eventFacts(r);
+  return sectionOf('events', [
+    jaccard('events.names', 'the event names', new Set(a.keys()), new Set(b.keys())),
+    agreement('events.payloads', 'each event carries the same typed payload', a, b, (x, y) => x === y),
+  ]);
+}
+
+// ---------------------------------------------------------------------------
+// the skeleton header
+// ---------------------------------------------------------------------------
+
+/**
+ * The header's box: `x`, `y`, `width`, `height` of the setup-pose bounding box
+ * — the box around the attachments at the setup pose, which is what the Spine
+ * format says the four are — or the absence of all four.
+ *
+ * 🔁 **Renamed from `stage_present`/`stage_box` by issue #907, because the old
+ * name had become a lie.** Until then `build` copied rigc's stage — the crop
+ * the art was painted in — into these four fields, so on a rigc candidate the
+ * measure read a stage and on an editor export it read a bounding box, under
+ * one word. Since #907 `build` writes the setup-pose bounding box there too
+ * (`headerBoundsOf` in `src/compile.ts`, held to spine-core's `getBounds`), so
+ * both sides of every comparison carry the same kind of value, and the stage —
+ * which a rig spec states and the model document carries — is not in the file
+ * at all. A measure called `stage` would send a reader to change the stage,
+ * which no longer moves this number.
+ *
+ * 🔍 **Why this measure exists at all** (issue #578). The header box was the
+ * one value `build` required and no instrument in this tree could see:
+ * `validate`, `check` and `render` all ignore it — `render` frames from the
+ * posed bounds — and `diff` had no header measure, so a sweep that handed a
+ * deliberately absurd unit stage `0,0,1,1` to 37 real exports read **1.000 on
+ * every measure** for 32 of them.
+ *
+ * ⭐ **`bounds_present` is 1/1 or 0/1 and never `0/0`.** Both sides always have
+ * a presence to compare, including when both say "none" — that is agreement,
+ * not an absence of data, and `total: 0` here would be the vacuous 1.000 this
+ * file refuses. `bounds_box` is the one that goes vacuous, and only when there
+ * are not two boxes to compare.
+ */
+interface HeaderBox {
+  present: boolean;
+  /**
+   * The four fields as the header MEANS them: the extent exactly as stated, and
+   * the origin of a stated box as stated or `0` where it is omitted. See
+   * `headerBox` for why the second half is a reading and not a fallback.
+   */
+  box: Array<number | null>;
+}
+
+const BOX_FIELDS = ['x', 'y', 'width', 'height'] as const;
+
+/**
+ * A header states a box by its EXTENT: a numeric `width` and `height`.
+ *
+ * `x`/`y` alone are an origin for a box that is not there — no export carries
+ * that shape, and rigc never emits it — so they do not make a box on their own.
+ *
+ * ⭐ **Inside a stated box, an omitted `x`/`y` IS `0`** (issue #620). That is a
+ * reading of the format, not a value invented for a gap — the distinction this
+ * file lives or dies by — and three measurements carry it, none of them
+ * anybody's word for the convention:
+ *
+ * - **The header's writer omits a field at its default.** All twelve exports
+ *   under `examples/` omit `referenceScale`, whose default the parser itself
+ *   spells two lines below the four raw assignments (`SkeletonJson.js:74`,
+ *   `getValue(skeletonMap, "referenceScale", 100)`), and none of the 389 bone
+ *   `x`/`y`/`rotation`/`shearX`/`shearY` values those same files DO write is an
+ *   explicit `0`. A box at the origin therefore has no spelling but the
+ *   omission, so reading the omission as absence reads a value the format cannot
+ *   express. (An editor round trip of a header stating `"x": 0, "y": 0` wrote
+ *   neither back — measured through a licensed 4.3.26 editor for issue #907.)
+ * - **The binary reader supplies it unconditionally.** `SkeletonBinary.js:69-72`
+ *   reads the four as four floats with no key to be missing, so one skeleton's
+ *   origin is `0` in a `.skel` and absent in a `.json`. A measure that called
+ *   those two different boxes would be reporting the container.
+ * - **The JSON reader's silence is an oversight rather than a meaning.**
+ *   `SkeletonJson.js:70-73` is `skeletonData.x = skeletonMap.x`, a raw
+ *   assignment that overwrites `SkeletonData`'s own `0` with `undefined`. The
+ *   line beside it does the same to `fps`, whose default is `30` and which every
+ *   one of the twelve omits — so taking `undefined` for a meaning would say the
+ *   editor has never exported a frame rate.
+ *
+ * ⚠️ **The default is the ORIGIN's alone**, and the guard is the paragraph above
+ * it: the extent is what states a box, so defaulting it would turn the box-less
+ * header of issue #578 into a `0x0` box at `0,0` and answer the question
+ * instead of reading it.
+ */
+function headerBox(root: Json): HeaderBox {
+  const header = isObj(root.skeleton) ? root.skeleton : {};
+  const box = BOX_FIELDS.map((k) => num(header[k]));
+  const present = box[2] !== null && box[3] !== null;
+  return { present, box: present ? [box[0] ?? 0, box[1] ?? 0, box[2], box[3]] : box };
+}
+
+/**
+ * The two header measures.
+ *
+ * ⚠️ **The box is compared EXACTLY, and that is a measurement rather than a
+ * choice.** The structural measures in this file have exactly one tolerance —
+ * `FRAME`, one sixtieth of a second, used once, for `animations.duration` — and
+ * no spatial one anywhere, because they compare no position at all (that is
+ * `bonedist.ts`). Each side's box is a number its writer computed: rigc's is
+ * spine-core's `getBounds` on the header's 1e-6 grid at float32 (`headerBoxNumber`; `tools/core_gate.ts` holds it), and
+ * the editor's is its own arithmetic, which on the twelve examples sits up to
+ * 0.0071 units from `getBounds` on the same skeleton and agrees with its
+ * float32 on 13 of the 48 numbers (issue #907's measurement). A rebuild and its
+ * export therefore read below 4/4 here by the editor's arithmetic alone, and an
+ * epsilon chosen to hide that would be a number nobody measured, in the file
+ * whose whole job is to report measured ones. The measure is reported and gates
+ * nothing on the ladder.
+ *
+ * ⭐ `diffSkeletonValues` (issue #615) is the second tolerance in the file and
+ * it does not weaken this one. It compares positions, so it needs one; both its
+ * terms are read off other code — the 1e-6 grid rigc's closed-form models are
+ * evaluated on and the parser's float32 storage — rather than chosen here; and
+ * the four numbers above are the one place the two overlap, where `bounds_box`
+ * stays the stricter reading and says so by staying exact.
+ */
+function diffHeader(c: Json, r: Json): DiffReported {
+  const a = headerBox(c);
+  const b = headerBox(r);
+  const both = a.present && b.present;
+  const agreed = both ? a.box.filter((v, i) => v === b.box[i]).length : 0;
+  const side = (f: HeaderBox): string => (f.present ? `${f.box[2]}x${f.box[3]} at ${f.box[0]},${f.box[1]}` : 'none');
+  return {
+    measures: [
+      measure(
+        'skeleton.bounds_present',
+        'both headers carry a setup-pose bounding box, or neither does',
+        a.present === b.present ? 1 : 0,
+        1,
+        `candidate ${side(a)}; reference ${side(b)}. A header carries a box by stating a width and a height`,
+      ),
+      measure(
+        'skeleton.bounds_box',
+        'the header carries the same box (x, y, width, height — the extent as stated, an omitted origin as the 0 it means)',
+        agreed,
+        both ? BOX_FIELDS.length : 0,
+        both
+          ? `candidate ${side(a)}; reference ${side(b)}`
+          : a.present === b.present
+            ? 'neither header carries a box, so there is no box to compare — `bounds_present` carries that'
+            : 'only one header carries a box, so there is no second box to compare — `bounds_present` carries that',
+      ),
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// the report
+// ---------------------------------------------------------------------------
+
+function orientation(root: Json): Record<string, number> {
+  const attachments = attachmentFacts(root);
+  return {
+    bones: objs(root.bones).length,
+    slots: objs(root.slots).length,
+    skins: objs(root.skins).length,
+    attachments: attachments.byKey.size,
+    constraints: objs(root.constraints).length,
+    animations: isObj(root.animations) ? Object.keys(root.animations).length : 0,
+    events: isObj(root.events) ? Object.keys(root.events).length : 0,
+  };
+}
+
+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, animationPairs),
+      diffEvents(c, r),
+    ],
+    header: diffHeader(c, r),
+    candidate: orientation(c),
+    reference: orientation(r),
+  };
+}
+
+/**
+ * Every NAME-MATCHED measure that is not a perfect match, by id. What a test
+ * asserts on.
+ *
+ * The name-agnostic reports are deliberately not folded in here. They are a
+ * separate comparison with its own measure set, and a single flattened list
+ * would make one edit's footprint depend on how many measures the other report
+ * happens to define — which is the opposite of what these assertions are for.
+ * `movedAgnosticMeasures` is the other half, and a case pins both.
+ */
+export function movedMeasures(report: DiffReport): string[] {
+  return report.sections.flatMap((s) => s.measures.filter((m) => m.ratio < 1).map((m) => m.id));
+}
+
+/** The same, over the name-agnostic reports. Empty when every shape agrees. */
+export function movedAgnosticMeasures(report: DiffReport): string[] {
+  return report.sections.flatMap((s) => (s.nameAgnostic?.measures ?? []).filter((m) => m.ratio < 1).map((m) => m.id));
+}
+
+/**
+ * The same, over the reported measures.
+ *
+ * A third list rather than a third of one flattened list, for the reason
+ * `movedAgnosticMeasures` gives: a case's expectation should not depend on how
+ * many measures a different report happens to define. Pinned on every case and
+ * not only the ones about a mesh or a curve — a figure nothing asserts on is a
+ * figure that can quietly stop moving, and these gate nothing, so nothing else
+ * would notice.
+ */
+export function movedReportedMeasures(report: DiffReport): string[] {
+  return [...report.sections.flatMap((s) => s.reported?.measures ?? []), ...report.header.measures]
+    .filter((m) => m.ratio < 1)
+    .map((m) => m.id);
+}
+
+// ---------------------------------------------------------------------------
+// The value level — what the structural measures above are blind to
+// ---------------------------------------------------------------------------
+
+/**
+ * The one absolute grid rigc still emits on: `onModelGrid` in
+ * [`compile.ts`](compile.ts), 1e-6 in a closed-form model's own unit, which a
+ * deform `transform` and a track `derive` are evaluated onto before they are
+ * written. So a value a model produced may sit up to one step of it from a
+ * reading that evaluated the same model in float64 — through no fault of
+ * anything this measure is looking for.
+ *
+ * ⚠️ **Restated, not retired, by issue #716.** This said `r6` until then — the
+ * six fixed decimals every emitted number took, and `keyTime` rounding a key
+ * time down over the same step. Both are gone: every number is now its
+ * float32's shortest name, whose distance from its double the second term
+ * already covers, and a key time steps at most one float down. What survives
+ * is the models' grid, which is absolute because a model's identities are
+ * exact zeros and a float's grid is relative. On the corpus, where nothing is
+ * a model, the term is idle: the twelve rebuilds read identical to their
+ * sources, value for value (`valueTolerance`'s figure).
+ */
+export const VALUE_EMITTED_GRID = 1e-6;
+
+/**
+ * One float32 ULP, relative. `spine-core` holds every frame, curve sample and
+ * vertex in a `Float32Array` (`Utils.newFloatArray`), so two decimals that
+ * differ by the grid above can land on adjacent float32s, and the difference
+ * the walk sees is the decimal gap plus that step.
+ *
+ * ⚠️ It is also the floor of what this measure can see AT ALL: a difference
+ * smaller than one float32 step is invisible to the parser and therefore to
+ * this. The tolerance states that rather than hiding it.
+ */
+export const VALUE_PARSED_ULP = 2 ** -23;
+
+/**
+ * What two readings of one number are allowed to differ by, and nothing more.
+ *
+ * Both terms are derived rather than fitted: the first is rigc's models' grid,
+ * the second is the parser's storage. Measured over the twelve editor exports
+ * in `examples/`, the widest gap between a rebuild and the file it was read
+ * from is **0** — none of 189,699 numeric values differs at all, since issue
+ * #716 made every emitted number its float's own name (it was 0.81 of this
+ * bound, over 56,951 values that differed, while rigc emitted six decimals) —
+ * so the corpus sits inside a bound that was not drawn around it, and no
+ * longer tests its width: `IG21` does.
+ */
+export function valueTolerance(magnitude: number): number {
+  return VALUE_EMITTED_GRID + VALUE_PARSED_ULP * magnitude;
+}
+
+/** Whether two readings of one path agree. `NaN` on both sides is agreement: neither file states it. */
+function valuesAgree(a: number | string, b: number | string): boolean {
+  if (typeof a !== 'number' || typeof b !== 'number') return a === b;
+  if (Number.isNaN(a) && Number.isNaN(b)) return true;
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return a === b;
+  return Math.abs(a - b) <= valueTolerance(Math.max(Math.abs(a), Math.abs(b)));
+}
+
+/**
+ * The measures `diffSkeletonValues` defines, in the order it prints them, and
+ * what each one is. The set is fixed rather than derived from the paths in
+ * front of it, so that a run can say a measure compared NOTHING — the same
+ * distinction `DiffMeasure.total` draws everywhere else in this file.
+ */
+const VALUE_MEASURES: ReadonlyArray<{ id: string; what: string; prefix: string }> = [
+  { id: 'values.skeleton', what: 'the header and its setup-pose bounding box', prefix: 'skeleton/' },
+  { id: 'values.bones', what: 'every bone setup pose, its length and its colour', prefix: 'bones/' },
+  { id: 'values.slots', what: 'every slot colour, dark colour, blend mode and setup attachment', prefix: 'slots/' },
+  { id: 'values.attachments', what: 'every attachment offset, size, vertex, weight, uv and triangle', prefix: 'skins/' },
+  {
+    id: 'values.constraints',
+    what: 'every constraint field the parser reads: pose, flags, offsets, and the property map and its kinds',
+    prefix: 'constraints/',
+  },
+  { id: 'values.events', what: 'every event payload in the setup pose', prefix: 'events/' },
+  { id: 'values.key_times', what: 'every key time, and each animation\'s duration', prefix: 'animations/' },
+  { id: 'values.key_values', what: 'every keyed value: poses, deform vertices, draw orders, event payloads', prefix: 'animations/' },
+  { id: 'values.curves', what: 'every curve type and the Bezier samples the parser built from its handles', prefix: 'animations/' },
+];
+
+/**
+ * Which measure a path belongs to. The first path segment decides it, except
+ * under `animations/`, where the three arms are the three questions that fail
+ * differently: a timing that moved, a value that moved, and an easing that
+ * moved. A segment nothing here names becomes a measure of its own rather than
+ * disappearing into one of these — a walk that grows a top-level kind should
+ * arrive as a new line, not as a silently wider denominator.
+ */
+function valueMeasureFor(path: string): string {
+  const head = path.slice(0, path.indexOf('/') + 1);
+  if (head === 'animations/') {
+    if (path.endsWith('/duration') || /\/key\/\d+\/time$/.test(path)) return 'values.key_times';
+    if (/\/curves\/\d+$/.test(path)) return 'values.curves';
+    return 'values.key_values';
+  }
+  const known = VALUE_MEASURES.find((m) => m.prefix === head);
+  return known === undefined ? `values.${head.slice(0, -1) || path}` : known.id;
+}
+
+/** How many offending paths a note spells out before it counts the rest. */
+const VALUE_OFFENDERS_SPELLED_OUT = 3;
+
+/**
+ * The value-level comparison: are the numbers inside the structure the same
+ * numbers?
+ *
+ * ## Why it is a separate call rather than a section of `diffSkeletons`
+ *
+ * Because its inputs are not JSON. Every default in the format — `time` absent
+ * is 0, `scaleX` absent is 1, a physics key's `value` absent is 0 while its
+ * `mix` is 1 — has to be applied before two files can be compared value by
+ * value, and writing that table here would be a second spelling of the format
+ * inside the gate. So the defaults come from the parser, through
+ * `skeletonValues` in [`validate.ts`](validate.ts), and this function compares
+ * what it returns: an ordered list of `path → value` with every default already
+ * applied by the one reader that owns them.
+ *
+ * ⚠️ **It reports; it does not gate the ladder.** A rung's brief withholds
+ * coordinates on purpose, so no reading of the reference frames could decide
+ * these — `docs/GATE.md`'s *What never gates* applies word for word. The corpus
+ * gate is the one place they DO decide a verdict, and for the reason `IG16`
+ * already gives about `mesh_edges`: there the reference is the very file the
+ * specs were read from, so a value that moved is a decompiler loss rather than
+ * a candidate's entitlement.
+ *
+ * ## What a difference means, and what it cannot mean
+ *
+ * A path missing on one side is counted as unmatched and named as such: it is a
+ * structural finding too, and the measures above it are where that is
+ * diagnosed. A number present on both sides is compared under
+ * `valueTolerance`, which is derived from rigc's quantiser and the parser's
+ * float32 storage — never from the corpus.
+ */
+export function diffSkeletonValues(candidate: SkeletonValue[], reference: SkeletonValue[]): DiffMeasure[] {
+  const left = new Map<string, number | string>();
+  for (const v of candidate) left.set(v.path, v.value);
+  const right = new Map<string, number | string>();
+  for (const v of reference) right.set(v.path, v.value);
+
+  interface Tally {
+    matched: number;
+    total: number;
+    offenders: string[];
+    unpaired: number;
+  }
+  const tallies = new Map<string, Tally>();
+  const order: string[] = VALUE_MEASURES.map((m) => m.id);
+  const tallyFor = (id: string): Tally => {
+    const held = tallies.get(id);
+    if (held !== undefined) return held;
+    const fresh: Tally = { matched: 0, total: 0, offenders: [], unpaired: 0 };
+    tallies.set(id, fresh);
+    if (!order.includes(id)) order.push(id);
+    return fresh;
+  };
+  for (const id of order) tallyFor(id);
+
+  // The candidate's paths in the candidate's own order, then whatever the
+  // reference has that the candidate does not — an iteration over the two
+  // lists as they were built, never over a set.
+  for (const { path, value } of candidate) {
+    const tally = tallyFor(valueMeasureFor(path));
+    tally.total++;
+    const other = right.get(path);
+    if (other === undefined) {
+      tally.unpaired++;
+      if (tally.offenders.length < VALUE_OFFENDERS_SPELLED_OUT) tally.offenders.push(`${path} (candidate only)`);
+      continue;
+    }
+    if (valuesAgree(value, other)) {
+      tally.matched++;
+      continue;
+    }
+    if (tally.offenders.length < VALUE_OFFENDERS_SPELLED_OUT) {
+      const gap =
+        typeof value === 'number' && typeof other === 'number'
+          ? `, off by ${Math.abs(value - other).toExponential(3)} against ${valueTolerance(
+              Math.max(Math.abs(value), Math.abs(other)),
+            ).toExponential(3)} allowed`
+          : '';
+      tally.offenders.push(`${path} ${JSON.stringify(value)} vs ${JSON.stringify(other)}${gap}`);
+    }
+  }
+  for (const { path } of reference) {
+    if (left.has(path)) continue;
+    const tally = tallyFor(valueMeasureFor(path));
+    tally.total++;
+    tally.unpaired++;
+    if (tally.offenders.length < VALUE_OFFENDERS_SPELLED_OUT) tally.offenders.push(`${path} (reference only)`);
+  }
+
+  return order.map((id) => {
+    const tally = tallyFor(id);
+    const defined = VALUE_MEASURES.find((m) => m.id === id);
+    const missed = tally.total - tally.matched;
+    const note =
+      tally.total === 0
+        ? 'neither side carries one'
+        : missed === 0
+          ? undefined
+          : `${missed} moved` +
+            (tally.unpaired === 0 ? '' : `, ${tally.unpaired} of them on one side only`) +
+            `: ${tally.offenders.join('; ')}` +
+            (missed > tally.offenders.length ? `; …and ${missed - tally.offenders.length} more` : '');
+    return measure(id, defined?.what ?? 'values under a path kind this report does not define', tally.matched, tally.total, note);
+  });
+}
+
+/** Every value measure that is not a perfect match, by id. What a test asserts on. */
+export function movedValueMeasures(measures: DiffMeasure[]): string[] {
+  return measures.filter((m) => m.ratio < 1).map((m) => m.id);
+}
+
+/**
+ * `skeleton 1.000 · bones 1.000 · …`, the same one-line shape `reportedFigures`
+ * has, and with no roll-up for the same reason: a mean over "did the times move"
+ * and "did the vertices move" is a number with no referent.
+ */
+export function valueFigures(measures: DiffMeasure[]): string {
+  return measures.map((m) => `${m.id.slice(m.id.indexOf('.') + 1)} ${fmt(m.ratio)}`).join(' · ');
+}
+
+const fmt = (n: number): string => n.toFixed(3);
+
+/**
+ * `mesh_edges 1.000 · key_density 0.333`, or `null` when nothing is reported.
+ *
+ * Every reported measure by name, and no roll-up of any kind: these have unlike
+ * units, so a digest over them would be the mean `DiffReported` exists to
+ * refuse. The section is dropped from the id because the ids are unique across
+ * the report and the line is a summary.
+ */
+export function reportedFigures(report: DiffReport): string | null {
+  const measures = [...report.sections.flatMap((s) => s.reported?.measures ?? []), ...report.header.measures];
+  if (measures.length === 0) return null;
+  return measures.map((m) => `${m.id.slice(m.id.indexOf('.') + 1)} ${fmt(m.ratio)}`).join(' · ');
+}
+
+/** `bones 0.567 (name-matched) · 1.000 (name-agnostic)`, or just the one figure. */
+export function sectionFigures(section: DiffSection): string {
+  const matched = `${fmt(section.ratio)} (name-matched)`;
+  return section.nameAgnostic === undefined
+    ? `${section.name} ${matched}`
+    : `${section.name} ${matched} · ${fmt(section.nameAgnostic.ratio)} (name-agnostic)`;
+}
+
+function measureLines(measures: DiffMeasure[], strip: number): string[] {
+  return measures.map((m) => {
+    const counts = `${m.matched}/${m.total}`;
+    return `      ${fmt(m.ratio)}  ${m.id.slice(strip).padEnd(28)} ${counts.padEnd(11)} ${m.what}${m.note ? `  — ${m.note}` : ''}`;
+  });
+}
+
+export function diffLines(report: DiffReport, labels: { candidate: string; reference: string }): string[] {
+  const lines: string[] = [];
+  lines.push(`  candidate  ${labels.candidate}`);
+  lines.push(`  reference  ${labels.reference}`);
+  const keys = Object.keys(report.reference);
+  lines.push(`  ..         ${keys.map((k) => `${k}=${report.candidate[k]}/${report.reference[k]}`).join('  ')}   (candidate/reference)`);
+  lines.push('');
+  // The `skeleton` block, first because that is where it sits in the file, and
+  // with `(no mean)` for the same reason a section's `(reported)` block has one.
+  lines.push(
+    `  ${'skeleton (reported)'.padEnd(21)} (no mean)   over ${report.header.measures.length} measures` +
+      '  — the header\'s setup-pose bounding box, which no reading of the frames could decide',
+  );
+  lines.push(...measureLines(report.header.measures, 'skeleton.'.length));
+  lines.push('');
+  // 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) {
+    lines.push(head(section.name, section.ratio, section.measures.length));
+    lines.push(...measureLines(section.measures, section.name.length + 1));
+    const agnostic = section.nameAgnostic;
+    if (agnostic) {
+      lines.push('');
+      lines.push(
+        `${head(`${section.name} (name-agnostic)`, agnostic.ratio, agnostic.measures.length)}` +
+          '  — 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));
+    }
+    // No mean on this heading, and the absence is the statement: see
+    // `DiffReported`. `(no mean)` sits where `mean 0.000` would, so the column
+    // the eye follows down the report is unbroken.
+    const reported = section.reported;
+    if (reported) {
+      lines.push('');
+      lines.push(
+        `  ${`${section.name} (reported)`.padEnd(21)} (no mean)   over ${reported.measures.length} ` +
+          `measure${reported.measures.length === 1 ? '' : 's'}` +
+          '  — unobservable from the frames, so reported and folded into nothing',
+      );
+      lines.push(...measureLines(reported.measures, section.name.length + 1));
+    }
+    lines.push('');
+  }
+  lines.push('  There is no overall score, on purpose: a section mean is an average of the');
+  lines.push('  measures printed under it, and averaging those together would hide which');
+  lines.push('  half of a rig is wrong. Read the measures.');
+  lines.push('');
+  lines.push('  `bones` and `slots` carry two figures because most of their measures are');
+  lines.push('  keyed on names, and a candidate is entitled to its own. They are two');
+  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 its box.');
+  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');
+  lines.push('  each side\'s box is its writer\'s own arithmetic.');
+  lines.push('');
+  lines.push('  A `(reported)` block has no mean because its measures have unlike units, and');
+  lines.push('  it stays out of the section mean above it for the same reason no clause may');
+  lines.push('  read it: no reading of the reference frames could have decided these. They are');
+  lines.push('  findings against the reference export all the same — each states its own');
+  lines.push('  convention, and a rate states which side is the bigger one.');
+  return lines;
+}