spine-rigc 0.18.1 → 0.19.0

package/docs/AUTHORING.md

@@ -1406,11 +1406,76 @@ 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.
 
+#### 3.5.2.1 What each `property` can actually be read AS
+
+**A `property` under `local: false` is read through the world transform, and four
+of those readings are bounded.** A range that names values the reader cannot
+return is dead there: the dial moves, the reading does not follow, and nothing at
+runtime says so. [measured] against `spine-core` 4.3.13, one reader at a time —
+`bench/studies/2026-09-06-readers`:
+
+| `property` | `"local"` | Reads | Producible floor | Producible ceiling |
+| --- | --- | --- | --- | --- |
+| `rotate` | `false` | `FromRotate`, world | `0`, reached | `360`, reached |
+| `rotate` | `true` | `FromRotate`, local | none | none |
+| `x` | `false` | `FromX`, world | none | none |
+| `x` | `true` | `FromX`, local | none | none |
+| `y` | `false` | `FromY`, world | none | none |
+| `y` | `true` | `FromY`, local | none | none |
+| `scaleX` | `false` | `FromScaleX`, world | `0`, reached | none |
+| `scaleX` | `true` | `FromScaleX`, local | none | none |
+| `scaleY` | `false` | `FromScaleY`, world | `0`, reached | none |
+| `scaleY` | `true` | `FromScaleY`, local | none | none |
+| `shearY` | `false` | `FromShearY`, world | `-449.99999468`, reached | `269.99999468`, reached |
+| `shearY` | `true` | `FromShearY`, local | none | none |
+
+- **`none` is not "very large"** — those readers are `source.<field> + offset` and
+  the field is whatever the animation wrote, so there is nothing there to bound.
+- **Every world row assumes the offsets are zero**, and a slider cannot make them
+  anything else: `Slider.offsets` is a private all-zero array. The same six
+  classes serve a transform constraint, which passes its own — there the scale
+  floors move to the offset and the `shearY` window slides by it.
+- **`scaleX` / `scaleY` under `local: false` lose the sign.** The reader is
+  `Math.sqrt(a² + c²)`, so a bone at `scaleX: −1` reads **`+1`**, not `−1`: a
+  squash axis driven through negative scale gets the mirror of the dial you wrote.
+  The floor `0` is *reached*, not approached — a bone whose own scale or whose
+  parent's is 0 reads exactly 0 — so a range whose bottom is exactly 0 is fine and
+  one that dips below it is dead.
+- **`shearY` under `local: false` wraps like `rotate` does, and worse.** It is a
+  difference of two `atan2` calls, so at any one bone orientation the readable
+  window is 360° wide — `(−270 − θx, 90 − θx]`, where `θx` is the bone's world
+  x-axis angle. The bound in the table is the union over every orientation. ⇒ the
+  seam is **not at a fixed value of the driven field**; it is wherever the bone is
+  pointing. Prefer `local: true` for a shear axis.
+- **The bounds are not round numbers because `MathUtils.PI` is `3.1415927`** — the
+  float32 π of the reference runtime. Every degree in spine-core passes through
+  `180 / 3.1415927`, so a full turn converts as `359.99999468178214` and a bone at
+  360° reads 5.3e-6° rather than 0°. `shearY`'s two ends are `±2π · radDeg − 90`.
+- 🔸 A negative `skeleton.scaleX` / `scaleY` — how a consumer mirrors a character —
+  changes **nothing**: every world reader divides the same factor back out, and
+  [measured] the readings are identical to the digit at (1,1), (−1,1), (1,−1),
+  (−1,−1), (2,0.5) and (−0.5,3). A `skeleton` scale of **zero** makes every world
+  reader `NaN`, and `Math.max(0, NaN)` is NaN — but nothing in skeleton data sets
+  that field, so it is the consumer's to avoid.
+
+⚠️ **`local: true` reads the number you authored only on a bone nothing else
+drives.** `Slider.update` calls `bone.appliedPose.validateLocalTransform` first,
+and on a bone a constraint moved that recomputes the local pose *from the world
+matrix* — `atan2Deg` for the angles and `Math.sqrt` for `scaleX`. [measured] on
+one rig, the same slider: a free bone at `rotation: −500` reads `−500` and the
+same bone inside a transform constraint's `bones` reads `−140.000006`; at
+`scaleX: −2` the free bone reads `−2` and the constrained one reads `+2`. The
+producible *set* is unbounded either way — the free case is in it — but if
+`local: true` is your repair for a world reader's floor, check that the driving
+bone is not itself constrained.
+
+#### 3.5.2.2 The circle a `rotate` world dial has to stay inside
+
 🚨 **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
