spine-rigc 0.19.0 → 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
 
@@ -2670,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
@@ -2939,6 +3005,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

package/docs/FACE.md

@@ -364,12 +364,54 @@ geometry ([AUTHORING §3.4](AUTHORING.md)):
 ```
         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
 ```
 
 Read it as a fact about **the sheet**. If the number is too small, the fix is in
 the map — flatten it where the part curves away — and not in the lattice.
 
+#### ⚠️ That rule presumes the map is continuous
+
+"Flatten it where the part curves away" is an edit to a **surface**, and it
+assumes there is one under the whole mesh. A depth sheet estimated from a
+picture of cut-out art is not a surface: it is piecewise, with a **cliff at every
+occlusion boundary** — figure against background at the silhouette, and one part
+of the figure over another wherever they overlap. There is nothing to flatten
+across a cliff, because the two sides are not two ends of a slope. They are two
+different things at two different depths, and a 2.5D turn does not model
+occlusion at all.
+
+The ceiling reads the cliff, correctly, and the number it reports is real:
+walked one degree at a time through the survey `A39` refuses from, a reported
+1.936° admits +1° and reverses 8 triangles at +2°. **The rig genuinely folds at
+two degrees.** What is wrong is not the instrument and not the mesh — it is that
+the question "how far can this turn" has no answer for an input with a
+discontinuity in it, and the ceiling proves it by halving with every doubling of
+the lattice: measured tangent ratios 2.02 / 1.95 / 2.02, `tan t ∝ h` exactly,
+with no limit to converge to.
+
+🚨 **And the two figures beside the ceiling both call it healthy.** The 1st
+percentile reads 1.02–2.17, which is a band reaching the limit together — and it
+*is* a band, because an outline is long. The depth step reads 148–252 levels of
+255, far above the quantisation floor — and the sheet really did say that much,
+in one step. Divided by the range, the same number says the opposite: the step
+share pins at **0.92–0.99** where rigc's own gallery reads 0.112 and 0.468.
+
+⇒ Two ways out, and **neither of them is flattening**:
+
+- **Mesh only what is continuous.** One face, one lock, one sleeve — a region
+  the sheet describes without a jump in it — rather than a lattice over a whole
+  figure. Whether a mask that tight gives a usable angle is not yet measured;
+  the mask has to be painted rather than thresholded, for the reason `soft`
+  is painted (§3.4's `soft` block).
+- **State a sheet that was authored rather than estimated.** §2.2's raised
+  cosine holds 63–64° from 289 vertices to 32,761 because somebody drew its
+  slope. That is the input this whole section is about.
+
+⛔ rigc will not decide that your sheet is the wrong kind of thing. It has every
+authority to say what it measured, and the step share is that
+([#448](https://github.com/firejune/rigc/issues/448)).
+
 📐 Method, harness and the full ladders live in the repository rather than in
 this package, as
 [`bench/studies/2026-09-05-density`](https://github.com/firejune/rigc/tree/main/bench/studies/2026-09-05-density) —
@@ -394,17 +436,22 @@ the range describes the same surface and reports 5.8° less of it. Method and
 ladders:
 [`bench/studies/2026-09-05-noise`](https://github.com/firejune/rigc/tree/main/bench/studies/2026-09-05-noise).
 
-⭐ **And you do not have to guess which of the two you are looking at.** The two
-lines under the ceiling say it ([#412](https://github.com/firejune/rigc/issues/412)):
-the **1st percentile over the ceiling** is near 1 when a band of the mesh reaches
-the limit together, which is a form, and near 10 when one triangle does, which is
-a texel — 1.003 against 10.652 for the two sheets above. The **depth step across
-the triangle that folds first**, in levels, is the other half: below about 3 the
-ceiling is quantisation, and at 1 it is `atan(255·h / zScale)` and carries nothing
-about the form at all. Both are reports and neither moves the ceiling — ⛔ rigc
-will not filter a depth map, because a smoothed measurement would describe a
-surface the deform key is not built from and `A39` would go on refusing at the
-raw angle. [AUTHORING §3.4](AUTHORING.md) has the reading table.
+⭐ **And you do not have to guess which of the three you are looking at.** The
+lines under the ceiling say it
+([#412](https://github.com/firejune/rigc/issues/412),
+[#448](https://github.com/firejune/rigc/issues/448)): the **1st percentile over
+the ceiling** is near 1 when a band of the mesh reaches the limit together and
+near 10 when one triangle does, which is a texel — 1.003 against 10.652 for the
+two sheets above. The **depth step across the triangle that folds first**, in
+levels, is the second: below about 3 the ceiling is quantisation, and at 1 it is
+`atan(255·h / zScale)` and carries nothing about the form at all. The **same step
+over the range the mesh sampled** is the third, and it is the one that separates
+a steep surface from a cliff — a form's halves with every doubling of the lattice
+while its angle settles, a discontinuity's does not move while its angle halves.
+All three are reports and none of them moves the ceiling — ⛔ rigc will not filter
+a depth map, because a smoothed measurement would describe a surface the deform
+key is not built from and `A39` would go on refusing at the raw angle.
+[AUTHORING §3.4](AUTHORING.md) has the reading table.
 
 ---
 
@@ -872,7 +919,7 @@ anything:
 Three collisions survive there: `headroll` rotate in all three, `brows`
 translatey in two, and the locks' rotate in two. ⚠️ **On plain Spine the fixes
 are ordinary — `MixBlend.add` on the layered track, or splitting a bone into a
-stack (`headroll_idle` under `headroll_scene`) — but both are runtime or rig
+stack (`headroll_idle` under `headroll_layer`) — but both are runtime or rig
 decisions the motion spec cannot express, so nothing warns an author that two of
 their animations will fight.**
 
@@ -1195,7 +1242,7 @@ by name, on both its keys, with the triangles listed:
 ```
 FAIL  A39_DEFORM_KEEPS_TRIANGLE_WINDING: animation "turn" deform head/head key 1
       (t=0.6200000047683716s): 8 of 32 triangle(s) reverse winding — triangle 0
-      [0,5,6] 1890.000 -> -544.548px²; …
+      [0,15,16] 1890.000 -> -544.548px²; …
 ```
 
 and builds (a) and the good one both still PASS it, because **an inverted band is

package/docs/SPEC_COVERAGE.md

@@ -1,13 +1,6 @@
 # Spine 4.3 export-format surface vs. rigc coverage vs. the example ladder
 
-<!--
-  The marker below is the machine half of the 🔼 note further down: this file's
-  statements are a dated snapshot, not current state, so the selftest's currency
-  gate (CUR01–CUR06, issue #360) leaves its numbers alone. Do NOT copy it into a
-  document that describes how rigc behaves today — that is the whole class the
-  gate exists to catch.
--->
-<!-- currency: dated-record -->
+**A dated record:** what this page states was measured on the date it carries and is not kept current, so the selftest's currency gate leaves its figures alone.
 
 Research note, 2026-08-22. A survey, not a plan: it establishes what the 4.3 export format can hold,
 what rigc emits today, and what the official example projects actually use — so the gap list is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.19.0",
+  "version": "0.20.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

@@ -910,6 +910,21 @@ function partPlate(img: CompiledImage): Plate {
   return img.atlas === undefined ? page : extractRegion(page, img.atlas);
 }
 
+/**
+ * A part's alpha channel on its own grid — where the drawing is, and where it
+ * is not.
+ *
+ * Two readers want exactly this and they used to be one inline loop and one
+ * absence: the contour generator traces it, and `sampleMeshDepth` counts the
+ * vertices whose depth came from outside it (issue #449). One function so the
+ * two cannot come to mean different things by "the part draws here".
+ */
+function plateAlpha(plate: Plate): Uint8Array {
+  const alpha = new Uint8Array(plate.width * plate.height);
+  for (let i = 0; i < alpha.length; i++) alpha[i] = plate.data[i * 4 + 3];
+  return alpha;
+}
+
 export function compile(opts: CompileOptions): CompileResult {
   const rigPath = resolve(opts.rigPath);
   const motionPath = resolve(opts.motionPath);
@@ -2711,9 +2726,40 @@ function buildGeneratedMesh(
  * sheet that carries an alpha channel is held to it, and the fix — dilate the
  * sheet past the mesh margin — is named in the message.
  *
- * A sheet with no alpha channel covers its whole grid by construction and the
- * third check has nothing to test; what the background level means is then the
- * author's statement, and `range` in the report is where it shows up.
+ * ## The count beside the third refusal, and why it is a count (issue #449)
+ *
+ * A sheet with no transparent texel anywhere covers its whole grid by
+ * construction, so the third refusal has nothing to hold it to and skips. That
+ * is the encoding a monocular depth estimator produces — a full-frame opaque
+ * render with the background in it — and it is a legitimate statement, so
+ * skipping the refusal is right. What was wrong is that nothing took its place:
+ * measured on one cell and one depth field, the same 54 %-background mesh is a
+ * named refusal when the sheet's alpha is cut to the art and a green build when
+ * it is 255 everywhere.
+ *
+ * ⚠️ **`range` is not where that shows up**, and this header said it was until
+ * #449 measured it. On the build above `range` reads `[0, 223.97]` of a stated
+ * 224 — full, healthy — because the background is a legitimate depth value and
+ * a map that is half background has exactly as full a range as one that is all
+ * subject. "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**.
+ *
+ * ⇒ what shows it is `undrawn`: how many of the mesh's vertices take their
+ * depth from a texel **the part image does not draw**, over the same four
+ * bilinear taps the refusal walks. That is a measurement, not a guess, so it is
+ * reported and never refused — a full-frame sheet is a statement rigc has no
+ * authority to guess away.
+ *
+ * 🔸 It is a raw count with no reach subtracted from it, which is why 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. That is the true reading of that geometry rather than a defect
+ * in the count — the rim's depth really did come from off the art, which is
+ * benign on a sheet dilated past the margin and is the whole failure on a
+ * full-frame estimate. Discounting the margin would be borrowing a number
+ * authored for the trace to mean "close enough" for the sheet, and rigc does
+ * not invent tolerances.
  */
 function sampleMeshDepth(
   spec: NonNullable<Extract<NonNullable<RigMeshAttachment['generator']>, { kind: 'contour' }>['depth']>,
@@ -2734,6 +2780,14 @@ function sampleMeshDepth(
    * units `z` is already in before it is taken.
    */
   toBind: (px: number, py: number) => readonly [number, number],
+  /**
+   * The PART's own alpha channel, in the same grid the sheet is sampled in —
+   * what the drawing actually covers, as against what the sheet covers.
+   *
+   * The two are different questions and the header says why. This one has no
+   * refusal behind it: it is counted, reported, and left to the author.
+   */
+  partAlpha: Uint8Array,
   partWidth: number,
   partHeight: number,
   where: string,
@@ -2771,19 +2825,32 @@ function sampleMeshDepth(
   // Every texel a bilinear tap touches has to be covered, not just the nearest
   // one: a vertex half a pixel outside the sheet blends real depth with the
   // background and lands somewhere neither states.
+  //
+  // 🔒 One walk, one footprint, two readings. `cover` is the SHEET's alpha and
+  // decides a refusal; `partAlpha` is the PART's and decides a count. They are
+  // deliberately the same four taps and the same clamp — the second is the
+  // first's instinct applied to the other input (issue #449), and writing it as
+  // a second loop is how the two would come to disagree about which texels a
+  // vertex reads.
+  const cx = (i: number): number => (i < 0 ? 0 : i > partWidth - 1 ? partWidth - 1 : i);
+  const cy = (j: number): number => (j < 0 ? 0 : j > partHeight - 1 ? partHeight - 1 : j);
   const uncovered: number[] = [];
-  if (!opaqueEverywhere) {
-    const cx = (i: number): number => (i < 0 ? 0 : i > partWidth - 1 ? partWidth - 1 : i);
-    const cy = (j: number): number => (j < 0 ? 0 : j > partHeight - 1 ? partHeight - 1 : j);
-    for (let v = 0; v < points.length; v++) {
-      const x0 = Math.floor(points[v][0] - 0.5);
-      const y0 = Math.floor(points[v][1] - 0.5);
-      let covered = true;
-      for (const [dx, dy] of [[0, 0], [1, 0], [0, 1], [1, 1]] as const) {
-        if (cover[cy(y0 + dy) * partWidth + cx(x0 + dx)] !== 255) covered = false;
-      }
-      if (!covered) uncovered.push(v);
+  let undrawn = 0;
+  for (let v = 0; v < points.length; v++) {
+    const x0 = Math.floor(points[v][0] - 0.5);
+    const y0 = Math.floor(points[v][1] - 0.5);
+    let covered = true;
+    let drawn = true;
+    for (const [dx, dy] of [[0, 0], [1, 0], [0, 1], [1, 1]] as const) {
+      const at = cy(y0 + dy) * partWidth + cx(x0 + dx);
+      if (cover[at] !== 255) covered = false;
+      // Zero, not a threshold: "the part image draws nothing here" is a fact
+      // about the file, and any other cut-off would be rigc deciding how faint
+      // a texel has to be before it stops counting as art.
+      if (partAlpha[at] === 0) drawn = false;
     }
+    if (!opaqueEverywhere && !covered) uncovered.push(v);
+    if (!drawn) undrawn++;
   }
   if (uncovered.length > 0) {
     const first = uncovered[0];
@@ -2825,6 +2892,7 @@ function sampleMeshDepth(
       zScale: spec.zScale,
       tone,
       range: [r6(lo), r6(hi)],
+      undrawn,
       ceiling: turnCeiling(
         points.map(([px, py]) => toBind(px, py)),
         z,
@@ -3064,6 +3132,7 @@ function buildGridAttachment(
           geometry.points,
           geometry.triangles,
           (px, py) => toBoneLocal(anchor, anchor.worldX + px * toArt - w / 2, anchor.worldY + h / 2 - py * toArt),
+          plateAlpha(plate),
           plate.width,
           plate.height,
           where,
@@ -3160,8 +3229,7 @@ function buildContourAttachment(
   // none — so "this part has no silhouette to trace" is a question about pixels,
   // and `buildContourMesh` refuses it by counting them.
   const plate = partPlate(img);
-  const alpha = new Uint8Array(plate.width * plate.height);
-  for (let i = 0; i < alpha.length; i++) alpha[i] = plate.data[i * 4 + 3];
+  const alpha = plateAlpha(plate);
 
   const margin = generator.margin ?? CONTOUR_DEFAULTS.margin;
   const maxVertices = generator.maxVertices ?? CONTOUR_DEFAULTS.maxVertices;
@@ -3219,6 +3287,7 @@ function buildContourAttachment(
           geometry.points,
           geometry.triangles,
           (px, py) => toBoneLocal(anchor, anchor.worldX + px * toArt - w / 2, anchor.worldY + h / 2 - py * toArt),
+          alpha,
           plate.width,
           plate.height,
           where,

package/src/depth.ts

@@ -374,14 +374,20 @@ const CEILING_AREA_FLOOR = 1e-6;
  * Where one triangle turns inside out, which triangle that is — and, beside it,
  * what the REST of this axis and side's triangles do.
  *
- * The first four fields are about one triangle. `count` and `p1` are about the
- * population it is the minimum of, and they are here because the minimum alone
- * cannot answer the question an author actually has: `degrees` is the same
- * number whether a whole band of the mesh reaches the limit together or one
- * triangle does, and those are a form and a bad texel respectively
+ * Everything down to `stepShare` is about one triangle. `count` and `p1` are
+ * about the population it is the minimum of, and they are here because the
+ * minimum alone cannot answer the question an author actually has: `degrees` is
+ * the same number whether a whole band of the mesh reaches the limit together
+ * or one triangle does, and those are a form and a bad texel respectively
  * ([#412](https://github.com/firejune/rigc/issues/412),
  * `bench/studies/2026-09-05-noise` §6).
  *
+ * ⚠️ And a band is not sufficient evidence of a form either, which is what
+ * `stepShare` is here for: an OUTLINE is a band, so a mesh whose ceiling is set
+ * by the occlusion edge of a cut-out reads `p1/degrees` near 1 and a `depthStep`
+ * of most of the sheet's range — both of the older figures reading *healthy* on
+ * the same measurement ([#448](https://github.com/firejune/rigc/issues/448)).
+ *
  * ⛔ Neither figure changes `degrees`, and neither is a threshold. rigc does not
  * have the authority to guess its input away, so nothing here filters,
  * smooths or rejects a sample — the ceiling stays the raw sheet read through
@@ -407,6 +413,42 @@ export interface FoldLimit {
    * with no form left in it (`bench/studies/2026-09-05-noise` §3).
    */
   depthStep: number;
+  /**
+   * `depthStep` over the depth range this mesh actually sampled — what fraction
+   * of everything the sheet said across the whole part it said across the one
+   * triangle that folds first.
+   *
+   * ⭐ The figure that tells a form from a cliff, and it is the one reading the
+   * other two cannot give ([#448](https://github.com/firejune/rigc/issues/448)).
+   * A form has a slope, so refining the lattice halves the step and halves this
+   * with it while the angle converges. A **discontinuity has no slope**: the
+   * step stays the whole range however fine the lattice gets, this figure pins
+   * near 1, and the ceiling halves with every doubling instead of converging —
+   * `tan t ∝ h`, an angle that describes nothing at any density.
+   *
+   * ⚠️ **The ceiling is not wrong when this reads high; the input is not a
+   * surface.** Measured on estimated sheets: reported 1.936°, and the runtime
+   * admits +1° and reverses 8 triangles at +2°. The rig genuinely folds at two
+   * degrees. What a `depthStep` near the whole range means is an occlusion
+   * boundary — figure against background, or one part of a figure over
+   * another — and a 2.5D turn does not model occlusion at all, so **no angle is
+   * the right one to quote for it**. The fix is upstream of the ceiling: mesh
+   * only what is continuous, or state a sheet that was authored rather than
+   * estimated.
+   *
+   * 🔒 In (0, 1] by construction, never a division by zero. `depthStep` is a
+   * difference between two of this mesh's own `z` values, so the span over all
+   * of them is at least as large; and a fold only exists where the axis area
+   * with `z` substituted in is non-zero, which needs two vertices of the
+   * triangle at different depths — so a mesh with no span reports no fold and
+   * never reaches the divide.
+   *
+   * ⛔ A report and never a threshold. rigc does not decide that an author's
+   * sheet is the wrong kind of thing; nothing here filters, and nothing here
+   * moves a ceiling. What to read off the number is stated in
+   * `docs/AUTHORING.md` §3.4.
+   */
+  stepShare: number;
   /** How many triangles fold on this axis and side — the population below. */
   count: number;
   /**
@@ -509,9 +551,26 @@ export interface TurnCeiling {
  * triangle, which is a texel. A `depthStep` of one level is `atan(255·h/zScale)`
  * and says nothing about the form at all.
  *
- * ⛔ Both are reports. Nothing here filters the sheet, and nothing here moves a
- * ceiling: a smoothed measurement would describe a surface the deform key is
- * not built from, and would part company with the gate that reads the raw one.
+ * ## What a band cannot say either (issue #448)
+ *
+ * Both of those figures read *healthy* on an estimated depth sheet over cut-out
+ * art, and they do not merely stay silent — they affirm it. `p1/degrees` comes
+ * back at 1.02–2.17, which reads as a band; `depthStep` at 148–252 levels of
+ * 255, which reads as plenty said. It **is** a band, because an outline is long,
+ * and the sheet did say a great deal across that triangle — it said the whole
+ * distance from the figure to the background in one step.
+ *
+ * So each `FoldLimit` also carries `stepShare`, the same step divided by the
+ * range this mesh sampled. A form's halves per refinement while its angle
+ * converges; a discontinuity's pins near 1 while the angle halves. Measured:
+ * rigc's own gallery 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 sheets 0.92–0.99.
+ *
+ * ⛔ All three are reports. Nothing here filters the sheet, and nothing here
+ * moves a ceiling: a smoothed measurement would describe a surface the deform
+ * key is not built from, and would part company with the gate that reads the
+ * raw one.
  *
  * @param points Vertices in the BIND space the deform offsets are authored in.
  *   Areas are translation-invariant, so the origin does not matter; the scale
@@ -546,6 +605,18 @@ export function turnCeiling(
   }
   const floor = largest * CEILING_AREA_FLOOR;
 
+  // The denominator `stepShare` is taken against: the depth range this mesh
+  // sampled, which is `range` in the report read off the same array. Taken over
+  // the WHOLE mesh rather than per triangle, because the question the figure
+  // answers is how much of what the sheet said here one triangle said.
+  let zLo = Infinity;
+  let zHi = -Infinity;
+  for (const d of z) {
+    if (d < zLo) zLo = d;
+    if (d > zHi) zHi = d;
+  }
+  const zSpan = zHi - zLo;
+
   // One list per axis and side, so the ceiling can say whether it is the floor
   // of a BAND or of a single triangle. Nothing here filters: every measurable
   // triangle goes in exactly once, in triangle order, and the sort below is
@@ -591,7 +662,11 @@ export function turnCeiling(
       // `count` and `p1` are filled once the whole population is in; a minimum
       // cannot know its own percentile while it is still being found.
       if (held === null || degrees < held.degrees) {
-        out[axis][side] = { degrees, triangle: n, ids, depthStep, count: 0, p1: null };
+        // `zSpan` cannot be zero here: `aAxis !== 0` needs two of this
+        // triangle's vertices at different depths, and the span over the whole
+        // mesh is at least that difference. A guard would be an unreachable
+        // branch, and an unreachable branch is not a control.
+        out[axis][side] = { degrees, triangle: n, ids, depthStep, stepShare: depthStep / zSpan, count: 0, p1: null };
       }
     }
   }

package/src/types.ts

@@ -1057,15 +1057,6 @@ export interface CompileResult {
      * authored mesh was not traced.
      */
     holePixels?: number;
-    /**
-     * What a depth map put on this mesh's vertices, when one was named.
-     *
-     * The digest is over the levels rather than the file, so a re-encode of the
-     * same sheet reports the same provenance; `range` is what was actually
-     * sampled, which is the number that says whether the map covers the part or
-     * a corner of it. Absent when no map was named — never zeroes, which would
-     * read as "sampled and found flat".
-     */
     /**
      * The soft region a `soft` block carried to its own bone, when one was
      * named — the mask, its digest, and how many vertices it reached.
@@ -1075,6 +1066,18 @@ export interface CompileResult {
      * and a nose does not wobble.
      */
     soft?: { mask: string; digest: string; bone: string; carried: number; ramped: number };
+    /**
+     * What a depth map put on this mesh's vertices, when one was named.
+     *
+     * The digest is over the levels rather than the file, so a re-encode of the
+     * same sheet reports the same provenance; `range` is what was actually
+     * sampled. Absent when no map was named — never zeroes, which would read as
+     * "sampled and found flat".
+     *
+     * ⚠️ This comment sat above `soft` rather than above the field it describes
+     * until issue #449 came to add to it, which is the same drift `CUR07` was
+     * built for one file over — nothing derives a doc comment's neighbour.
+     */
     depth?: {
       /** The sheet, as written in the spec. */
       image: string;
@@ -1086,6 +1089,24 @@ export interface CompileResult {
       tone: { gamma: number; contrast: number; bias: number };
       /** Least and greatest `z` over the mesh's vertices, in attachment units. */
       range: [number, number];
+      /**
+       * How many of the mesh's vertices took their depth from a texel **the
+       * part image does not draw** (issue #449).
+       *
+       * ⚠️ Not what `range` says, and this is the field that exists because
+       * `range` was claimed to say it. A map that is half background has
+       * exactly as full a range as one that is all subject, because a
+       * background level is a legitimate depth — so a full-frame sheet over a
+       * cut-out part reports a healthy `[0, 223.97]` of 224 with 54 % of the
+       * mesh reading background.
+       *
+       * A count and never a refusal: the same defect is already a named refusal
+       * when the sheet's alpha is cut to the art, and a sheet that is opaque
+       * everywhere is a statement rigc has no authority to guess away. Zero is
+       * a real answer here rather than an absence — every mesh that names a
+       * depth map also names an image, so the measurement is always taken.
+       */
+      undrawn: number;
       /**
        * The turn this geometry takes on this sheet before a triangle reverses,
        * per axis and per direction — `src/depth.ts`'s `turnCeiling`.