spine-rigc 0.18.0 → 0.19.0

package/src/deformmeasure.ts

@@ -95,6 +95,13 @@ import {
   AtlasAttachmentLoader,
   type Bone,
   DeformTimeline,
+  FromProperty,
+  FromRotate,
+  FromScaleX,
+  FromScaleY,
+  FromShearY,
+  FromX,
+  FromY,
   MeshAttachment,
   Physics,
   Skeleton,
@@ -298,24 +305,127 @@ export interface DeformReach {
   /** The slider's driving bone. `null` on the track, and on a bone-less slider. */
   bone: string | null;
   /**
-   * The transform property the slider reads off that bone, as spine-core's own
-   * reader class is named minus the `From` (`rotate`, `x`, `y`, `scaleX`, …), or
-   * `null` when there is no bone. Derived from which local field moves the
-   * slider's time rather than from a table, so it cannot drift from the runtime.
+   * The transform property the slider reads off that bone, as a rig spec spells
+   * it (`rotate`, `x`, `y`, `scaleX`, …), or `null` when there is no bone.
+   *
+   * 🚨 Off the **artifact** since issue #419 — spine-core's own `FromProperty`
+   * subclass, which is what the parser built out of the rig spec's `property`
+   * field. It used to be whichever local field the probe below found first, and
+   * float noise makes `rotation` move a world `sqrt(a² + c²)` reading, so every
+   * world `scaleX` / `scaleY` / `shearY` slider was reported as `rotate`.
    */
   property: string | null;
+  /**
+   * The bone field the solve actually drives, when that is **not** the one
+   * `property` names; `null` when they are the same, which is every rig that has
+   * a plain parent.
+   *
+   * They come apart under `local: false`, where the reader goes through the world
+   * transform: a `FromX` slider on a bone whose parent is at 90° reads a world x
+   * that local `x` does not move at all and local `y` moves entirely.
+   */
+  drive: string | null;
   /** `SliderData.local` — whether the property is read local or world. */
   local: boolean;
   /** The clause the `DEFORM` block and A39's stats line print. */
   label: string;
 }
 
+/** The span of one animation's own `0..duration` a dial can select, in seconds. */
+export interface DialSpan {
+  lo: number;
+  hi: number;
+}
+
+/**
+ * A dial whose probe **tied** and whose artifact broke the tie (issue #419).
+ *
+ * 🔒 **Not a disagreement, and it must never be reported as one.** There is one
+ * belief here, not two: the probe measured two fields moving the reading by the
+ * same amount, named neither, and the skeleton's own reader said which of them
+ * the author wrote. A `FromX` slider under `local: false` on a bone whose parent
+ * is at 45° is exactly that, and it is legitimate geometry. So there is no second
+ * answer, no second reach and nothing to compare — which is why this is a type of
+ * its own and not a `verdict` field on the one below.
+ */
+export interface DeformDialTie {
+  /** The slider whose dial this is. */
+  slider: string;
+  /** Its driving bone. */
+  bone: string;
+  /** The field the artifact named, which is therefore the one the survey drives. */
+  drive: string;
+  /** What one step of it moved the reading by. */
+  driveResponse: number;
+  /** The other fields inside `DIAL_PROBE_MARGIN` of it, and what each moved it by. */
+  rivals: Array<{ field: string; response: number }>;
+}
+
+/**
+ * A dial the artifact and the probe name **differently**, with the span each of
+ * their answers can select (issues #419, #427).
+ *
+ * ⭐ Structured, and on the survey rather than only inside `DeformReach.label`,
+ * because that label is prose only `explain` prints. A `build`-only run is the
+ * loop an agent that cannot see the rig actually runs, and until this existed the
+ * fact that rigc's two halves disagreed about which dial was turned reached that
+ * run not at all.
+ *
+ * 🚨 **What the two reaches settle.** The property's name is not what makes this
+ * survey trustworthy — the set of frames it poses is. So both answers are turned
+ * into the span of the animation each can select, and `outside` is the part of
+ * what was posed that the artifact's answer could not have reached. Measured
+ * (issue #427): under a disagreement `driveReach` **always contains**
+ * `statedReach`, because the driven field is the largest response the probe found
+ * and a disagreement needs it to clear the artifact's field by
+ * `DIAL_PROBE_MARGIN`. So the survey never poses fewer frames than the artifact's
+ * answer would have, and `outside` is what the artifact's answer would have
+ * MISSED — never what this one invented.
+ */
+export interface DeformDialDispute {
+  /** The slider whose dial this is. */
+  slider: string;
+  /** Its driving bone. */
+  bone: string;
+  /**
+   * The field the artifact names, rig-spec spelled — or the reader's class name
+   * when it is one this file does not know.
+   */
+  stated: string;
+  /** What one step of the artifact's field moves the reading by. */
+  statedResponse: number | null;
+  /**
+   * The part of the animation's own `0..duration` the artifact's field can
+   * select, or `null` when it can select none of it — and on the one reader
+   * this file cannot name, where there is no field to probe.
+   */
+  statedReach: DialSpan | null;
+  /** The field the survey drives, which is the one that measurably moves the reading. */
+  drive: string;
+  /** What one step of THAT moves the reading by. */
+  driveResponse: number;
+  /** The part of `0..duration` the drive can select, or `null` when it can select none. */
+  driveReach: DialSpan | null;
+  /**
+   * The deform key times this survey posed through `drive` that no settable value
+   * of the artifact's field reaches, in ascending order.
+   *
+   * ⭐ Empty is a **reading**, not an absence: it says both answers pose the same
+   * frames, so the disagreement changed nothing about what was measured. A39
+   * prints `outside:none` for it rather than omitting the field, because a
+   * comparison that was made and came out equal must not look like one nobody
+   * made.
+   */
+  outside: number[];
+}
+
 /** The reach every animation has when no slider applies it. */
 const TRACK_REACH: DeformReach = {
   kind: 'track',
   slider: null,
   bone: null,
   property: null,
+  drive: null,
   local: false,
   label: 'played on a track',
 };
@@ -343,6 +453,17 @@ export interface DeformDial {
    * `local: false`, where the reader goes through the world transform.
    */
   driven: number;
+  /**
+   * The drive the mapping asked for when it was past `DIAL_DRIVE_LIMIT` and the
+   * bone was therefore stopped at the bound instead — `null` on every dial that
+   * stayed inside it, which is every correct rig (issue #419).
+   *
+   * 🚨 The runaway made visible. Before #419 a world scale slider was solved
+   * through `rotation`, whose response to it is float noise, and the drive ran to
+   * 4.9e9 with nothing saying so. Now the ask is carried here, the bone is not
+   * posed there, and the key is reported unreachable naming both numbers.
+   */
+  beyondLimit: number | null;
   /** `SliderPose.time` the runtime then computed, read off the posed skeleton. */
   applied: number;
   /** What `Slider.update` would have stored for this key's own time. */
@@ -351,9 +472,11 @@ export interface DeformDial {
    * `applied` is not `wanted`: **no dial value selects this key's time.**
    *
    * The reachable one, and it is not hypothetical: `FromRotate.value` ends
-   * `if (value < 0) value += 360`, so a `rotate` slider reading a WORLD rotation
-   * cannot be driven below 0° and everything the inversion asks for down there
-   * arrives 360° away (issue #405). `Math.max(0, time)` is the other.
+   * `if (value < 0) value += 360` over an `atan2`, so `[0, 360)` is the whole of
+   * what a `rotate` slider reading a WORLD rotation can be driven to, and
+   * everything the inversion asks for outside it arrives 360° away — below 0°
+   * (issue #405) and at or above 360° (issue #417) alike. `Math.max(0, time)` is
+   * the other.
    *
    * ⚠️ A key like that is measured — at the frame the runtime does land on, which
    * the report names — and then left OUT of the gate's counts, because the
@@ -559,6 +682,17 @@ export interface DeformSurvey {
    * and this is (`DW16`).
    */
   spanProbes: number;
+  /**
+   * Dials whose probe tied and whose artifact broke the tie, in the skeleton's
+   * own constraint order (issue #419). Empty on every rig where it did not.
+   */
+  dialTies: DeformDialTie[];
+  /**
+   * Dials the artifact and the probe name differently, in the same order, each
+   * carrying both answers, both reaches and the frames the artifact's answer
+   * could not have posed (issues #419, #427).
+   */
+  dialDisputes: DeformDialDispute[];
 }
 
 /**
@@ -577,15 +711,33 @@ export function unreachableWhy(key: DeformKeyMeasure): string {
     key.reach.bone === null
       ? `slider "${key.reach.slider}"'s own time`
       : `${key.reach.bone}.${key.reach.property} (${key.reach.local ? 'local' : 'world'})`;
+  // 🚨 The runaway, named with both numbers instead of printed as a dial (issue
+  // #419). This comes first because it is a different fact from the one below: the
+  // bone was never put where the mapping asked, so what the runtime applied is the
+  // clamp's time and says nothing about whether the key is otherwise reachable.
+  if (dial.beyondLimit !== null) {
+    const field = key.reach.drive ?? key.reach.property;
+    return (
+      `the dial for t=${key.time}s is out of bounds: slider "${key.reach.slider}" maps that time back to ` +
+      `${dial.value.toFixed(6)}, which needs ${key.reach.bone}.${field} at ${dial.beyondLimit.toExponential(4)} — ` +
+      `past the ±${DIAL_DRIVE_LIMIT} this solve will drive a bone field to. Past 2^24 a float32 no longer holds ` +
+      'two consecutive integers apart, so a figure up there is not a value anybody can set and read back. The ' +
+      'bone was left at its setup value rather than driven there, so what was posed is the setup frame and not ' +
+      `the one that mapping names — the runtime applied ${dial.applied.toFixed(6)}s against the ` +
+      `${dial.wanted.toFixed(6)}s wanted`
+    );
+  }
   // The one reader that cannot produce a value it is asked for, named where an
   // author will meet it: a WORLD rotation is an `atan2` ending in
   // `if (value < 0) value += 360`, so **[0, 360) is the whole of its range** and
   // `"local": true` is the fix (issue #405).
   //
-  // ⚠️ Both ends, not just the low one. The compiler refuses a range that dips
-  // below 0° — the natural way to author a face yaw, and the case #405 was filed
-  // on — and says nothing about one that runs past 360°, which dies in exactly
-  // the same way. This is the surface that sees it.
+  // ⚠️ Both ends, not just the low one — a range running past 360° dies in
+  // exactly the way one dipping below 0° does. The compiler refuses both since
+  // issue #417 (it refused only the low end when #405 landed), so a rig spec in
+  // this repository cannot ask for either. This clause is still not redundant:
+  // an artifact reaching the gate from the editor, a hand edit or an older rigc
+  // can carry a dead range, and the artifact is what this file reads.
   const wrap =
     key.reach.property === 'rotate' && !key.reach.local && (dial.value < 0 || dial.value >= 360)
       ? '. A world rotation is read through `FromRotate.value`, an `atan2` ending `if (value < 0) value += 360`, ' +
@@ -640,6 +792,8 @@ export function surveyDeformKeys(data: SkeletonData, exempt: ReadonlySet<string>
   let notReachable = 0;
   let notReachableReversed = 0;
   let spansNotScanned = 0;
+  const dialTies: DeformDialTie[] = [];
+  const dialDisputes: DeformDialDispute[] = [];
   const reaches = reachesOf(data);
   for (const anim of data.animations) {
     // One pass per way in (issue #407). The animations nothing applies get the
@@ -648,6 +802,17 @@ export function surveyDeformKeys(data: SkeletonData, exempt: ReadonlySet<string>
       const poseFrame = (time: number): PoseOfFrame =>
         dials === null ? { posed: poseAt(data, anim.name, time), dial: null } : poseDial(data, dials, time);
       const reach = dials === null ? TRACK_REACH : dials.reach;
+      /**
+       * The key times this plan actually **reached**, for the reach comparison
+       * below (#427).
+       *
+       * ⚠️ A key the drive itself could not select is not in here. It is already
+       * named on the stats line as `deformKeysUnreachable`, with the ask and the
+       * bound, and the artifact's answer cannot reach it either — so listing it
+       * as something the artifact's answer missed would count one defect twice
+       * and inflate a disagreement with a frame the disagreement did not cost.
+       */
+      const posedTimes = new Set<number>();
       for (const timeline of anim.timelines) {
         if (!(timeline instanceof DeformTimeline)) continue;
         timelines++;
@@ -695,6 +860,7 @@ export function surveyDeformKeys(data: SkeletonData, exempt: ReadonlySet<string>
             notDrawnReversed += frameMeasure.measure.reversed.length;
           }
           keys.push({ ...named, key: frame, time, ...frameMeasure.measure });
+          if (at.dial?.unreachable !== true) posedTimes.add(time);
           if (previous !== null) {
             // ⚠️ A span whose end is a frame the runtime cannot reach has no
             // interpolation to scan: the anchors it would solve the quadratic
@@ -720,6 +886,56 @@ export function surveyDeformKeys(data: SkeletonData, exempt: ReadonlySet<string>
           previous = frameMeasure;
         }
       }
+      // --- what the artifact's own answer could NOT have posed (issue #427) ---
+      //
+      // ⭐ Posed, not predicted. The survey builds a second plan out of the field
+      // the SKELETON names and runs it through the same `poseDial` every real
+      // frame goes through, so each entry is spine-core saying "no settable value
+      // of this field lands me on that time" rather than this file inferring it
+      // off an interval. Measured (#427): the list is empty whenever the two
+      // answers reach the same span, and empty is the reading that says the
+      // disagreement changed nothing about which frames were measured.
+      //
+      // 🚨 And nothing is reported at all about a dial that posed NOTHING — a
+      // slider whose animation carries no deform timeline. `outside` would be
+      // empty there for the one reason that must never print as agreement:
+      // there were no frames to disagree about. A comparison of nothing and a
+      // comparison that came out equal are the vacuous pass this file exists
+      // to keep apart.
+      if (posedTimes.size === 0) continue;
+      // A plan is visited exactly once — a slider names one animation — so the
+      // two lists need no de-duplication and come out in the skeleton's own
+      // constraint order.
+      if (dials?.tie) dialTies.push(dials.tie);
+      if (dials?.dispute) dialDisputes.push(dials.dispute);
+      if (dials?.dispute && dials.statedMap !== null) {
+        const shadow: DialPlan = {
+          ...dials,
+          field: dials.statedMap.field,
+          u0: dials.statedMap.u0,
+          v0: dials.statedMap.v0,
+          u1: dials.statedMap.u1,
+          v1: dials.statedMap.v1,
+        };
+        // ⚠️ The one time posing cannot answer: a field that moves the reading by
+        // NOTHING has no map to invert, so `poseDial` divides by zero and calls
+        // every time out of bounds — including the setup time, which that field
+        // reaches by being left alone. The reach says which one that is, and it
+        // is a single point. Nothing in spine-core 4.3 has been measured getting
+        // here (a parent at exactly 90° still moves a world x reading by 2.3e-8),
+        // and a report that over-stated a disagreement by one key would be the
+        // false red this file has paid for twice.
+        const flat = dials.statedMap.v1 === dials.statedMap.v0;
+        const only = dials.dispute.statedReach;
+        const outside = [...posedTimes]
+          .filter((time) =>
+            flat
+              ? only === null || Math.abs(time - only.lo) > DIAL_TIME_EPSILON
+              : poseDial(data, shadow, time).dial?.unreachable === true,
+          )
+          .sort((a, b) => a - b);
+        dials.dispute.outside.push(...outside);
+      }
     }
   }
   let spanProbes = 0;
@@ -749,6 +965,8 @@ export function surveyDeformKeys(data: SkeletonData, exempt: ReadonlySet<string>
     spansUnconfirmed,
     spansNotScanned,
     spanProbes,
+    dialTies,
+    dialDisputes,
   };
 }
 
@@ -789,6 +1007,70 @@ function dialStep(field: DialField): number {
   return field === 'scaleX' || field === 'scaleY' ? 0.25 : 1;
 }
 
+/**
+ * Which `BonePose` field spine-core's own reader is named for — off the ARTIFACT,
+ * which is the second, independent answer the probe below is checked against
+ * (issue #419).
+ *
+ * ⭐ This is an identity, not a dispatch table. `SliderData.property` is one of
+ * six classes the parser built out of the rig spec's `property` field, so asking
+ * which class it is asks the file what the author wrote; it says nothing about
+ * *how* the value is computed, which is the part #407 was careful never to
+ * transcribe and which the probe still measures.
+ *
+ * `null` for a reader this file does not know — unreachable against spine-core
+ * 4.3, which has exactly these six, and deliberately not folded into a default:
+ * a seventh reader in some later runtime must be **named** in the report, not
+ * silently mapped to whatever the probe happened to find.
+ */
+function readerField(property: FromProperty): DialField | null {
+  if (property instanceof FromRotate) return 'rotation';
+  if (property instanceof FromX) return 'x';
+  if (property instanceof FromY) return 'y';
+  if (property instanceof FromScaleX) return 'scaleX';
+  if (property instanceof FromScaleY) return 'scaleY';
+  if (property instanceof FromShearY) return 'shearY';
+  return null;
+}
+
+/**
+ * How the artifact's answer and the probe's answer settled (issue #419).
+ *
+ * - `agreed` — one field responds decisively and it is the reader's own. Every
+ *   rig in the gallery and every `local: true` slider.
+ * - `settled` — the probe was **not** decisive (two or more fields within
+ *   `DIAL_PROBE_MARGIN` of each other) and the reader's own field is one of them,
+ *   so the artifact broke the tie. Real: a `FromX` slider under `local: false` on
+ *   a bone whose parent is at 45° is driven exactly equally by local `x` and
+ *   local `y`, and letting list order decide between them would be the same
+ *   silent arbitrariness #419 was filed on.
+ * - `disagreed` — the field that moves the reading is not the reader's own field.
+ *   Also real: the same slider with the parent at 90° is moved by local `y` alone
+ *   and not at all by local `x`. The probe wins the drive, because it is the one
+ *   that measured something, and the disagreement is printed rather than resolved.
+ */
+type DialVerdict = 'agreed' | 'settled' | 'disagreed';
+
+/** The two answers, what they were, and how they settled. */
+interface DialDiscovery {
+  /** The reader's own field, off the artifact. `null` on a reader not known here. */
+  stated: DialField | null;
+  /** What the artifact's reader is called, for a report that has to name it. */
+  reader: string;
+  /** The field the solve drives. Always one the probe measured a response on. */
+  drive: DialField;
+  /** What one step of that field moved the reading by. */
+  driveResponse: number;
+  /**
+   * The other fields inside `DIAL_PROBE_MARGIN` of the winner — the ones that
+   * stopped the probe being decisive. Empty whenever it was.
+   */
+  rivals: Array<{ field: DialField; response: number }>;
+  /** What the reader's OWN field responded, when it is not the one driven. */
+  statedResponse: number | null;
+  verdict: DialVerdict;
+}
+
 /**
  * A slider whose animation is being posed, with everything the inversion needs
  * measured off the runtime rather than assumed.
@@ -796,6 +1078,13 @@ function dialStep(field: DialField): number {
 interface DialPlan {
   slider: SliderData;
   reach: DeformReach;
+  /**
+   * The probe's tie, when it had one — the survey collects these so a `build`
+   * sees them and not only `explain` (issues #419, #427).
+   */
+  tie: DeformDialTie | null;
+  /** The two answers and their two reaches, when they named different fields. */
+  dispute: DeformDialDispute | null;
   /**
    * The bone field that drives it, or `null` on a bone-less slider — whose time
    * IS its pose value and is set directly.
@@ -806,6 +1095,30 @@ interface DialPlan {
   v0: number;
   u1: number;
   v1: number;
+  /**
+   * The ARTIFACT's own field as a map of its own, kept only on a disputed dial
+   * (issue #427).
+   *
+   * ⭐ It is what lets `DeformDialDispute.outside` be **posed** rather than
+   * predicted: the survey builds a second plan out of it and runs the same
+   * `poseDial` the real frames go through, so "no settable value of `knob.x`
+   * reaches t=0.5s" is a measurement taken against spine-core and not an
+   * inference off an interval.
+   */
+  statedMap: DialProbe | null;
+}
+
+/**
+ * One field's probe: how far one step of it moved the reading, and the two points
+ * of the affine map that step traced.
+ */
+interface DialProbe {
+  field: DialField;
+  response: number;
+  u0: number;
+  v0: number;
+  u1: number;
+  v1: number;
 }
 
 /**
@@ -823,6 +1136,51 @@ const DIAL_TIME_EPSILON = 1e-6;
 /** How many secant steps the solve takes before it calls a time unreachable. */
 const DIAL_SOLVE_STEPS = 4;
 
+/**
+ * How far the largest probe response has to clear the runner-up before the probe
+ * alone is allowed to name the field the solve drives (issue #419).
+ *
+ * ⭐ **A ratio, so it carries no units and no fixture's scale.** What it separates
+ * was measured rather than assumed, on this file's own probe:
+ *
+ * | reading | field | response to one step | ratio to the winner |
+ * | --- | --- | --- | --- |
+ * | `FromScaleX`, world, plain parent | `scaleX` | 2.5e-1 | — |
+ * | | `rotation` | 4.0e-10 (float noise in `sqrt(a²+c²)`) | 6.2e8 |
+ * | `FromX`, world, parent at 90° | `y` | 1.0 | — |
+ * | | `x` | 4.6e-8 (float noise) | 2.2e7 |
+ * | `FromScaleX`, world, parent scaled 2×1 | `scaleX` | 5.0e-1 | — |
+ * | | `rotation` | 2.3e-4 (**real**, not noise) | 2.2e3 |
+ * | `FromX`, world, parent at 45° | `x` | 7.07e-1 | — |
+ * | | `y` | 7.07e-1 (**real**, and exactly equal) | 1.0 |
+ *
+ * So 1e3 sits between the smallest genuine secondary dependency measured (2.2e3)
+ * and the largest float-noise ratio (2.2e7), with four orders of headroom on the
+ * side that matters. ⚠️ It is not a noise threshold and must not be read as one:
+ * a rig with a heavier parent scale pushes that 2.2e3 down through it, and what
+ * happens then is not a wrong answer but an *ambiguous* one — which this file
+ * reports and the artifact settles, below.
+ */
+const DIAL_PROBE_MARGIN = 1e3;
+
+/**
+ * The largest magnitude the solve will drive a bone field to (issue #419).
+ *
+ * 🚨 **This is the bound that replaces "gave up at 4.9e9".** A dial figure is an
+ * instruction — *set `knob.scaleX` to this* — and past 2²⁴ a float32 cannot hold
+ * two consecutive integers apart, so a number up there is not one an author can
+ * set and read back; the emitted skeleton, which rounds to six decimals, has lost
+ * the precision long before. A drive the mapping asks for beyond this is
+ * therefore **not posed**: the bone stops at the bound, the runtime lands on some
+ * other time, and the key is reported unreachable with the ask and the bound both
+ * named — never printed as if it were advice.
+ *
+ * The runaway #419 was filed on reached 1.2e9, 2.5e9 and 4.9e9, all two orders
+ * above this, and every dial `gallery/look` and the DW fixtures ask for is under
+ * 200.
+ */
+const DIAL_DRIVE_LIMIT = 2 ** 24;
+
 /**
  * Every way each animation is reached, keyed by animation name.
  *
@@ -867,46 +1225,212 @@ function sliderOn(skeleton: Skeleton, data: SliderData): Slider | null {
  * Find which local field of the driving bone moves a slider's time, and read the
  * affine map from that field to the property value off two probes.
  *
- * ⭐ **Probed rather than tabulated.** Which `BonePose` field a `FromProperty`
- * reads is spine-core's business, and under `local: false` the reader goes
- * through the world transform — so a table here would be a second copy of the
- * runtime's dispatch AND a claim about parents this file has no business making.
- * Two calls to `data.property.value` — the same call `Slider.update` makes, with
- * the same all-zero offsets — say it instead, and every one of the six readers is
- * affine in its own field at a fixed parent pose, so two points are the whole map.
+ * ⭐ **Probed rather than tabulated.** How a `FromProperty` turns a bone into a
+ * number is spine-core's business, and under `local: false` it goes through the
+ * world transform — so a table of that here would be a second copy of the
+ * runtime's arithmetic AND a claim about parents this file has no business
+ * making. Calls to `data.property.value` — the same call `Slider.update` makes,
+ * with the same all-zero offsets — say it instead, and every one of the six
+ * readers is affine in its own field at a fixed parent pose, so two points of the
+ * winner are the whole map.
+ *
+ * 🚨 **What the probe is NOT allowed to do is stop at the first field that
+ * moves** (issue #419). A world scale is read as `sqrt(a² + c²)`; perturbing
+ * `rotation` changes `a` and `c` by amounts that do not cancel in floating point,
+ * `rotation` is probed first, and every world `scaleX` / `scaleY` / `shearY`
+ * slider was therefore reported as `rotate` — and then solved through a field
+ * whose response to it is 4e-10, which is how a drive reached 4.9e9. So:
+ *
+ *  1. **every** field is probed and they are ranked by response;
+ *  2. the winner has to clear the runner-up by `DIAL_PROBE_MARGIN` to be called
+ *     decisive — a tie is a real thing (a `FromX` slider on a bone whose parent
+ *     is at 45° is moved exactly equally by local `x` and local `y`) and letting
+ *     `DIAL_FIELDS`'s order settle it silently is the same defect one step over;
+ *  3. and the answer is cross-checked against the **artifact** — spine-core's own
+ *     reader class, which is what the parser built out of the rig spec's
+ *     `property`. That is what the report names, it settles a tie the probe could
+ *     not, and where the two genuinely differ the report says so by name.
+ *
+ * ⛔ Nothing here falls back to `rotation`, or to any field, when the search does
+ * not settle. Two answers that disagree are two answers, printed.
  */
 function planDial(data: SkeletonData, slider: SliderData): DialPlan | null {
-  const reach = (field: DialField | null): DeformReach => ({
-    kind: 'slider',
-    slider: slider.name,
-    bone: slider.bone?.name ?? null,
-    property: field === null ? null : DIAL_PROPERTY[field],
-    local: slider.local,
-    label:
-      field === null
-        ? `applied by slider "${slider.name}" at its own time`
-        : `applied by slider "${slider.name}" off ${slider.bone?.name ?? '?'}.${DIAL_PROPERTY[field]}` +
-          `${slider.local ? ' (local)' : ' (world)'}`,
-  });
+  const boneName = slider.bone?.name ?? '?';
+  const where = slider.local ? ' (local)' : ' (world)';
+  const reach = (discovery: DialDiscovery | null): DeformReach => {
+    if (discovery === null) {
+      return {
+        kind: 'slider',
+        slider: slider.name,
+        bone: slider.bone?.name ?? null,
+        property: null,
+        drive: null,
+        local: slider.local,
+        label: `applied by slider "${slider.name}" at its own time`,
+      };
+    }
+    // The name comes off the artifact whenever the artifact has one. A reader
+    // this file does not know is named by its class rather than by a guess.
+    const property = discovery.stated === null ? discovery.reader : DIAL_PROPERTY[discovery.stated];
+    const drive = discovery.stated === discovery.drive ? null : DIAL_PROPERTY[discovery.drive];
+    return {
+      kind: 'slider',
+      slider: slider.name,
+      bone: slider.bone?.name ?? null,
+      property,
+      drive,
+      local: slider.local,
+      label:
+        `applied by slider "${slider.name}" off ${boneName}.${property}${where}` +
+        dialDiscoveryClause(discovery, boneName),
+    };
+  };
   // The bone-less form: `Slider.update` leaves `p.time` alone, so the dial IS the
   // pose value and the map is the identity.
-  if (slider.bone === null) return { slider, reach: reach(null), field: null, u0: 0, v0: 0, u1: 1, v1: 1 };
+  if (slider.bone === null) {
+    return { slider, reach: reach(null), tie: null, dispute: null, field: null, u0: 0, v0: 0, u1: 1, v1: 1, statedMap: null };
+  }
   const skeleton = new Skeleton(data);
   const instance = sliderOn(skeleton, slider);
   const bone = instance?.bone ?? null;
   if (instance === null || bone === null) return null;
+  // ⚠️ Every field is kept, the dead ones included, because the ARTIFACT may name
+  // one of them: a reach comparison needs the map of the field the skeleton
+  // declares even when that field moves the reading by nothing at all (#427).
+  const all: DialProbe[] = [];
   for (const field of DIAL_FIELDS) {
     const step = dialStep(field);
     skeleton.setupPose();
     const base = bone.pose[field];
     const v0 = dialValue(skeleton, slider, bone, field, base);
     const v1 = dialValue(skeleton, slider, bone, field, base + step);
-    if (v1 === v0) continue;
-    return { slider, reach: reach(field), field, u0: base, v0, u1: base + step, v1 };
+    all.push({ field, response: Math.abs(v1 - v0), u0: base, v0, u1: base + step, v1 });
   }
+  const probes = all.filter((p) => Number.isFinite(p.response) && p.response !== 0);
   // Nothing moves it: a bone another constraint pins, or a reader that cannot see
   // this bone at all. A37 owns the `scale: 0` shape of the same silence.
-  return null;
+  if (probes.length === 0) return null;
+  // ⚠️ A stable sort on a strict comparison, so an exact tie keeps `DIAL_FIELDS`'s
+  // order and the tie is DETECTED below rather than decided here. A comparator
+  // that broke ties would put the arbitrary choice back where nothing sees it.
+  probes.sort((a, b) => b.response - a.response);
+  const winner = probes[0];
+  const stated = readerField(slider.property);
+  const leaders = probes.filter((p) => p.response * DIAL_PROBE_MARGIN >= winner.response);
+  const decisive = leaders.length === 1;
+  const chosen = decisive || stated === null ? winner : (leaders.find((p) => p.field === stated) ?? winner);
+  const verdict: DialVerdict = chosen.field === stated ? (decisive ? 'agreed' : 'settled') : 'disagreed';
+  const discovery: DialDiscovery = {
+    stated,
+    reader: slider.property.constructor.name,
+    drive: chosen.field,
+    driveResponse: chosen.response,
+    rivals: leaders.filter((p) => p.field !== chosen.field).map((p) => ({ field: p.field, response: p.response })),
+    statedResponse:
+      stated === null || stated === chosen.field ? null : (all.find((p) => p.field === stated)?.response ?? 0),
+    verdict,
+  };
+  // 🔒 A tie and a disagreement are built as two different things, because they
+  // ARE two different things: a tie has one belief the artifact broke, and a
+  // disagreement has two that have to be compared. Folding them into one record
+  // with a `verdict` field is how a report comes to say "disagreed" about
+  // legitimate geometry (issues #419, #427).
+  const statedMap = stated === null ? null : (all.find((p) => p.field === stated) ?? null);
+  const tie: DeformDialTie | null =
+    verdict !== 'settled'
+      ? null
+      : {
+          slider: slider.name,
+          bone: boneName,
+          drive: DIAL_PROPERTY[chosen.field],
+          driveResponse: chosen.response,
+          rivals: discovery.rivals.map((r) => ({ field: DIAL_PROPERTY[r.field], response: r.response })),
+        };
+  const dispute: DeformDialDispute | null =
+    verdict !== 'disagreed'
+      ? null
+      : {
+          slider: slider.name,
+          bone: boneName,
+          stated: stated === null ? discovery.reader : DIAL_PROPERTY[stated],
+          statedResponse: discovery.statedResponse,
+          statedReach: statedMap === null ? null : dialReachOf(slider, statedMap),
+          drive: DIAL_PROPERTY[chosen.field],
+          driveResponse: chosen.response,
+          driveReach: dialReachOf(slider, chosen),
+          outside: [],
+        };
+  return {
+    slider,
+    reach: reach(discovery),
+    tie,
+    dispute,
+    field: chosen.field,
+    u0: chosen.u0,
+    v0: chosen.v0,
+    u1: chosen.u1,
+    v1: chosen.v1,
+    statedMap: dispute === null ? null : statedMap,
+  };
+}
+
+/**
+ * The part of an animation's own `0..duration` one field of the driving bone can
+ * select, or `null` when it can select none of it (issue #427).
+ *
+ * ⭐ **Closed form, and exact against the thing that decides.** `poseDial` refuses
+ * outright a drive whose magnitude exceeds `DIAL_DRIVE_LIMIT`, and the two maps
+ * between a field and a time are both affine — the probe's `field -> value`, and
+ * `Slider.update`'s own `value -> time` inverted. So the times a *settable* value
+ * of this field asks for are an interval, and its two ends are `±DIAL_DRIVE_LIMIT`
+ * put through both. A field that moves the reading by nothing gives a single
+ * point, which is the honest answer for it: the setup time and no other.
+ *
+ * ⚠️ It is a statement about what can be **asked for**, not about what the runtime
+ * then does with it — `FromRotate`'s `[0, 360)` wrap can refuse a time this
+ * interval contains. That is why the frames a disputed dial could not have posed
+ * are POSED rather than read off here.
+ */
+function dialReachOf(slider: SliderData, map: DialProbe): DialSpan | null {
+  const timeAt = (u: number): number => {
+    const value = map.v0 + ((u - map.u0) * (map.v1 - map.v0)) / (map.u1 - map.u0);
+    return slider.offset + (value - slider.property.offset) * slider.scale;
+  };
+  const ends = [timeAt(-DIAL_DRIVE_LIMIT), timeAt(DIAL_DRIVE_LIMIT)];
+  if (!ends.every((t) => Number.isFinite(t))) return null;
+  const lo = Math.max(0, Math.min(ends[0], ends[1]));
+  const hi = Math.min(slider.animation.duration, Math.max(ends[0], ends[1]));
+  return lo <= hi ? { lo, hi } : null;
+}
+
+/**
+ * The clause the frame line carries when the two answers did not simply agree —
+ * empty on every rig where they did, which is every one in the gallery.
+ *
+ * ⭐ It names both answers and both responses, because "the probe and the file
+ * disagree" without the numbers is a sentence an author cannot act on.
+ */
+function dialDiscoveryClause(discovery: DialDiscovery, bone: string): string {
+  if (discovery.verdict === 'agreed') return '';
+  const drive = `${bone}.${DIAL_PROPERTY[discovery.drive]} ${discovery.driveResponse.toExponential(3)}`;
+  if (discovery.verdict === 'settled') {
+    const rivals = discovery.rivals
+      .map((r) => `${bone}.${DIAL_PROPERTY[r.field]} ${r.response.toExponential(3)}`)
+      .join(', ');
+    return (
+      `, driven through ${bone}.${DIAL_PROPERTY[discovery.drive]} — the probe did not settle that on its own ` +
+      `(${drive} against ${rivals}, inside the ${DIAL_PROBE_MARGIN}x margin), so the skeleton's own reader broke ` +
+      'the tie'
+    );
+  }
+  const statedName = discovery.stated === null ? discovery.reader : `${bone}.${DIAL_PROPERTY[discovery.stated]}`;
+  const statedAt =
+    discovery.statedResponse === null ? 'which this file does not know' : `which moves it by ${discovery.statedResponse.toExponential(3)}`;
+  return (
+    `, driven through ${bone}.${DIAL_PROPERTY[discovery.drive]} — the probe moves the reading by ${drive} while ` +
+    `the skeleton says the reader is ${statedName}, ${statedAt}. The two disagree and both are reported: the ` +
+    'drive is the one that measurably moves the reading'
+  );
 }
 
 /**
@@ -996,7 +1520,24 @@ function poseDial(data: SkeletonData, plan: DialPlan, time: number): PoseOfFrame
     };
   };
   /** The affine first guess, and what it is judged against. */
-  const first = plan.u0 + ((value - plan.v0) * (plan.u1 - plan.u0)) / (plan.v1 - plan.v0);
+  const asked = plan.u0 + ((value - plan.v0) * (plan.u1 - plan.u0)) / (plan.v1 - plan.v0);
+  // 🚨 The bound, and it is on the drive the answer is READ off, not on the
+  // arithmetic that got there (issue #419). Two different things wanted bounding
+  // and they want it differently:
+  //
+  //  - **the mapping's own ask.** A map measured through a field the reading
+  //    barely moves inverts to nonsense — this is #419's own case, where a world
+  //    scale solved through `rotation` asked for 4.9e9 — and that is the frame
+  //    the report would print as advice. Out of bounds, it is not posed at all:
+  //    the bone stays at the setup value of its field, the key is unreachable,
+  //    and `unreachableWhy` names the ask and the bound.
+  //  - **a secant step.** The loop below is a search and a search may step
+  //    anywhere; a step out of bounds is a step this stops taking, not a verdict.
+  //    `FromRotate`'s wrap sends one there routinely on a rig whose real defect is
+  //    the wrap, and reporting the bound instead of the wrap would swap a
+  //    diagnosis for a symptom.
+  const runaway = !Number.isFinite(asked) || Math.abs(asked) > DIAL_DRIVE_LIMIT;
+  const first = runaway ? plan.u0 : asked;
   const near = 1e-9 * (1 + Math.abs(value));
   let u = first;
   let got = at(u);
@@ -1008,11 +1549,11 @@ function poseDial(data: SkeletonData, plan: DialPlan, time: number): PoseOfFrame
   // on and a wandered secant point is not.
   let pu = first === plan.u0 ? plan.u1 : plan.u0;
   let pv = Number.NaN;
-  for (let step = 0; step < DIAL_SOLVE_STEPS && Math.abs(got.read - value) > near; step++) {
+  for (let step = 0; !runaway && step < DIAL_SOLVE_STEPS && Math.abs(got.read - value) > near; step++) {
     if (!Number.isFinite(pv)) pv = at(pu).read;
     if (pv === got.read || !Number.isFinite(pv) || !Number.isFinite(got.read)) break;
     const next = u + ((value - got.read) * (u - pu)) / (got.read - pv);
-    if (!Number.isFinite(next)) break;
+    if (!Number.isFinite(next) || Math.abs(next) > DIAL_DRIVE_LIMIT) break;
     pu = u;
     pv = got.read;
     u = next;
@@ -1027,9 +1568,13 @@ function poseDial(data: SkeletonData, plan: DialPlan, time: number): PoseOfFrame
     dial: {
       value,
       driven: u,
+      beyondLimit: runaway ? asked : null,
       applied: got.applied,
       wanted,
-      unreachable: !(Math.abs(got.applied - wanted) <= DIAL_TIME_EPSILON),
+      // ⚠️ A drive the bound refused is unreachable WHATEVER the runtime then
+      // landed on. Nothing was posed where the mapping asked, so a time that
+      // happens to match is a coincidence of the setup pose and not a measurement.
+      unreachable: runaway || !(Math.abs(got.applied - wanted) <= DIAL_TIME_EPSILON),
     },
   };
 }