rig-c 0.0.0-stage → 2.20.4

package/src/core/walk.ts

@@ -0,0 +1,197 @@
+/**
+ * The core's looping walk (issue #1025, cut 4c-5a of step 4c of #380): one
+ * animation on a LOOPING track, reset at the setup pose and then stepped at
+ * the caller's steps, every pose returned as the doubles the core computed —
+ * a value that is not finite included, in place, rather than refused.
+ *
+ * This is the walk `A10_NO_NAN_AFTER_STEPPING` takes, and the reason it is
+ * its own entry rather than the raw entry (`./raw.ts`) under another name is
+ * the two things the raw entry's contract excludes on purpose: its track
+ * holds at the duration, and it refuses a non-finite value by name
+ * (`CoreInputError`), because a renderer handed one would draw a different
+ * picture in silence. A10's subject is exactly that value, so here it is the
+ * answer, not a refusal. Everything else is the raw entry's walk, called
+ * rather than restated (`walkIn` in `./raw.ts`, which branches on the two).
+ *
+ * ## The walk, measured
+ *
+ * Written from spine-core 4.3.13 running A10's own recipe — `Skeleton`,
+ * `AnimationState` with `setAnimation(0, name, true)`; `setupPose()`,
+ * `update(0)`, `updateWorldTransform(Physics.reset)`; then per step
+ * `AnimationState.update(dt)`, `apply`, `Skeleton.update(dt)`,
+ * `updateWorldTransform(Physics.update)` — and read off `TrackEntry.trackTime`,
+ * `TrackEntry.getAnimationTime()`, every bone's `appliedPose`, every shown
+ * region's and mesh's world vertices, every slot's colours and the calls the
+ * runtime makes to `PhysicsConstraint.reset`. The PR of issue #1025's cut
+ * 4c-5a carries the tables; each rule names the count that held it.
+ *
+ * - **Pose 0 is the setup pose, reset** — the animation is set and not yet
+ *   applied, so the reset is taken at the setup pose (`RawReset` `setup`).
+ * - **The track time is the running sum of the steps**, as on the raw
+ *   entry's walk: `TrackEntry.trackTime` equalled it on every step of the
+ *   nineteen tree rows' walks (6,480 of 6,480).
+ * - **The time** — the animation is applied at the track time wrapped by the
+ *   duration (`loopedTime` in `./raw.ts`): `trackTime % duration` in double,
+ *   so a track time of exactly the duration is 0, the first pose again, and
+ *   over a duration of 0 the time is 0 whatever the track time (an animation
+ *   keying nothing, or keying only at 0) — `getAnimationTime()` read so on
+ *   6,480 of 6,480 steps, 1,087 of them at or past the duration and 4 exactly
+ *   on it; before the zero-duration reading it read 6,000.
+ * - **The physics clock moves by the step itself** (`Skeleton.update(dt)`),
+ *   whatever the wrap does to the animation time: moved by the animation
+ *   time's own change instead, 32 of 82 seeded and forged walks read off.
+ * - **A `reset` key across the wrap.** A key is crossed when it lies in
+ *   `(previous animation time, animation time]`, as on the raw entry; on a
+ *   step whose animation time went DOWN — the wrap — it is crossed when it
+ *   lies after the previous time or at or before the new one, `(last, ∞)`
+ *   and `(−1, t]` (`resetCrossed` in `./constraints_physics.ts`). A step
+ *   that passes the duration once or more while its animation time still
+ *   rises is not a wrap there: a key at 0.25 s of a 0.3 s animation stepped
+ *   by 0.7 s fired on neither of the two steps that carried the track past
+ *   it, and an equal time is not a wrap either (a 0.25 s animation stepped by
+ *   0.25 s fired its key at 0 once). With the wrap firing nothing, 957 of
+ *   14,460 poses of a seeded population read off.
+ * - **A value that is not finite** is the IEEE result of the same
+ *   arithmetic, kept: a world matrix term, a world position, a vertex, a slot
+ *   colour channel. Where the raw entry writes such a value `null` and
+ *   refuses, this entry writes the double; on 4,333 poses holding one, every
+ *   NaN and Infinity stood where spine-core's did.
+ *
+ * Events are not carried: A10 reads none, and what a looping track fires
+ * across the wrap was not measured. Nor are the clipped rows, and the walk
+ * does not cut them (issue #1179): every clip it starts is still planned, so
+ * a clip the core does not draw refuses the walk by name, as below.
+ *
+ * ⛔ **What is still refused** is the raw entry's other refusal: a construct
+ * the core would leave out (a block the oracle's core dump names absent) is a
+ * `CoreInputError` naming why, as there — a pose with a block missing is not
+ * a pose whose values can be judged finite.
+ *
+ * 🔁 **A slider whose animation keys a physics timeline** was refused here
+ * by name until issue #1049 (`sliderPhysicsWhy`): six of the path-slider
+ * suite's distinct builds walked off spine-core from the third step, and the
+ * raw entry read the same gap. The core had not applied a slider's physics keys at all;
+ * it now does, under the step, by the rule `./constraints_slider.ts` *Its
+ * physics timelines* states and the core suite's `CO31` holds — so this walk
+ * poses the class as the raw entry does, and refuses nothing the raw entry
+ * does not.
+ */
+import { scanSetupIn, scanWalkIn, setupPoseIn, walkIn, type RawBone, type RawDrawn, type ScanPlant, type ScanPose, type WalkMode } from './raw.ts';
+import { activeBones, type CompiledDocument, type CorePlant, type CoreSlotRow } from './index.ts';
+import { historyTaint } from './constraints.ts';
+import type { TimelinePlant } from './animation.ts';
+
+/** One pose of the looping walk: the raw entry's pose less what this walk does not carry (events, the clip rows, the shown records). */
+export interface WalkPose {
+  /** The running sum of the steps, 0 for pose 0. */
+  trackTime: number;
+  /** The time the animation was applied at: the track time wrapped by the duration (`loopedTime`). */
+  animationTime: number;
+  /** Every bone in document order, its world matrix and origin as computed, finite or not. */
+  bones: RawBone[];
+  /** Every slot row (`CoreSlotRow`) with its colour channels as computed, finite or not. */
+  slots: CoreSlotRow[];
+  /** The slot names in the posed draw order. */
+  drawOrder: string[];
+  /** Every region and mesh a slot shows, in draw order, its world vertices as computed, finite or not. */
+  drawn: RawDrawn[];
+}
+
+/**
+ * The bones and slots whose numbers the walk does not vouch for, because the
+ * runtime's own value there is HISTORY (issue #979): a bone the view leaves
+ * unposed — inactive, or below an inactive bone — that a constraint writing
+ * into an inactive bone reaches (`historyTaint` in `./constraints.ts`, the
+ * walk the core's leak refusal reads), each with that writer; and every slot
+ * on such a bone. spine-core never updates an inactive bone, so what a
+ * constraint wrote into it on the step before is what the constraint reads
+ * on the next one; the core poses every step from the setup pose. Measured on
+ * a public probe (a transform constraint writing four skin-required bones no
+ * skin activates): at mix 1 the two differ only in the sign of zero of the
+ * matrix cells (`atan2` of a zero matrix is 0° or 180° by those signs), and at
+ * a translate mix of 0.5 by value (worldX 30.000000348 in spine-core against
+ * 20.000000232 in the core at step 1), on the bones and on an active child of
+ * one. Where such a value reaches a posed bone the core already refuses the
+ * document (`unposedLeakWhy`); here nothing posed reads it, so a walk
+ * comparison counts these numbers apart by name and compares them with
+ * nothing, as `tools/pose_oracle.ts unposed` does under the step.
+ */
+export function walkHistory(view: CompiledDocument): { bones: Map<string, string>; slots: Map<string, string> } {
+  const active = activeBones(view);
+  const unposed = new Set<string>();
+  for (const b of view.bones) if (!active.has(b.name) || (b.parent !== undefined && unposed.has(b.parent))) unposed.add(b.name);
+  const bones = new Map<string, string>();
+  for (const [bone, w] of historyTaint(view).tainted) if (unposed.has(bone)) bones.set(bone, `${w.kind}/${w.name} on inactive ${w.inactive}`);
+  return { bones, slots: new Map(view.slots.filter((s) => bones.has(s.bone)).map((s) => [s.name, s.bone])) };
+}
+
+/** The looping walk's mode: the track loops, and a non-finite value stays in the pose. */
+const LOOPING: WalkMode = { loop: true, keep: true };
+
+/**
+ * The looping walk's plants (the core suite's `CO26`), each the reading the
+ * walk was measured against and rejected, in a copy: the time a step applies
+ * at, what the physics clock moves by, and what a number is written as.
+ * Nothing but a control passes one.
+ */
+export interface WalkPlant {
+  time?: WalkMode['time'];
+  clock?: WalkMode['clock'];
+  wrapResets?: WalkMode['wrapResets'];
+  /** Every number of a pose rewritten — a swallowed non-finite value is `(v) => (Number.isFinite(v) ? v : 0)`. */
+  number?: (v: number) => number;
+}
+
+/** A raw pose narrowed to what the looping walk carries, every number through `number`. */
+function narrow(p: { trackTime: number; animationTime: number; bones: RawBone[]; slots: CoreSlotRow[]; drawOrder: string[]; drawn: RawDrawn[] }, number?: (v: number) => number): WalkPose {
+  if (number === undefined) return { trackTime: p.trackTime, animationTime: p.animationTime, bones: p.bones, slots: p.slots, drawOrder: p.drawOrder, drawn: p.drawn };
+  const n = (v: number | null): number | null => (v === null ? null : number(v));
+  return {
+    trackTime: p.trackTime,
+    animationTime: p.animationTime,
+    bones: p.bones.map((b) => ({ ...b, a: number(b.a), b: number(b.b), c: number(b.c), d: number(b.d), worldX: number(b.worldX), worldY: number(b.worldY) })),
+    slots: p.slots.map((r): CoreSlotRow => [r[0], r[1], n(r[2]), n(r[3]), n(r[4]), n(r[5]), r[6] === null ? null : [n(r[6][0]), n(r[6][1]), n(r[6][2])], r[7], r[8]]),
+    drawOrder: p.drawOrder,
+    drawn: p.drawn.map((d) => ({ ...d, vertices: d.vertices.map(number) })),
+  };
+}
+
+/**
+ * The setup pose, every physics state reset, every value kept whatever it is —
+ * what A10 reads before any animation is set.
+ */
+export function poseWalkSetup(doc: CompiledDocument, plant: CorePlant = {}, walkPlant: WalkPlant = {}): WalkPose {
+  return narrow(setupPoseIn(doc, plant, LOOPING), walkPlant.number);
+}
+
+/**
+ * One animation on a looping track (the header's *The walk*): pose 0 the setup
+ * pose reset, then one pose per step of `steps` — `steps.length + 1` poses in
+ * all. A step must be a finite time at or above 0 and the animation the
+ * document's, as on the raw entry; a construct the core would leave out
+ * refuses the call by name; a value that is not finite does not.
+ */
+export function poseLoopingWalk(doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant = {}, walkPlant: WalkPlant = {}): WalkPose[] {
+  const mode: WalkMode = { ...LOOPING, ...(walkPlant.time === undefined ? {} : { time: walkPlant.time }), ...(walkPlant.clock === undefined ? {} : { clock: walkPlant.clock }), ...(walkPlant.wrapResets === undefined ? {} : { wrapResets: walkPlant.wrapResets }) };
+  return walkIn(doc, animation, steps, plant, 'setup', mode).map((p) => narrow(p, walkPlant.number));
+}
+
+/**
+ * The scan's walk (issue #1179, the second part): `poseLoopingWalk` and
+ * `poseWalkSetup` as A10 reads them, each pose a `ScanPose` — the bones' world
+ * matrix and origin, the slot rows and the drawn attachments, and nothing the
+ * walk forms beside them for other readers (the bones' oracle rows and getter
+ * readings). The same walk: `walkIn`'s body in `./raw.ts`, posing each step by
+ * the same operations in the same order and refusing at the same places, with
+ * another assembler (`PoseShape`). `src/assertions/model/stepped_poses.ts` is
+ * its one caller; the public entries above are unchanged, and the core suite
+ * holds the two to the same numbers (`CO43`, `CO44`, `CO45`).
+ */
+export function scanLoopingWalk(doc: CompiledDocument, animation: string, steps: readonly number[], scanPlant: ScanPlant = {}): ScanPose[] {
+  return scanWalkIn(doc, animation, steps, {}, 'setup', LOOPING, scanPlant);
+}
+
+/** `poseWalkSetup` as the scan reads it (`scanLoopingWalk`). */
+export function scanWalkSetup(doc: CompiledDocument): ScanPose {
+  return scanSetupIn(doc, {}, LOOPING);
+}

