spine-rigc 1.7.0 → 1.9.0

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/a47.ts

@@ -0,0 +1,59 @@
+/**
+ * A47, the body (issue #1025, step 4c of #380): an ik constraint muted for
+ * good — resting at mix 0 with no animation switching it on — is refused,
+ * unless the rig declares that the consumer drives its mix.
+ *
+ * The question A23, A36 and A37 ask of their own kinds, asked of the kind
+ * editor exports use most (issue #765): a constraint that rests muted and
+ * that no animation switches on parses, sits in the update cache and moves
+ * nothing. 🔑 Live is the runtime's own test, `!== 0`: `IkConstraint.update`
+ * returns on `mix === 0`, so a negative mix runs. Channel 0 of an ik frame is
+ * `mix`; the other four are softness, bend direction, compress and stretch.
+ * The argument with its measurements sits above the `check` call in
+ * `validate()`.
+ *
+ * Moved out of `src/validate.ts` whole: the bones, the target, the setup mix
+ * and the keyed ones are the rig's, the declaration the rig spec's.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { ConstraintFacts } from '../facts/constraints.ts';
+import { consumerDriven, consumerSkip, declaredButLive, declareIt, ikLive, noneKeysItsMixAbove0, REST_OR_KEY_ITS_MIX, switchedOn } from '../constraint_words.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a47IkConstraintNotMutedThroughout({ fail, skip, stats }: Verdicts, facts: ConstraintFacts, rig: RigInfo | undefined): void {
+  const NAME = 'A47_IK_CONSTRAINT_NOT_MUTED_THROUGHOUT';
+  const constraints = facts.constraints.flatMap((c, index) => (c.ik === undefined ? [] : [{ name: c.name, ik: c.ik, index }]));
+  if (!constraints.length) return skip(NAME, 'the skeleton declares no ik constraint');
+  // Channel 0 is `mix`; the other four are softness, bend direction, compress and stretch.
+  const ikSwitchedOn = switchedOn(facts, (timeline) => timeline.kind === 'ik', 1, (_timeline, value, channel) => channel === 0 && ikLive(value));
+  const declared = consumerDriven(rig, 'ik');
+  const exempt: Array<[string, string]> = [];
+  for (const { name, ik: constraint, index } of constraints) {
+    const mix = constraint.mix;
+    const live = ikLive(mix) || ikSwitchedOn.has(index);
+    const why = declared.get(name);
+    if (why !== undefined) {
+      if (!live) exempt.push([name, why]);
+      else {
+        fail(
+          NAME,
+          declaredButLive(
+            `ik constraint "${name}"`,
+            ikLive(mix) ? `it rests at mix ${mix}` : 'an animation keys its mix above 0',
+          ),
+        );
+      }
+      continue;
+    }
+    if (live) continue;
+    fail(
+      NAME,
+      `ik constraint "${name}" has mix ${mix} at setup and ${noneKeysItsMixAbove0(facts.animations)}; ` +
+        `update() returns on mix 0, so ${constraint.bones.map((bone) => `"${bone}"`).join(' and ')} never ` +
+        `reach${constraint.bones.length === 1 ? 'es' : ''} for "${constraint.target}" — ${REST_OR_KEY_ITS_MIX}, ` +
+        declareIt('ik', name),
+    );
+  }
+  if (exempt.length) stats.ikConsumerDriven = exempt.map(([name]) => name).join(',');
+  if (exempt.length === constraints.length) return skip(NAME, consumerSkip('ik', exempt, facts.animations));
+}

package/src/assertions/bodies/a48.ts

@@ -0,0 +1,83 @@
+/**
+ * A48, the body (issue #1025, step 4c of #380): a transform constraint muted
+ * for good on every mix it reads is refused, unless the rig declares that the
+ * consumer drives its mix.
+ *
+ * 🔑 **A transform mix is read only for a property the constraint drives.**
+ * The early return in `TransformConstraint.update` is over all six mixes, but
+ * it is not what decides whether anything moves: each `to` entry reads its own
+ * mix (`ToRotate.mix` is `mixRotate`, …). At setup the parser only reads a mix
+ * whose property is declared, so the two tests agree there — but a timeline
+ * key that omits a mix is read as 1 (`SkeletonJson.js`, every `getValue(…, 1)`),
+ * so a key of `mixRotate: 0` alone on a rotate-only constraint passes the
+ * six-mix test on five mixes nothing reads. [measured] that key poses every
+ * bone exactly where no constraint does, and so does one keying `mixX` 1 on
+ * the same constraint. So this reads the mixes of the declared `to` kinds,
+ * at setup and on every value a key poses — the fact's `mixes`, `null` where
+ * the constraint declares no `to` of that property. Live is `!== 0`
+ * (`ikLive`'s note).
+ *
+ * Moved out of `src/validate.ts` whole: the declared `to` kinds, the setup
+ * mixes and the keyed ones are the rig's, the declaration the rig spec's.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { ConstraintFacts } from '../facts/constraints.ts';
+import { consumerDriven, consumerSkip, declaredButLive, declareIt, noneKeysItsMixAbove0, switchedOn } from '../constraint_words.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a48TransformConstraintNotMutedThroughout({ fail, skip, stats }: Verdicts, facts: ConstraintFacts, rig: RigInfo | undefined): void {
+  const NAME = 'A48_TRANSFORM_CONSTRAINT_NOT_MUTED_THROUGHOUT';
+  const constraints = facts.constraints.flatMap((c, index) => (c.transform === undefined ? [] : [{ name: c.name, transform: c.transform, index }]));
+  if (!constraints.length) return skip(NAME, 'the skeleton declares no transform constraint');
+  /** Which of the six channels `constraint` reads at all: the ones whose `to` kind it declares. */
+  const transformReads = (index: number): boolean[] => (facts.constraints[index]?.transform?.mixes ?? []).map((mix) => mix !== null);
+  const transformSwitchedOn = switchedOn(facts, (timeline) => timeline.kind === 'transform', 6, (timeline, value, channel) => {
+    const constraint = facts.constraints[timeline.constraint];
+    return constraint?.transform !== undefined && transformReads(timeline.constraint)[channel] && value !== 0;
+  });
+  const declared = consumerDriven(rig, 'transform');
+  const exempt: Array<[string, string]> = [];
+  for (const { name, transform: constraint, index } of constraints) {
+    const where = `transform constraint "${name}"`;
+    const pose: Record<string, number> = {};
+    for (const mix of constraint.mixes) if (mix !== null) pose[mix.field] = mix.setup;
+    const read = constraint.mixes.flatMap((mix) => (mix === null ? [] : [mix.field]));
+    if (read.length === 0) {
+      // No `to` at all: no mix is ever read, so neither remedy below applies.
+      fail(
+        NAME,
+        `${where} drives no property — its \`properties\` name no \`to\` — so no mix it carries is ever read and it ` +
+          'moves nothing; declare the property it should drive',
+      );
+      continue;
+    }
+    const resting = read.filter((field) => pose[field] !== 0);
+    const live = resting.length > 0 || transformSwitchedOn.has(index);
+    const why = declared.get(name);
+    if (why !== undefined) {
+      if (!live) exempt.push([name, why]);
+      else {
+        fail(
+          NAME,
+          declaredButLive(
+            where,
+            resting.length ? `it rests at ${resting.map((field) => `${field} ${pose[field]}`).join(', ')}` : 'an animation keys its mix above 0',
+          ),
+        );
+      }
+      continue;
+    }
+    if (live) continue;
+    fail(
+      NAME,
+      `${where} drives ${read.map((field) => field.slice(3).replace(/^./, (c) => c.toLowerCase())).join(', ')} and has ` +
+        `${read.map((field) => `${field} ${pose[field]}`).join(', ')} at setup, and ` +
+        `${noneKeysItsMixAbove0(facts.animations)}; a mix is read only for a property the constraint drives, and ` +
+        `update() skips each one at 0, so nothing ever moves ${constraint.bones.map((bone) => `"${bone}"`).join(', ')} — ` +
+        `rest ${read.length === 1 ? read[0] : `one of ${read.join(', ')}`} above 0, or key its mix above 0 in an animation, ` +
+        declareIt('transform', name),
+    );
+  }
+  if (exempt.length) stats.transformConsumerDriven = exempt.map(([name]) => name).join(',');
+  if (exempt.length === constraints.length) return skip(NAME, consumerSkip('transform', exempt, facts.animations));
+}

