rig-c 0.0.0-stage → 2.20.4

package/src/assertions/bodies/a43.ts

@@ -0,0 +1,181 @@
+/**
+ * A43, the body (issue #1025, cut 4c-3 of step 4c of #380): the two-colour
+ * tint loads and poses as written.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads, which is
+ * `TwoColourFacts` (`../facts/two_colour.ts`) where it read the skeleton JSON
+ * and the loaded skeleton: the dark colour each slot states and the one the
+ * runtime loaded, the file's slot timelines, whether an animation exists, and
+ * a slot's two colours posed at a key's time — which `validate()` takes from
+ * spine-core and the model side from rigc's core. The argument for the rule is
+ * above its `check` call, which stays in `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { TwoColourFacts } from '../facts/two_colour.ts';
+import { SKIP_NO_TWO_COLOR_TINT } from '../reasons.ts';
+import { atStoredKey, isObj } from '../values.ts';
+
+export function a43TwoColorTintLoadsAndPosesAsWritten({ fail, skip, stats }: Verdicts, facts: TwoColourFacts): void {
+  /** `rrggbb`, or `rrggbbaa` whose last pair the format drops. Null for anything else. */
+  const readDarkHex = (hex: string): [number, number, number] | null => {
+    const body = hex.startsWith('#') ? hex.slice(1) : hex;
+    if (!/^[\da-fA-F]{6}([\da-fA-F]{2})?$/.test(body)) return null;
+    return [0, 2, 4].map((i) => Number.parseInt(body.slice(i, i + 2), 16) / 255) as [number, number, number];
+  };
+  /** `rrggbbaa`, or `rrggbb` the runtime opens at alpha 1. Null for anything else. */
+  const readLightHex = (hex: string): [number, number, number, number] | null => {
+    const body = hex.startsWith('#') ? hex.slice(1) : hex;
+    if (!/^[\da-fA-F]{6}([\da-fA-F]{2})?$/.test(body)) return null;
+    const rgb = [0, 2, 4].map((i) => Number.parseInt(body.slice(i, i + 2), 16) / 255);
+    return [rgb[0], rgb[1], rgb[2], body.length === 8 ? Number.parseInt(body.slice(6, 8), 16) / 255 : 1];
+  };
+  /**
+   * Half a quantisation step. A channel is one byte in the file and a
+   * `Float32Array` entry in a timeline, so the widest honest gap between the
+   * number written and the number posed is well under `1/510`.
+   */
+  const STEP = 1 / 510;
+  const off = (found: number, want: number): boolean => !Number.isFinite(found) || Math.abs(found - want) > STEP;
+  const show = (c: readonly number[]): string => c.map((n) => (Number.isFinite(n) ? n.toFixed(4) : 'NaN')).join(', ');
+
+  // -- the subjects, read off the FILE ---------------------------------
+  const declared = new Map<string, string>();
+  for (const { slot, dark } of facts.slotDarks) declared.set(slot, dark);
+  // `rgb2` joined in issue #730, and it is this rule's subject rather than a
+  // new one's because it is the same tint with the light alpha left out:
+  // `RGB2Timeline` writes the light rgb and the dark colour, and on a slot
+  // with no dark colour it throws in `apply1` exactly as `RGBA2Timeline`
+  // does (measured on a forged file: `TypeError: null is not an object
+  // (evaluating 'dark.r = …')`). The one thing it does differently is the
+  // alpha it does NOT pose, which is `A45`'s question, not this one's.
+  const keyed: Array<{ anim: string; slot: string; timeline: 'rgba2' | 'rgb2'; keys: unknown[] }> = [];
+  for (const { animation: animName, slot: slotName, timelines } of facts.slotTimelines) {
+    for (const timeline of ['rgba2', 'rgb2'] as const) {
+      const keys = timelines[timeline];
+      if (Array.isArray(keys)) keyed.push({ anim: animName, slot: slotName, timeline, keys });
+    }
+  }
+  if (declared.size === 0 && keyed.length === 0) {
+    return skip('A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN', SKIP_NO_TWO_COLOR_TINT);
+  }
+  stats.darkSlots = declared.size;
+  stats.rgba2Timelines = keyed.filter((t) => t.timeline === 'rgba2').length;
+  stats.rgb2Timelines = keyed.filter((t) => t.timeline === 'rgb2').length;
+
+  // -- clause 1: the setup pose ----------------------------------------
+  for (const [name, hex] of declared) {
+    const want = readDarkHex(hex);
+    const loaded = facts.loadedDark(name);
+    // ⚠️ "The parser kept nothing" is asked FIRST, and the order is the
+    // finding rather than a style: an empty string is both unreadable as a
+    // colour and dropped outright, and only the second sentence is about
+    // what the loaded skeleton holds. Asked the other way round, `""` was
+    // reported as "not six hex digits" — true, and about the file, on the
+    // one input where the file is not what went wrong.
+    if (loaded === null) {
+      fail(
+        'A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN',
+        `slot "${name}" states dark ${JSON.stringify(hex)} and the loaded skeleton holds no dark colour for ` +
+          'it at all — the slot reader takes `dark` through a truthiness test, so a falsy value is dropped ' +
+          'in silence and the slot is tinted with one colour',
+      );
+      continue;
+    }
+    if (want === null) {
+      fail(
+        'A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN',
+        `slot "${name}" states dark ${JSON.stringify(hex)}, which is not six hex digits — the parser reads ` +
+          'fixed two-character slices and stores whatever `parseInt` returns, so the loaded colour is ' +
+          `(${show([loaded.r, loaded.g, loaded.b])}) rather than a failure`,
+      );
+      continue;
+    }
+    const found: [number, number, number] = [loaded.r, loaded.g, loaded.b];
+    if (found.some((n, i) => off(n, want[i]))) {
+      fail(
+        'A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN',
+        `slot "${name}" states dark ${JSON.stringify(hex)} and the runtime loaded (${show(found)}), wanted ` +
+          `(${show(want)})`,
+      );
+    }
+  }
+
+  // -- clauses 2 and 3: every rgba2 and rgb2 timeline --------------------
+  //
+  // ⚠️ Clause 2 poisons its whole ANIMATION, not only its own timeline: the
+  // throw happens inside `state.apply`, which applies every timeline of the
+  // animation at once, so posing a second — correct — `rgba2` timeline in the
+  // same animation would take this assertion down with a `threw:` line
+  // instead of the two named failures it has already worked out.
+  const cannotPose = new Set(keyed.filter((t) => !declared.has(t.slot)).map((t) => t.anim));
+  for (const { anim: animName, slot: slotName, timeline, keys } of keyed) {
+    const where = `animation "${animName}" slot "${slotName}" ${timeline}`;
+    if (!declared.has(slotName)) {
+      fail(
+        'A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN',
+        `${where}: slot "${slotName}" declares no setup "dark", so the runtime allocates no dark colour for ` +
+          `it and applying this animation throws instead of tinting — give the slot a \`dark\`, or key ` +
+          `"${timeline === 'rgba2' ? 'rgba' : 'rgb'}"`,
+      );
+      continue;
+    }
+    if (cannotPose.has(animName)) continue;
+    if (!facts.hasAnimation(animName)) {
+      fail('A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN', `${where}: the loaded skeleton has no animation "${animName}"`);
+      continue;
+    }
+    for (const rawKey of keys) {
+      if (!isObj(rawKey)) continue;
+      const time = typeof rawKey.time === 'number' ? rawKey.time : 0;
+      const wantLight = typeof rawKey.light === 'string' ? readLightHex(rawKey.light) : null;
+      const wantDark = typeof rawKey.dark === 'string' ? readDarkHex(rawKey.dark) : null;
+      // ⚠️ Posed BEFORE the key's own spelling is judged, so that a key whose
+      // hex cannot be read is still reported with the colour the runtime
+      // actually holds. `Color.setFromString` slices fixed offsets and stores
+      // whatever `parseInt` gives back, so the value found is the product
+      // here — "not six hex digits" alone would be the value REQUIRED twice
+      // over and the found value nowhere.
+      // At the key as the runtime stores it — see `atStoredKey` (#771).
+      const posed = facts.posedTint(animName, slotName, atStoredKey(time));
+      const light = posed?.light;
+      const dark = posed?.dark ?? null;
+      if (!light || dark === null) {
+        fail(
+          'A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN',
+          `${where} (t=${time}): the posed skeleton has no ${light ? 'dark colour' : 'slot'} to read`,
+        );
+        continue;
+      }
+      const foundLight: [number, number, number, number] = [light.r, light.g, light.b, light.a];
+      const foundDark: [number, number, number] = [dark.r, dark.g, dark.b];
+      if (wantLight === null || wantDark === null) {
+        fail(
+          'A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN',
+          `${where} (t=${time}): the key states light ${JSON.stringify(rawKey.light)} and dark ` +
+            `${JSON.stringify(rawKey.dark)} — an ${timeline} key needs both, each six or eight hex digits — and the ` +
+            `runtime poses light (${show(foundLight)}), dark (${show(foundDark)})`,
+        );
+        continue;
+      }
+      // An `rgb2` key's light colour is three channels, and the posed alpha
+      // is not its to state — `RGB2Timeline` leaves it where it was — so the
+      // comparison is over the channels the timeline writes. For `rgba2`
+      // that is all four, and the line reads as it always did.
+      const lightChannels = timeline === 'rgba2' ? 4 : 3;
+      if (foundLight.slice(0, lightChannels).some((n, i) => off(n, wantLight[i]))) {
+        fail(
+          'A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN',
+          `${where} (t=${time}): light posed (${show(foundLight.slice(0, lightChannels))}), the key states ` +
+            `${JSON.stringify(rawKey.light)} = (${show(wantLight.slice(0, lightChannels))})`,
+        );
+      }
+      if (foundDark.some((n, i) => off(n, wantDark[i]))) {
+        fail(
+          'A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN',
+          `${where} (t=${time}): dark posed (${show(foundDark)}), the key states ${JSON.stringify(rawKey.dark)} ` +
+            `= (${show(wantDark)})`,
+        );
+      }
+    }
+  }
+}