package/src/core/world.ts

@@ -0,0 +1,289 @@
+/**
+ * The core's own setup evaluator: every bone's world matrix and origin from
+ * the compiled model's bones (issue #925). Written from what a bone's fields
+ * mean and from measurement against the runtime's pose dump
+ * (`tools/pose_oracle.ts dump`, spine-core 4.3.13), and held to it by the core
+ * suite's equivalence controls.
+ *
+ * ⭐ **The compiler's setup transforms are this evaluator too** (issue #1015),
+ * under the same arithmetic (issue #1021). `src/transform.ts` held a second
+ * evaluator of its own until #1015, and the two differed in exactly three
+ * places, none of them a different matrix: the degree factor (`Math.PI / 180`
+ * there, the runtime's 3.1415927 here), the frame of a bone with scale 1 and
+ * no shear (`[cos, −sin, sin, cos]` of the rotation there, the y column at
+ * `rotation + 90` here), and how a radian angle is turned into degrees
+ * (divided by the degree factor there, multiplied by `180 / pi` here). #1015
+ * made them a parameter (`WorldArithmetic`) so that no byte moved; #1021
+ * measured which binds closer — every point the compiler binds from a world
+ * position, posed by spine-core from the emitted build, against that position
+ * — and the runtime's three put every one at the float32 floor where the
+ * compiler's left `gallery/look`'s up to 8.6e-5 off. So the compiler passes
+ * none now, and `RUNTIME_ARITHMETIC`, the measured choices below, is the only
+ * arithmetic anything here runs under; the parameter stays for the plants
+ * that swap one choice back in to show a control fire.
+ *
+ * ## What each measured choice is
+ *
+ * - **Degrees to radians with pi written 3.1415927.** The runtime's root bone
+ *   at rotation 0 reads `b = -2.3205103333142417e-8` and
+ *   `d = 0.9999999999999998`: `cos` and `sin` of 90 degrees converted with
+ *   pi = 3.1415927, since `(3.1415927 - pi) / 2 = 2.3205e-8`. It is that
+ *   decimal in double arithmetic — not float32: pi rounded to float32 would
+ *   give `4.37e-8`, and the bone fields read through `Math.fround` moved the
+ *   dump further, not closer (measured on the nineteen recipes).
+ * - **The degree factor is taken once**, `pi / 180`, and every angle is
+ *   multiplied by it.
+ * - **The y column is `cos(rotation + 90 + shearY)` and `sin(…)` on every
+ *   bone**, never `-sin`/`cos` of the rotation. With the constant above but
+ *   the `-sin` form, `2-the-12-principles` stays 61 millionths off.
+ * - **A root bone is its local matrix at its own `x`, `y`**: the skeleton is
+ *   at the origin, unscaled, in every dump taken.
+ *
+ * Both halves together read IDENTICAL, worst delta exactly 0, on the 12
+ * recipes without constraints (`tools/core_gate.ts`); either half alone is
+ * exact on none of them.
+ *
+ * ## The five inherit modes
+ *
+ * What each mode takes from the parent, as the format's documentation words
+ * it, then how it is computed here. A child's ORIGIN is always the parent's
+ * matrix applied to the local `x`, `y` plus the parent's origin — the modes
+ * change only the matrix.
+ *
+ * - `normal` — everything: parent matrix times local matrix.
+ * - `onlyTranslation` — the parent's position only: the local matrix alone.
+ * - `noRotationOrReflection` — the parent's scale (and what shear leaves of
+ *   it), not its rotation and not a reflection. The parent's matrix is made
+ *   conformal on its x axis: that axis kept, the y axis turned to 90 degrees
+ *   from it with length `|det| / |x axis|` (so the area, the scale the parent
+ *   carries, is kept and its sign is not); the local matrix is built at the
+ *   bone's rotation MINUS the parent's x-axis angle; the product is the world.
+ *   ⚠️ **A parent x axis whose squared length is at most `1e-5` squared is
+ *   collapsed** (issue #979, `COLLAPSED_X_AXIS_SQ`): the conformal frame is
+ *   then the parent's y column with its x component negated, beside a zero x
+ *   column, and the local matrix is built at the rotation less 90 plus the y
+ *   column's angle, summed in that order. Measured on a child of such a
+ *   parent: by bisection on the x axis's length, 1e-5 reads collapsed and the
+ *   next double above does not, at parent rotations 0, 30 and 45 (whether the
+ *   runtime compares the squared length with `1e-5 · 1e-5` or the length with
+ *   `1e-5`, 200,000 parents searched separated no pair); 480 probes of x axes
+ *   from 1e-4 down to 1e-20 and 0 under y axes up to 2e17, sheared, scaled and
+ *   reflected, read exact, where the reading this replaced (collapsed only at
+ *   length 0, the y column as it is, the angle less 90) read 71 of 96 off and
+ *   the rotation-first sum `rotation − (90 − angle)` 10 of 480. The zero
+ *   matrix of a bone below an inactive one is the collapsed case at length 0,
+ *   and it fixes the signs of zero of every child in this mode there (`CC13`).
+ * - `noScale` — the parent's rotation (and reflection), not its scale: the
+ *   bone's local rotation is carried through the parent's matrix as a
+ *   direction, normalised to unit length; the y axis is that direction turned
+ *   90 degrees, turned the other way when the parent reflects (`det < 0`);
+ *   the bone's own shear and scale are applied on that frame.
+ * - `noScaleOrReflection` — as `noScale`, never turned for a reflection.
+ *
+ * ## To the bit (issue #966)
+ *
+ * The rules above were measured on the oracle's six-decimal grid; three of
+ * the modes matched it and not the runtime's last bit (issue #959). Held
+ * against `pose_oracle.ts dump --raw` at tolerance 0 — a bone in the mode
+ * under a parent rotated, scaled, sheared and reflecting, two children 1e9
+ * units out (the core suite's `CR02`, 300 per mode) — three operation orders
+ * are the runtime's and the grid could not tell them:
+ *
+ * - a radian angle is turned into degrees by multiplying with `180 / pi`
+ *   (`RUNTIME_DEG`), not by dividing by `pi / 180`: the division read 106
+ *   of 300 `noRotationOrReflection` bones off;
+ * - `noRotationOrReflection`'s y angle is `r + shearY + 90`, the shear
+ *   added before the right angle (`r + 90 + shearY` read 46 of 300 off);
+ * - `noScale`'s direction is normalised by multiplying with the reciprocal
+ *   of its length (dividing read 138 of 300 off).
+ *
+ * Measured: `normal` on 12 recipes, `onlyTranslation` on 1 and
+ * `noRotationOrReflection` on 2 of the tree's corpus; all five, under rotated,
+ * scaled, sheared and reflecting parents, on the hand-written probe the core
+ * suite builds (`CO07`), because the corpus reaches `noScale` only on a rig
+ * with constraints and `noScaleOrReflection` on none.
+ */
+import type { ModelBone } from '../model.ts';
+
+/** Pi as the runtime converts degrees with it — see the header. */
+export const RUNTIME_PI = 3.1415927;
+const RAD = RUNTIME_PI / 180;
+/** Radians to degrees as the runtime converts them (issue #966): multiplied by `180 / pi`, not divided by `pi / 180` — the two differ in the last bit. */
+export const RUNTIME_DEG = 180 / RUNTIME_PI;
+
+/** A parent x axis whose squared length is at most this is collapsed for `noRotationOrReflection` (issue #979): `1e-5` squared, as measured — see the header. */
+export const COLLAPSED_X_AXIS_SQ = 0.00001 * 0.00001;
+
+/**
+ * The three places an evaluator's arithmetic may differ in the last bit while
+ * computing the same matrix (issue #1015) — see the header. The core poses and
+ * the compiler binds with `RUNTIME_ARITHMETIC` (issue #1021); another value is
+ * a plant's.
+ */
+export interface WorldArithmetic {
+  /** Degrees to radians: every angle is multiplied by it. */
+  radiansPerDegree: number;
+  /** Radians to degrees — the angle `noRotationOrReflection` takes off a parent's axis. */
+  degreesOf: (radians: number) => number;
+  /** A bone with scale 1 and no shear takes `[cos r, −sin r, sin r, cos r]` instead of the y column at `r + 90`; the general frame everywhere else. */
+  rotationOnlyFrame: boolean;
+}
+
+/** The runtime's arithmetic, as measured (the header's three choices): what the core poses with. */
+export const RUNTIME_ARITHMETIC: WorldArithmetic = {
+  radiansPerDegree: RAD,
+  degreesOf: (radians) => radians * RUNTIME_DEG,
+  rotationOnlyFrame: false,
+};
+
+/** One bone's world transform: the matrix `[a b; c d]` and the origin, y up. */
+export interface CoreWorld {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  worldX: number;
+  worldY: number;
+}
+
+/** The five modes, after the first-letter fold the rig spec admits. */
+export type CoreInheritMode = 'normal' | 'onlyTranslation' | 'noRotationOrReflection' | 'noScale' | 'noScaleOrReflection';
+
+export type M2 = [number, number, number, number];
+
+/** What computes a child's world matrix from its mode, its parent's world, its own fields and the arithmetic in force. */
+export type InheritComputation = (mode: CoreInheritMode, parent: CoreWorld, bone: ModelBone, arithmetic: WorldArithmetic) => M2;
+
+/** The matrix of a rotation, shears and scales, in the column form the header states. */
+function frame(rotation: number, shearX: number, shearY: number, scaleX: number, scaleY: number, rad: number = RAD): M2 {
+  const xAngle = (rotation + shearX) * rad;
+  const yAngle = (rotation + 90 + shearY) * rad;
+  return [Math.cos(xAngle) * scaleX, Math.cos(yAngle) * scaleY, Math.sin(xAngle) * scaleX, Math.sin(yAngle) * scaleY];
+}
+
+/** A bone's own frame — a root's matrix, and the local factor of `normal` and `onlyTranslation` — under `arithmetic`. */
+function localFrame(arithmetic: WorldArithmetic, rotation: number, shearX: number, shearY: number, scaleX: number, scaleY: number): M2 {
+  const rad = arithmetic.radiansPerDegree;
+  if (arithmetic.rotationOnlyFrame && scaleX === 1 && scaleY === 1 && shearX === 0 && shearY === 0) {
+    const cos = Math.cos(rotation * rad);
+    const sin = Math.sin(rotation * rad);
+    return [cos, -sin, sin, cos];
+  }
+  return frame(rotation, shearX, shearY, scaleX, scaleY, rad);
+}
+
+function times(p: M2, q: M2): M2 {
+  return [p[0] * q[0] + p[1] * q[2], p[0] * q[1] + p[1] * q[3], p[2] * q[0] + p[3] * q[2], p[2] * q[1] + p[3] * q[3]];
+}
+
+/**
+ * The unit direction a `noScale` / `noScaleOrReflection` bone's x axis takes:
+ * its local rotation carried through the parent's matrix and normalised. Shared
+ * by the forward frame and `localFromWorld`'s read-back (`./constraints.ts`),
+ * which builds the frame to read the bone's columns in from the rotation it
+ * has just read, through this same arithmetic (issue #966).
+ */
+export function noScaleDirection(p: M2, rotation: number, rad: number = RAD): [number, number] {
+  const r = rotation * rad;
+  const cos = Math.cos(r);
+  const sin = Math.sin(r);
+  const ux = p[0] * cos + p[1] * sin;
+  const uy = p[2] * cos + p[3] * sin;
+  // Normalised by multiplying with the reciprocal of the length, not by dividing by it (issue #966): the division reads 1 ulp off on 375 bone-samples of the corpus's `noScale` row.
+  const inverse = 1 / Math.sqrt(ux * ux + uy * uy);
+  return [ux * inverse, uy * inverse];
+}
+
+/** The world matrix of a child under `parent` in `mode`, under `arithmetic` (the runtime's unless a caller passes its own). */
+function modeMatrix(mode: CoreInheritMode, parent: CoreWorld, bone: ModelBone, arithmetic: WorldArithmetic = RUNTIME_ARITHMETIC): M2 {
+  const rotation = bone.rotation ?? 0;
+  const shearX = bone.shearX ?? 0;
+  const shearY = bone.shearY ?? 0;
+  const scaleX = bone.scaleX ?? 1;
+  const scaleY = bone.scaleY ?? 1;
+  const rad = arithmetic.radiansPerDegree;
+  const p: M2 = [parent.a, parent.b, parent.c, parent.d];
+  switch (mode) {
+    case 'normal':
+      return times(p, localFrame(arithmetic, rotation, shearX, shearY, scaleX, scaleY));
+    case 'onlyTranslation':
+      return localFrame(arithmetic, rotation, shearX, shearY, scaleX, scaleY);
+    case 'noRotationOrReflection': {
+      const xLengthSq = p[0] * p[0] + p[2] * p[2];
+      let conformal: M2;
+      let r: number;
+      if (xLengthSq > COLLAPSED_X_AXIS_SQ) {
+        const k = Math.abs(p[0] * p[3] - p[1] * p[2]) / xLengthSq;
+        conformal = [p[0], -p[2] * k, p[2], p[0] * k];
+        r = rotation - arithmetic.degreesOf(Math.atan2(p[2], p[0]));
+      } else {
+        // A collapsed x axis (issue #979): the parent's y column with its x component negated, and the rotation less 90 plus the y column's angle — see the header.
+        conformal = [0, -p[1], 0, p[3]];
+        r = rotation - 90 + arithmetic.degreesOf(Math.atan2(p[3], p[1]));
+      }
+      // The y angle adds the shear before the right angle here, unlike `frame` (issue #966): `(r + 90 + shearY)` reads last-bit off on 81 of 205 sheared or scaled bones at a 1e9 amplifier, `(r + shearY + 90)` on none; `r = rotation − parentAngle` taken first (adding the shear before the parent's angle is taken off reads 102 of 205 off).
+      const xAngle = (r + shearX) * rad;
+      const yAngle = (r + shearY + 90) * rad;
+      return times(conformal, [Math.cos(xAngle) * scaleX, Math.cos(yAngle) * scaleY, Math.sin(xAngle) * scaleX, Math.sin(yAngle) * scaleY]);
+    }
+    case 'noScale':
+    case 'noScaleOrReflection': {
+      const [ux, uy] = noScaleDirection(p, rotation, rad);
+      const flip = mode === 'noScale' && p[0] * p[3] - p[1] * p[2] < 0 ? -1 : 1;
+      const turned: M2 = [ux, -uy * flip, uy, ux * flip];
+      return times(turned, frame(0, shearX, shearY, scaleX, scaleY, rad));
+    }
+  }
+}
+
+/** The fold the rig spec admits: the first letter lower-cased; anything else is not a mode. */
+function modeOf(bone: ModelBone): CoreInheritMode {
+  const stated = bone.inheritMode;
+  if (stated === undefined) return 'normal';
+  const folded = stated.length === 0 ? stated : stated[0].toLowerCase() + stated.slice(1);
+  if (folded === 'normal' || folded === 'onlyTranslation' || folded === 'noRotationOrReflection' || folded === 'noScale' || folded === 'noScaleOrReflection') return folded;
+  throw new Error(`bone "${bone.name}": inheritMode ${JSON.stringify(stated)} is no mode (readModel refuses it first)`);
+}
+
+/**
+ * Every bone's setup world transform, parents first as the model lists them.
+ *
+ * `active`, when given, is the set of bones the applied skins leave active; a
+ * bone outside it is not posed. Measured on a hand-written skeleton: the
+ * runtime's dump reads an inactive bone as all zeros — matrix and origin, its
+ * world as a skeleton is created — and a bone under it, active or not, is
+ * posed from those zeros like any child. `inherit` replaces the mode
+ * computation — the core suite's plant passes a copy with one mode's sign
+ * flipped, and nothing else does. `arithmetic` is the runtime's unless a
+ * caller states its own, and only a plant does: `src/transform.ts` takes the
+ * default since issue #1021, as every posing path does.
+ */
+export function worldTransforms(
+  bones: readonly ModelBone[],
+  active: ReadonlySet<string> | null = null,
+  inherit: InheritComputation = modeMatrix,
+  arithmetic: WorldArithmetic = RUNTIME_ARITHMETIC,
+): Map<string, CoreWorld> {
+  const out = new Map<string, CoreWorld>();
+  for (const bone of bones) {
+    if (active !== null && !active.has(bone.name)) {
+      out.set(bone.name, { a: 0, b: 0, c: 0, d: 0, worldX: 0, worldY: 0 });
+      continue;
+    }
+    const x = bone.x ?? 0;
+    const y = bone.y ?? 0;
+    if (bone.parent === undefined) {
+      const [a, b, c, d] = localFrame(arithmetic, bone.rotation ?? 0, bone.shearX ?? 0, bone.shearY ?? 0, bone.scaleX ?? 1, bone.scaleY ?? 1);
+      out.set(bone.name, { a, b, c, d, worldX: x, worldY: y });
+      continue;
+    }
+    const parent = out.get(bone.parent);
+    if (parent === undefined) throw new Error(`bone "${bone.name}": parent "${bone.parent}" is not posed before it`);
+    const [a, b, c, d] = inherit(modeOf(bone), parent, bone, arithmetic);
+    out.set(bone.name, { a, b, c, d, worldX: parent.a * x + parent.b * y + parent.worldX, worldY: parent.c * x + parent.d * y + parent.worldY });
+  }
+  return out;
+}
+
+/** The mode computation `worldTransforms` uses, exported so a control can wrap it. */
+export { modeMatrix };

