spine-rigc 0.18.1 → 0.20.0

package/README.md

@@ -467,10 +467,12 @@ was verified, and what writing it cost. Repository material: a clone and
 
 <p align="center"><em>The portrait rig playing its three animations in one take — the turn is
 the shot: both silhouette edges move apart, which a flat slide cannot do, because every
-feature carries its own depth. Scene direction of this kind is authorable on plain Spine
-4.3 — no plugin, no runtime patch — and the split was authoring cost rather than runtime
-capability; the cost is now one stated expression per key. Compiled and
-rendered entirely by the published package.</em></p>
+feature carries its own depth. The rig guarantees the seams — <code>idle</code> loops
+while <code>gaze</code> and <code>turn</code> return to rest, so the hand-offs meet at 0
+differing pixels — and the composing is the consumer's. Authorable on plain Spine 4.3, no
+plugin, no runtime patch; the split was authoring cost rather than runtime capability, and
+the cost is now one stated expression per key. Compiled and rendered entirely by the
+published package.</em></p>
 
 🎞️ **How the three films on this page were made** is kept with them, one directory per
 film in [`films/`](https://github.com/firejune/rigc/tree/main/films) — a `run.sh` that
@@ -575,6 +577,7 @@ letting `A17` blame the editor for the harness's own doing.
 | 🔬 **[docs/SPEC_COVERAGE.md](docs/SPEC_COVERAGE.md)** | Spine 4.3's full export surface against what rigc emits and what the official examples measurably use, with the ordered gap list |
 | 🎓 **[the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md)** | **why you can trust the output.** The yardstick, `diff` and `check` and what neither can see, the eight-rung ladder and the spineboy graduation exam, the run viewer, the 41 named assertions with their profiles, and the selftest that has watched every one of them fire. Repository material — it is not in the npm package |
 | 📋 [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) · [GATE.md](https://github.com/firejune/rigc/blob/main/docs/GATE.md) · [PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md) | the live rung ledger, the clause statements a candidate is graded against, and how to run an agent through the ladder and score what comes back |
+| 🗺️ [ROADMAP.md](https://github.com/firejune/rigc/blob/main/ROADMAP.md) | where this is going, and where it has been. What 1.0 has to mean before the number is claimed — conditions rather than a feature list, because direction here comes from what users hit |
 
 ## Why you can trust the output
 

package/cli.ts

@@ -492,6 +492,30 @@ function meshDepthNote(m: CompileResult['meshes'][number]): string {
       `depth "${m.depth.image}" ${m.depth.digest} near=${m.depth.near} zScale=${m.depth.zScale} ` +
         `z=[${m.depth.range[0]}, ${m.depth.range[1]}]`,
     );
+    // Directly under the sheet's own line, because it is the other half of
+    // "what did this mesh read": `z=[…]` says how much of the map's range
+    // reached the vertices, and this says how many of them read a texel that
+    // draws nothing (issue #449). Reported only when there is something to
+    // report, so a mesh whose every vertex sits on drawn art gains no line.
+    //
+    // ⭐ A `contour` gets the OTHER half of the sentence, because rigc built
+    // that outline and knows what it is: `buildContourMesh` returns
+    // `hullVertices: points.length` over `offsetPolygon(simplified, margin)`,
+    // so every vertex of a contour mesh is the traced silhouette pushed out by
+    // the margin — there are no interior vertices for the count to be about.
+    // Nothing is derived, inferred or thresholded to say so; it is what the
+    // generator returns, and `generatedHullAndEdges` already cross-checks that
+    // hull against the triangulation's own outline. Without it the line reads
+    // as a fault on every correct contour rig, which is a diagnostic authors
+    // learn to ignore.
+    if (m.depth.undrawn > 0) {
+      parts.push(
+        `${m.depth.undrawn} of ${m.vertices} vertices sample a texel the part image does not draw — ` +
+          (m.kind === 'contour'
+            ? 'a contour\'s vertices are all traced outline, pushed out by the margin, so this is the topology and not the sheet'
+            : 'their z is the sheet\'s reading of somewhere the part is not'),
+      );
+    }
     const c = m.depth.ceiling;
     parts.push(`turn ceiling  yaw ${ceilingPair(c.yaw)}   pitch ${ceilingPair(c.pitch)}`);
     const worst = tightestFold(c);
@@ -503,7 +527,13 @@ function meshDepthNote(m: CompileResult['meshes'][number]): string {
         ? `              nothing in this sheet folds: ${c.measured} triangle(s) measured, none with a depth gradient across it`
         : `              first to fold: ${worst.kind} ${worst.sign} at ${worst.limit.degrees.toFixed(2)}°, ` +
           `triangle ${worst.limit.triangle} [${worst.limit.ids.join(',')}], the sheet steps ` +
-          `${depthStepLevels(worst.limit.depthStep, m.depth.zScale).toFixed(2)} level(s) across it` +
+          `${depthStepLevels(worst.limit.depthStep, m.depth.zScale).toFixed(2)} level(s) across it, ` +
+          // The same step over the range the mesh sampled (issue #448). A
+          // suffix and not a line of its own: it is an apposition on the step
+          // beside it, and the reading that matters is the two together — a
+          // discontinuity says "plenty of levels" and "nearly all of them" at
+          // once, and they have to be read in one breath to say the opposite.
+          `which is ${worst.limit.stepShare.toFixed(3)} of the range this mesh sampled` +
           `${c.degenerate ? `; ${c.degenerate} triangle(s) too flat in setup to measure` : ''}`,
     );
   }
@@ -887,9 +917,37 @@ function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>):
   // animation are two frames and two rollups: merging them would average a fold
   // one dial reaches into a run of keys another one is clean over, which is the
   // hiding the two frames exist to prevent.
+  // 🔒 ONE derivation of a rollup's identity, read by every filter below.
+  //
+  // ⚠️ It was spelled three times and one of them drifted. The two key filters
+  // separate animation from slider with a NUL; the span filter used a SPACE, so
+  // its `=== id` never matched on any rig and `spans` was always empty — the
+  // "N span(s) … scanned" line silently stopped printing everywhere, taking with
+  // it the one thing issue #403 added it to say: that the scan RAN and found
+  // nothing, as opposed to never having run. A dead branch is the same silence
+  // this tool exists to convert into a named failure, and it survived because
+  // the identity was a literal at each site rather than a derivation (#440).
+  const rollupId = (animation: string, slider: string | null): string => `${animation}\u0000${slider ?? ''}`;
+  /**
+   * The readings A39 puts on its stats line for the three things this rollup
+   * reports — each spelled ONCE here and nowhere else in this file.
+   *
+   * 🔒 Checked rather than derived, and the difference is forced: `src/validate.ts`
+   * sets these on a `Record<string, number | string>`, so there is no type to take
+   * a name off and no constant to import. So they are spelled here and a control
+   * compiles a rig that triggers each one, then asserts the breadcrumb names a
+   * reading A39 really printed — two independent derivations compared, which is
+   * the shape `CUR07` uses for the same reason.
+   */
+  const A39_COUNTS = {
+    notDrawn: 'deformKeysNotDrawn',
+    unreachable: 'deformKeysUnreachable',
+    dialsDisagreed: 'deformDialsDisagreed',
+    dialDisagreed: 'deformDialDisagreed',
+  } as const;
   const rollups = new Map<string, { animation: string; label: string }>();
   for (const key of survey.keys) {
-    rollups.set(`${key.animation}${key.reach.slider ?? ''}`, {
+    rollups.set(rollupId(key.animation, key.reach.slider), {
       animation: key.animation,
       label: key.reach.kind === 'slider' ? `${key.animation} via ${key.reach.slider}` : key.animation,
     });
@@ -899,7 +957,7 @@ function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>):
     // the same two counts and A39 reads none of a key that draws nothing, nor of
     // one at a time no dial selects. The ones it left out get their own line
     // rather than a silence (issues #401, #407).
-    const mine = survey.keys.filter((k) => `${k.animation}${k.reach.slider ?? ''}` === id);
+    const mine = survey.keys.filter((k) => rollupId(k.animation, k.reach.slider) === id);
     const unreachable = mine.filter((k) => k.dial?.unreachable === true);
     const keys = mine.filter((k) => k.dial?.unreachable !== true && k.draw.blank === null);
     const blank = mine.filter((k) => k.dial?.unreachable !== true && k.draw.blank !== null);
@@ -934,7 +992,7 @@ function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>):
         `  ..      ${keys.length ? ''.padEnd(label.length) : label}  ${blank.length} key(s) draw no pixels ` +
           `at their own time and are read for no winding, carrying ` +
           `${blank.reduce((n, k) => n + k.reversed.length, 0)} reversed triangle(s) nothing gates  <- A39 counts ` +
-          'them as deformKeysNotDrawn',
+          `them as ${A39_COUNTS.notDrawn}`,
       );
     }
     if (unreachable.length) {
@@ -942,17 +1000,42 @@ function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>):
         `  ..      ${keys.length || blank.length ? ''.padEnd(label.length) : label}  ${unreachable.length} key(s) ` +
           'at a time no dial selects, measured in the frame the runtime lands on instead and read for no winding, ' +
           `carrying ${unreachable.reduce((n, k) => n + k.reversed.length, 0)} reversed triangle(s) nothing gates ` +
