spine-rigc 0.16.0 → 0.18.0

package/README.md

@@ -48,13 +48,30 @@ it cuts both ways:
 
 - The output loads in any Spine runtime, and it **imports into the Spine editor**.
   A compiled rig is a starting point on a timeline, not a finished shot — **an AI
-  drafts, a human refines in the editor**. rigc is complementary to the editor. It
-  is not a replacement for it, and it is not a way around one.
+  drafts, a human refines in the editor**. That hand-off is what emitting somebody
+  else's format buys, and `tools/editor_roundtrip.ts` measures that it survives
+  the trip in both directions.
 - rigc **links `@esotericsoftware/spine-core`** to validate what it emits — the
   round-trip through the official parser is the only reason its output can be
   trusted at all. So the [Spine Runtimes License Agreement](https://esotericsoftware.com/spine-runtimes-license)
   applies to rigc exactly as it applies to any other runtime integration.
 
+🗓️ **One sentence left this section on 2026-09-05, and its removal is a decision
+rather than a tidy-up.** It read *"rigc is complementary to the editor. It is not
+a replacement for it, and it is not a way around one."* That was a claim about
+what rigc would never become, and
+[#380](https://github.com/firejune/rigc/issues/380) — a format-agnostic core with
+its own format and web player, Spine kept as one backend among others — is a
+course the claim cannot survive. A promise the roadmap contradicts is worth less
+than no promise, so it is retired rather than reworded
+([#398](https://github.com/firejune/rigc/issues/398)). What a reader can check is
+unchanged: rigc emits Spine skeleton data, links `spine-core`, validates through
+it with no flag that turns that off, and carries the licence obligation the next
+section states in full. A backend emitting something other than Spine data would
+have no spine-core to check it against, and #380 treats an oracle of its own as
+the prerequisite for shipping one — nothing here makes an unchecked emit path
+acceptable.
+
 ### Licensing, stated plainly
 
 rigc's own code is MIT (see [LICENSE](LICENSE)). That says nothing about Spine, and
@@ -488,9 +505,9 @@ work on any frames you have, and `bench` is a repository workflow that needs a c
 and `bun run fetch-examples`. The reasoning behind all three is in
 [the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).
 
-`build` and `validate` both default to `--profile spine` — the 25 validity rules, which
+`build` and `validate` both default to `--profile spine` — the 26 validity rules, which
 ask *is this valid Spine 4.3 that any runtime plays correctly?* `--profile spine-html`
-adds all 40: the other 15 are one renderer's policy and one canvas budget's, and they
+adds all 41: the other 15 are one renderer's policy and one canvas budget's, and they
 fire on perfectly correct editor-produced Spine data, so reach for that profile when
 you are shipping into *that* project rather than to be thorough. A report always names
 the profile it ran and lists what that profile left out.
@@ -501,6 +518,50 @@ relative to the `cuts.json` file itself, so the table lives with the project tha
 the art. Its shape is under
 [Usage](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md#usage).
 
+### The editor round trip — for a licence holder, never in CI
+
+`tools/editor_roundtrip.ts` drives the loop the output's whole premise rests on:
+build → **import into the Spine editor** → export back to JSON → gate, `diff`,
+`render` and `check` the export against the build it came from.
+
+```
+bun cli.ts build --rig … --motion … --out build/ --copy-images
+bun tools/editor_roundtrip.ts --build build/ --editor /Applications/Spine.app/Contents/MacOS/Spine
+```
+
+It prints the import and export exit codes, the validator's verdict on the
+export, every `diff` measure that moved, `check`'s mean MAE and worst drift per
+animation, and a field-by-field list of what the editor rewrote. On its first
+run it found three emitter defects — [#368](https://github.com/firejune/rigc/issues/368),
+[#369](https://github.com/firejune/rigc/issues/369),
+[#370](https://github.com/firejune/rigc/issues/370) — and then showed that a
+human edit made in the editor survives the trip back.
+
+🔒 **It requires a licensed Spine editor on the machine, by construction**, and
+drives only the [documented command line](https://esotericsoftware.com/spine-command-line-interface)
+— never the UI, and it produces nothing the editor did not produce. With no
+editor present it refuses by name and exits non-zero, and so does the **trial**:
+the trial cannot save projects or export animation data, so the refusal names
+what it found — the executable, the bundle, the `CFBundleName` that bundle
+declares, or the banner the binary prints about itself — rather than starting it
+and failing downstream. Both refusals point at `--exported <file>`, which
+measures an export the editor already made and is the half of this tool that
+needs no editor at all.
+
+⛔ **The round trip is not, and must not become, a selftest control.** `bun run
+selftest` is self-contained and CI has no editor; a control that needed one would
+report SKIP for ever, which is how a gate comes to look kept while checking
+nothing. Run the round trip by hand, on a machine that has the editor. Its
+**refusals** are gated, because they are the half a machine with no editor can
+answer for: the suite points the tool at stubs in a temp directory and reads what
+comes back, including the case that must *not* be refused — an editor at an
+unfamiliar path, which is who `--editor` exists for.
+
+⚠️ Build with `--copy-images`. An ordinary build's atlas names its pages by a
+relative path back to the art directory, and the round trip copies that atlas to
+a directory at another depth — the tool refuses such a build by name rather than
+letting `A17` blame the editor for the harness's own doing.
+
 ## Documentation
 
 | Document | For |
@@ -512,7 +573,7 @@ the art. Its shape is under
 | 📥 **[docs/INGEST.md](docs/INGEST.md)** | **working with a skeleton you did not author.** What every command can and cannot do with a foreign `skeleton.json`, reading it with the toolchain, transcription as the route that makes it yours, what each validator complaint means on an export, and the re-pivot/rename/extend recipes. Ships in the package too |
 | 🤖 **[docs/PROMPTING.md](docs/PROMPTING.md)** | **handing the authoring to an AI agent** — the prompt clauses a measured pilot run paid for, and what you can leave unsaid. Ships in the package too |
 | 🔬 **[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 40 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 |
+| 🎓 **[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 |
 
 ## Why you can trust the output
@@ -567,7 +628,7 @@ quality."* All six, with their verdicts, are in
 [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md).
 
 The whole dossier — the yardstick, `diff` and `check` and what neither of them can
-see, every rung, the run viewer, the 40 assertions and the selftest behind them — is
+see, every rung, the run viewer, the 41 assertions and the selftest behind them — is
 [docs/BENCHMARK.md](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).
 Live rung status is
 [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md).

package/cli.ts

@@ -61,8 +61,10 @@ import { compile, CompileError, type CompileOptions } from './src/compile.ts';
 import {
   skeletonDataFromText,
   surveyDeformKeys,
+  unreachableWhy,
   type DeformExtreme,
   type DeformKeyMeasure,
+  type DeformSpan,
 } from './src/deformmeasure.ts';
 import { diffLines, diffSkeletons, reportedFigures, sectionFigures, type DiffReport } from './src/diff.ts';
 import { copyAtlasImages } from './src/emit.ts';
@@ -112,8 +114,16 @@ import {
   type FramesSidecar,
   type FrameSet,
 } from './src/render.ts';
-import { CLI_DEFAULT_PROFILE, reportLines, validate, VALIDATE_PROFILES, type ValidateProfile } from './src/validate.ts';
+import {
+  assertionCountForProfile,
+  CLI_DEFAULT_PROFILE,
+  reportLines,
+  validate,
+  VALIDATE_PROFILES,
+  type ValidateProfile,
+} from './src/validate.ts';
 import { parseMotionSpec } from './src/motion.ts';
+import { depthStepLevels, type FoldLimit, type TurnCeiling } from './src/depth.ts';
 import type { CompileResult } from './src/types.ts';
 
 /**
@@ -407,10 +417,109 @@ function runGate(
  * unconditionally, so a build whose only mesh was a ribbon or a contour got a
  * sentence about a rim ring and a seam it does not have.
  */
+/**
+ * What a depth map and a soft region put on a mesh, when it named either.
+ *
+ * The digests are the reason this prints at all: a claim about a rig can name
+ * WHICH sheet produced it, and two runs a reader believes differ can be shown to
+ * have read the same pixels. The ranges and counts are what say the input
+ * reached the geometry rather than merely being resolved — a `carried 0` never
+ * gets here (it is refused) and a `ramped 0` is a hard-edged mask, which is
+ * legal and usually not what somebody meant.
+ */
+/**
+ * One axis's two ceilings, as `+31.41 / -18.03`, or what is unbounded on it.
+ *
+ * ⚠️ `none` and a number are different claims and are printed differently. A
+ * sheet with no gradient along an axis cannot fold anything on it AT ANY ANGLE,
+ * which is a fact about the sheet worth reading; printing `90` for it would be
+ * a limit nothing measured.
+ */
+function ceilingPair(axis: { positive: FoldLimit | null; negative: FoldLimit | null }): string {
+  const one = (l: FoldLimit | null, sign: string) => (l === null ? `${sign}none` : `${sign}${l.degrees.toFixed(2)}°`);
+  return `${one(axis.positive, '+')} / ${one(axis.negative, '-')}`;
+}
+
+/**
+ * The same axis's two 1st percentiles, each with its ratio to the ceiling above
+ * it and the population it came out of — `+64.80° x1.003 of 5988`.
+ *
+ * ⭐ The ratio is the whole point and it is printed rather than judged. A
+ * ceiling set by the FORM is the floor of a band: the steepest region of a
+ * smooth sheet has area, so the 1st percentile sits a fraction of a percent
+ * above the minimum. A ceiling set by one bad texel has 99 % of the mesh
+ * surviving to the form's angle while the reported number collapses — 64.58°
+ * against 6.08° for one texel of 160,000, with the percentile unmoved at 64.80°
+ * in both ([#412](https://github.com/firejune/rigc/issues/412),
+ * `bench/studies/2026-09-05-noise` §6).
+ *
+ * Three spellings, three different claims, for the reason `ceilingPair` prints
+ * `none` rather than 90: `+none` is a side nothing folds on at all, `+unranked
+ * of 36` is a side whose population is too small for a first percentile to be
+ * anything but the minimum itself, and a number is a measurement.
+ *
+ * ⛔ No threshold lives here. What ratio means what is in `docs/AUTHORING.md`
+ * §3.4, because a number rigc printed an adjective beside would be a policy the
+ * compiler invented out of a measurement — and `A39` would go on refusing at the
+ * raw angle either way.
+ */
+function spreadPair(axis: { positive: FoldLimit | null; negative: FoldLimit | null }): string {
+  const one = (l: FoldLimit | null, sign: string) =>
+    l === null
+      ? `${sign}none`
+      : l.p1 === null
+        ? `${sign}unranked of ${l.count}`
+        : `${sign}${l.p1.toFixed(2)}° x${(l.p1 / l.degrees).toFixed(3)} of ${l.count}`;
+  return `${one(axis.positive, '+')} / ${one(axis.negative, '-')}`;
+}
+
+/** The tightest of the four, so the line that names a triangle names the right one. */
+function tightestFold(c: TurnCeiling): { kind: string; sign: string; limit: FoldLimit } | null {
+  const all = [
+    { kind: 'yaw', sign: '+', limit: c.yaw.positive },
+    { kind: 'yaw', sign: '-', limit: c.yaw.negative },
+    { kind: 'pitch', sign: '+', limit: c.pitch.positive },
+    { kind: 'pitch', sign: '-', limit: c.pitch.negative },
+  ].filter((e): e is { kind: string; sign: string; limit: FoldLimit } => e.limit !== null);
+  if (all.length === 0) return null;
+  return all.reduce((best, e) => (e.limit.degrees < best.limit.degrees ? e : best));
+}
+
+function meshDepthNote(m: CompileResult['meshes'][number]): string {
+  const parts: string[] = [];
+  if (m.depth) {
+    parts.push(
+      `depth "${m.depth.image}" ${m.depth.digest} near=${m.depth.near} zScale=${m.depth.zScale} ` +
+        `z=[${m.depth.range[0]}, ${m.depth.range[1]}]`,
+    );
+    const c = m.depth.ceiling;
+    parts.push(`turn ceiling  yaw ${ceilingPair(c.yaw)}   pitch ${ceilingPair(c.pitch)}`);
+    const worst = tightestFold(c);
+    if (worst !== null) {
+      parts.push(`  1st pct     yaw ${spreadPair(c.yaw)}   pitch ${spreadPair(c.pitch)}`);
+    }
+    parts.push(
+      worst === null
+        ? `              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` +
+          `${c.degenerate ? `; ${c.degenerate} triangle(s) too flat in setup to measure` : ''}`,
+    );
+  }
+  if (m.soft) {
+    parts.push(
+      `soft "${m.soft.mask}" ${m.soft.digest} -> ${m.soft.bone}, ${m.soft.carried} carried / ${m.soft.ramped} in the falloff`,
+    );
+  }
+  return parts.length === 0 ? '' : `\n        ${parts.join('\n        ')}`;
+}
+
 const MESH_KIND_NOTES: Record<CompileResult['meshes'][number]['kind'], string> = {
   ring: 'ring      rim ring pinned on the window edge, seam ring pinned on the mask contour, aperture moves',
   ribbon: 'ribbon    entry row pinned, rows share their weights so the strip lengthens without widening',
   contour: 'contour   the art\'s own silhouette, every vertex pinned to the slot bone (geometry, not a deformation)',
+  grid: 'grid      a lattice over the part window at stated column and row positions, every vertex pinned to the slot bone',
   authored: 'authored  geometry rigc did not build; it assumes nothing about the topology',
 };
 
@@ -578,11 +687,27 @@ function sameKeyTime(specTime: number, loaded: number): boolean {
  * - the reversal and collapse counts are the **survey's**, which is A39's own
  *   survey ([`src/deformmeasure.ts`](src/deformmeasure.ts)) — one measurement,
  *   two readers, so the block and the gate cannot disagree about a fold;
+ * - 🔒 and so is **the frame each key was posed in** (issue #407), which every
+ *   `DEFORM` line now names: `on a track`, or the slider that applies the
+ *   animation and the dial value its own mapping had to be inverted to. The
+ *   derivation moved and the report had to move with it — a block that went on
+ *   printing the same figures under a changed meaning would be worse than the
+ *   red it replaced;
  * - a key's model is the **compiler's** `transform` report (§4.11.1), so the
  *   block names the same `kind` and parameters the spec stated;
  * - the fold ANGLE is nowhere here. It is A39's, derived at run time from the
  *   grid, and a second copy of it printed beside a ratio would be a number that
- *   goes stale when somebody moves a column.
+ *   goes stale when somebody moves a column;
+ * - and a key the gate read **no winding** off — because the slot draws no pixels
+ *   of the mesh at that key's own time (issue #401) — says so on a `skipped` line
+ *   with the survey's own sentence, and is kept out of the rollup's counts,
+ *   because that line ends by claiming A39 reads the same two;
+ * - the **spans** between the keys are the survey's too (issue #403). A `BETWEEN`
+ *   line appears wherever the closed form found a fold at a time no key lands
+ *   on, whether the gate refuses it or passes it over because nothing is drawn
+ *   there — and a `spans` line says how many were scanned even when nothing was
+ *   found, because a scan that ran and found nothing has to be distinguishable
+ *   from a scan that never ran.
  *
  * ## And what it deliberately does not print
  *
@@ -605,6 +730,8 @@ function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>):
     out.push(
       '  ..    every key measured at its OWN time against the same pose with the deform CLEARED, so the',
       '  ..    denominator is 1.000 by definition and a NEGATIVE area ratio IS a reversed triangle',
+      '  ..    the FRAME is on each key line: on a track, or the slider that applies the animation with the',
+      '  ..    dial value its mapping was inverted to — a slider picks the time, so the key\'s time IS it',
       '  ..    stretch is 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 there; their product is |area ratio|',
       '  ..    coverage is NOT here: it is rasterised from the uvs, which no deform moves, so the figure on',
@@ -632,6 +759,54 @@ function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>):
       `  DEFORM  ${key.animation}  ${key.skin}/${key.slot}/${key.placeholder}  key ${key.key}  ` +
         `t=${key.time.toFixed(6)}  ${states}`,
     );
+    // 🔒 The frame, on every key, because the derivation is shared with A39 and
+    // this block is where a reader finds out which one it was (issue #407). A
+    // track frame says so in three words; a slider frame names the dial value
+    // its own mapping inverts this time to, which is the number an author sets.
+    out.push(
+      `          frame      ${key.reach.label}` +
+        (key.dial === null
+          ? ''
+          : `, dial ${key.dial.value.toFixed(6)}` +
+            (key.reach.local || key.dial.driven === key.dial.value
+              ? ''
+              : ` (bone local ${key.dial.driven.toFixed(6)})`) +
+            ` -> t=${key.dial.applied.toFixed(6)}`),
+    );
+    // A key at a time no dial selects: the figures below are the frame the
+    // runtime DOES land on, which is some other time's geometry, so the line
+    // that says so comes before them and the gate reads none of them.
+    if (key.dial?.unreachable === true) {
+      out.push(
+        `          unreachable A39 gates nothing here: ${unreachableWhy(key)}. Every figure below is that other ` +
+          "frame's, not this key's",
+      );
+    }
+    // ⚠️ An exemption nobody can see is how a gate comes to look kept while
+    // checking nothing (issue #401). A key the gate passed over because the mesh
+    // draws no pixels there says so on its own line, in the survey's own words,
+    // whether or not it folds.
+    if (key.draw.blank !== null) {
+      out.push(
+        `          skipped    A39 reads no winding off this key: ${key.draw.blank} — a triangle that draws no ` +
+          'pixels cannot draw them backwards',
+      );
+    }
+    // And when the slot shows something else, the figures below would be a
+    // second falsehood rather than a caveat: the runtime applies no deform to a
+    // slot that is not showing the mesh (`DeformTimeline.applyToSlot`), so every
+    // figure would be the identity and `moved 0` would read as "this key is the
+    // setup pose" — which is exactly what the key is NOT.
+    if (!key.draw.showsThisMesh) {
+      out.push(
+        `          ..         the slot shows ${key.draw.shown === null ? 'no attachment' : `"${key.draw.shown}"`} ` +
+          'here, so the runtime applied no deform and there is no posed geometry to measure' +
+          (key.draw.blank === null
+            ? ' — but the mesh IS drawn in another slot this deform reaches (timelineSlots), so nothing here is exempt'
+            : ''),
+      );
+      continue;
+    }
     // A key that moves nothing gets one line and no figures. `{ "t": 2.2 }` with
     // no run is the format's own way of writing "back to the setup pose" (§4.11),
     // and its geometry is bit-identical to the cleared pose it would be measured
@@ -662,9 +837,11 @@ function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>):
     // A39 does not refuse it — it SKIPs the slot entirely.
     const exempted = exempt.has(key.slot);
     const fold = key.reversed.length
-      ? exempted
-        ? '  <- a fold, and A39 does not gate it — see below'
-        : '  <- a fold: A39 refuses this key by name'
+      ? key.draw.blank !== null
+        ? '  <- a fold, and nothing gates it: this key draws no pixels (see above)'
+        : exempted
+          ? '  <- a fold, and A39 does not gate it — see below'
+          : '  <- a fold: A39 refuses this key by name'
       : '';
     out.push(
       `          winding    ${key.triangles - key.reversed.length} of ${key.triangles} kept, ` +
@@ -676,11 +853,53 @@ function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>):
       );
     }
   }
+  // The folds at times no key lands on (issue #403), printed after the keys they
+  // lie between rather than interleaved: they are a different measurement — the
+  // closed form named the time and the runtime was posed there — and a reader
+  // needs to be able to tell the two apart at a glance.
+  for (const span of survey.spans) {
+    if (span.fold === null) continue;
+    const at = span.fold;
+    out.push(
+      `  BETWEEN ${span.animation}${span.reach.kind === 'slider' ? ` via ${span.reach.slider}` : ''}  ` +
+        `${span.skin}/${span.slot}/${span.placeholder}  key ${span.fromKey} -> ` +
+        `${span.toKey}  t=${at.time.toFixed(6)}  ${span.curve}` +
+        (span.curve === 'stepped' ? '  (held, not interpolated)' : `  ${(at.percent * 100).toFixed(1)}% of the way`),
+    );
+    out.push(
+      `          winding    ${at.measure.triangles - at.measure.reversed.length} of ${at.measure.triangles} kept, ` +
+        `${at.measure.collapsed} collapsed  <- a fold at a time no key lands on` +
+        (at.measure.draw.blank !== null
+          ? ', and nothing gates it: nothing is drawn there'
+          : exempt.has(span.slot)
+            ? ', and A39 does not gate it (invariants.deformMayFold)'
+            : `: A39 refuses this span by name, at alpha ${at.measure.draw.alpha.toFixed(4)}`),
+    );
+  }
   // The rollup, per animation: the worst key by each quantity. A timeline's own
   // eight keys are eight blocks above, and "which of them is the one to look at"
   // is the question the sweep in issue #313's landing comment answered by hand.
-  for (const animation of [...new Set(survey.keys.map((k) => k.animation))]) {
-    const keys = survey.keys.filter((k) => k.animation === animation);
+  //
+  // ⚠️ Per animation AND per frame (issue #407). Two sliders applying one
+  // 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.
+  const rollups = new Map<string, { animation: string; label: string }>();
+  for (const key of survey.keys) {
+    rollups.set(`${key.animation}${key.reach.slider ?? ''}`, {
+      animation: key.animation,
+      label: key.reach.kind === 'slider' ? `${key.animation} via ${key.reach.slider}` : key.animation,
+    });
+  }
+  for (const [id, { animation, label }] of rollups) {
+    // Only the keys the gate ran on, because the line ends by claiming A39 reads
+    // 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 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);
     const worst = (
       pick: (key: DeformKeyMeasure) => DeformExtreme | null,
       better: (a: number, b: number) => boolean,
@@ -696,19 +915,123 @@ function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>):
     const reversed = keys.reduce((n, k) => n + k.reversed.length, 0);
     const collapsed = keys.reduce((n, k) => n + k.collapsed, 0);
     const samples = keys.reduce((n, k) => n + k.triangles, 0);
+    if (keys.length) {
+      out.push(
+        `  WORST   ${label}  area ${worst((k) => k.areaRatioMin, (a, b) => a < b)}  ` +
+          `stretch ${worst((k) => k.stretchMax, (a, b) => a > b)}  ` +
+          `squash ${worst((k) => k.stretchMin, (a, b) => a < b)}`,
+      );
+      out.push(
+        `  ..      ${''.padEnd(label.length)}  reversed ${reversed}, collapsed ${collapsed}, over ` +
+          `${keys.length} key(s) and ${samples} triangle sample(s)  <- A39 reads the same two counts`,
+      );
+    }
+    if (blank.length) {
+      out.push(
+        `  ..      ${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',
+      );
+    }
+    if (unreachable.length) {
+      out.push(
+        `  ..      ${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',
+      );
+    }
+    // ⚠️ 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);
+    if (spans.length) {
+      out.push(
+        `  ..      ${keys.length || blank.length || unreachable.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`,
+      );
+    }
+  }
+  // ⚠️ And the spans that were NOT scanned, once, because a scan that did not
+  // run has to be distinguishable from one that ran and found nothing — the same
+  // rule the line above keeps, on the other side of it (issue #407).
+  if (survey.spansNotScanned) {
     out.push(
-      `  WORST   ${animation}  area ${worst((k) => k.areaRatioMin, (a, b) => a < b)}  ` +
-        `stretch ${worst((k) => k.stretchMax, (a, b) => a > b)}  ` +
-        `squash ${worst((k) => k.stretchMin, (a, b) => a < b)}`,
-    );
-    out.push(
-      `  ..      ${''.padEnd(animation.length)}  reversed ${reversed}, collapsed ${collapsed}, over ` +
-        `${keys.length} key(s) and ${samples} triangle sample(s)  <- A39 reads the same two counts`,
+      `  ..      ${survey.spansNotScanned} span(s) NOT scanned: one of the two keys bounding each is at a time no ` +
+        'dial selects, so the interpolation between them is between two poses of some other time',
     );
   }
   return out;
 }
 
+/** What the between-keys scan found, in one clause (issue #403). */
+function spanTally(spans: readonly DeformSpan[]): string {
+  const folds = spans.filter((s) => s.fold !== null).length;
+  const notDrawn = spans.filter((s) => s.notDrawn > 0).length;
+  const unconfirmed = spans.filter((s) => s.unconfirmed).length;
+  const probes = spans.reduce((n, s) => n + s.probed.length, 0);
+  if (folds === 0 && notDrawn === 0 && unconfirmed === 0) {
+    return `none folds (the closed form flagged nothing, so no span cost a posed measurement)`;
+  }
+  return (
+    [
+      folds ? `${folds} fold(s)` : '',
+      notDrawn ? `${notDrawn} folding only where nothing is drawn` : '',
+      unconfirmed ? `${unconfirmed} predicted a fold no probe reproduced` : '',
+    ]
+      .filter(Boolean)
+      .join(', ') + `, at a cost of ${probes} posed measurement(s)`
+  );
+}
+
+/**
+ * The header the `scale` rows carry, because the figure beside them lies without
+ * it.
+ *
+ * ⛔ Three things it has to say, and each one is a way the number is wrong if
+ * taken at face value:
+ *   - it is the key's OWN factor. A nonuniform parent shears its children, so
+ *     the drawn area is not this product;
+ *   - a key that moved only one axis has no product to state, and gets none
+ *     rather than an invented 1 on the other;
+ *   - a uniform scale has a product too, and it is a zoom rather than a squash.
+ */
+const SCALE_PRODUCT_NOTE =
+  '..  x·y is the key\'s own local area factor: ~1.00 is the volume kept, and it is a READING, never a rule — ' +
+  'a nonuniform parent shears this, and a uniform scale has a product without being a squash';
+
+/**
+ * `x·y` for a `scale` key that states both, and nothing otherwise.
+ *
+ * ⭐ Why it is here at all: `explain` ALREADY prints this reading for the other
+ * spelling of squash and stretch. A `transform: affine` deform key reports
+ * `area x1.020800`, which is exactly its own `0.88 × 1.16` — so the author who
+ * reaches for the advanced spelling is told whether the volume held and the
+ * author who reaches for the cheap one is not, while `docs/MOTION.md` §7 points
+ * a first candidate at the cheap one on purpose. That asymmetry is the defect;
+ * this is not a new kind of number (issue #377).
+ *
+ * 🔒 A reading and never an assertion. `deformReportLines` states the test a
+ * geometric figure has to pass to become a gate — no legitimate counter-example
+ * — and this fails it in quantity: a shadow, a zoom, a cartoon squash that
+ * gains mass on purpose. Volume preservation is a style commitment no spec can
+ * declare, so a bar here would be one consumer's house style failing correct
+ * foreign data. There is no honest SKIP either: an absent declaration is not
+ * "nothing to measure", it is "no way to know what was meant".
+ */
+function scaleProduct(timelineName: string, key: Record<string, unknown>): string {
+  if (timelineName !== 'scale') return '';
+  const x = key.x;
+  const y = key.y;
+  // Both axes, or nothing: a key that moved one axis has no area factor, and
+  // defaulting the other to 1 would invent the very number being reported.
+  if (typeof x !== 'number' || typeof y !== 'number') return '';
+  return `  x·y=${(x * y).toFixed(4)}`;
+}
+
 /**
  * Read one non-negative integer flag, or its default.
  *
@@ -796,7 +1119,8 @@ function cmdBuild(flags: Record<string, string>): void {
   for (const m of result.meshes) {
     console.log(
       `  MESH  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
-        `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}`,
+        `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}` +
+        meshDepthNote(m),
     );
   }
   for (const ph of result.physics) {
@@ -2019,6 +2343,7 @@ function cmdExplain(flags: Record<string, string>): void {
       const drives = result.meshBones.includes(boneName) ? '  <- drives a mesh' : '';
       for (const [timelineName, keys] of Object.entries(timelines)) {
         console.log(`    ${boneName}.${timelineName}  ${keys.length} key(s)${drives}`);
+        if (timelineName === 'scale') console.log(`      ${SCALE_PRODUCT_NOTE}`);
         for (const key of keys) {
           const fields = Object.entries(key)
             .filter(([k]) => k !== 'time' && k !== 'curve')
@@ -2029,7 +2354,7 @@ function cmdExplain(flags: Record<string, string>): void {
             : key.curve === 'stepped'
               ? 'stepped'
               : 'linear';
-          console.log(`      t=${String(key.time).padEnd(7)} ${fields.padEnd(30)} ${curve}`);
+          console.log(`      t=${String(key.time).padEnd(7)} ${fields.padEnd(30)} ${curve}${scaleProduct(timelineName, key)}`);
         }
       }
     }
@@ -2127,6 +2452,24 @@ function cmdExplain(flags: Record<string, string>): void {
                 }
                 console.log(`                 ${pairs.join('  ')}`);
               }
+              // On a multi-influence attachment those pairs are the model's
+              // WORLD displacements, and the file holds one `Mᵢ⁻¹·D` pair per
+              // influence instead (issue #389). Printing the first without the
+              // second would put numbers on the screen that are nowhere in the
+              // artifact — the exact gap this block exists to close.
+              if (gen.expanded !== undefined) {
+                console.log(
+                  `               written as ${gen.expanded.length / 2} per-influence pair(s), each vertex's D through ` +
+                    'its own bone inverse',
+                );
+                for (let i = 0; i < gen.expanded.length / 2; i += 4) {
+                  const pairs: string[] = [];
+                  for (let k = i; k < Math.min(i + 4, gen.expanded.length / 2); k++) {
+                    pairs.push(`i${String(k).padStart(3)} (${gen.expanded[2 * k]}, ${gen.expanded[2 * k + 1]})`);
+                  }
+                  console.log(`                 ${pairs.join('  ')}`);
+                }
+              }
             }
           }
         }
@@ -2223,9 +2566,14 @@ function cmdExplain(flags: Record<string, string>): void {
     console.log('\nmeshes');
     for (const kind of new Set(result.meshes.map((m) => m.kind))) console.log(`  ${MESH_KIND_NOTES[kind]}`);
     for (const m of result.meshes) {
+      // The depth block belongs here more than it belongs in `build`: `explain`
+      // is the command that says what a spec MEANS, and the turn ceiling is the
+      // number an author needs before writing a key rather than after a refusal.
+      // It was absent, while `docs/AUTHORING.md` said both commands printed it.
       console.log(
         `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
-          `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]${meshFit(m)}`,
+          `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]${meshFit(m)}` +
+          meshDepthNote(m),
       );
     }
   }
@@ -2606,10 +2954,11 @@ const USAGE = [
   '',
   'build, validate and bench take --profile spine|spine-html:',
   '  spine       is this valid Spine 4.3 that any runtime plays correctly?',
-  '              THE DEFAULT — 20 rules, and the question the output answers when',
+  `              THE DEFAULT — ${assertionCountForProfile('spine')} rules, and the question the output answers when`,
   '              you import it into the Spine editor.',
   '  spine-html  the above, plus this project\'s renderer and archetype policy:',
-  '              all 36 rules, opt-in. Those extra 14 fire on real, correct,',
+  `              all ${assertionCountForProfile('spine-html')} rules, opt-in. Those extra ` +
+    `${assertionCountForProfile('spine-html') - assertionCountForProfile('spine')} fire on real, correct,`,
   '              editor-produced Spine data, so they are somebody\'s policy rather',
   '              than anybody\'s validity.',
   '',