package/src/assertions/bodies/a44.ts

@@ -0,0 +1,23 @@
+/**
+ * A44, the body (issue #1025, step 4c of #380): a linked mesh states no
+ * geometry of its own.
+ *
+ * Moved out of `src/validate.ts` by its subject only. Which links the file
+ * declares is the rig's — a document's `linkedmesh` record is one — so the
+ * roster moved, and a rig with no link SKIPs on both sides. What A44 refuses
+ * is the encoding's: a link record holds no geometry field, and `uvs`,
+ * `triangles`, `vertices`, `hull` and `edges` written on a link exist only in
+ * the Spine text (the census's row for A44). That clause, and the sentence it
+ * prints, stay with the round trip, which hands its finding about each link in
+ * as the link's `encoding`, printed in the order the body always printed it.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { LinkFacts } from '../facts/linked_meshes.ts';
+import { SKIP_NO_LINKED_MESH } from '../reasons.ts';
+
+export function a44LinkedMeshStatesNoGeometryOfItsOwn({ fail, skip }: Verdicts, { links }: LinkFacts): void {
+  if (links.length === 0) return skip('A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN', SKIP_NO_LINKED_MESH);
+  for (const link of links) {
+    for (const detail of link.encoding) fail('A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN', detail);
+  }
+}

package/src/assertions/bodies/a45.ts

@@ -0,0 +1,172 @@
+/**
+ * A45, the body (issue #1025, step 4c of #380): the separable colour timelines
+ * own their channels and pose as written.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads, which is
+ * three facts (`../facts/slot_colour.ts`) where it read the skeleton JSON and
+ * the loaded skeleton: the animations' slot timelines in the file's order, as
+ * the file spells them; whether an animation exists; and a slot's colour posed
+ * at a time on a fresh track, which `validate()` takes from spine-core and the
+ * model side from rigc's core. The `check` call stays in `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { SlotColourFacts } from '../facts/slot_colour.ts';
+import { SKIP_NO_SEPARABLE_COLOR } from '../reasons.ts';
+import { atStoredKey, isObj } from '../values.ts';
+import { SLOT_COLOR_CHANNELS } from '../../timelines.ts';
+
+// ⭐ **Why this is its own rule and not a clause on `A43`.** `rgb` and
+// `alpha` pose no dark colour, so under A43's name a failure would be a
+// verdict saying "two-colour tint" about a file that states one colour —
+// the name would say something other than what it decides (the rule #712
+// applied to A43 itself, against a clause on A10). And the SKIP is the
+// sharper half: a rig with a `dark` and no separable timeline has A43's
+// subject present, so a clause there could only PASS on it, which is a pass
+// for an absent subject.
+//
+// 🚨 **What it decides is what makes `rgb` + `alpha` not `rgba`**, and both
+// clauses are about the file against the runtime:
+//
+//   1. **One channel, one timeline.** Each colour timeline poses its
+//      channels at EVERY time — before its first key it writes the setup
+//      value — so when two of one slot share a channel, the one applied
+//      later (the one the file states later) overwrites the other
+//      everywhere and the first one's keys on it are read by nothing
+//      (`SLOT_COLOR_CHANNELS`). It is the shape a converter that writes a
+//      separable `rgb` as `rgba` leaves beside the `alpha` it kept, and it
+//      loads without a word.
+//   2. **Posed as written.** Stepped to each key's own time, the channels
+//      the timeline writes are the key's: a colour that is not six hex
+//      digits loads as NaN, and a key whose time another key repeats is
+//      read by nothing, and both parse in silence.
+//
+// ⚠️ An `rgb` timeline alone that a converter wrote as `rgba` with the
+// setup alpha is NOT this rule's to see, and nothing that reads only the
+// file can see it: the result is a correct `rgba`, which is also what an
+// author keying the light colour and holding its alpha would write. What
+// differs is what happens UNDER another track that moves the alpha, which
+// is the consumer's composing rather than the object (CLAUDE.md). That
+// file SKIPs here — it keys no `rgb` or `alpha` — and says so.
+//
+// ⚠️ The required values are parsed HERE, as A43's are, and the channel
+// table is `timelines.ts`'s rather than the loaded timelines' property ids:
+// a check that asked the parser what a timeline writes would agree with it
+// whatever it did. A selftest control holds that table to the runtime's ids.
+export function a45SeparableColorTimelinesOwnTheirChannelsAndPoseAsWritten({ fail, skip, stats }: Verdicts, facts: SlotColourFacts): void {
+  const NAME = 'A45_SEPARABLE_COLOR_TIMELINES_OWN_THEIR_CHANNELS_AND_POSE_AS_WRITTEN';
+  /** `rrggbb`, or `rrggbbaa` whose alpha an `rgb` key cannot pose. Null for anything else. */
+  const readRgbHex = (hex: unknown): [number, number, number] | null => {
+    if (typeof hex !== 'string') return null;
+    const body = hex.startsWith('#') ? hex.slice(1) : hex;
+    if (!/^[\da-fA-F]{6}([\da-fA-F]{2})?$/.test(body)) return null;
+    return [0, 2, 4].map((i) => Number.parseInt(body.slice(i, i + 2), 16) / 255) as [number, number, number];
+  };
+  /** Half a byte step for a hex channel; a stored `Float32` for an alpha `value`. */
+  const HEX_STEP = 1 / 510;
+  const FLOAT_STEP = 1e-6;
+  const off = (found: number, want: number, step: number): boolean => !Number.isFinite(found) || Math.abs(found - want) > step;
+  const show = (c: readonly number[]): string => c.map((n) => (Number.isFinite(n) ? n.toFixed(4) : 'NaN')).join(', ');
+
+  // -- the subjects, read off the FILE ---------------------------------
+  const subjects: Array<{ anim: string; slot: string; timelines: Record<string, unknown> }> = [];
+  for (const { animation: animName, slot: slotName, timelines } of facts.slotTimelines) {
+    if (Array.isArray(timelines.rgb) || Array.isArray(timelines.alpha)) {
+      subjects.push({ anim: animName, slot: slotName, timelines });
+    }
+  }
+  if (subjects.length === 0) return skip(NAME, SKIP_NO_SEPARABLE_COLOR);
+  stats.separableColorTimelines = subjects.reduce(
+    (n, s) => n + (Array.isArray(s.timelines.rgb) ? 1 : 0) + (Array.isArray(s.timelines.alpha) ? 1 : 0),
+    0,
+  );
+
+  for (const { anim: animName, slot: slotName, timelines } of subjects) {
+    const at = `animation "${animName}" slot "${slotName}"`;
+    // In FILE order, which is the order `readAnimation` pushes them and so
+    // the order they apply in.
+    const colour = Object.keys(timelines).filter((name) => name in SLOT_COLOR_CHANNELS && Array.isArray(timelines[name]));
+
+    // -- clause 1: one channel, one timeline ---------------------------
+    let shared = false;
+    for (const channel of ['rgb', 'alpha', 'dark'] as const) {
+      const writers = colour.filter((name) => SLOT_COLOR_CHANNELS[name].includes(channel));
+      if (writers.length < 2 || !writers.some((name) => name === 'rgb' || name === 'alpha')) continue;
+      shared = true;
+      const last = writers[writers.length - 1];
+      fail(
+        NAME,
+        `${at}: ${writers.map((name) => `"${name}"`).join(' and ')} ${writers.length === 2 ? 'both' : 'all'} key the ${channel === 'rgb' ? 'light rgb' : channel === 'alpha' ? 'alpha' : 'dark colour'} ` +
+          `— each poses it at every time, its setup value before its first key included, so "${last}", which the ` +
+          `file states last, overwrites ${writers.length === 2 ? `"${writers[0]}"` : 'the others'} everywhere and ` +
+          'those keys are read by nothing. Key each channel once: "rgb" and "alpha" on their own key times, or one "rgba"',
+      );
+    }
+    if (shared) continue;
+
+    // -- clause 2: posed as written ------------------------------------
+    //
+    // ⚠️ Two things this does NOT do, both measured rather than skipped:
+    // it does not read the loaded timeline's CLASS back, and it does not
+    // hold a channel the timeline leaves alone to the setup pose. Against
+    // the linked parser neither can fail — every `rgb` / `alpha` array that
+    // loads at all loads as an `RGBTimeline` / `AlphaTimeline`, and the
+    // three other outcomes (an empty array, a slot the skeleton lacks, a
+    // name outside the switch) throw at `A00` — so either would be a clause
+    // nobody can see fire. The selftest reads both off spine-core directly
+    // (`S82`–`S84`), where they are measurements of the runtime rather than
+    // checks on a file.
+    if (!facts.hasAnimation(animName)) {
+      fail(NAME, `${at}: the loaded skeleton has no animation "${animName}"`);
+      continue;
+    }
+    for (const name of ['rgb', 'alpha'] as const) {
+      const keys = timelines[name];
+      if (!Array.isArray(keys)) continue;
+      const where = `${at} ${name}`;
+      for (const rawKey of keys) {
+        if (!isObj(rawKey)) continue;
+        const time = typeof rawKey.time === 'number' ? rawKey.time : 0;
+        // At the key as the runtime stores it, not one float step before
+        // it — see `atStoredKey` (issue #771).
+        const posed = facts.posedSlot(animName, slotName, atStoredKey(time));
+        if (!posed) {
+          fail(NAME, `${where} (t=${time}): the posed skeleton has no slot "${slotName}" to read`);
+          continue;
+        }
+        const light = [posed.color.r, posed.color.g, posed.color.b, posed.color.a];
+        if (name === 'rgb') {
+          const stated = readRgbHex(rawKey.color);
+          if (stated === null) {
+            fail(
+              NAME,
+              `${where} (t=${time}): the key states color ${JSON.stringify(rawKey.color)} — an rgb key is six hex ` +
+                `digits — and the runtime poses (${show(light.slice(0, 3))})`,
+            );
+          } else if (light.slice(0, 3).some((n, i) => off(n, stated[i], HEX_STEP))) {
+            fail(
+              NAME,
+              `${where} (t=${time}): rgb posed (${show(light.slice(0, 3))}), the key states ` +
+                `${JSON.stringify(rawKey.color)} = (${show(stated)})`,
+            );
+          }
+        } else {
+          // `readTimeline1(…, 0, 1)`: an absent `value` IS 0, and an editor
+          // omits it there, so absence is read the parser's way rather than
+          // as a malformed key.
+          const stated = rawKey.value === undefined ? 0 : rawKey.value;
+          if (typeof stated !== 'number' || off(light[3], stated, FLOAT_STEP)) {
+            fail(
+              NAME,
+              `${where} (t=${time}): alpha posed ${show([light[3]])}, the key states value ${JSON.stringify(rawKey.value)}` +
+                (typeof stated !== 'number'
+                  ? ' — an alpha key\'s value is a number'
+                  : stated < 0 || stated > 1
+                    ? ' — the runtime clamps a posed alpha to 0..1'
+                    : ''),
+            );
+          }
+        }
+      }
+    }
+  }
+}

