spine-rigc 1.8.0 → 1.9.0

package/src/assertions/bodies/a38.ts

@@ -0,0 +1,73 @@
+/**
+ * A38, the body (issue #1025, step 4c of #380): a skin's member list and its
+ * members' `skin: true` flag agree.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the bones,
+ * the constraints and the skins' lists are a fact (`../facts/skin_members.ts`)
+ * — which spine-core's loaded `SkeletonData` satisfies as it stands. Why both
+ * halves of the switch are dead data alone stays above the `check` call in
+ * `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { MemberBone, SkinMemberFacts } from '../facts/skin_members.ts';
+
+export function a38SkinMembersAreSkinRequired({ fail, skip, stats }: Verdicts, data: SkinMemberFacts): void {
+  /** Every bone a skin can switch on, including the ancestors it drags in. */
+  const activatable = new Set<string>();
+  // The constraint OBJECTS a skin lists, never their names: a name is not a
+  // constraint in this format, and two constraints of one name under two
+  // kinds are two objects a skin may list separately (issue #692). Keyed by
+  // name, a `transform` `leg` that no skin lists read as listed because an
+  // `ik` `leg` was — a skinRequired constraint that never runs, reported
+  // green by the one assertion that looks for exactly that.
+  const listedConstraints = new Set(data.skins.flatMap((skin) => skin.constraints));
+  let listed = 0;
+  for (const skin of data.skins) {
+    for (const bone of skin.bones) {
+      listed++;
+      for (let cursor: MemberBone | null = bone; cursor; cursor = cursor.parent) activatable.add(cursor.name);
+      if (!bone.skinRequired) {
+        fail(
+          'A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED',
+          `skin "${skin.name}" activates bone "${bone.name}", which is not skinRequired — updateCache starts it ` +
+            'active anyway, so it poses under every skin and this list changes nothing',
+        );
+      }
+    }
+    for (const constraint of skin.constraints) {
+      listed++;
+      if (!constraint.skinRequired) {
+        fail(
+          'A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED',
+          `skin "${skin.name}" activates constraint "${constraint.name}", which is not skinRequired — it runs ` +
+            'under every skin, so this list changes nothing',
+        );
+      }
+    }
+  }
+  const required = data.bones.filter((b) => b.skinRequired).length + data.constraints.filter((c) => c.skinRequired).length;
+  if (listed === 0 && required === 0) {
+    return skip(
+      'A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED',
+      'no skin activates a bone or a constraint, and nothing declares itself skinRequired',
+    );
+  }
+  for (const bone of data.bones) {
+    if (bone.skinRequired && !activatable.has(bone.name)) {
+      fail(
+        'A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED',
+        `bone "${bone.name}" is skinRequired and no skin's bones list reaches it, so it is never active — ` +
+          'it and its subtree hold the setup pose under every skin',
+      );
+    }
+  }
+  for (const constraint of data.constraints) {
+    if (constraint.skinRequired && !listedConstraints.has(constraint)) {
+      fail(
+        'A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED',
+        `constraint "${constraint.name}" is skinRequired and no skin lists it, so it never runs`,
+      );
+    }
+  }
+  stats.skinMembers = listed;
+}

package/src/assertions/bodies/a41.ts

