spine-rigc 0.18.0 → 0.18.1

package/cli.ts

@@ -768,9 +768,12 @@ function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>):
         (key.dial === null
           ? ''
           : `, dial ${key.dial.value.toFixed(6)}` +
+            // ⚠️ `reach.drive` names the field when it is NOT the one `property`
+            // names, which happens under `local: false` on a rotated parent — a
+            // bare figure there would read as a value of the wrong field (#419).
             (key.reach.local || key.dial.driven === key.dial.value
               ? ''
-              : ` (bone local ${key.dial.driven.toFixed(6)})`) +
+              : ` (bone local ${key.reach.drive === null ? '' : `${key.reach.drive} `}${key.dial.driven.toFixed(6)})`) +
             ` -> t=${key.dial.applied.toFixed(6)}`),
     );
     // A key at a time no dial selects: the figures below are the frame the

package/docs/AUTHORING.md

@@ -1406,27 +1406,53 @@ sharing one of those overwrite each other whatever you write. A40 names that cas
 separately, because the fix is different: key such a property from one slider
 only, or move both edits into the single animation one slider applies.
 
-🚨 **A `rotate`-driven slider with `local: false` cannot cross 0°.** `local: false`
-reads the bone's **world** rotation through `FromRotate.value`, which ends
-`if (value < 0) value += 360`. A yaw axis authored the natural way — neutral at 0°,
-range −15°..+15° — therefore never sees a negative value: the bone at −15° arrives
-as 345°, and `time = to + (value − from) * scale` lands far past the animation.
-[measured] with `from: 0, to: 0.5, scale: 0.033333` over a 1 s animation the dial
-at −15° applies time **12.000 s**, so with `loop: false` the entire negative half
-of the axis holds the last frame — 15° of face jumping between −0.001° and 0°, with
-nothing anywhere reporting it. The same rig with `"local": true` ramps
-0 s → 0.5 s → 1 s as written.
-
-⇒ **`local: true` is the form a face axis wants.** It reads `source.rotation`
-signed and unwrapped, which for a dial bone is the number you authored. rigc
-refuses the crossing case at compile, with that arithmetic in the message; the
-alternative it leaves open is to move the range so it does not cross 0° (a neutral
-at 180°, say), which is the only form `local: false` can express.
-
-⚠️ **The refusal is on the LOW end only.** `[0, 360)` is the whole of what
-`FromRotate.value` returns, so a range running past **360°** is dead in the same
-way and compiles clean. Nothing refuses that at compile; `A39` reports it from the
-artifact side as a key at a time no dial selects (§4.11.4).
+🚨 **A `rotate`-driven slider with `local: false` has to stay inside the circle
+`[0, 360]`.** `local: false` reads the bone's **world** rotation through
+`FromRotate.value`, which is a `Math.atan2` — so `(−180, 180]` — with
+`if (value < 0) value += 360` on the end, and the `offsets` a slider hands it are
+all zero. `[0, 360)` is therefore the whole set of values that reader can ever
+return, and a range leaving it on either side is a wall:
+
+- **Below 0°.** A yaw axis authored the natural way — neutral at 0°, range
+  −15°..+15° — never sees a negative value: the bone at −15° arrives as 345°, and
+  `time = to + (value − from) * scale` lands far past the animation. [measured]
+  with `from: 0, to: 0.5, scale: 0.033333` over a 1 s animation the dial at −15°
+  applies time **12.000 s**, so with `loop: false` the entire negative half of the
+  axis holds the last frame — 15° of face jumping between −0.001° and 0°.
+- **Past 360°.** There is nothing above 360 to wrap *from*, so the value arrives
+  360 **lower** instead. [measured] with `from: 300, to: 0, scale: 0.005` over a
+  1 s animation the range is 300°..500°; the bone turned to 500° has a world
+  rotation of 140°, is read as 140°, and applies time **−0.800 s** —
+  `Math.max(0, time)` under `loop: false`. Swept through spine-core, that rig
+  reaches only **0.000 s..0.2995 s of its own 1 s animation**: the top 140° of the
+  dial does not merely fail to arrive, it arrives somewhere else.
+
+Both are refused at compile, each with its own arithmetic in the message and its
+own repair — *"move the range so it does not cross 0°"* and *"move the range so it
+does not run past 360°"*.
+
+⭐ **A range ending exactly on 360° is legal**, and that is the whole turn: a
+wheel, a turntable, a head that goes all the way round, written `from: 0` with a
+`scale` that puts 360° on the last frame. It misses exactly one value — its own
+supremum — and that value is not a dial position: a bone at 360° *is* a bone at
+0°, and [measured] it poses the skeleton to within **4e-7°** of it, an `atan2`
+artefact rather than a frame. Swept at 0.1° over the circle, `from: 0,
+scale: 0.0025` on a 0.9 s animation lands every reading within **1.7e-8 s** of the
+time the mapping asks for; on `loop: true` the endpoint is not even distinct,
+closing on **0.900000 s** exactly. Use `loop: true` for a dial that really does go
+round, so the seam at 0°/360° is the wrap it is meant to be.
+
+⇒ **`local: true` is the form a face axis wants**, and it is the first repair both
+messages name. It reads `source.rotation` signed and unwrapped, which for a dial
+bone is the number you authored — 500° included — because `FromRotate`'s wrap is
+not on that path at all. The alternative each refusal leaves open is to move the
+range inside the circle (a neutral at 180°, say), which is the only form
+`local: false` can express.
+
+⚠️ **An artifact can still carry a dead range** — one exported from the editor,
+hand-edited, or built by an older rigc. `A39` reports that from the artifact side
+as a key at a time no dial selects (§4.11.4); the compile refusal above is what
+stops a rig spec in this repository from producing one.
 
 📌 **A slider's animation is measured in the slider's own frame** — `A39` inverts
 the mapping above and drives the bone to the value it names, rather than playing
