spine-rigc 1.7.0 → 1.9.0

package/src/assertions/bodies/a20.ts

@@ -0,0 +1,122 @@
+/**
+ * A20, the body (issue #1025, step 4c of #380): a weighted mesh's weights
+ * cohere — every vertex bound, every weight finite and non-negative, every
+ * vertex's weights summing to 1 — and, under `spine-html`, a generated mesh is
+ * weighted, binds only bones that move it and binds every bone it declares.
+ *
+ * Moved out of `src/validate.ts` clause by clause, every clause about the
+ * weights themselves moving: a document's mesh names each vertex's bindings,
+ * so a vertex count that disagrees with the `uvs`, an empty binding list, a
+ * weight that is not finite, below 0 or 0 on a generated mesh, a sum off 1 and
+ * a declared bone no vertex binds each have a place to live there (the reader
+ * refuses the first three by the record's name). The one clause that does not
+ * — a binding's index past the bone array — is about the encoding: the
+ * document names a binding's bone, and the index is the emitter's to write.
+ * It stays with the round trip, which hands its finding in on the binding
+ * (`MeshBinding.encoding`), printed where the body always printed it.
+ *
+ * The weights are the ones the runtime holds — float32 — and a binding's bone
+ * its index in the roster, because the weight-0 clause prints it.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { MeshFacts } from '../facts/mesh_attachments.ts';
+import { meshKindOf } from '../mesh_kinds.ts';
+import { SKIP_NO_MESH_ATTACHMENT } from '../reasons.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a20MeshWeightsCoherent({ fail, skip }: Verdicts, { meshes, bones }: MeshFacts, policy: boolean, rig: RigInfo | undefined): void {
+  if (meshes.length === 0) return skip('A20_MESH_WEIGHTS_COHERENT', SKIP_NO_MESH_ATTACHMENT);
+  for (const mesh of meshes) {
+    // 🚨 Authored geometry is not rigc's to have opinions about. The two
+    // policy branches in this assertion are both statements about what a
+    // rigc GENERATOR is supposed to produce — "a mesh here is weighted",
+    // "a generated mesh binds only bones that move it" — and neither is a
+    // fact about Spine or about somebody else's mesh. Applying them to
+    // authored geometry failed correct data (issue #44). The coherence
+    // rules below the branch are unconditional and still apply.
+    const generated = meshKindOf(mesh, rig) !== 'authored';
+    if (!mesh.weights) {
+      // 📐 PROFILE. An unweighted mesh is perfectly valid Spine — spineboy
+      // ships two — and the runtime poses it from the slot bone. What is
+      // NOT valid, in any profile, is a weighted mesh whose weights do not
+      // cohere, which is everything below this branch. So the requirement
+      // that a mesh be weighted at all is the policy half, and it is the
+      // only half gated here.
+      if (policy && generated) {
+        fail('A20_MESH_WEIGHTS_COHERENT', `mesh "${mesh.name}" is unweighted; the ring tier drives meshes by bones`);
+      }
+      continue;
+    }
+    const perVertex = mesh.weights;
+    const expected = mesh.worldVerticesLength / 2;
+    if (perVertex.length !== expected) {
+      fail(
+        'A20_MESH_WEIGHTS_COHERENT',
+        `mesh "${mesh.name}" has weights for ${perVertex.length} vertices but ${expected} uv pairs`,
+      );
+      continue;
+    }
+    perVertex.forEach((vertex, i) => {
+      if (!vertex.length) fail('A20_MESH_WEIGHTS_COHERENT', `mesh "${mesh.name}" vertex ${i} has no bones`);
+      let sum = 0;
+      for (const { bone, weight, encoding } of vertex) {
+        if (!Number.isFinite(weight) || weight < 0) {
+          fail('A20_MESH_WEIGHTS_COHERENT', `mesh "${mesh.name}" vertex ${i} has weight ${weight}`);
+        }
+        // 📐 PROFILE. A weight of exactly 0 is legal, harmless Spine: the
+        // runtime accumulates `(…) * weight` (Attachment.js:131), so the
+        // binding contributes nothing. The Spine editor writes them — the
+        // auto-weighted meshes in 6-arcs, 7-anticipation and 8-follow-through
+        // carry dozens, and their vertex weights still sum to 1. Treating one
+        // as corruption failed three rungs of the ladder on correct data.
+        // In a rigc-GENERATED ring or ribbon it is still a defect: the
+        // generator bound a bone that does nothing, which is a bug in the
+        // generator and dead work in the runtime's inner loop. So it stays a
+        // failure under spine-html and is not one under spine.
+        else if (policy && generated && weight === 0) {
+          fail(
+            'A20_MESH_WEIGHTS_COHERENT',
+            `mesh "${mesh.name}" vertex ${i} is bound to bone index ${bone} at weight 0; a generated mesh binds only bones that move it`,
+          );
+        }
+        // The index's range is the encoding's, kept with the round trip (the header).
+        if (encoding !== undefined) fail('A20_MESH_WEIGHTS_COHERENT', encoding);
+        sum += weight;
+      }
+      if (Math.abs(sum - 1) > 1e-3) {
+        fail('A20_MESH_WEIGHTS_COHERENT', `mesh "${mesh.name}" vertex ${i} weights sum to ${sum.toFixed(4)}`);
+      }
+    });
+    // 📐 PROFILE, and the converse of the weight-0 branch above: that one
+    // says a generated mesh binds only bones that MOVE it, and this one says
+    // every bone it declares moves it. They are halves of one sentence — the
+    // bone set the mesh declares is the bone set its weights reference — so
+    // they are one assertion rather than two, and neither is a fact about
+    // Spine: a declared bone nothing binds loads and renders perfectly.
+    //
+    // 🚨 It is the one mesh question a vertex cannot answer, which is why
+    // every per-vertex rule above was green on the ring that raised it: a
+    // rig-spec ring naming two grips bound one of them, and the absent bone
+    // appears in no vertex, in no sum and in no index (issue #684). The
+    // declaration comes from the compiler's own record of what it bound,
+    // which is what the `MESH` report line prints.
+    if (policy && generated && rig) {
+      const declared = rig.meshDeclaredBones[mesh.slot] || [];
+      const bound = new Set<string>();
+      for (const vertex of perVertex) {
+        for (const { bone } of vertex) {
+          const named = bones[bone];
+          if (named !== undefined) bound.add(named);
+        }
+      }
+      for (const name of declared) {
+        if (bound.has(name)) continue;
+        fail(
+          'A20_MESH_WEIGHTS_COHERENT',
+          `mesh "${mesh.name}" declares bone "${name}" and none of its ${perVertex.length} vertices binds it; ` +
+            `the weights reference ${[...bound].map((n) => `"${n}"`).join(', ')}`,
+        );
+      }
+    }
+  }
+}

package/src/assertions/bodies/a21.ts

@@ -0,0 +1,190 @@
+/**
+ * A21, the body (issue #1025, step 4c of #380): a generated mesh's rim — or
+ * a ribbon's entry row — is pinned to the slot's own bone, and a soft region
+ * moves only the vertices it declares. An `archetype` rule.
+ *
+ * Moved out of `src/validate.ts` whole: every clause is about the rig — which
+ * vertex sits on the region border or the hull, which bone carries it and at
+ * what weight — and a document's mesh states each of those (its `uvs`, its
+ * `hull`, its bindings by bone). Nothing it reads is the encoding's. The
+ * weights are the runtime's float32, a binding's bone its index in the roster
+ * (named back through the roster where the sentence names it), and a link's
+ * geometry its source's.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { MeshFacts } from '../facts/mesh_attachments.ts';
+import { authoredMeshNames, meshKindOf } from '../mesh_kinds.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a21MeshRimPinned({ fail, skip }: Verdicts, { meshes, bones }: MeshFacts, rig: RigInfo | undefined): void {
+  // Without the rig, ring and ribbon cannot be told apart — and the two kinds
+  // pin OPPOSITE edges, so guessing one would either check the wrong edge or
+  // check nothing while reporting a pass.
+  if (!rig) {
+    return skip('A21_MESH_RIM_PINNED', 'no rig info (validating a bare directory), so ring and ribbon cannot be told apart');
+  }
+  if (!meshes.some((m) => m.weights)) {
+    return skip('A21_MESH_RIM_PINNED', 'the skeleton has no weighted mesh attachment, so there is no rim to find unpinned');
+  }
+  // An authored mesh has no rim rigc drew and no entry row rigc placed, and
+  // a linked mesh has no rim of its OWN at all — the one it draws belongs to
+  // its source, and is measured there. Nothing to measure is a SKIP — never
+  // a pass, and never a failure on somebody else's correct geometry.
+  //
+  // 🔸 A `segments` mesh is rigc's own geometry and still has no rim to pin:
+  // its outline is traced off the art and weighted by distance like every
+  // other vertex, because a layer pulled by named bones is SUPPOSED to move
+  // at its edge. "Pinned to the slot bone" is not a claim that generator
+  // makes, so there is nothing here to hold it to — and `A20`'s coherence
+  // rules, which it does make, still apply to it in full.
+  const rimless = (m: (typeof meshes)[number]): boolean => meshKindOf(m, rig) === 'authored' || meshKindOf(m, rig) === 'segments';
+  const measurable = meshes.filter((m) => m.weights && !rimless(m));
+  if (measurable.length === 0) {
+    const authored = authoredMeshNames(meshes.filter((m) => m.weights), rig);
+    const segmented = meshes.filter((m) => m.weights && meshKindOf(m, rig) === 'segments').map((m) => `"${m.name}"`);
+    return skip(
+      'A21_MESH_RIM_PINNED',
+      segmented.length === 0
+        ? `every weighted mesh here is authored or linked geometry (${authored.join(', ')}), not a rigc ring or ` +
+            'ribbon — rigc did not place its rim, so it has no rim of its own to find unpinned'
+        : `every weighted mesh here is ${authored.length ? `authored or linked geometry (${authored.join(', ')}) or ` : ''}` +
+            `a "segments" lattice (${segmented.join(', ')}), not a rigc ring or ribbon — a segments mesh weights its ` +
+            'outline by distance to the bones it names, so it has no rim pinned to the slot bone to find unpinned',
+    );
+  }
+  for (const mesh of measurable) {
+    if (!mesh.weights) continue;
+    const perVertexAll = mesh.weights;
+    const slotBoneOf = mesh.slotBone;
+    // A ribbon's outer boundary is SUPPOSED to move — that is the whole point
+    // of a strip that changes length. So the rule splits by mesh kind rather
+    // than being relaxed: for a ribbon the invariant is that the ENTRY row
+    // cannot move, because that row is where the strip joins the part it
+    // comes out of. Both rules protect the same thing (the mesh's join to the
+    // plate underneath); they just live at different edges of the mesh.
+    //
+    // A `contour` takes the hull path below, and that is the check it wants
+    // rather than a third branch: a contour mesh's hull IS every vertex it
+    // has, and every one is pinned to the slot bone at weight 1, so "the rim
+    // is pinned" reads over the whole mesh. If a later contour tier ever
+    // moves interior vertices, this is the assertion that has to grow a
+    // branch — it will fail rather than pass quietly, which is the right way
+    // round.
+    if (meshKindOf(mesh, rig) === 'ribbon') {
+      const uvs = mesh.regionUVs ?? [];
+      let entryRow = 0;
+      for (let v = 0; v < perVertexAll.length; v++) {
+        if (Math.abs(uvs[v * 2 + 1]) > 1e-6) continue; // not on the entry edge
+        entryRow++;
+        const vertex = perVertexAll[v];
+        if (vertex.length !== 1 || Math.abs(vertex[0].weight - 1) > 1e-6) {
+          fail(
+            'A21_MESH_RIM_PINNED',
+            `ribbon "${mesh.name}" entry vertex ${v} is not pinned (${vertex.map((w) => w.weight.toFixed(3)).join('+')})`,
+          );
+          continue;
+        }
+        if (slotBoneOf && bones[vertex[0].bone] !== slotBoneOf) {
+          fail(
+            'A21_MESH_RIM_PINNED',
+            `ribbon "${mesh.name}" entry vertex ${v} is pinned to "${bones[vertex[0].bone]}", not the anchor bone "${slotBoneOf}"`,
+          );
+        }
+      }
+      if (entryRow < 2) {
+        fail('A21_MESH_RIM_PINNED', `ribbon "${mesh.name}" has ${entryRow} vertices on its entry edge; a strip needs two`);
+      }
+      continue;
+    }
+    // A rim a soft mask deliberately CARRIED (issue #382). The rule splits
+    // by declaration rather than being relaxed — the same move the ribbon
+    // branch above makes, and for the same reason: a wobbling silhouette is
+    // supposed to move, and the invariant is that nothing ELSE does. So on
+    // such a mesh a vertex is either pinned to the slot bone at 1 or shared
+    // between it and the ONE bone the rig declared, and a third bone, a
+    // wrong bone or a weight that does not close is still a failure.
+    const boundBone = rig.meshSoftBones[mesh.slot] ?? null;
+    if (boundBone !== null) {
+      const allowed = new Set([slotBoneOf, boundBone]);
+      let carried = 0;
+      for (let v = 0; v < perVertexAll.length; v++) {
+        const vertex = perVertexAll[v];
+        let sum = 0;
+        for (const { bone, weight } of vertex) {
+          const name = bones[bone];
+          if (!allowed.has(name)) {
+            fail(
+              'A21_MESH_RIM_PINNED',
+              `mesh "${mesh.name}" vertex ${v} is carried by "${name}", and this mesh declares only ` +
+                `"${slotBoneOf}" and the soft region's "${boundBone}"`,
+            );
+          }
+          if (name === boundBone && weight > 0) carried = carried + (weight >= 1 ? 1 : 0);
+          sum += weight;
+        }
+        if (Math.abs(sum - 1) > 1e-4) {
+          fail(
+            'A21_MESH_RIM_PINNED',
+            `mesh "${mesh.name}" vertex ${v} weights sum to ${sum.toFixed(4)}; a depth-bound mesh splits each ` +
+              'vertex between the slot bone and the bound bone, so it closes at 1',
+          );
+        }
+      }
+      // A mask that carried nothing reached here as a mesh pinned exactly
+      // as before, which is not the thing that was declared.
+      if (carried === 0) {
+        fail(
+          'A21_MESH_RIM_PINNED',
+          `mesh "${mesh.name}" declares a soft region on "${boundBone}" and no vertex is fully carried by it`,
+        );
+      }
+      continue;
+    }
+    const hullVertices = mesh.hullLength / 2;
+    if (!Number.isInteger(hullVertices) || hullVertices < 3) {
+      fail('A21_MESH_RIM_PINNED', `mesh "${mesh.name}" declares hull ${mesh.hullLength / 2}; the rim must be a real ring`);
+      continue;
+    }
+    const perVertex = mesh.weights;
+    if (hullVertices > perVertex.length) {
+      fail('A21_MESH_RIM_PINNED', `mesh "${mesh.name}" hull is ${hullVertices} of ${perVertex.length} vertices`);
+      continue;
+    }
+    // The rim is the alpha contour where generated pixels meet untouched
+    // base. One bone at weight 1, and that bone must be the slot's own —
+    // anything else and the seam can move.
+    const slotBone = mesh.slotBone;
+    for (let i = 0; i < hullVertices; i++) {
+      const vertex = perVertex[i];
+      if (vertex.length !== 1 || Math.abs(vertex[0].weight - 1) > 1e-6) {
+        fail(
+          'A21_MESH_RIM_PINNED',
+          `mesh "${mesh.name}" rim vertex ${i} is not pinned (${vertex.map((v) => v.weight.toFixed(3)).join('+')})`,
+        );
+        continue;
+      }
+      if (slotBone && bones[vertex[0].bone] !== slotBone) {
+        fail(
+          'A21_MESH_RIM_PINNED',
+          `mesh "${mesh.name}" rim vertex ${i} is pinned to "${bones[vertex[0].bone]}", not the slot bone "${slotBone}"`,
+        );
+      }
+    }
+    // Independent of the ring ORDER: whatever sits on the region border is
+    // the outline, and the outline moving means the part's own edge moving.
+    // Without this, reordering the rings would move the pinned prefix off
+    // the outline and A21 would still pass on the count alone.
+    const uvs = mesh.regionUVs ?? [];
+    for (let v = 0; v < perVertex.length; v++) {
+      const u = uvs[v * 2];
+      const t = uvs[v * 2 + 1];
+      const onBorder = [u, t].some((c) => Math.abs(c) < 1e-6 || Math.abs(c - 1) < 1e-6);
+      if (!onBorder) continue;
+      const vertex = perVertex[v];
+      if (vertex.length !== 1 || Math.abs(vertex[0].weight - 1) > 1e-6) {
+        fail('A21_MESH_RIM_PINNED', `mesh "${mesh.name}" vertex ${v} is on the region border but not pinned`);
+        break;
+      }
+    }
+  }
+}

package/src/assertions/bodies/a22.ts

@@ -0,0 +1,39 @@
+/**
+ * A22, the body (issue #1025, step 4c of #380): every mesh's authored UVs lie
+ * in the unit square, one pair per vertex.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the meshes
+ * are a fact (`../facts/skin_meshes.ts`). The `check` call stays in
+ * `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { SkinMeshFacts } from '../facts/skin_meshes.ts';
+import { SKIP_NO_MESH_ATTACHMENT } from '../reasons.ts';
+
+export function a22MeshUvsInUnitRange({ fail, skip }: Verdicts, { meshes }: SkinMeshFacts): void {
+  const meshAttachments = meshes;
+  if (meshAttachments.length === 0) return skip('A22_MESH_UVS_IN_UNIT_RANGE', SKIP_NO_MESH_ATTACHMENT);
+  for (const mesh of meshAttachments) {
+    // `regionUVs` is what the JSON authored; `uvs` is the page-space result
+    // and stays EMPTY until a renderer calls computeUVs, so asserting on it
+    // here would be asserting on the wrong array (measured: length 0 after
+    // a clean load). With one part per page the two are equal anyway —
+    // computeUVs reduces to `u + regionUV * width` with u=0, width=1
+    // (MeshAttachment.js:173-174), which is the claim this assertion rests
+    // on and this is where it is checked.
+    const uvs = mesh.regionUVs;
+    if (!uvs || uvs.length !== mesh.worldVerticesLength) {
+      fail(
+        'A22_MESH_UVS_IN_UNIT_RANGE',
+        `mesh "${mesh.name}" has ${uvs?.length ?? 0} authored uv values for ${mesh.worldVerticesLength}`,
+      );
+      continue;
+    }
+    for (let i = 0; i < uvs.length; i++) {
+      if (!Number.isFinite(uvs[i]) || uvs[i] < -1e-6 || uvs[i] > 1 + 1e-6) {
+        fail('A22_MESH_UVS_IN_UNIT_RANGE', `mesh "${mesh.name}" uv[${i}] is ${uvs[i]}`);
+        break;
+      }
+    }
+  }
+}

package/src/assertions/bodies/a23.ts

@@ -0,0 +1,255 @@
+/**
+ * A23, the body (issue #1025, step 4c of #380): a physics constraint that
+ * does nothing, quietly — at its setup pose, and on every physics key.
+ *
+ * Moved out of `src/validate.ts` whole: every clause is about the rig — the
+ * components a constraint drives, its four bounded setup values, its `fps`,
+ * every value a physics timeline keys and what switches a muted constraint on
+ * — and a document's constraint and timeline records state each. Nothing it
+ * reads is the encoding's. The values are the ones the runtime holds after
+ * its parse, through the facts (`../facts/constraints.ts`): a field left out
+ * at the parser's value, `massInverse` = `1 / mass`, `step` = `1 / fps`, a
+ * key's time and value as float32, a key's value as the pose field it lands
+ * in (`posed`), and the constraints a timeline naming none reaches.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { ConstraintFacts, PhysicsSetup } from '../facts/constraints.ts';
+import type { MeshFacts } from '../facts/mesh_attachments.ts';
+import { noneKeysItsMixAbove0, PHYSICS_COMPONENTS, REST_OR_KEY_ITS_MIX, switchedOn } from '../constraint_words.ts';
+import { SKIP_NO_PHYSICS_CONSTRAINT } from '../reasons.ts';
+import {
+  PHYSICS_POSE_RULES,
+  physicsBasisFor,
+  physicsBasisSays,
+  physicsKeyRefusal,
+  physicsOutsideSays,
+  physicsRuleFor,
+  type PhysicsPoseRule,
+} from '../../timelines.ts';
+
+/**
+ * What A23 says about a SETUP pose outside its bound, per property.
+ *
+ * The predicate lives in `PHYSICS_POSE_RULES` and the sentence lives here, and
+ * the split is deliberate: the predicate is the thing the compiler and this file
+ * must not disagree about, while the sentence names what happens to THIS rig —
+ * "it is muted", "nothing pulls it back" — which is what the author acts on and
+ * is worth nothing to a compiler refusing a key. `PHYSICS_POSE_RULES` is the
+ * index, so a rule added there with no sentence here fails to type-check rather
+ * than printing `undefined`.
+ *
+ * ⚠️ These are the SETUP pose's sentences and nothing else, which matters on the
+ * two rows whose keyed bound is wider than their resting one — `mix` since issue
+ * #610 and `strength` since #727. A key of 0 on either is accepted, so "it is
+ * muted" and "nothing pulls it back" are read here by a rig that states the
+ * number at rest, and what a key is refused with is the row's own `why`.
+ *
+ * `animations` is how many animations the skeleton declares, and only the `mix`
+ * sentence reads it: that bound is the one a key can satisfy instead of the
+ * setup pose (`inertAtSetup`, issue #743), so the refusal has to say that the
+ * other half was looked for and how wide the search was. A rig with no animation
+ * at all then says "none of the 0 animations" rather than implying somebody
+ * keyed something.
+ *
+ * `rule` is the row the value was judged by, and every sentence reads it: the
+ * reason each prints is the row's `basis` arm for the value (issue #798), the
+ * same object the key's sentence quotes, so what the setup pose and a key say
+ * about one number is one text — and whether that reason is the runtime's
+ * arithmetic or rigc's call is stated rather than implied.
+ */
+const SETUP_POSE_SAYS: Record<string, (pose: PhysicsSetup, animations: number, rule: PhysicsPoseRule) => string> = {
+  // Every reason below is the row's `basis` arm for the value (issue #798): an
+  // arithmetic arm names its expression, a behavioural one says refusing it is
+  // rigc's call and what the value does. ⚠️ Until then a setup mix BELOW 0 was
+  // told "it is muted", which it is not — [measured] it moves the bone by
+  // exactly −1× what +0.5 does — so the two ways out print two sentences.
+  mix: (pose, animations, rule) =>
+    `has mix ${pose.mix} and ${noneKeysItsMixAbove0(animations)}; ${setupBasisSays(rule, pose.mix)} — ${REST_OR_KEY_ITS_MIX}`,
+  mass: (pose, _animations, rule) => `has massInverse ${pose.massInverse}; mass must be ${rule.states} — ${setupBasisSays(rule, pose.massInverse)}`,
+  // Two arms, read off the row (issue #748): 0 is a constraint nothing pulls
+  // back and below 0 one that is pushed away, and the row's `why` — the key's
+  // sentence — quotes the second from the same object. The basis sentence ends
+  // on the arm's own words, which `T100` holds.
+  strength: (pose, _animations, rule) => `has strength ${pose.strength}; ${setupBasisSays(rule, pose.strength)}`,
+  // The bound is read off the row, so the setup pose and a key cannot state two
+  // intervals; the reason is the arm the value took, since the ends are inside (#794).
+  damping: (pose, _animations, rule) =>
+    `has damping ${pose.damping}; must be ${rule.states} — the per-step decay is \`damping ** (60 * step)\`, and ` +
+    setupBasisSays(rule, pose.damping),
+};
+
+/**
+ * The basis sentence for a setup value, or the bound itself where no arm holds
+ * — a pose value the parser handed over that none of the row's arms is about
+ * (a NaN, say), which has no reason to give and must not borrow another's.
+ */
+function setupBasisSays(rule: PhysicsPoseRule, poseValue: number): string {
+  const arm = physicsBasisFor(rule, poseValue);
+  return arm === undefined ? physicsOutsideSays(rule, poseValue) : physicsBasisSays(arm);
+}
+
+// Every failure mode here is silent. The five component fields default to
+// 0, so a constraint can drive nothing at all; `mix` 0 mutes it; `mass` 0
+// becomes an infinite massInverse; and `damping` above 1 never settles, which
+// on a mesh-driving bone means the canvas re-rasterises forever. 1 itself is
+// inside the bound since issue #794: it never decays, which is finite and a
+// choice, and what it costs a consumer's frame is the consumer's to judge.
+//
+// 🔑 **Two arms, one criterion.** The second arm below reads every physics
+// TIMELINE key, and it is written against `PHYSICS_POSE_RULES` — the table
+// this one is also written against, and the table `compileValueTrack`
+// refuses a spec's own out-of-range number with. Three readings of one rule
+// is how two of them come to disagree, so there is one (issue #610).
+export function a23PhysicsConstraintEffective({ fail, skip, stats }: Verdicts, facts: ConstraintFacts, meshFacts: MeshFacts): void {
+  // ⟨subject⟩_⟨property⟩, and its two siblings already read this way: A36
+  // skips on "the skeleton declares no path constraint" and A37 on "no
+  // slider constraint", while this one passed over an empty filter (#580).
+  // The stat is written before the guard so a reader of a SKIP still sees
+  // the count that produced it.
+  stats.physicsConstraints = facts.constraints.filter((c) => c.physics !== undefined).length;
+  if (stats.physicsConstraints === 0) return skip('A23_PHYSICS_CONSTRAINT_EFFECTIVE', SKIP_NO_PHYSICS_CONSTRAINT);
+  const meshBoneNames = new Set<string>();
+  for (const mesh of meshFacts.meshes) meshBoneNames.add(mesh.slotBone);
+  for (const mesh of meshFacts.meshes) {
+    if (!mesh.weights) continue;
+    for (const vertex of mesh.weights) {
+      for (const { bone: index } of vertex) {
+        const bone = meshFacts.bones[index];
+        if (bone !== undefined) meshBoneNames.add(bone);
+      }
+    }
+  }
+  // --- which constraints an animation switches ON (issue #743) ----------
+  //
+  // 🔑 The setup pose is the rig AT REST, and one of the four bounds is a
+  // state rather than a break there: `PHYSICS_POSE_RULES` marks `mix`
+  // `inertAtSetup`, because `update` opens with `if (mix === 0) return;`
+  // (`PhysicsConstraint.js:109-111`) and nothing else in the pose has such a
+  // branch. So a constraint that rests muted and is keyed above 0 by an
+  // animation is a rig the runtime plays as authored, and refusing it would
+  // refuse a design: physics off at rest, switched on by the animation that
+  // needs it.
+  //
+  // 📏 Measured on a generated physics fixture, 36 steps at 60 fps with the
+  // constraint's own bone swung by its parent: resting at `mix` 0 with an
+  // animation keying `mix` to 1 poses the bone IDENTICALLY to the same rig
+  // resting at 1 (max |dx| 0.000000) and up to 7.771177 away from the twin
+  // that keys nothing — which poses identically to one keyed to 0 only
+  // (max |dx| 0.000000). Two states, and the file says which.
+  //
+  // ⚠️ The escape is the rule's own field rather than the word "mix": a
+  // setup `mass` of 0 is `massInverse` Infinity BEFORE anything plays, and
+  // [measured] at rest it reads NaN on every frame although an animation
+  // keys `mass` to 1. A key cannot rescue a value that has already broken
+  // the rig it is resting in.
+  //
+  // The keys are read by `switchedOn`, the one reading A36 and A37 share
+  // (issue #752), through the runtime's own accessor: the pose field is
+  // where the integrator reads the number, and for `mass` that is not the
+  // number the key states. It counts the unnamed global form through the
+  // timeline's reach and a Bezier segment's samples as well as its keys.
+  const unmuted = new Map<number, Set<string>>();
+  for (const rule of PHYSICS_POSE_RULES) {
+    if (!rule.inertAtSetup) continue;
+    const reached = switchedOn(
+      facts,
+      (timeline) => timeline.kind === 'physics' && timeline.word === rule.timeline,
+      1,
+      (timeline, value) => rule.poseOk(timeline.posed === undefined ? value : timeline.posed(value)),
+    );
+    facts.constraints.forEach((one, index) => {
+      if (one.physics === undefined || !reached.has(index)) return;
+      const by = unmuted.get(index) ?? new Set<string>();
+      by.add(rule.timeline);
+      unmuted.set(index, by);
+    });
+  }
+  let mutedUntilKeyed = 0;
+  facts.constraints.forEach((constraint, index) => {
+    const physics = constraint.physics;
+    if (physics === undefined) return;
+    const where = `physics "${constraint.name}"`;
+    const components = PHYSICS_COMPONENTS.filter((k) => physics.components[k] > 0);
+    if (!components.length) {
+      fail('A23_PHYSICS_CONSTRAINT_EFFECTIVE', `${where} drives no component; it parses and does nothing`);
+    }
+    const pose = physics.setup;
+    // The four bounded fields, each judged by its `PHYSICS_POSE_RULES` row.
+    // The wording is per-field and stays so: "it is muted" and "nothing
+    // pulls it back" say what happens to THIS rig, which is what the author
+    // needs, and the shared table supplies the predicate rather than the
+    // sentence.
+    for (const rule of PHYSICS_POSE_RULES) {
+      if (rule.poseOk(pose[rule.field])) continue;
+      if (rule.inertAtSetup && unmuted.get(index)?.has(rule.timeline)) {
+        mutedUntilKeyed++;
+        continue;
+      }
+      const drivesAMesh = rule.timeline === 'damping' && meshBoneNames.has(physics.bone);
+      fail(
+        'A23_PHYSICS_CONSTRAINT_EFFECTIVE',
+        `${where} ${SETUP_POSE_SAYS[rule.timeline](pose, facts.animations, rule)}` +
+          (drivesAMesh ? ' — and this bone drives a mesh, so the canvas never rests' : ''),
+      );
+    }
+    if (physics.step <= 0 || !Number.isFinite(physics.step)) {
+      fail('A23_PHYSICS_CONSTRAINT_EFFECTIVE', `${where} has step ${physics.step} (fps must be > 0)`);
+    }
+  });
+  // What the PASS would otherwise not say: this rig rests with physics off
+  // on that many constraints and an animation is what switches them on. A
+  // pass carries no detail — `passed` is a list of names — so `stats` is the
+  // channel that exists, and a number is what belongs in a line printed as
+  // `k=v`: naming every such constraint and the animations that reach it
+  // would be a paragraph on one line, and the rig where nobody meant it is
+  // the rig where the NUMBER is the surprise. Absent rather than 0 when
+  // nothing rests muted, so it appears only where it says something.
+  if (mutedUntilKeyed) stats.physicsMutedUntilKeyed = mutedUntilKeyed;
+
+  // --- the same criterion, on every physics timeline key (issue #610) ----
+  //
+  // The arm above reads the setup pose and, until this one existed, nothing
+  // else — complete while a motion spec could key `mix` and `reset` only,
+  // and incomplete from #593 on, when it became able to key all seven.
+  //
+  // 📏 Measured on the tree before this landed, one keyed value at a time on
+  // a generated physics rig, 24 steps at 60 fps: `mass: 0` reached
+  // `massInverse` Infinity and every offset NaN — named by
+  // `A10_NO_NAN_AFTER_STEPPING`, from the BONE, with no word about the
+  // animation, the constraint, the timeline or the key; `damping: 2` ran the
+  // x offset to −26,634 and the velocity to −1.55e6 and still climbing, with
+  // **zero** gate failures; `strength: 0` drifted monotonically with zero gate
+  // failures; `mix: 1.5` produced zero gate failures and an integration
+  // identical to `mix: 1`, because mix multiplies the finished offset onto
+  // the bone and never enters the solve.
+  //
+  // ⭐ The value is judged where the runtime keeps it, not where the file
+  // writes it: `posed` is the number the runtime's own accessor writes, so a
+  // `mass` key lands as its reciprocal and is then held to exactly the
+  // predicate the setup arm holds `massInverse` to.
+  let keysRead = 0;
+  for (const timeline of facts.timelines) {
+    // A `reset` timeline keys no value, and was never one of the seven the pose holds.
+    if (timeline.kind !== 'physics' || timeline.word === 'reset') continue;
+    const name = timeline.word;
+    const rule = physicsRuleFor(name);
+    // -1 is the global form: the timeline drives every physics constraint
+    // whose matching `…Global` flag is set, so there is no one name to give.
+    const target =
+      timeline.constraint === -1
+        ? 'every physics constraint'
+        : `physics "${facts.constraints[timeline.constraint]?.name ?? `#${timeline.constraint}`}"`;
+    for (const frame of timeline.frames) {
+      keysRead++;
+      if (rule === undefined) continue;
+      const value = frame.value;
+      const refusal = physicsKeyRefusal(rule, value, timeline.posed === undefined ? undefined : timeline.posed(value));
+      if (refusal === null) continue;
+      fail(
+        'A23_PHYSICS_CONSTRAINT_EFFECTIVE',
+        `animation "${timeline.animation}" ${target} ${name} key at t=${frame.time.toFixed(6)}s is ${refusal}`,
+      );
+    }
+  }
+  stats.physicsTimelineKeys = keysRead;
+}