package/src/correspondence.ts

@@ -0,0 +1,15 @@
+/**
+ * The two spellings of a bone correspondence — what `rigc bonedist --bones`
+ * and `rigc bench --bones` take — moved here unchanged from `./bonedist.ts`
+ * (issue #1052), which re-exports both.
+ *
+ * Their own module because the CLI's help states them (`--bones`'s flag row)
+ * and an entry that links nothing of the runtime prints that help, while
+ * `./bonedist.ts` poses both skeletons through spine-core by design.
+ */
+
+/** The sidecar spec a correspondence file declares, and the report's own. */
+export const BONEDIST_SPEC = 'rigc-bonedist/1';
+
+/** What `--bones identity` is spelled as, where a file path would go. */
+export const IDENTITY_CORRESPONDENCE = 'identity';

package/src/deformbuild.ts

@@ -0,0 +1,60 @@
+/**
+ * The deform survey of a build, through the reader and poser asked for —
+ * `explain`'s `DEFORM` block and `tools/survey_hashes.ts` (issues #969,
+ * #1019).
+ *
+ * Moved here unchanged from `./deformmeasure.ts` (issue #1052, step 4e of
+ * #380), which re-exports both names: the choice between the model document
+ * posed by the core and the Spine skeleton posed by spine-core names no
+ * runtime class, and `explain` makes it on a rigc build without touching the
+ * runtime — so an entry that links nothing of spine-core has to be able to
+ * load it. The spine-core half (`throughSpine`) is `./deformmeasure.ts`'s,
+ * reached through the seam (`./spine_side.ts`); where nothing registered it,
+ * a survey that needs it is refused by name (`SpineRuntimeError`).
+ */
+import { CoreInputError, readModel } from './core/index.ts';
+import { surveyOfModel, type DeformSurvey, type DeformSurveySource } from './deformsurvey.ts';
+import { spineFileSha256 } from './model.ts';
+import { spineSurveyFor } from './spine_side.ts';
+
+/** A build's three texts, as `explain` and `tools/survey_hashes.ts` hold them. */
+export interface DeformSurveyInput {
+  skeletonText: string;
+  atlasText: string;
+  /** The model document (`skeleton.model.json`), or `null` when the input carries none (a Spine export). */
+  modelText: string | null;
+  /** What a refusal names the survey's input as; `the deform survey` unstated. */
+  label?: string;
+}
+
+/**
+ * The survey of a build, through the reader and poser asked for (issues #969,
+ * #1019): `model` — the model document's structure posed by the core,
+ * refused when there is none or when the Spine file beside it is not the one
+ * it records; `spine-core` — the Spine skeleton read and posed by the runtime;
+ * `auto` — the model document when the input carries one and the core poses
+ * it, spine-core otherwise, the reason named in `source.why`. On the model
+ * path spine-core is not touched: the Spine text is hashed, never parsed.
+ */
+export function surveyOfBuild(input: DeformSurveyInput, exempt: ReadonlySet<string>, asked: 'auto' | DeformSurveySource): DeformSurvey {
+  const label = input.label ?? 'the deform survey';
+  // `./deformmeasure.ts`'s reader and poser, through the seam: it touches the runtime first and refuses by name where it cannot be used.
+  const throughSpine = (why: string | null): DeformSurvey => spineSurveyFor(label, why ?? '--poser spine').throughSpine(label, why, input, exempt);
+  if (asked === 'spine-core') return throughSpine(null);
+  if (input.modelText === null) {
+    if (asked === 'model') throw new CoreInputError('the survey was asked to pose the model document, and the input carries none');
+    return throughSpine('the input carries no model document (skeleton.model.json), so the survey posed the Spine skeleton through spine-core');
+  }
+  try {
+    const doc = readModel(input.modelText);
+    // The document reads the rig it was built with; the Spine file beside it must be that build's (issue #968's rule).
+    const found = spineFileSha256(input.skeletonText);
+    if (found !== doc.spine.sha256) {
+      throw new CoreInputError(`the skeleton is not the one the model document was written beside: its sha256 is ${found}, the document records ${doc.spine.sha256 || 'none'}`);
+    }
+    return surveyOfModel(doc, exempt);
+  } catch (err) {
+    if (!(err instanceof CoreInputError) || asked === 'model') throw err;
+    return throughSpine(`the core refused to pose the model document — ${err.message}`);
+  }
+}