-          ' <- A39 counts them as deformKeysUnreachable',
+          ` <- A39 counts them as ${A39_COUNTS.unreachable}`,
+      );
+    }
+    // ⚠️ The dial rigc's two halves disagree about (issues #427, #440). It is a
+    // property of the SLIDER and not of any one key, so it is placed by the
+    // rollup's own identity rather than by a key filter — and it is REPORTED,
+    // never gated: A39 refuses nothing for it, because a disagreement can pose
+    // every frame correctly. Both readings are named because they differ by one
+    // letter, and a breadcrumb that named only one of `deformDialsDisagreed` /
+    // `deformDialDisagreed` would send a reader to grep for the other.
+    const disputes = survey.dialDisputes.filter((dispute) => rollupId(animation, dispute.slider) === id);
+    if (disputes.length) {
+      out.push(
+        `  ..      ${keys.length || blank.length || unreachable.length ? ''.padEnd(label.length) : label}  ` +
+          `${disputes.length} dial(s) the skeleton and the probe disagree about: ` +
+          disputes
+            .map(
+              (dispute) =>
+                `the skeleton reads ${dispute.bone}.${dispute.stated} and the probe drives ` +
+                `${dispute.bone}.${dispute.drive}, ` +
+                (dispute.outside.length === 0
+                  ? 'and both answers pose the same frames'
+                  : `${dispute.outside.length} key time(s) outside what the skeleton's own field reaches`),
+            )
+            .join('; ') +
+          `  <- A39 counts them as ${A39_COUNTS.dialsDisagreed} and spells them out as ${A39_COUNTS.dialDisagreed}`,
       );
     }
     // ⚠️ Printed on a clean animation too. "The scan ran and found nothing" and
     // "the scan never ran" are the two things a gate must never say the same
     // way, and this line is the only place an author can tell them apart
     // (issue #403).