+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
@@ -1431,12 +1496,66 @@ 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°"*.
 
+⭐ **The reading in that message is a modulo, not one turn** — the wrap the bone's
+matrix has already applied by the time `atan2` reads it, so a range that leaves
+the circle by *more* than 360° is folded all the way back into `[0, 360)`. The two
+examples above each sit within one turn, where a single ±360 gives the same
+answer; past that only the modulo does. [measured] through spine-core, a bone
+parked at **−500°** drives the slider to **3.600000 s**, which is exactly where a
+bone parked at **220°** drives it — so the reading is 220°, not −140°, and a
+refusal naming −140° would be naming a value that reader cannot return at all
+(issue [#431](https://github.com/firejune/rigc/issues/431)). The same on the other
+side: **900°** drives it to **0.200000 s**, the time a bone at **180°** selects.
+
+📐 **The consequence in that message is computed, not described.** Both refusals
+end on two numbers read off `[0, 360]` met with the driving values that reach the
+animation — the same two the message has already printed:
+
+```
+reachable = { to + (v − from) × scale : v ∈ [0, 360] } ∩ [0, duration]
+held      = { v ∈ [0, 360] : the mapped time falls outside [0, duration] }
+```
+
+so the 300°..500° dial above is refused with *"This dial reaches only
+0.000s..0.300s of the animation's 1s, and 83.3% of the circle — every reading
+below 300.000° — is held on the frame at 0.000s"*, and the −15°..15° one with
+*"…only 0.500s..1.000s of the animation's 1s, and 95.8% of the circle — every
+reading above 15.000° — is held on the frame at 1.000s"*. [measured] the first of
+those reproduces a 0.1° sweep of the rig through `spine-core` to **3.2e-8 s**,
+which is the reader's own `atan2` noise.
+
+⚠️ **`loop: true` gets a different sentence, because it is a different runtime.**
+`Slider.js:63-66` is `p.time = duration + (p.time % duration)` when the slider
+loops and `Math.max(0, p.time)` when it does not, so nothing is held on a looping
+slider — [measured] the same 300°..500° rig pins 5⁄6 of the circle to frame 0 at
+the default and pins *nothing* under `loop: true`. The refusal says so: *"Nothing
+is held: `"loop": true` wraps the time as `duration + (time % duration)`, so the
+140.000° of the range past 360° selects nothing a reading inside the circle does
+not already select."* The range is still refused either way — a bone cannot be
+read at 500°, whatever happens to the time afterwards.
+
+⭐ **The degrees in that sentence are a *width*** — how much of `lowest..highest`
+lies outside `[0, 360]` — and not the reach from the boundary to the far end. The
+two are the same number for a range that *straddles* a boundary, as `300°..500°`
+does. A range lying **wholly** outside is told its own width instead: `400°..500°`
+reads *"the 100.000° of the range past 360°"*, and `-500°..-300°` *"the 200.000°
+of the range below 0°"* (issue
+[#434](https://github.com/firejune/rigc/issues/434) — both used to print the
+reach, which on the first of those was 140.000°, wider than the 100°-wide range
+it was describing).
+
 ⭐ **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` that puts 360° on the last frame. It misses **nothing**: [measured] the
+wrap `value += 360` on a reading a hair below zero *rounds*, and bisecting the
+runtime's own `v + 360 === 360` puts the threshold at exactly half an ulp of 360 —
+so every reading in `[-2.842170943040401e-14°, 0°)` is read as exactly `360`, and
+the top of that range is reached rather than approached. Nor is 360 a separate
+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. (The
+other half of that same `atan2` leaves a 5.3e-6°-wide hole at 180°, between
+`179.99999734…` and `180.00000265…` — measured, reported for completeness, and
+narrower than any dial anybody writes.) 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
@@ -2740,7 +2859,7 @@ dial and not reached at all through another.
 - ⚠️ **A key at a time no dial can select is named, not passed.** The cause is
   [#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
+  **`[0, 360]` is the whole of its range** and a mapping needing anything outside
   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
@@ -2795,9 +2914,45 @@ the line says so rather than picking one silently.**
   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.
+**And a `build` says it too, on `A39`'s stats line**
+([#427](https://github.com/firejune/rigc/issues/427)) — because `explain` is not
+the loop you run, and until this the whole finding lived on a line only `explain`
+prints. Nothing appears on a rig where the two answers agreed, which is every
+`local: true` slider and every gallery example:
+
+```
+deformDialsTied=1 deformDialTied=dial|artifact:knob.x@7.071e-1|tied:knob.y@7.071e-1
+deformDialsDisagreed=1 deformDialDisagreed=dial|artifact:knob.x@2.321e-8|reaches:0.000000..0.003893s|probe:knob.y@1.000e+0|reaches:0.000000..1.000000s|outside:0.500000s+1.000000s
+```
+
+- `artifact:` is the field the **skeleton** names and what one unit of it moves the
+  reading by; `probe:` is the field that **measurably** moves it and by how much.
+- `reaches:` is the part of that animation's own `0..duration` each of them can
+  select. It is bounded by the same `±16777216` the dial figure is: a field that
+  barely moves the reading needs an unsettable value to move it a whole second.
+- `outside:` is the key times this survey posed through `probe:` that **no
+  settable value of the field the skeleton names reaches**. Each one is posed
+  through that field and the runtime is asked where it landed, so the list is a
+  measurement. ⭐ `outside:none` is a reading, not an absence — it says both
+  answers select every frame that was measured, so the disagreement changed
+  nothing about what `A39` looked at.
+- A **tie** never carries `probe:`, `reaches:` or `outside:`, and never counts as a
+  disagreement. There is one belief there, not two.
+
+⛔ **None of it refuses a build**, and the reason is measured rather than chosen.
+The field the survey drives is the largest response the probe found, so its reach
+always *contains* the artifact's: a disagreement cannot make `A39` miss a frame the
+runtime reaches. And every frame it does pose is checked against `SliderPose.time`
+by spine-core itself, so it cannot make `A39` pose one that never happens either.
+What is left is a rig naming a property no settable value of turns far enough —
+which the line above tells you, and which no edit rigc could demand would fix,
+because the rig may be perfectly correct and driven through the other field.
+
+None of this needs anything from you unless a `frame` line or one of those stats
+readings appears. If one does, it is telling you the dial bone's parent transform
+is doing something you may not have intended — and if `outside:` names times, it is
+telling you the dial cannot be turned to them through the property your rig spec
+declares.
 
 ⚠️ **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
@@ -2973,8 +3128,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° … 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 |
+| `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 it misses nothing: the wrap rounds, so a bone a hair below 0° is read as exactly 360 |
 | `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.1",
+  "version": "0.19.0",
   "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

@@ -3540,11 +3540,9 @@ 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);
-        // 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.
+        // Which end of the circle the range leaves. 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
@@ -3554,27 +3552,162 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
           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;
+          /**
+           * What `FromRotate.value` actually returns for a bone at that end: a
+           * MODULO, not one subtraction (issue #431).
+           *
+           * 🚨 `lowest + 360` / `highest - 360` is right only while the range
+           * stays within one turn of the circle, which every fixture in this
+           * tree happened to be. Further out it printed a number the reader
+           * cannot return, inside a refusal whose entire subject is which
+           * readings the reader CAN return: `from: -500, scale: 0.005` over a
+           * 1 s animation said *"the bone at -500.000° is read as -140.000° and
+           * maps to time 1.800s"*, and -140° is not in `[0, 360)` at all. Both
+           * figures in that sentence were wrong. Measured through spine-core,
+           * a bone parked at -500° drives `Slider.appliedPose.time` to
+           * 3.600000s — the same six decimals a bone parked at 220° drives it
+           * to — so the reading is 220° and the time is 3.600s.
+           *
+           * ⭐ Derived off `dead.end` rather than inside the two branches, so
+           * the wrap is written ONCE. That is what #424 collapsed the two ends
+           * into one record for, and a second copy of `% 360` with a sign
+           * edited is how the pair drifts apart again.
+           *
+           * ⚠️ The consequence clause below does NOT go through here and does
+           * not need to: `reachLo`/`reachHi` intersect the driving window with
+           * `[0, 360)` directly, which is the same set however many turns out
+           * the window sits. Swept through spine-core at 0.1° over the whole
+           * circle on both a beyond-a-turn low range (-500°..-300°) and a
+           * beyond-`+720°` high one (100°..900°), the held fraction and the
+           * frame the held arc pins to are the ones this clause names — 100.0%
+           * at 1.000s and 27.8% at 0.000s — and the runtime's own applied time
+           * tracks the closed form to 3.3e-8s.
+           */
+          const readAs = ((dead.end % 360) + 360) % 360;
+          /**
+           * The time this mapping puts a driving value at, before the runtime
+           * touches it — the one arithmetic every figure below comes off.
+           *
+           * ⚠️ **Computed, not asserted** (issue #423). This clause used to end
+           * *"— outside the animation's Ds. With `loop`: false that is
+           * `Math.max(0, time)` holding the last frame; with `loop`: true it
+           * wraps to some other frame"*, which states a consequence rather than
+           * measuring one — and is flatly false for a range spanning a full
+           * turn, where the wrapped reading lands INSIDE the animation. It also
+           * printed both loop modes and left the reader to pick. A message that
+           * hedges is a message that has not measured.
+           */
+          const timeAt = (value: number): number => toTime + (value - fromValue) * perUnit;
+          const lands = timeAt(readAs);
+          // `[0, 360)` is the whole of what `FromRotate.value` returns (issue
+          // #417), so the readings that reach the animation at all are that
+          // circle met with the driving window `lowest`..`highest` the range
+          // clause above already prints. A second derivation beside these two
+          // numbers is exactly how a pair drifts, which is why #417 collapsed
+          // the two ends into one `dead` record in the first place.
+          const reachLo = Math.max(0, lowest);
+          const reachHi = Math.min(360, highest);
+          const reaches = reachLo <= reachHi;
+          const intoFrame = (time: number): number => Math.min(Math.max(time, 0), duration);
+          const reachA = intoFrame(timeAt(reachLo));
+          const reachB = intoFrame(timeAt(reachHi));
+          const span = `${Math.min(reachA, reachB).toFixed(3)}s..${Math.max(reachA, reachB).toFixed(3)}s`;
+          // ⭐ Exactly ONE arc of the circle is ever left over, and that is what
+          // lets the message name one bound and one frame instead of a set: the
+          // refusal means `[lowest, highest]` already runs off one end of
+          // `[0, 360)`, so the part of the circle outside it is a single run.
+          // (Both ends outside means the whole circle reaches — `dead` is 0° wide
+          // — and neither end outside is not a refusal at all.)
+          const dark = reaches ? 360 - (reachHi - reachLo) : 360;
+          const heldAt = intoFrame(timeAt(reachLo > 0 ? 0 : 360));
+          const arc = !reaches
+            ? 'every reading'
+            : reachLo > 0
+              ? `every reading below ${reachLo.toFixed(3)}°`
+              : `every reading above ${reachHi.toFixed(3)}°`;
+          /**
+           * How much of the range is a bone position no reader ever returns:
+           * the WIDTH of `[lowest, highest]` lying outside `[0, 360]` (issue
+           * #434).
+           *
+           * 🚨 `-lowest` / `highest - 360` is the distance from the boundary to
+           * the FAR end, and that equals the dead width only while the range
+           * STRADDLES the boundary. A range lying wholly outside had the gap
+           * between the boundary and its NEAR end counted too: `400°..500°` —
+           * inside one turn and reachable today — was told `140.000°` of it is
+           * dead, wider than the 100° range itself, and `-500°..-300°` was told
+           * `500.000°` against a true 200°. Clamping the near end to the
+           * boundary is the whole of the fix, and it moves ONLY the ranges that
+           * lie wholly outside: measured, a range straddling either boundary, a
+           * range ending exactly on one, and a range hanging off both at once
+           * all print what they printed before. `PS45` is the two that move and
+           * `PS46` is the four that must not.
+           *
+           * ⭐ **Third instance of one shape in this clause.** #417 tested one
+           * end of the range because its fixture only ever left the circle at
+           * that end; #431 wrapped by a single subtraction because every
+           * fixture sat within one turn; this measured to the far end because
+           * `PS42` — the only control that reads this string — straddles 360°,
+           * where the two arithmetics agree to the bit. Every time, a
+           * computation right about the case its fixture happened to be and
+           * silent about the case beside it, with no second fixture standing
+           * anywhere else to say so.
+           *
+           * ⭐ Why it read as a measurement rather than as a bug: the wrong
+           * figure is always a number ALREADY IN THE SENTENCE. Past 360°,
+           * `highest - 360` reproduces `readAs` — `400°..500°` printed the same
+           * `140.000°` twice, once as the reading and once as a width. Below 0°,
+           * `-lowest` reproduces `dead.end` with its sign dropped.
+           *
+           * ⚠️ Each term stays BEHIND the test that says its side is the one
+           * that crossed, and those guards are load-bearing rather than tidy —
+           * measured, not argued. Drop `lowest < 0` and the low term on
+           * `400°..500°` is `Math.min(0, 500) - 400 = -400`, a negative
+           * contribution to a width: the refusal prints `-300.000°`, and
+           * `300°..500°` and `100°..900°` move to `-160.000°` and `440.000°`.
+           * Drop `highest > 360` and `-340°..-305°` prints `-630.000°`. Neither
+           * is a width, and a width is what the sentence says it is.
+           */
+          const outside =
+            (lowest < 0 ? Math.min(0, highest) - lowest : 0) + (highest > 360 ? highest - Math.max(360, lowest) : 0);
+          // ⚠️ WHICH consequence the runtime produces is the slider's own `loop`,
+          // read rather than guessed: `Slider.js:63-66` is
+          // `p.time = duration + (p.time % duration)` when it is true and
+          // `Math.max(0, p.time)` when it is false, so a reading held on one
+          // frame under the second is replayed from elsewhere under the first and
+          // nothing is dead in time at all. Swept through spine-core at 0.1° over
+          // the whole circle before this was written, both ways.
+          const consequence =
+            spec.loop === true
+              ? `Nothing is held: "loop": true wraps the time as \`duration + (time % duration)\`, so the ` +
+                `${outside.toFixed(3)}° of the range ${dead.side} selects nothing a reading inside the circle does ` +
+                'not already select.'
+              : !reaches
+                ? `This dial reaches none of the animation's ${duration}s — the whole circle is held on the frame at ` +
+                  `${heldAt.toFixed(3)}s.`
+                : dark === 0
+                  ? `This dial reaches only ${span} of the animation's ${duration}s, and no reading of the circle ` +
+                    'reaches the rest of it.'
+                  : `This dial reaches only ${span} of the animation's ${duration}s, and ` +
+                    `${((dark / 360) * 100).toFixed(1)}% of the circle — ${arc} — is held on the frame at ` +
+                    `${heldAt.toFixed(3)}s.`;
           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 ${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 ${dead.side} is dead and ` +
+              `at ${dead.end.toFixed(3)}° is read as ${readAs.toFixed(3)}° and maps to time ${lands.toFixed(3)}s. ` +
+              `${consequence} 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 ${dead.repair}.`,
           );

package/src/deformmeasure.ts

@@ -331,6 +331,94 @@ export interface DeformReach {
   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',
@@ -594,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[];
 }
 
 /**
@@ -693,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
@@ -701,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++;
@@ -748,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
@@ -773,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;
@@ -802,6 +965,8 @@ export function surveyDeformKeys(data: SkeletonData, exempt: ReadonlySet<string>
     spansUnconfirmed,
     spansNotScanned,
     spanProbes,
+    dialTies,
+    dialDisputes,
   };
 }
 
@@ -913,6 +1078,13 @@ interface DialDiscovery {
 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.
@@ -923,6 +1095,17 @@ 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;
 }
 
 /**
@@ -1104,22 +1287,26 @@ function planDial(data: SkeletonData, slider: SliderData): DialPlan | null {
   };
   // 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;
-  const probes: DialProbe[] = [];
+  // ⚠️ 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);
-    const response = Math.abs(v1 - v0);
-    if (!Number.isFinite(response) || response === 0) continue;
-    probes.push({ field, response, 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.
   if (probes.length === 0) return null;
@@ -1140,10 +1327,80 @@ function planDial(data: SkeletonData, slider: SliderData): DialPlan | null {
     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),
+      stated === null || stated === chosen.field ? null : (all.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 };
+  // 🔒 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;
 }
 
 /**

package/src/validate.ts

@@ -45,7 +45,14 @@ import {
 // A19 needs the DECODED page, not its header, to measure one region's own
 // rectangle on a shared page.
 import { readPlate } from '../tools/plate.ts';
-import { surveyDeformKeys, unreachableWhy, type DeformReach } from './deformmeasure.ts';
+import {
+  surveyDeformKeys,
+  unreachableWhy,
+  type DeformDialDispute,
+  type DeformDialTie,
+  type DeformReach,
+  type DialSpan,
+} from './deformmeasure.ts';
 import { colourTypeName, readPngInfo } from './png.ts';
 import { CHANNELS_BY_KIND, KEY_TIME_EPSILON, walkTimelines } from './timelines.ts';
 import type { RigInfo } from './types.ts';
@@ -238,6 +245,49 @@ function frameClause(reach: DeformReach): string {
   return reach.kind === 'slider' ? ` (applied by slider "${reach.slider}", not played on a track)` : '';
 }
 
+/**
+ * A dial's reach as A39's stats line spells it, or `none` when it can select no
+ * part of its animation at all.
+ *
+ * Six decimals because a key time has six: a reach whose end is printed coarser
+ * than the times it is compared against cannot be read against them.
+ */
+function dialSpanText(span: DialSpan | null): string {
+  return span === null ? 'none' : `${span.lo.toFixed(6)}..${span.hi.toFixed(6)}s`;
+}
+
+/**
+ * One disputed dial on A39's stats line — both answers, both reaches, and the
+ * frames the artifact's answer could not have posed (issue #427).
+ *
+ * ⭐ **`outside:` is always there, `none` included.** The comparison it reports is
+ * what decides whether a disagreement changed anything the survey measured, and a
+ * comparison that came out equal must not look like one nobody made. It is the
+ * difference between "both answers pose the same frames, so the disagreement is a
+ * fact about rigc and not about this rig" and "these key times were surveyed
+ * through a field the skeleton does not name and no settable value of the one it
+ * does reaches them".
+ *
+ * ⚠️ No spaces anywhere in it: the stats line is `k=v` pairs joined by spaces, and
+ * a value with a space in it turns one reading into two.
+ */
+function dialDisputeText(dispute: DeformDialDispute): string {
+  const stated = dispute.statedResponse === null ? 'unmeasured' : dispute.statedResponse.toExponential(3);
+  return (
+    `${dispute.slider}|artifact:${dispute.bone}.${dispute.stated}@${stated}` +
+    `|reaches:${dialSpanText(dispute.statedReach)}` +
+    `|probe:${dispute.bone}.${dispute.drive}@${dispute.driveResponse.toExponential(3)}` +
+    `|reaches:${dialSpanText(dispute.driveReach)}` +
+    `|outside:${dispute.outside.length === 0 ? 'none' : dispute.outside.map((t) => `${t.toFixed(6)}s`).join('+')}`
+  );
+}
+
+/** One tied dial on the same line, in the shape that cannot be read as a dispute. */
+function dialTieText(tie: DeformDialTie): string {
+  const rivals = tie.rivals.map((r) => `${tie.bone}.${r.field}@${r.response.toExponential(3)}`).join('+');
+  return `${tie.slider}|artifact:${tie.bone}.${tie.drive}@${tie.driveResponse.toExponential(3)}|tied:${rivals}`;
+}
+
 const FRAME = 1 / 60;
 const STEP_FRAMES = 120;
 
@@ -1668,6 +1718,36 @@ export function validate(input: ValidateInput): ValidateReport {
         );
       }
       const survey = surveyDeformKeys(data, new Set(input.rig.deformMayFold));
+      // 🚨 Which dial was turned, when rigc's two halves did not simply agree
+      // about that — and BEFORE any of the returns below, because every one of
+      // them is a run that posed frames through this dial (issue #427).
+      //
+      // The verdict used to live in `DeformReach.label`, which `explain` prints
+      // and nothing else does, so a `build`-only run — the normal loop, and the
+      // one an agent that cannot see the rig actually runs — never learned that
+      // the artifact and the probe named different fields.
+      //
+      // ⛔ Not a refusal, and the measurement rather than taste is why (#427).
+      // The frames this survey posed were each checked against `SliderPose.time`
+      // by the runtime itself, so a disagreement cannot make it pose one that
+      // does not happen; and the field it drives is the largest response the
+      // probe found, so it cannot make it miss one that does. What a
+      // disagreement CAN do is leave the rig naming a property no settable value
+      // of turns far enough — which is what `outside` measures and what an
+      // author can act on. A refusal would refuse a rig spine-core poses
+      // correctly at every key, with no edit that would make it green.
+      //
+      // 🔒 A tie is not a disagreement and gets a line that cannot be read as
+      // one: there the probe named no field, the artifact broke the tie, and the
+      // parent-45° geometry that reaches it is legitimate.
+      if (survey.dialTies.length) {
+        stats.deformDialsTied = survey.dialTies.length;
+        stats.deformDialTied = survey.dialTies.map(dialTieText).join(',');
+      }
+      if (survey.dialDisputes.length) {
+        stats.deformDialsDisagreed = survey.dialDisputes.length;
+        stats.deformDialDisagreed = survey.dialDisputes.map(dialDisputeText).join(',');
+      }
       /** A key this rule is refusing, by the triple that identifies it. */
       const refusedKey = new Set<string>();
       for (const key of survey.keys) {