spine-rigc 0.19.0 → 0.20.1

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

@@ -773,8 +773,13 @@ between two things it has in front of it: the emitted triangles, and the PNG the
 attachment names with `image`. So any mesh that names one gets the figure on its
 `MESH` line, authored or generated:
 
+```bash
+bun cli.ts build --rig gallery/squash/rig.json \
+                 --motion gallery/squash/motion.json --out /tmp/squash
+```
+
 ```
-  MESH  ball         authored 9 vertices / 8 triangles  (budget 8)  bones=[ball]  attachments=[ball]  covers 94.31% of the art, reaching 2.50px past it
+  MESH  ball         authored 9 vertices / 8 triangles  (budget 8)  bones=[ball]  attachments=[ball]  covers 100.00% of the art, reaching 15.00px past it
 ```
 
 **A number, not a bar.** A `contour` under 99.5% is *refused* because rigc
@@ -782,11 +787,17 @@ generated that geometry as a claim about the art; an authored mesh that sits ins
 its art is a legitimate thing to draw — a soft feather, a trimmed hull, a mesh
 meant to bend a core while its edges stretch — so the figure informs and the
 decision stays with the author. A mesh with no `image` reports nothing, because
-there is nothing to measure it against. The silence was worth closing: the line
-above is a round part meshed as a centre vertex plus 8 rim vertices placed on the
-silhouette, and an octagon's sides pass `R · cos(π/8)` from its centre, so 5.7% of
-the drawing — its whole ink outline, between the spokes — was not going to be
-drawn, and every assertion passed (issue #277).
+there is nothing to measure it against.
+
+**The silence was worth closing, and that example is where it was found.** The
+ball is a centre vertex plus 8 rim vertices, and the first version placed them
+*on* the silhouette — but an octagon's sides pass `R · cos(π/8)` from its centre,
+so its whole ink outline between the spokes was not going to be drawn, and every
+assertion passed (issue #277). That is why the command above prints 100.00%
+rather than the figure it was filed over:
+[`gallery/squash`](https://github.com/firejune/rigc/tree/main/gallery/squash)'s
+README carries the inradius arithmetic, both coverage readings, and the rim move
+that settled it.
 
 The generators are `ring`, `ribbon`, `contour` and `grid` (see
 [`src/mesh.ts`](../src/mesh.ts)); the first two encode a deformation model rather
@@ -1004,7 +1015,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 +1023,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,38 +1037,66 @@ 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
-gallery/look/rig.json --motion gallery/look/motion.json --images
-gallery/look/parts --out <dir>`, whose two meshes happen to print two of the
-three spellings:
+A real one rather than the illustration above — `gallery/look`, whose two meshes
+happen to print two of the three spellings:
+
+```bash
+bun cli.ts build --rig gallery/look/rig.json \
+                 --motion gallery/look/motion.json \
+                 --images gallery/look/parts --out /tmp/look
+```
 
 ```
   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 +1163,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
 
@@ -2016,6 +2097,7 @@ is not the arrangement the format has. Spine keys one bone per timeline, so the
 six numbers of a head turn are eighty lines apart in the artifact and nobody can
 see a wrong sign in them.
 
+**No run reproduces this:** the legend and one group's record lifted out of one `explain` run, which prints the two `bone "faceshift"` records between them
 ```
 group members  (the per-member values of one track, side by side — issue #295)
   ..    a row per member and a block per key, because a wrong sign is visible in a column of six and
@@ -2595,10 +2677,15 @@ makes against them.
 
 **It is auditable.** `explain` prints the model, the scalars the closed form
 derived from it, and every offset it produced — the emitted ones, not a second
-evaluation:
+evaluation. This is the `t=0.62` key of the spec above, whole:
+
+```bash
+bun cli.ts explain --rig gallery/portrait/rig.json \
+                   --motion gallery/portrait/motion.json --out /tmp/explain
+```
 
 ```
-      t=0.62    deform[0..50]  25 pair(s)                      bezier[4]
+      t=0.62    deform[0..50]  25 pair(s)                      stepped
                transform yaw  radius=170 degrees=12
                dx = (x−about)·(cos t − 1) − z·sin t,   z = √(radius² − (x−about)²)
                  t = 0.20944 rad
@@ -2607,9 +2694,19 @@ evaluation:
                  centre shift = −radius·sin t = -35.344987
                25 vertices, largest offset 35.344987px at vertex 2
                  v  0 (-7.17493, 0)  v  1 (-22.413595, 0)  v  2 (-35.344987, 0)  v  3 (-27.658171, 0)
-                 …five more lines
+                 v  4 (-14.255108, 0)  v  5 (-14.255108, 0)  v  6 (-14.255108, 0)  v  7 (-14.255108, 0)
+                 v  8 (-14.255108, 0)  v  9 (-27.658171, 0)  v 10 (-35.344987, 0)  v 11 (-22.413595, 0)
+                 v 12 (-7.17493, 0)  v 13 (-7.17493, 0)  v 14 (-7.17493, 0)  v 15 (-7.17493, 0)
+                 v 16 (-22.413595, 0)  v 17 (-35.344987, 0)  v 18 (-27.658171, 0)  v 19 (-22.413595, 0)
+                 v 20 (-35.344987, 0)  v 21 (-27.658171, 0)  v 22 (-22.413595, 0)  v 23 (-35.344987, 0)
+                 v 24 (-27.658171, 0)
 ```
 
+The curve reads `stepped` where the spec says `"ease": "swell"`, and that is
+§4.5's hold rule rather than a discrepancy: the next key emits these same 25
+offsets, so the segment between them would draw nothing and is written the way
+the editor writes it.
+
 📌 **Float behaviour, stated.** The closed forms are evaluated in float64 and
 quantised to six decimals like every other emitted number, so the same spec emits
 the same bytes and `A18_DETERMINISTIC_EMIT` proves it on a second compile. The
@@ -2635,6 +2732,7 @@ triangles. It is a report and it never gates: `explain` takes no `--profile` and
 exits 0 on a rig `build` would refuse, so the figures are readable on the build
 that is failing.
 
+**No run reproduces this:** abridged — the `WORST` rollup follows key 1 here, where the run prints `head/head`'s other two keys and all four of `hair_bang/hair_bang` between them
 ```
 deform  (what each key does to the geometry — figures with names, never a bar; issue #316)
   ..    every key measured at its OWN time against the same pose with the deform CLEARED, so the
@@ -2670,7 +2768,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
@@ -2731,8 +2829,12 @@ clothes. The quantity that does move — how much art each drawn pixel now carri
 📘 **[FACE.md](FACE.md) §9.2** is this block on real art, as three builds of
 `gallery/portrait`: the good one, one with a band inverted, and one folded. The
 inverted build is the case worth reading — `A39` passes it (correctly: nothing
-reverses), and the block is what says `x1.362834` where the model's own table
-says `x1.319121`, with no reference render anywhere.
+reverses), and the block is what says `x1.362834` on the band the model's own key
+reports as `x0.637174`, with no reference render anywhere. ⭐ The comparison is
+per **triangle** and that is what makes it a reading: the block names one beside
+every ratio, so the two blocks can be lined up band against band instead of worst
+against worst — which on this build would have paired the inverted band with an
+untouched one and called the difference mild.
 
 📘 **[`gallery/nod`](https://github.com/firejune/rigc/tree/main/gallery/nod)'s
 README is a second reading of the same block** (repository material, hence the
@@ -2757,15 +2859,23 @@ the frames just before it are drawn, nearly folded, and land on no key at all. O
 the turn probe that is **8 reversed triangles at alpha 0.20, gating green**.
 
 ⇒ `A39` now scans every interval between two consecutive deform keys as well, and
-refuses one with its own sentence:
-
-```
-FAIL  A39_DEFORM_KEEPS_TRIANGLE_WINDING: animation "turn" deform head/head BETWEEN key 0
-      (t=0s) and key 1 (t=0.5s), at t=0.444089s — 88.8% of the way from one to the other:
-      8 of 32 triangle(s) reverse winding — triangle 0 [0,15,16] 1890.001 -> -272.314px²; …
-      NO KEY LANDS THERE: the runtime interpolates between the two keys, and the mesh is
-      inside out for part of the way, drawing its texture backwards at alpha 0.1118 …
-```
+refuses one with its own sentence. No spec this repository ships produces one — the
+rig it was written from is a probe `selftest.ts` generates and nothing else can
+invoke — so the sentence is described here rather than transcribed.
+
+**What it carries**, in the order it says it: `BETWEEN key <i> (t=…s) and key <j>
+(t=…s)` where a key refusal puts one index; the time the closed form solved for, and
+how far along the segment that is — or `(a stepped segment)` instead, which
+interpolates nothing and holds the earlier key's geometry across the span; the
+reversed count out of the triangle total, with the first four named and each one's
+vertex ids and its signed area before and after; `NO KEY LANDS THERE` in those words,
+then whether the runtime interpolates across the span or holds it; the alpha read at
+that same instant, present only where it is not 1; and the ways out — for an
+interpolating span the four the table below gives, the fade one among them only
+where the alpha is not 1, and for a stepped one the key it holds instead, with
+`invariants.deformMayFold` the last resort either way.
+[`src/validate.ts`](../src/validate.ts) builds it, beside the key sentence §4.11.2
+quotes.
 
 **What to change when you see it**, in the order worth trying:
 
@@ -2833,7 +2943,13 @@ value = from + (time − to) / scale         what A39 sets the dial to
 
 🔒 **The `DEFORM` block prints the frame on every key**, because the derivation
 changed and a block that went on printing the same figures under a changed meaning
-would be worse than the red it replaced:
+would be worse than the red it replaced. `gallery/look`'s `turn` is the animation
+a slider applies, and this is one of its keys:
+
+```bash
+bun cli.ts explain --rig gallery/look/rig.json \
+                   --motion gallery/look/motion.json --out /tmp/explain-look
+```
 
 ```
   DEFORM  turn  default/head/head  key 6  t=1.900000  transform yaw  depth=true degrees=19
@@ -2939,6 +3055,21 @@ deformDialsDisagreed=1 deformDialDisagreed=dial|artifact:knob.x@2.321e-8|reaches
 - 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
@@ -3140,6 +3271,7 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 
 The report prints one line per assertion:
 
+**No run reproduces this:** assembled — one line of each verdict kind; the `PASS` and the `PROF` are verbatim from a `build` this page states, the `SKIP` is cut at the ellipsis and only `--profile spine-html` prints it, and the `FAIL` is invented, because a green build prints none
 ```
   PASS  A08_REGION_NAMES_MATCH_ATTACHMENTS
   SKIP  A21_MESH_RIM_PINNED: the skeleton has no weighted mesh attachment, …