package/src/assertions/bodies/a46.ts

@@ -0,0 +1,224 @@
+/**
+ * A46, the body (issue #1025, cut 4c-3 of step 4c of #380): a numbered series
+ * shows the frame the file states.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads, which is
+ * `SequenceFacts` (`../facts/sequences.ts`) where it read the skeleton JSON and
+ * the loaded skeleton — and for one change of key: what it knew about an
+ * attachment it used to file under the loaded attachment OBJECT, and now files
+ * under the entry's address (skin, slot, placeholder), the one key both sides
+ * hold. The runtime's side loads one object per address, so every map below
+ * holds what it held. The argument for the rule is above its `check` call,
+ * which stays in `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import { entryAddress, type EntryAddress, type SequenceFacts } from '../facts/sequences.ts';
+import { attachmentRegionLookups } from '../region_lookups.ts';
+import { SKIP_NO_SEQUENCE } from '../reasons.ts';
+import { atStoredKey, isObj } from '../values.ts';
+import { SEQUENCE_MODES } from '../../timelines.ts';
+
+export function a46SequenceAttachmentsShowTheFrameTheFileStates({ fail, skip, stats }: Verdicts, facts: SequenceFacts): void {
+  const NAME = 'A46_SEQUENCE_ATTACHMENTS_SHOW_THE_FRAME_THE_FILE_STATES';
+  type Series = { where: string; lookups: string[] | null; count: number; setup: number };
+  /** The loaded attachment's address -> what the FILE says its series is. */
+  const series = new Map<EntryAddress, Series>();
+  /** The addresses the runtime loaded an attachment at, for the timelines to find. */
+  const loadedAt = new Set<EntryAddress>();
+  /** Attachments whose block was already refused above — their timelines say nothing more. */
+  const refused = new Set<EntryAddress>();
+  const whole = (v: unknown, fallback: number): number | null =>
+    v === undefined ? fallback : typeof v === 'number' && Number.isInteger(v) ? v : null;
+  let blocks = 0;
+  for (const entry of facts.entries) {
+    const at = entryAddress(entry.skin, entry.slot, entry.placeholder);
+    const loaded = entry.loaded;
+    const where = `skin ${JSON.stringify(entry.skin)} slot ${JSON.stringify(entry.slot)} attachment ${JSON.stringify(entry.placeholder)}`;
+    if (loaded) loadedAt.add(at);
+    if (entry.sequence === undefined || entry.sequence === null) continue;
+    blocks++;
+    const seq = entry.sequence;
+    const name = typeof entry.name === 'string' ? entry.name : entry.placeholder;
+    const path = typeof entry.path === 'string' ? entry.path : name;
+    const count = isObj(seq) ? whole(seq.count, 0) : null;
+    const setup = isObj(seq) ? whole(seq.setup, 0) : null;
+    if ((count === null || setup === null || count < 1) && loaded) refused.add(at);
+    if (count === null || setup === null || count < 1) {
+      fail(
+        NAME,
+        `${where}: the sequence states ${JSON.stringify(seq)}` +
+          (isObj(seq) && seq.count === undefined
+            ? ' and no "count" — `readSequence` reads 0 (`SkeletonJson.js:644`), so the attachment loads holding no region and draws nothing'
+            : ' — "count" is a whole number of at least 1 and "setup" a whole number, or the series the parser builds is not the one written'),
+      );
+      continue;
+    }
+    if ((setup < 0 || setup >= count) && loaded) refused.add(at);
+    if (setup < 0 || setup >= count) {
+      fail(
+        NAME,
+        `${where}: the sequence's setup frame is ${setup} of a ${count}-frame series (frames 0 to ${count - 1}); ` +
+          '`Sequence.resolveIndex` clamps it, so the setup pose shows ' +
+          `${setup < 0 ? 'no frame at all' : `frame ${count - 1}, which the file does not name`}`,
+      );
+      continue;
+    }
+    if (!loaded) continue; // A00/A08 own an attachment that did not load
+    series.set(at, { where, lookups: attachmentRegionLookups(seq, path), count, setup });
+  }
+
+  /**
+   * The frame the file's statement gives for one key at one elapsed time —
+   * A46's prediction, not a call into the runtime. What holds it is the
+   * comparison it feeds: every sample sets it against the frame the posed
+   * slot shows, so a reading that disagreed with the runtime would fail A46
+   * on a correct file. A46 passing with samples posed on the selftest's
+   * series probes is that measurement for the modes they key; `M73` is its
+   * red half.
+   */
+  const frameOf = (mode: string, index: number, elapsed: number, delay: number, count: number): number => {
+    if (mode === 'hold') return index;
+    let i = index + Math.trunc(elapsed / delay + 0.00001);
+    const n = count * 2 - 2;
+    switch (mode) {
+      case 'once':
+        return Math.min(count - 1, i);
+      case 'loop':
+        return i % count;
+      case 'pingpong':
+        i = n === 0 ? 0 : i % n;
+        return i >= count ? n - i : i;
+      case 'onceReverse':
+        return Math.max(count - 1 - i, 0);
+      case 'loopReverse':
+        return count - 1 - (i % count);
+      default: // pingpongReverse
+        i = n === 0 ? 0 : (i + count - 1) % n;
+        return i >= count ? n - i : i;
+    }
+  };
+
+  let timelines = 0;
+  let compared = 0;
+  let unshown = 0;
+  for (const { animation: animName, skin: skinName, slot: slotName, placeholder, keys } of facts.timelines) {
+    if (keys.length === 0) continue; // `readAnimation` skips it; A34 owns an empty timeline
+    timelines++;
+    const where = `animation ${JSON.stringify(animName)} ${skinName}/${slotName}/${placeholder} sequence`;
+    const keyed = entryAddress(skinName, slotName, placeholder);
+    if (!loadedAt.has(keyed)) continue; // the parser throws on a missing target: A00's
+    if (refused.has(keyed)) continue; // its block is already named above
+    const own = series.get(keyed);
+    if (own === undefined) {
+      fail(
+        NAME,
+        `${where}: the timeline steps an attachment that carries no "sequence" block. The parser gives it a ` +
+          'series of ONE region (`readSequence(null)` is `new Sequence(1, false)`), so every mode shows that ' +
+          'region at every time — measured: a "loop" key on a plain region showed it throughout',
+      );
+      continue;
+    }
+    // -- the keys, as the file states them --------------------------
+    type Key = { time: number; mode: string; index: number; delay: number };
+    const read: Key[] = [];
+    let carried = 0;
+    let malformed = false;
+    keys.forEach((rawKey, k) => {
+      const key = isObj(rawKey) ? rawKey : {};
+      const at = `${where} key ${k}`;
+      const time = typeof key.time === 'number' ? key.time : 0;
+      const mode = key.mode === undefined ? 'hold' : key.mode;
+      const index = key.index === undefined ? 0 : key.index;
+      if (key.delay !== undefined) carried = typeof key.delay === 'number' ? key.delay : Number.NaN;
+      if (typeof mode !== 'string' || !(SEQUENCE_MODES as readonly string[]).includes(mode)) {
+        malformed = true;
+        fail(
+          NAME,
+          `${at} (t=${time}): mode ${JSON.stringify(key.mode)} is not one of the ${SEQUENCE_MODES.length} the ` +
+            `format has (${SEQUENCE_MODES.join(', ')}); the parser reads \`SequenceMode[mode]\`, which is ` +
+            'undefined, stores mode bits 0, and the key plays as "hold"',
+        );
+        return;
+      }
+      if (typeof index !== 'number' || !Number.isInteger(index) || index < 0 || index >= own.count) {
+        malformed = true;
+        fail(
+          NAME,
+          `${at} (t=${time}): index ${JSON.stringify(key.index)} is not a frame of the ${own.count}-frame series ` +
+            `(0 to ${own.count - 1}); the runtime stores \`index << 4\`, truncating a fraction, and ` +
+            '`Sequence.resolveIndex` clamps a frame past the end to the last one',
+        );
+        return;
+      }
+      if (mode !== 'hold' && !(carried > 0)) {
+        malformed = true;
+        fail(
+          NAME,
+          `${at} (t=${time}): "${mode}" at a delay of ${String(carried)}${key.delay === undefined ? ' (carried from the key before, 0 on the first)' : ''} — ` +
+            'the frame advances by `(time - keyTime) / delay`, and at 0 that is Infinity, `Infinity | 0` is 0, ' +
+            'and the key shows its first frame throughout: "hold" spelt as another mode',
+        );
+        return;
+      }
+      read.push({ time, mode, index, delay: carried });
+    });
+    if (malformed) continue;
+
+    // -- the pose, sampled ------------------------------------------
+    const end = facts.duration(animName);
+    if (end === null || !facts.hasSlot(slotName)) continue; // A00's
+    /** `key` is the index into `read`, or -1 before the first key (the setup frame). */
+    const samples: Array<{ time: number; key: number; steps: number }> = [];
+    if (read[0].time > 0) samples.push({ time: read[0].time / 2, key: -1, steps: 0 });
+    read.forEach((key, k) => {
+      const until = k + 1 < read.length ? read[k + 1].time : end;
+      if (key.mode === 'hold') {
+        samples.push({ time: key.time, key: k, steps: 0 });
+        return;
+      }
+      // Mid-frame, and enough steps to wrap every mode at least once.
+      for (let step = 0; step < own.count * 2 + 2; step++) {
+        const time = key.time + (step + 0.5) * key.delay;
+        if (time >= until || time > end) break;
+        samples.push({ time, key: k, steps: step + 0.5 });
+      }
+    });
+    let shownHere = 0;
+    for (const sample of samples) {
+      // A `hold` sample is AT its key, so it is posed at the key as
+      // the runtime stores it (`atStoredKey`); a mid-frame sample is
+      // half a delay from any key and is posed where it is.
+      const pose = facts.posedFrame(animName, slotName, sample.key >= 0 && sample.steps === 0 ? atStoredKey(sample.time) : sample.time);
+      // The slot must show the keyed attachment or one playing its
+      // timelines — the only case `applyToSlot` writes.
+      if (pose === null || (pose.shown !== keyed && pose.playsAs !== keyed)) continue;
+      const drawn = series.get(pose.shown);
+      if (drawn === undefined || drawn.lookups === null) continue;
+      shownHere++;
+      compared++;
+      // The frame count the runtime folds by is the SHOWN attachment's:
+      // a link with a series of its own steps it by its source's keys.
+      const key = sample.key < 0 ? null : read[sample.key];
+      const want = key === null ? drawn.setup : frameOf(key.mode, key.index, sample.time - key.time, key.delay, drawn.count);
+      const region = pose.region;
+      if (region !== drawn.lookups[want]) {
+        fail(
+          NAME,
+          `${where} (t=${Number(sample.time.toFixed(4))}): the slot shows region ${JSON.stringify(region)}, and ` +
+            `the file states frame ${want} of ${drawn.count} — ${JSON.stringify(drawn.lookups[want])} — ` +
+            (key === null
+              ? 'the setup frame, before the first key'
+              : `key ${sample.key} plays "${key.mode}" from frame ${key.index} every ${key.delay}s, ` +
+                `${sample.steps} delay(s) in`),
+        );
+        break;
+      }
+    }
+    if (shownHere === 0) unshown++;
+  }
+  if (blocks === 0 && timelines === 0) return skip(NAME, SKIP_NO_SEQUENCE);
+  stats.sequenceBlocks = blocks;
+  stats.sequenceTimelines = timelines;
+  stats.sequenceSamples = compared;
+  if (unshown > 0) stats.sequenceSamplesUnshown = unshown;
+}