package/src/assertions/constraint_words.ts

@@ -0,0 +1,177 @@
+/**
+ * What the constraint bodies share (issue #1025, step 4c of #380): the one
+ * reading of "does an animation switch this on", the one predicate a path or
+ * slider mix is judged by, the physics components, and the sentences A23,
+ * A36, A37, A47 and A48 say alike. Moved here from `src/validate.ts`, each
+ * unchanged but for what `switchedOn` reads — the facts
+ * (`./facts/constraints.ts`) rather than the loaded timelines — because the
+ * bodies that read them moved, and a second copy is how two rules come to
+ * disagree. `src/validate.ts` imports what A40 still reads.
+ *
+ * Links nothing from the runtime.
+ */
+import type { ConstraintFacts, ConstraintTimeline } from './facts/constraints.ts';
+import type { RigInfo } from '../types.ts';
+
+/**
+ * Every component a physics constraint can drive (`PhysicsConstraintData`), and
+ * the subset the **Spine editor** models.
+ *
+ * ⭐ One list, read by both A23 and A41, because the relationship between those
+ * two rules is the thing most worth keeping true: A23 fires when the driven set
+ * is EMPTY, A41 when it contains something outside `EDITOR_PHYSICS_COMPONENTS`.
+ * Written against one array those conditions cannot both hold on one constraint,
+ * and a reader can see that they cannot. Two copies of the vocabulary could
+ * drift into overlapping, and a rig refused twice for one fact is a report that
+ * has stopped saying what is wrong with it.
+ *
+ * 📏 The subset is measured rather than read off a document, and it is the whole
+ * of issue #540: three rigs, twelve constraints, predictions recorded before the
+ * round trip and scored by the code that printed them. A lone `y` came back, `x`
+ * and `y` together came back — so the rule is membership and not arity — and a
+ * lone `rotate`, a lone `scaleX` and a lone `shearX` each came back driving no
+ * component at all, with neither `scaleY` mode rescuing `scaleX`. Every
+ * constraint carried a fixed-point `strength` and all twelve returned exactly,
+ * so the rows that reported nothing were reading live data. Measured on Spine
+ * 4.3.26 Professional.
+ */
+export const PHYSICS_COMPONENTS = ['x', 'y', 'rotate', 'scaleX', 'shearX'] as const;
+export const EDITOR_PHYSICS_COMPONENTS: ReadonlySet<(typeof PHYSICS_COMPONENTS)[number]> = new Set(['x', 'y'] as const);
+
+/**
+ * The half of a muted-at-rest refusal that says what was searched, and how
+ * widely — one text for `A23`, `A36` and `A37`, which ask one question of three
+ * constraint kinds (issues #743, #752). A rig with no animation at all says
+ * "none of the 0 animations" rather than implying somebody keyed something.
+ */
+export function noneKeysItsMixAbove0(animations: number): string {
+  return `none of the ${animations} animation${animations === 1 ? '' : 's'} keys its mix above 0`;
+}
+
+/** The two repairs a muted-at-rest refusal names, since either one is a rig the runtime plays. */
+export const REST_OR_KEY_ITS_MIX = 'rest it above 0, or key its mix above 0 in an animation';
+
+/**
+ * The one predicate a path or slider mix is judged by, at setup and on every
+ * value a key poses: above 0, where `update()` does anything at all.
+ */
+export const mixLive = (value: number): boolean => value > 0;
+
+/**
+ * 🔑 **An ik or transform mix is live by the runtime's own test, `!== 0`, and
+ * not `mixLive`'s `> 0`.** `IkConstraint.update` returns on `mix === 0` and a
+ * transform's inner loop applies a property only when `to.mix(pose) !== 0`, so
+ * a negative mix runs. That is not a corner: [measured] five transform
+ * constraints across four of the editor's own example exports rest at mixX =
+ * mixY = −1, nothing keys them, and each moves its bones at setup against the
+ * same constraint with every mix 0. A `> 0` reading refuses all five.
+ * (`A36`/`A37` still read `> 0` — a path or slider resting negative is a
+ * question for their own card.)
+ */
+export const ikLive = (value: number): boolean => value !== 0;
+
+/**
+ * The constraints some animation keys to a value `live` accepts, on any of the
+ * first `channels` channels of a timeline `owns` claims — the one answer to
+ * "does anything switch this on" for `A23`, `A36`, `A37`, `A40`, `A47` and
+ * `A48` (issues #743, #752), as positions in `facts.constraints`.
+ *
+ * ⭐ It replaced `keyedBy`, which read the raw JSON and took a non-empty key
+ * array as the answer, and it did so rather than teaching that one to read
+ * values, because the raw file is the wrong place to read a value: a path
+ * `mix` key that omits `mixRotate` means 1 (`SkeletonJson.js:1011-1013`), a
+ * `mixY` it omits means that key's `mixX`, and a Bezier between two keys
+ * poses values neither key states. So this reads every value a channel poses
+ * — each key's own and every sample of each Bézier segment the parser built
+ * between two keys (`ConstraintTimeline.channelValues`): spine-core's loaded
+ * timelines on one side, the core's reading of the document on the other.
+ * [measured] the reading `keyedBy` gave was wrong in the accepting
+ * direction: a path constraint and a slider, both muted at rest and keyed to
+ * 0 only, pose every bone exactly where the same rig with no timeline does
+ * (max |Δ| 0.000000 over 60 steps at 60 fps) and both passed.
+ *
+ * A timeline naming no constraint is the physics family's global form, and
+ * its `reach` says who it writes; every other constraint timeline names its
+ * one constraint.
+ *
+ * `live` is handed the channel as well as the value, because not every
+ * channel of every constraint timeline is a mix (issue #765): an ik frame is
+ * mix, softness, bend direction, compress and stretch, so a bend direction of
+ * +1 is not a key that switches anything on, and a transform frame carries
+ * six mixes of which only the ones for a property the constraint drives are
+ * ever read. `channels` is how many leading channels the caller's `live` can
+ * accept a value on.
+ */
+export function switchedOn(
+  facts: ConstraintFacts,
+  owns: (timeline: ConstraintTimeline) => boolean,
+  channels: number,
+  live: (timeline: ConstraintTimeline, value: number, channel: number) => boolean,
+): Set<number> {
+  const reached = new Set<number>();
+  for (const timeline of facts.timelines) {
+    if (!owns(timeline)) continue;
+    let keysLive = false;
+    for (let channel = 0; channel < channels && !keysLive; channel++) {
+      keysLive = timeline.channelValues(channel).some((value) => live(timeline, value, channel));
+    }
+    if (!keysLive) continue;
+    for (const one of timeline.reach) reached.add(one);
+  }
+  return reached;
+}
+
+// 🔑 **The third door: the consumer drives the mix (issue #784).** A muted
+// constraint nothing in the file switches on is either a leftover or a dial
+// a game turns from code, and the two export as the same bytes — so the rig
+// spec says which, in `invariants.consumerDrivenMix`, and a declared
+// constraint is not measured by `A47` / `A48`. What that buys is never a pass
+// on it:
+//
+//   * every constraint of the kind declared — nothing is left to measure, so
+//     the rule SKIPs, naming each constraint, the declaration and its `why`;
+//   * some declared and some not — the rest are measured, and the declared
+//     ones go on the stats line, which is `A39`'s shape for `deformMayFold`.
+//     A SKIP there would put "nothing measured" over a rule that measured,
+//     and the summary would count a measured rule as skipped (`reportLines`'
+//     four buckets partition the registry, one row per rule).
+//
+// ⛔ A declared constraint the file ALSO switches on — resting live, or keyed
+// above 0 — is refused: the declaration exempts nothing there, which is the
+// shape `deformMayFold` on a slot with no mesh is refused for. [measured]
+// (`scratchpad/consumerdriven_runtime.ts`) an ik keyed at mix 0.5 with code
+// writing 1: code before `state.apply` is overwritten (applied mix 0.5),
+// code after it wins (1.0) — so which author holds a frame is the order of
+// the consumer's own loop, a fact about the scene rather than the object.
+
+/** The rig's consumer-driven declarations of one kind: constraint name -> why. */
+export function consumerDriven(rig: RigInfo | undefined, type: 'ik' | 'transform'): Map<string, string> {
+  return new Map((rig?.consumerDrivenMix ?? []).filter((e) => e.type === type).map((e) => [e.constraint, e.why]));
+}
+
+/** The third repair a muted-throughout refusal names. */
+export function declareIt(type: 'ik' | 'transform', name: string): string {
+  return (
+    `or declare that the consumer drives its mix, in the rig spec as invariants.consumerDrivenMix: ` +
+    `[{ "constraint": "${name}", "type": "${type}", "why": … }]`
+  );
+}
+
+/** The refusal of a declaration that exempts nothing. */
+export function declaredButLive(where: string, how: string): string {
+  return (
+    `${where} is declared in the rig spec as invariants.consumerDrivenMix, and the file already switches it on — ` +
+    `${how} — so the declaration exempts nothing; drop the entry. Where code also sets that mix, which of the two ` +
+    'holds on a frame is the order of the consumer\'s own loop: `state.apply` overwrites a mix written before it, ' +
+    'and a mix written after it replaces the key'
+  );
+}
+
+/** The SKIP when every constraint of the kind is declared consumer-driven. */
+export function consumerSkip(kind: string, exempt: Array<[string, string]>, animations: number): string {
+  return (
+    `every ${kind} constraint here is declared in the rig spec as invariants.consumerDrivenMix, so its mix is the ` +
+    `consumer's to set and nothing in this file shows it moving — ${exempt.map(([name, why]) => `"${name}" (why: ${why})`).join('; ')}: ` +
+    `${exempt.length === 1 ? 'it rests' : 'each rests'} muted and ${noneKeysItsMixAbove0(animations)}`
+  );
+}