@@ -2519,7 +2545,7 @@ deform  (what each key does to the geometry — figures with names, never a bar;
 | Row | What it is |
 | --- | --- |
 | the `DEFORM` line | `animation`, the `skin/slot/attachment` triple the timeline is keyed on, the key's index — **the same index `A39`'s message names** — its time, and its model: the `transform` kind and parameters the spec stated (§4.11.1), or `authored table` |
-| `frame` | how the animation was reached, which is the pose everything below was measured in: `played on a track`, or the slider that applies it with the dial value its mapping inverts this time to (§4.11.4). On a key at a time no dial selects, an `unreachable` line follows it and the figures below belong to the frame the runtime landed on instead |
+| `frame` | how the animation was reached, which is the pose everything below was measured in: `played on a track`, or the slider that applies it, the property that slider reads off its bone **as the emitted skeleton names it**, and the dial value its mapping inverts this time to (§4.11.4). Under `local: false` a further clause appears when the field that measurably moves the reading is not the one the skeleton names, or when two fields move it equally — reported, never resolved out of sight. On a key at a time no dial selects, an `unreachable` line follows it and the figures below belong to the frame the runtime landed on instead |
 | `moved` | how many vertices this key moves at all, and the largest **world** displacement with the vertex carrying it. Not the same number as §4.11.1's `largest offset`: that one is the offset the spec stated, this one is where the vertex ended up after the bones |
 | `area` | signed area **after ÷ before**, its smallest and largest over the triangles, each with the triangle. `x0.637` is a band compressed to 64%; **a negative ratio is a triangle turned inside out** |
 | `stretch` | the two singular values of the map from the cleared triangle to the deformed one — the worst stretch and the worst squash the **drawing** takes. `σ₁·σ₂ = \|area ratio\|`, so the two rows are two readings of one map and cannot disagree |
@@ -2715,12 +2741,13 @@ dial and not reached at all through another.
   [#405](https://github.com/firejune/rigc/issues/405)'s wrap: `FromRotate.value`
   under `local: false` is an `atan2` ending `if (value < 0) value += 360`, so
   **`[0, 360)` is the whole of its range** and a mapping needing anything outside
-  it selects nothing. 🚨 The compiler refuses a range that dips **below** 0°
-  (§3.5.2) and says nothing about one running **past 360°** — `from: 300` with
-  `scale: 0.005` over a 1 s animation needs 300°..500° and compiles clean — so
-  this is the surface that sees the second half. `A39` measures the frame the
-  runtime *does* land on, leaves the key out of `deformKeysMeasured`, and names
-  it:
+  it selects nothing. 🚨 A **rig spec** can no longer ask for one — the compiler
+  refuses both ends of that circle (§3.5.2), the low one since #405 and the high
+  one since [#417](https://github.com/firejune/rigc/issues/417) — but an
+  **artifact** can, because it may have come from the editor, from a hand edit or
+  from an older rigc, and this is the surface that reads what actually shipped.
+  `A39` measures the frame the runtime *does* land on, leaves the key out of
+  `deformKeysMeasured`, and names it:
 
 ```
 deformKeysUnreachable=2 deformUnreachable=turn/head/head#0@10.800000,turn/head/head#1@11.300000
@@ -2730,6 +2757,47 @@ deformSpansNotScanned=2
   — the `@` is the time the runtime lands on instead — with the `DEFORM` block
   giving the whole sentence and the spans those keys bound left unscanned rather
   than scanned over two poses of some other time.
+- 🚨 **A dial past `±16777216` is named, not printed.** The drive is a number you
+  are meant to act on — *set `knob.scaleX` to this* — and past 2²⁴ a float32 no
+  longer separates consecutive integers, so a figure up there is not one anybody
+  can set and read back. `A39` leaves the bone at its setup value instead, counts
+  the key as unreachable, and says so with both numbers:
+
+```
+unreachable A39 gates nothing here: the dial for t=1s is out of bounds: slider "dial" maps
+that time back to 17000000.000000, which needs knob.rotate at 1.7000e+7 — past the ±16777216
+this solve will drive a bone field to. …
+```
+
+  The usual cause is a `from` or a `scale` that puts the animation's own range out
+  of reach; check the two against `value = from + (time − to) / scale` above.
+
+#### Which property the `frame` line names
+
+The name on the `frame` line — `off yaw_dial.rotate (local)` — is read off the
+**emitted skeleton**: it is whichever `FromProperty` the parser built out of your
+`property` field, so it is the word you wrote. rigc *also* probes all six local
+fields of the driving bone to find which one moves the reading, because under
+`local: false` the reader goes through the world transform and only a measurement
+can say what drives it there. **The two answers must agree, and when they do not
+the line says so rather than picking one silently.**
+
+- Under `local: true` they always agree and the line carries nothing extra.
+- Under `local: false` they can legitimately differ, because the reading is a
+  *world* one. A bone whose parent is turned 90° has a world x that its own local
+  `x` does not move at all and its local `y` moves entirely, so the line reads
+  `off knob.x (world), driven through knob.y — the probe moves the reading by
+  knob.y 1.000e+0 while the skeleton says the reader is knob.x, which moves it by
+  2.321e-8. The two disagree and both are reported…`, and the `bone local` figure
+  beside the dial names its field (`bone local y 398.999991`).
+- At 45° the two fields move it *equally*, which no ranking can separate; the line
+  says the probe did not settle it and that the skeleton's own reader broke the
+  tie. ⛔ Neither case is a refusal and neither is guessed past — an ambiguous
+  discovery is a thing to report.
+
+None of this needs anything from you unless a `frame` line carries one of those
+clauses. If one does, it is telling you the dial bone's parent transform is doing
+something you may not have intended.
 
 ⚠️ **What the artifact cannot say, and rigc therefore does not:** whether a
 slider's animation is *also* played on a track somewhere. Nothing in skeleton data
@@ -2905,7 +2973,8 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `rig constraint "X": applies animation "Y", which the motion spec does not declare (it declares: …)` | §3.5.2 — fix the slider's `animation`, or add it to the motion spec |
 | `rig constraint "X": declares both a "bone" and "time"` | §3.5.2 — `bone` picks the model and `time` belongs to the other one |
 | `rig constraint "X": declares "property" but no "bone"` | §3.5.2 — name the driving bone, or key `slider.<name>.time` instead |
-| `rig constraint "X": drives off bone "Y" rotate with "local": false, and the driving values that reach animation "A" (0s..Ds) run from −15.000° to 15.000° …` | §3.5.2 — add `"local": true`, which reads the bone's own rotation signed and unwrapped, or move the range so it does not cross 0°. A world rotation is wrapped into `[0, 360)` before the slider maps it, so the negative half of the range is unreachable and pins to one frame |
+| `rig constraint "X": drives off bone "Y" rotate with "local": false, and the driving values that reach animation "A" (0s..Ds) run from −15.000° to 15.000° … the whole part of the range below 0° is dead` | §3.5.2 — add `"local": true`, which reads the bone's own rotation signed and unwrapped, or move the range so it does not cross 0°. A world rotation is wrapped into `[0, 360)` before the slider maps it, so the negative half of the range is unreachable and pins to one frame |
+| `… run from 300.000° to 500.000° … the whole part of the range past 360° is dead` | §3.5.2 — the same wall at the other end, and the same first repair: `"local": true`, or move the range so it does not run past 360°. `[0, 360)` is the whole of what that reader returns, so a bone turned to 500° is read as 140° and selects a time far from the one the range asked for. Ending *exactly* on 360° is fine — that is the full turn, and the only value it misses is a supremum no dial can be parked at separately |
 | `skin "S" activates bone "B", but that bone does not declare \`"skin": true\`` | §3.4.1 — the list and the flag are one switch; add the flag or drop the list |
 | `bone "B" declares \`"skin": true\` but no skin activates it` | §3.4.1 — the other half: list it in the skin it belongs to, or drop the flag |
 | `skin "S": uses the long form … and also has a key "X"` | §3.4.1 — move the slot inside `attachments` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {

package/src/compile.ts

@@ -3265,6 +3265,21 @@ type RigConstraintInput = { name: string; type: string } & Record<string, unknow
 /** The six property names a transform constraint may map between (`:241`, `:521`). */
 const TRANSFORM_PROPERTIES = ['rotate', 'x', 'y', 'scaleX', 'scaleY', 'shearY'];
 
+/**
+ * How far past a boundary an end of a `rotate` slider's driving range may sit
+ * before the refusal below fires, in degrees.
+ *
+ * ⭐ **Outward at both ends**, which is the whole reason it is named: 0° and 360°
+ * are the two values an author of a face axis or a full-circle dial actually aims
+ * at, and `from − to / scale` is three authored numbers and a division, so an
+ * intended 0° can arrive as `-1e-13` and an intended 360° as `360.0000000001`.
+ * The slack exists so arithmetic noise around either aim is not a refusal.
+ *
+ * Nothing is tuned. The failure it separates from is gross: a wrapped reading
+ * moves the applied time by `360 · scale`.
+ */
+const SLIDER_WRAP_SLACK = 1e-6;
+
 /** What a constraint's names resolve against. */
 interface ConstraintContext {
   boneNames: Set<string>;
@@ -3467,11 +3482,14 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
       //   let value = Math.atan2(source.c / sy, source.a / sx) * radDeg + …;
       //   if (value < 0) value += 360;
       //
-      // so a driving value below 0° is one the runtime never produces: it arrives
-      // as `value + 360` instead, and `time = to + (value - from) * scale` then
-      // lands far outside the animation. A yaw axis with its neutral at 0° — the
-      // natural way to author a face — therefore has its entire negative half
-      // pinned to one frame, and nothing anywhere says so (issue #402).
+      // `Math.atan2` returns `(-180, 180]` and the `offsets` a slider hands that
+      // reader are `Slider.offsets`, a private all-zero array — so **`[0, 360)`
+      // is the whole of what it can ever produce**. A driving value outside that
+      // is one the runtime never returns: it arrives 360° away, and
+      // `time = to + (value - from) * scale` then lands far outside the
+      // animation. A yaw axis with its neutral at 0° — the natural way to author
+      // a face — therefore has its entire negative half pinned to one frame, and
+      // nothing anywhere says so (issue #402).
       //
       // ⭐ Refused here rather than documented, and rather than left to the gate,
       // for three reasons. The failure is invisible AND total, so a note in a
@@ -3483,10 +3501,35 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
       // has in front of it: the range of driving values that can reach a frame is
       // exactly `[to, to + duration]` mapped back through `scale`.
       //
+      // ⚠️ **Both ends, out of one piece of arithmetic** (issue #417). As #405
+      // landed it, `highest` was computed and never tested, so a range running
+      // PAST 360° — `"from": 300, "scale": 0.005` over a 1 s animation asks for
+      // 300°..500° — compiled clean with everything above 360° just as dead: turn
+      // the bone to 500° and its world rotation is 140°, read as 140°, mapped to
+      // a time nowhere near the one the author meant. A copy-pasted second branch
+      // with a sign edited is how such a pair drifts apart, so the two ends share
+      // `dead` below and every number in the message comes off it.
+      //
+      // ⭐ **And the line is PAST 360°, not at it** — measured before it was
+      // written, because the two are one degree of arc apart and only one of them
+      // costs an author anything. A range ending exactly on 360° misses exactly
+      // one value, its own supremum, and that value is not a dial position: a
+      // bone at 360° IS a bone at 0°, reads within 5.3e-6° of it and poses the
+      // skeleton identically. Swept through spine-core over 0°..360° at 0.1°, a
+      // `from: 0, scale: 0.0025` dial on a 0.9 s animation lands every reading
+      // within **1.7e-8 s** of the time the mapping asks for, and on `loop: true`
+      // the endpoint is not even distinct — the circle closes on 0.900000 s
+      // exactly. Above 360° the dead set has width instead: 300°..500° reaches
+      // only 0.000 s..0.2995 s of its own 1 s animation, and the dial positions
+      // an author would set for the top 140° of it are read as something else and
+      // land on a wrong frame. That silent wrong answer is the hazard, and it
+      // starts strictly above 360.
+      //
       // The refusal is deliberately narrow: `rotate` only, because `FromRotate` is
       // the one property whose reader wraps, and only when the range actually
-      // crosses (or sits below) 0°, because a dial authored at 340°..20° is how
-      // you write this axis under `local: false` and it works.
+      // runs outside `[0, 360]`, because a dial inside that circle — 20°..340°,
+      // or the whole turn 0°..360° — is how you write this axis under
+      // `local: false` and it works.
       if (property === 'rotate' && spec.local !== true) {
         const fromValue = spec.from === undefined ? 0 : needNumber(spec.from, 'from');
         const toTime = spec.to === undefined ? 0 : needNumber(spec.to, 'to');
@@ -3497,18 +3540,43 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
         const atEnd = fromValue + (duration - toTime) / perUnit;
         const lowest = Math.min(atStart, atEnd);
         const highest = Math.max(atStart, atEnd);
-        if (lowest < -1e-6) {
-          const readAs = lowest + 360;
-          const lands = toTime + (readAs - fromValue) * perUnit;
+        // Which end of the circle the range leaves, and which way the reader
+        // moves it: below 0° the wrap ADDS 360, past 360° there is nothing above
+        // to wrap from and the value arrives 360 LOWER instead. One record, so
+        // the end, its reading, the time it lands on and the two clauses that
+        // name the side are derived once rather than twice.
+        //
+        // The two tests ARE each other's mirror, and that is deliberate: each
+        // gives its own boundary — 0° and 360°, the two values an author aims at
+        // — the same outward slack, so only a range that genuinely leaves the
+        // closed circle `[0, 360]` is refused.
+        const dead =
+          lowest < -SLIDER_WRAP_SLACK
+            ? {
+                end: lowest,
+                readAs: lowest + 360,
+                side: 'below 0°',
+                repair: 'move the range so it does not cross 0°',
+              }
+            : highest > 360 + SLIDER_WRAP_SLACK
+              ? {
+                  end: highest,
+                  readAs: highest - 360,
+                  side: 'past 360°',
+                  repair: 'move the range so it does not run past 360°',
+                }
+              : null;
+        if (dead !== null) {
+          const lands = toTime + (dead.readAs - fromValue) * perUnit;
           throw new CompileError(
             `${where}: drives off bone "${String(spec.bone)}" rotate with "local": false, and the driving values ` +
               `that reach animation "${animation}" (0s..${duration}s) run from ${lowest.toFixed(3)}° to ${highest.toFixed(3)}°. ` +
               'A world rotation is read through `FromRotate.value`, which ends `if (value < 0) value += 360`, so the bone ' +
-              `at ${lowest.toFixed(3)}° is read as ${readAs.toFixed(3)}° and maps to time ${lands.toFixed(3)}s — outside ` +
+              `at ${dead.end.toFixed(3)}° is read as ${dead.readAs.toFixed(3)}° and maps to time ${lands.toFixed(3)}s — outside ` +
               `the animation's ${duration}s. With "loop": false that is \`Math.max(0, time)\` holding the last frame; with ` +
-              '"loop": true it wraps to some other frame. Either way the whole part of the range below 0° is dead and ' +
+              `"loop": true it wraps to some other frame. Either way the whole part of the range ${dead.side} is dead and ` +
               'nothing at runtime reports it. Add `"local": true` to read the bone\'s own rotation signed and unwrapped — ' +
-              'that is the form a face axis wants — or move the range so it does not cross 0°.',
+              `that is the form a face axis wants — or ${dead.repair}.`,
           );
         }
       }

package/src/deformmeasure.ts

@@ -95,6 +95,13 @@ import {
   AtlasAttachmentLoader,
   type Bone,
   DeformTimeline,
+  FromProperty,
+  FromRotate,
+  FromScaleX,
+  FromScaleY,
+  FromShearY,
+  FromX,
+  FromY,
   MeshAttachment,
   Physics,
   Skeleton,
@@ -298,12 +305,26 @@ 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. */
@@ -316,6 +337,7 @@ const TRACK_REACH: DeformReach = {
   slider: null,
   bone: null,
   property: null,
+  drive: null,
   local: false,
   label: 'played on a track',
 };
@@ -343,6 +365,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 +384,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
@@ -577,15 +612,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`, ' +
@@ -789,6 +842,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.
@@ -808,6 +925,19 @@ interface DialPlan {
   v1: number;
 }
 
+/**
+ * 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;
+}
+
 /**
  * How near the wanted time the runtime has to land before the dial is called
  * good, in seconds.
@@ -823,6 +953,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,27 +1042,66 @@ 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 };
@@ -895,18 +1109,71 @@ function planDial(data: SkeletonData, slider: SliderData): DialPlan | null {
   const instance = sliderOn(skeleton, slider);
   const bone = instance?.bone ?? null;
   if (instance === null || bone === null) return null;
+  const probes: 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 };
+    const response = Math.abs(v1 - v0);
+    if (!Number.isFinite(response) || response === 0) continue;
+    probes.push({ field, response, u0: base, v0, u1: base + step, v1 });
   }
   // 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 : (probes.find((p) => p.field === stated)?.response ?? 0),
+    verdict,
+  };
+  return { slider, reach: reach(discovery), field: chosen.field, u0: chosen.u0, v0: chosen.v0, u1: chosen.u1, v1: chosen.v1 };
+}
+
+/**
+ * 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 +1263,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 +1292,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 +1311,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),
     },
   };
 }