@@ -0,0 +1,83 @@
+/**
+ * A41, the body (issue #1025, step 4c of #380): a physics component the Spine
+ * editor cannot hold, refused on a rig declared for the editor.
+ *
+ * 🚨 The silence this converts is not in the artifact — it is one consumer
+ * downstream of it. An author builds a rig whose cowlick jiggles, opens it
+ * in the editor to move an eyebrow, saves, exports, and the hair has stopped
+ * moving. The returned file says nothing: the component is simply absent,
+ * and absent parses as 0. `gallery/look` is exactly that rig.
+ *
+ * 🔑 **rigc's output is correct, so the refusal is opt-in.** `rotate` on a
+ * physics constraint is valid Spine 4.3 that every runtime plays, and
+ * refusing it by default would be refusing correct data on behalf of a
+ * pipeline rigc was never told about. What rigc can see is the object; which
+ * consumers it is for is the rig's to say, and it says it with
+ * `invariants.editorRoundTrip` (`src/rig.ts`).
+ *
+ * ⚠️ **The SKIP is the other half of the product and is not a shrug.** A rig
+ * that declares nothing is not gated — but the reason names the constraint
+ * and the components a round trip would drop, so the one thing that must not
+ * happen (nobody finds out) does not happen either. That is why this reads
+ * the whole skeleton before it reads the declaration, rather than returning
+ * early on a rig that asked for nothing.
+ *
+ * 🔸 **Against A23, on the far side of the same trip.** A23 refuses a
+ * constraint driving NOTHING — which is what the editor hands back, after
+ * the loss — and it is what fires today on a round-tripped `look`. This
+ * refuses a constraint driving something the editor will not keep, before
+ * the trip. They cannot both fire on one constraint: A23's condition is an
+ * empty driven set and this one's is a non-empty one (see
+ * `PHYSICS_COMPONENTS`), so the two are disjoint by construction rather than
+ * by agreement.
+ *
+ * Moved out of `src/validate.ts` whole: the components are the document's
+ * physics records, the declaration the rig's.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { ConstraintFacts } from '../facts/constraints.ts';
+import { EDITOR_PHYSICS_COMPONENTS, PHYSICS_COMPONENTS } from '../constraint_words.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a41PhysicsSurvivesEditorRoundTrip({ fail, skip }: Verdicts, facts: ConstraintFacts, rig: RigInfo | undefined): void {
+  // Counted here rather than read off `stats.physicsConstraints`: that entry
+  // is written by A23, and a rule whose SKIP depends on another rule having
+  // run is a rule that reports "nothing to measure" when its neighbour threw.
+  const physics = facts.constraints.flatMap((c) => (c.physics === undefined ? [] : [{ name: c.name, components: c.physics.components }]));
+  const dropped: string[] = [];
+  for (const constraint of physics) {
+    const lost = PHYSICS_COMPONENTS.filter((k) => constraint.components[k] > 0 && !EDITOR_PHYSICS_COMPONENTS.has(k));
+    if (lost.length) dropped.push(`physics "${constraint.name}" drives ${lost.join(', ')}`);
+  }
+  const editorKeeps = [...EDITOR_PHYSICS_COMPONENTS].join(' and ');
+  const found =
+    dropped.length === 0
+      ? 'no physics constraint here drives a component it would discard'
+      : `${dropped.join('; ')}, and the editor's physics model holds ${editorKeeps} only, so a round trip ` +
+        'returns that constraint driving nothing at all (issue #540)';
+  if (rig?.editorRoundTrip !== true) {
+    return skip(
+      'A41_PHYSICS_SURVIVES_EDITOR_ROUND_TRIP',
+      `${
+        rig
+          ? `the rig "${rig.archetype}" does not declare \`invariants.editorRoundTrip\``
+          : 'this is a bare directory, with no rig info to declare `invariants.editorRoundTrip`'
+      }, so nothing here is gated against the Spine editor. What is here: ${found}`,
+    );
+  }
+  if (physics.length === 0) {
+    return skip(
+      'A41_PHYSICS_SURVIVES_EDITOR_ROUND_TRIP',
+      `the rig "${rig.archetype}" is declared for the editor, but it carries no physics constraint — ` +
+        'there is nothing here whose components could be lost',
+    );
+  }
+  for (const one of dropped) {
+    fail(
+      'A41_PHYSICS_SURVIVES_EDITOR_ROUND_TRIP',
+      `${one}; the editor's physics model holds ${editorKeeps} only, and this ` +
+        'rig declares `invariants.editorRoundTrip` — drive it in x/y, or drop the declaration if this rig never ' +
+        'goes through the editor (issue #540)',
+    );
+  }
+}

package/src/assertions/bodies/a42.ts

@@ -0,0 +1,97 @@
+/**
+ * A42, the body (issue #1025, step 4c of #380): a constraint a slider's
+ * animation keys updates after that slider.
+ *
+ * `Skeleton.updateCache` walks the `constraints` array in order and each
+ * constraint's `sort` pushes itself as it is reached — `Slider.sort` included,
+ * which pushes bones and never a constraint — so the array IS the update order,
+ * for every kind. Every constraint then opens its `update` by reading its own
+ * applied pose, so a slider that keys any property of a constraint is read by
+ * that constraint only when it comes LATER in the array; written the other way
+ * round the value lands in a pose whose only reader has already run, and
+ * `Posed.resetConstrained` puts the pose back before the next frame (the
+ * argument and its measurements sit above the `check` call in `validate()`).
+ *
+ * Moved out of `src/validate.ts` whole: the array's order, the slider's
+ * animation and the constraint timelines it holds — which constraint each
+ * names, what it keys, and whom a physics timeline naming none reaches — are
+ * the rig's, and a document's records state each. The words the sentence
+ * prints are the facts' own: what a timeline keys (`word`, the motion spec's
+ * word for it) and the runtime class whose `update` reads it (`runtimeClass`).
+ */
+import type { Verdicts } from '../harness.ts';
+import type { ConstraintFacts } from '../facts/constraints.ts';
+
+export function a42DrivenConstraintsUpdateAfterTheirDriver({ fail, skip, stats }: Verdicts, facts: ConstraintFacts): void {
+  const sliders = facts.constraints.flatMap((c, index) => (c.slider === undefined ? [] : [{ name: c.name, slider: c.slider, index }]));
+  if (!sliders.length) {
+    return skip('A42_DRIVEN_CONSTRAINTS_UPDATE_AFTER_THEIR_DRIVER', 'the skeleton declares no slider constraint');
+  }
+  let pairs = 0;
+  let resets = 0;
+  for (const driver of sliders) {
+    const driverIndex = driver.index;
+    const animationName = driver.slider.animation?.name;
+    for (const timeline of facts.timelines) {
+      if (animationName === undefined || timeline.animation !== animationName) continue;
+      if (timeline.kind === 'physics' && timeline.word === 'reset') {
+        resets++;
+        continue;
+      }
+      const word = timeline.word;
+      const everyPhysics = timeline.constraint < 0;
+      // A physics timeline whose animation names no constraint reaches every
+      // ACTIVE physics constraint whose own data declares that property
+      // global — the timeline's `reach`, the one reading of it A23 and A34
+      // share (issue #726).
+      for (const drivenIndex of timeline.reach) {
+        const driven = facts.constraints[drivenIndex];
+        if (driven === undefined) continue;
+        pairs++;
+        if (drivenIndex > driverIndex) continue;
+        const kind = { word: driven.kind, runtime: driven.runtimeClass };
+        const animation = `animation "${animationName}"`;
+        const reference = `\`${kind.word}.${driven.name}${word === kind.word ? '' : `.${word}`}\``;
+        fail(
+          'A42_DRIVEN_CONSTRAINTS_UPDATE_AFTER_THEIR_DRIVER',
+          drivenIndex === driverIndex
+            ? `slider "${driver.name}" (constraints[${driverIndex}]) keys its own \`${word}\` in ${animation}. ` +
+                '`Slider.update` reads `appliedPose.' +
+                `${word}\` as the ${word === 'mix' ? 'alpha it applies that animation with' : 'time it applies that animation at'}, ` +
+                'before the animation runs, so the key is written after its only reader and `Posed.resetConstrained` ' +
+                `puts the pose back before the next frame${
+                  word === 'mix'
+                    ? ' — and at `mix` 0 `update` returns before applying anything at all, so the key that would raise it is unreachable'
+                    : ''
+                }. Key ${reference} from a slider EARLIER in \`constraints\`, or state the ` +
+                `\`${word}\` this slider should start at in the rig spec`
+            : `slider "${driver.name}" (constraints[${driverIndex}]) keys ${
+                word === kind.word ? `the \`${word}\` timeline` : `\`${word}\``
+              } of ${kind.word} constraint ` +
+                `"${driven.name}" (constraints[${drivenIndex}]) in ${animation}${
+                  everyPhysics ? ' — the timeline names no constraint, which the runtime reads as every physics constraint declaring that property global —' : ''
+                }, and "${driven.name}" updates FIRST. The \`constraints\` array is the update order ` +
+                '(`Skeleton.updateCache` walks it and each constraint\'s `sort` pushes itself as it is reached) and ' +
+                `\`${kind.runtime}.update\` reads its own \`appliedPose\` before applying anything, so that key is ` +
+                'written after the only read of it and `Posed.resetConstrained` discards it before the next frame: ' +
+                `what "${driven.name}" drives is dead at every reading of "${driver.name}"'s dial, although its pose ` +
+                `still holds the number. Move "${driver.name}" before "${driven.name}" in \`constraints\`, or key ` +
+                `${reference} from a slider that already is`,
+        );
+      }
+    }
+  }
+  if (pairs === 0) {
+    return skip(
+      'A42_DRIVEN_CONSTRAINTS_UPDATE_AFTER_THEIR_DRIVER',
+      `no animation applied by one of the ${sliders.length} slider constraint${sliders.length === 1 ? '' : 's'} keys a ` +
+        `property of a constraint, so no slider here drives a constraint${
+          resets === 0
+            ? ''
+            : ` — the ${resets} \`physics\` \`reset\` key(s) they do carry are not a pose write, and [measured] a slider ` +
+              'applies its animation at one instant, so `PhysicsConstraintResetTimeline` never fires from one in either array order'
+        }`,
+    );
+  }
+  stats.sliderDrivenConstraints = pairs;
+}

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/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;
+}