package/src/assertions/facts/animated_bones.ts

@@ -0,0 +1,28 @@
+/**
+ * Which bones an animation keys (issue #1025, step 4c of #380) — the roster
+ * half of the census's F18 that A15 reads: whether the skeleton holds an
+ * animation of a name, whether it keys any bone, and which bones, in the
+ * order the file keys them.
+ *
+ * ⭐ **Three states, because A15 says three different things.** No such
+ * animation, an animation that keys no bone, and the bones it keys are each a
+ * sentence of their own in A15 — one is a missing subject, the next a subject
+ * with nothing in it, the last the subject — so the fact keeps them apart
+ * rather than folding the first two into an empty list.
+ *
+ * The order is the file's: A15 prints one line per keyed bone in it. The file
+ * keys an animation's bones in the order the emitter writes the model's
+ * (`emitAnimation`), which is the document's own list.
+ *
+ * Links nothing from the runtime: `validate()` reads it off the skeleton JSON
+ * as A15 always did, and the model side off the document
+ * (`../model/animated_bones.ts`).
+ */
+export interface AnimatedBoneFacts {
+  /**
+   * The bones `animation` keys, in the file's order — `undefined` when the
+   * skeleton holds no animation of that name, `null` when it holds one that
+   * carries no bone timeline at all.
+   */
+  bonesKeyedBy(animation: string): readonly string[] | null | undefined;
+}