-    const spans = survey.spans.filter((s) => `${s.animation} ${s.reach.slider ?? ''}` === id);
+    const spans = survey.spans.filter((s) => rollupId(s.animation, s.reach.slider) === id);
     if (spans.length) {
       out.push(
-        `  ..      ${keys.length || blank.length || unreachable.length ? ''.padEnd(label.length) : label}  ` +
+        `  ..      ${keys.length || blank.length || unreachable.length || disputes.length ? ''.padEnd(label.length) : label}  ` +
           `${spans.length} span(s) between consecutive keys scanned for a fold no key lands on: ` +
           `${spanTally(spans)}  <- A39 reads the same scan`,
       );

package/docs/AUTHORING.md

@@ -1004,7 +1004,7 @@ number that says whether the map covers the part or a corner of it.
         depth "face_depth.png" f552a2f50d21 near=white zScale=60 z=[0, 60]
         turn ceiling  yaw +31.41° / -32.01°   pitch +32.01° / -31.41°
           1st pct     yaw +31.55° x1.004 of 1004 / -32.10° x1.003 of 1044   pitch +32.10° x1.003 of 1044 / -31.55° x1.004 of 1004
-                      first to fold: yaw + at 31.41°, triangle 960 [113,112,593], the sheet steps 12.52 level(s) across it
+                      first to fold: yaw + at 31.41°, triangle 960 [113,112,593], the sheet steps 12.52 level(s) across it, which is 0.049 of the range this mesh sampled
 ```
 
 Past that angle a triangle turns inside out and `A39` refuses the build by name.
@@ -1012,9 +1012,10 @@ The loop this replaces is *pick an angle, build, read the refusal, guess again*.
 
 #### Is the ceiling describing the form, or the sheet's grain?
 
-The second and third lines answer that, and they are **reports only** — nothing
+The lines under the ceiling answer that, and they are **reports only** — nothing
 in them refuses a build or moves a ceiling
-([#412](https://github.com/firejune/rigc/issues/412)).
+([#412](https://github.com/firejune/rigc/issues/412),
+[#448](https://github.com/firejune/rigc/issues/448)).
 
 The ceiling is the **minimum** of the per-triangle fold angles, and a minimum
 cannot say whether it is the floor of a band or one bad pixel. Measured: a clean
@@ -1025,9 +1026,10 @@ triangle does not, and nothing on the first line says so.
 
 | the figure | how to read it |
 | --- | --- |
-| `x1.003` — the **1st percentile over the ceiling** | near 1 means a *band* of the mesh reaches the limit together, which is what a smooth form looks like: its steepest region has area. Near 10 means **one triangle** does, which is what a bad texel looks like. The clean and stray sheets above read `x1.003` and `x10.652` |
+| `x1.003` — the **1st percentile over the ceiling** | near 1 means a *band* of the mesh reaches the limit together, and near 10 means **one triangle** does, which is what a bad texel looks like. The clean and stray sheets above read `x1.003` and `x10.652`. ⚠️ A band is **not** sufficient evidence of a form, which is the third case: **an outline is a band**. A depth sheet estimated over cut-out art has a cliff along the whole silhouette, so its ceiling is a band too and this figure reads 1.02–2.17 — healthy — on a mesh whose angle means nothing. The row below is what tells those two apart |
 | `of 1004` — the **population** that percentile came out of | it is the nearest rank, so below **51** folding triangles there is no percentile to take and the line says `unranked of 36` instead of printing the minimum twice. Just over 51 it is the *second*-smallest angle, and a limit two triangles share is not yet a band |
 | `12.52 level(s)` — the **depth step across the triangle that folds first** | how much of the sheet's 0–255 range that triangle actually read. **Below about 3 the ceiling is quantisation rather than form**, and at exactly 1 it is `atan(255·h / zScale)` for cell size `h` — arithmetic about the encoding, with no form left in it at any density |
+| `which is 0.049 of the range this mesh sampled` — the **same step, over the range this mesh sampled** | how much of everything the sheet said across the whole part it said across that one triangle. A form's slope is bounded, so this **halves every time you double the lattice** while the angle settles. Near 1 it is a **cliff**: a step with no slope in it, whose angle halves with the lattice instead and describes nothing at any density. Measured: `gallery/look` reads 0.112 and 0.468, a synthetic raised cosine 0.394 falling to 0.027 under refinement, the same cosine with one planted cliff a flat 0.50, and estimated depth sheets over cut-out art **0.92–0.99** |
 | `+none` | on the ceiling line, nothing folds on that side at all, at any angle. On the percentile line it is the same statement — there is no population, because there is nothing to take a percentile of |
 
 A real one rather than the illustration above — `bun cli.ts build --rig
@@ -1038,25 +1040,48 @@ three spellings:
 ```
   MESH  head         grid     189 vertices / 320 triangles  (budget 320)  bones=[head]  attachments=[head]
         depth "face_depth.png" bf156ea0cfc970a3 near=white zScale=194 z=[0, 194]
+        80 of 189 vertices sample a texel the part image does not draw — their z is the sheet's reading of somewhere the part is not
         turn ceiling  yaw +19.32° / -19.32°   pitch +22.92° / -26.94°
           1st pct     yaw +19.32° x1.000 of 80 / -19.32° x1.000 of 80   pitch +22.92° x1.000 of 102 / -26.94° x1.000 of 130
-                      first to fold: yaw + at 19.32°, triangle 174 [119,138,139], the sheet steps 28.50 level(s) across it
+                      first to fold: yaw + at 19.32°, triangle 174 [119,138,139], the sheet steps 28.50 level(s) across it, which is 0.112 of the range this mesh sampled
   MESH  hair_lock_l  grid     39 vertices / 48 triangles  (budget 320)  bones=[lock_l]  attachments=[hair_lock_l]
         depth "lock_l_depth.png" 0c4eaeb36b7c5cac near=white zScale=64 z=[22.086275, 63.874511]
+        32 of 39 vertices sample a texel the part image does not draw — their z is the sheet's reading of somewhere the part is not
         turn ceiling  yaw +17.04° / -45.80°   pitch +none / -none
           1st pct     yaw +unranked of 12 / -unranked of 36   pitch +none / -none
-                      first to fold: yaw + at 17.04°, triangle 2 [1,28,29], the sheet steps 78.00 level(s) across it
+                      first to fold: yaw + at 17.04°, triangle 2 [1,28,29], the sheet steps 78.00 level(s) across it, which is 0.468 of the range this mesh sampled
 ```
 
 ⭐ Both of those sheets are **form**, and the figures say so from opposite ends:
 the head's 320 triangles put the percentile exactly on the ceiling, and the
 lock's 48 are too few to rank at all — but at 28.50 and 78.00 levels across the
-folding triangle, neither ceiling is anywhere near the encoding.
-
-⇒ **A small ceiling with a ratio near 1 and a step well above 3 is a steep
-surface: flatten the map.** A small ceiling with a large ratio, or with a step
-near 1, is a *sheet* problem: the grain, the 8-bit rounding, or a stray pixel.
-[`docs/FACE.md` §2.2](FACE.md) has the amplitudes and what each one costs.
+folding triangle, neither ceiling is anywhere near the encoding, and at 0.112
+and 0.468 of their own range neither step is a cliff.
+
+🔸 The line under each `depth "…"` is the other question, and it is not about
+the ceiling. A `grid` spans the whole part window and a head is not a rectangle, so
+some of the lattice lands where `head.png` draws nothing and takes its depth
+from the sheet out there. That is a **count and not a complaint** — read it
+against the mesh: 80 of 189 is the border of a lattice over a cut-out and the
+ceiling is still a form, while a count approaching the whole mesh with a step
+share near 1 beside it is a mesh reading background.
+
+⇒ **A small ceiling with a ratio near 1, a step well above 3 and a step share
+well under 1 is a steep surface: flatten the map.** A small ceiling with a large
+ratio, or with a step near 1, is a *sheet* problem: the grain, the 8-bit
+rounding, or a stray pixel. A small ceiling with a step share **near 1** is
+neither — it is a **discontinuity**, and no angle is the right one to quote for
+it. [`docs/FACE.md` §2.2](FACE.md) has the amplitudes, what each one costs, and
+why flattening does not apply to the third case.
+
+🚨 **How to tell a discontinuity from a steep surface in one move: refine the
+lattice and build again.** A form's ceiling settles and its step share halves; a
+cliff's ceiling **halves** and its step share does not move. Measured on a
+synthetic raised cosine against the same cosine with one column of cliff planted
+in it, over three doublings: the form goes 0.358 → 0.195 → 0.100 while its
+ceiling moves 41.99° → 39.59° → 38.84°, and the cliff goes 0.460 → 0.489 → 0.497
+while its ceiling goes 37.07° → 18.59° → 9.24°. The second one is not converging
+on anything.
 
 ⛔ **rigc will not filter the sheet for you, and you should not want it to.** A
 smoothed measurement would describe a surface the deform key is not built from:
@@ -1123,9 +1148,50 @@ refuses it instead:
 | `gamma` or `contrast` at or below 0 | `collapses the range onto the midpoint … so the map would describe a flat part` |
 | a `near` that is neither | `it is "white" or "black"` |
 
-A sheet with **no alpha channel** covers its whole grid by construction and the
-coverage check has nothing to test; what its background level means is then your
-statement, and the reported range is where it shows up.
+A sheet that is **opaque everywhere** — a full-frame render with the background
+in it, which is what monocular depth estimation produces — covers its whole grid
+by construction, so the coverage refusal has nothing to hold it to and skips.
+That is right: a full-frame sheet is a legitimate statement and rigc has no
+authority to guess an input away. But the defect the refusal exists to catch is
+still reachable in that encoding, so the report counts it instead
+([#449](https://github.com/firejune/rigc/issues/449)):
+
+```
+        80 of 189 vertices sample a texel the part image does not draw — their z is the sheet's reading of somewhere the part is not
+```
+
+⚠️ **The reported range is NOT where this shows up**, and this guide said it was
+until it was measured. A background level is a legitimate depth value, so a map
+half of which is background reports exactly as full a range as one that is all
+subject: on the measured build, `z=[0, 223.97]` of a stated 224 — healthy — with
+54 % of the mesh reading background. "Covers its whole grid" is true and about
+the wrong grid; the question was never coverage of the *sheet*, it was whether
+the mesh is sampling **art**.
+
+| The input | What you get |
+| --- | --- |
+| a sheet cut to the art's alpha, over a mesh that reaches past it | **refused** — `does not cover N of the mesh's V vertices`, with the fix for your topology named |
+| the same field stored opaque everywhere, over the same mesh | **compiled**, with `N of V vertices sample a texel the part image does not draw` in the report. The same N |
+| a mesh every one of whose vertices sits on drawn art | nothing — no line, and no refusal |
+
+🔸 It is a raw count with **no reach subtracted from it**, so a `contour` mesh
+reports most or all of its vertices: its outline is pushed `margin` pixels
+outside the silhouette by design, and out there the part draws nothing.
+Discounting the margin would mean borrowing a number authored for the trace to
+mean "close enough" for the sheet, and rigc does not invent tolerances.
+
+⭐ **So the line says why instead**, because rigc built that outline and knows
+what it is:
+
+```
+        15 of 15 vertices sample a texel the part image does not draw — a contour's vertices are all traced outline, pushed out by the margin, so this is the topology and not the sheet
+```
+
+The attribution is on a `contour` and **nowhere else**. A `grid`'s border is
+where your `us`/`vs` put it, not where a margin did, so the same sentence there
+would be a lie and the count stands alone. What that leaves true either way: the
+rim's depth really did come from off the art, which is harmless on a sheet
+dilated past the margin and is the whole failure on a full-frame estimate.
 
 ##### `soft` — which part is soft, and which bone carries it
 
@@ -1406,11 +1472,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 +1562,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
@@ -2551,7 +2736,7 @@ deform  (what each key does to the geometry — figures with names, never a bar;
 | `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 |
 | `winding` | triangles whose winding survived, and how many the key pinched onto zero area. A fold says so and points at `A39` |
 | the `BETWEEN` line | a fold at a time **no key lands on** (§4.11.3): the two keys it lies between, the time, the segment's curve kind, and how far along the interpolation it is. Present only where one was found |
-| `WORST` | per animation: the worst key by each quantity, then the reversal and collapse totals over every key, then how many spans between keys were scanned and what the scan found |
+| `WORST` | per animation **and per frame**: the worst key by each quantity, then the reversal and collapse totals over every key, then how many spans between keys were scanned and what the scan found. Each further line ends with a breadcrumb naming the `A39` reading that counts it — keys that draw no pixels (`deformKeysNotDrawn`, below), keys at a time no dial selects (`deformKeysUnreachable`, §4.11.4), and a dial the skeleton and the probe disagree about (`deformDialsDisagreed`, §4.11.4) |
 
 📌 **The frame is the posed one, and the denominator is 1.000 by definition.**
 Both sides of every comparison are taken at the key's own time with the animation
@@ -2740,7 +2925,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 +2980,60 @@ 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.
+
+**And `explain`'s rollup carries it too, with the breadcrumb its neighbours have**
+([#440](https://github.com/firejune/rigc/issues/440)). The per-key `frame` lines
+say it once each; the rollup says it once per animation, and ends by naming the
+two readings a `build` prints it under — because they differ by one letter, and a
+breadcrumb naming only one would send a reader to grep for the other:
+
+```
+  ..                     1 dial(s) the skeleton and the probe disagree about: the skeleton reads knob.x and the probe drives knob.y, 2 key time(s) outside what the skeleton's own field reaches  <- A39 counts them as deformDialsDisagreed and spells them out as deformDialDisagreed
+```
+
+The count after `outside` is the length of the stats line's own `outside:` list,
+and `deformDialsDisagreed` / `deformDialDisagreed` are checked against the keys
+`A39` really printed rather than restated — `DW34`. An agreed dial adds no line
+(`DW35`) and a **tie** is never rolled up as a disagreement (`DW36`).
+
+⛔ **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 +3209,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` |