package/src/assertions/bodies/a27.ts

@@ -0,0 +1,33 @@
+/**
+ * A27, the body (issue #1025, step 4c of #380): the only region on a page is
+ * named for the page's file.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the regions
+ * are a fact (`../facts/atlas_regions.ts`). Why the second link of the
+ * attachment -> region -> file chain needs holding stays above the `check`
+ * call in `validate()`.
+ */
+import { basename } from 'node:path';
+import type { Verdicts } from '../harness.ts';
+import type { AtlasRegionFacts } from '../facts/atlas_regions.ts';
+import { SKIP_NO_ATLAS, SKIP_NO_ATLAS_REGION } from '../reasons.ts';
+
+export function a27RegionNameMatchesPageFilename({ fail, skip }: Verdicts, { atlas }: AtlasRegionFacts): void {
+  if (!atlas) return skip('A27_REGION_NAME_MATCHES_PAGE_FILENAME', SKIP_NO_ATLAS);
+  if (atlas.regions.length === 0) return skip('A27_REGION_NAME_MATCHES_PAGE_FILENAME', SKIP_NO_ATLAS_REGION);
+  const perPage = new Map<string, number>();
+  for (const region of atlas.regions) perPage.set(region.page.name, (perPage.get(region.page.name) ?? 0) + 1);
+  for (const region of atlas.regions) {
+    // A real packer puts many regions on one page and the names stop matching
+    // filenames by design. Then this check has nothing to say, so it says
+    // nothing rather than something wrong.
+    if ((perPage.get(region.page.name) ?? 0) !== 1) continue;
+    const expected = basename(region.page.name).replace(/\.png$/i, '');
+    if (region.name !== expected) {
+      fail(
+        'A27_REGION_NAME_MATCHES_PAGE_FILENAME',
+        `region "${region.name}" is the only region on page "${region.page.name}", whose basename is "${expected}"`,
+      );
+    }
+  }
+}