package/src/assertions/facts/atlas_pages.ts

@@ -0,0 +1,19 @@
+/**
+ * The atlas's pages, as the bodies that read them see them (issue #1025, step
+ * 4c of #380) — the census's F20, without `pma`, which the model document does
+ * not hold and a later cut supplies from the caller.
+ *
+ * Links nothing from the runtime: a spine-core `TextureAtlas` satisfies the
+ * shape structurally, which is how `validate()` supplies it, and the model
+ * side supplies the document's `pages` section (`../model/atlas_pages.ts`).
+ */
+
+/** One page: its name, a path relative to the directory the atlas sits in. */
+export interface AtlasPage {
+  readonly name: string;
+}
+
+/** The atlas, or `null` when there is none to read — the round trip refused it, or the model side read no document. */
+export interface AtlasPageFacts {
+  readonly atlas: { readonly pages: readonly AtlasPage[] } | null;
+}

package/src/assertions/facts/atlas_regions.ts

@@ -0,0 +1,52 @@
+/**
+ * The atlas as the page rules read it (issue #1025, step 4c of #380) — the
+ * census's F20 and F21 whole: every page's name, declared size and `pma`, every
+ * region's rectangle and the page it sits on, and the region a name resolves
+ * to. A06, A19 and A27 read it; A17, which reads only the page names, keeps the
+ * narrower `./atlas_pages.ts`.
+ *
+ * ⭐ **The order is a fact, and it is the file's.** A06 and A27 print one line
+ * per offending page or region, and A06's overlap clause prints a pair in the
+ * order it meets them, so `pages` and `regions` hold the atlas's own order —
+ * pages as the file lists them, regions page by page in the file's order — and
+ * `findRegion` answers with the FIRST region of exactly that name, the one the
+ * runtime's lookup returns.
+ *
+ * Links nothing from the runtime: spine-core's `TextureAtlas` satisfies the
+ * shape structurally, which is how `validate()` supplies it. The model side
+ * supplies the document's `pages` section, with each page's `pma` given by its
+ * caller until the document states it (issue #1026) — `../model/atlas_regions.ts`.
+ */
+
+/** One page: its name (a path relative to the directory the atlas sits in), the size it declares, and whether it claims premultiplied alpha. */
+export interface AtlasRegionPage {
+  readonly name: string;
+  readonly width: number;
+  readonly height: number;
+  readonly pma: boolean;
+}
+
+/** One region: its name exactly as the atlas spells it, the rectangle in the page's texels, and the page it sits on. */
+export interface AtlasRegionEntry {
+  readonly name: string;
+  readonly page: AtlasRegionPage;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly degrees: number;
+  readonly offsetX: number;
+  readonly offsetY: number;
+  readonly originalWidth: number;
+  readonly originalHeight: number;
+}
+
+/** The atlas, or `null` when there is none to read — the round trip refused it, or the model side read no document. */
+export interface AtlasRegionFacts {
+  readonly atlas: {
+    readonly pages: readonly AtlasRegionPage[];
+    readonly regions: readonly AtlasRegionEntry[];
+    /** The first region of exactly this name, pages in order — or `null`. */
+    findRegion(name: string): AtlasRegionEntry | null;
+  } | null;
+}